ClaudeAgentSDK.Permission.Result (claude_agent_sdk v0.5.3)

View Source

Permission result returned by permission callbacks.

A permission result indicates whether a tool should be allowed to execute, and optionally modifies the tool's input parameters or permission rules.

Result Types

Allow

Permits the tool to execute:

Result.allow()
Result.allow(updated_input: %{"file_path" => "/safe/path.txt"})

Deny

Blocks the tool from executing:

Result.deny("Command not allowed")
Result.deny("Critical violation", interrupt: true)

Fields

For Allow Results

  • behavior - Always :allow
  • updated_input - Optional modified tool input (map)
  • updated_permissions - Optional permission rule updates (list)

For Deny Results

  • behavior - Always :deny
  • message - Explanation for denial (string)
  • interrupt - If true, stops entire agent execution (boolean)

Examples

# Simple allow
Result.allow()

# Allow with input modification
Result.allow(updated_input: %{"command" => "ls -la /safe/dir"})

# Simple deny
Result.deny("Tool not allowed in this context")

# Deny with interrupt
Result.deny("Security violation detected", interrupt: true)

Summary

Types

behavior()

Permission result behavior.

t()

Permission result struct.

Functions

allow(opts \\ [])

Creates an allow permission result.

deny(message, opts \\ [])

Creates a deny permission result.

to_json_map(result)

Converts a permission result to a JSON-compatible map for the CLI.

validate(result)

Validates a permission result.

Types

behavior()

@type behavior() :: :allow | :deny

Permission result behavior.

t()

@type t() :: %ClaudeAgentSDK.Permission.Result{
  behavior: behavior(),
  interrupt: boolean(),
  message: String.t() | nil,
  updated_input: map() | nil,
  updated_permissions: [map()] | nil
}

Permission result struct.

For allow results:

  • behavior - :allow
  • updated_input - Optional modified tool input
  • updated_permissions - Optional permission updates

For deny results:

  • behavior - :deny
  • message - Explanation for denial
  • interrupt - Whether to stop entire execution

Functions

allow(opts \\ [])

@spec allow(keyword()) :: t()

Creates an allow permission result.

Parameters

  • opts - Keyword list of options

Options

  • :updated_input - Modified tool input (map)
  • :updated_permissions - Permission rule updates (list of maps)

Examples

# Simple allow
Result.allow()

# Allow with input modification
Result.allow(updated_input: %{"file_path" => "/safe/output.txt"})

# Allow with permission updates
Result.allow(
  updated_permissions: [
    %{type: "addRules", tool_name: "Bash", behavior: "deny"}
  ]
)

deny(message, opts \\ [])

@spec deny(
  String.t(),
  keyword()
) :: t()

Creates a deny permission result.

Parameters

  • message - Explanation for the denial (required)
  • opts - Keyword list of options

Options

  • :interrupt - If true, stops entire agent execution (default: false)

Examples

# Simple deny
Result.deny("Tool not allowed")

# Deny with interrupt
Result.deny("Security policy violation", interrupt: true)

to_json_map(result)

@spec to_json_map(t()) :: map()

Converts a permission result to a JSON-compatible map for the CLI.

Examples

iex> result = Result.allow()
iex> Result.to_json_map(result)
%{"behavior" => "allow"}

iex> result = Result.deny("Not allowed")
iex> Result.to_json_map(result)
%{"behavior" => "deny", "message" => "Not allowed", "interrupt" => false}

iex> result = Result.allow(updated_input: %{"key" => "value"})
iex> Result.to_json_map(result)
%{"behavior" => "allow", "updated_input" => %{"key" => "value"}}

validate(result)

@spec validate(term()) :: :ok | {:error, String.t()}

Validates a permission result.

Returns :ok if valid, {:error, reason} otherwise.

Examples

iex> Result.validate(Result.allow())
:ok

iex> Result.validate(Result.deny("Reason"))
:ok

iex> Result.validate(%{})
{:error, "Result must be a ClaudeAgentSDK.Permission.Result struct"}