ClaudeAgentSDK.Permission.Update (claude_agent_sdk v0.11.0)

Copy Markdown View Source

Permission update types for configuring permissions via the control protocol.

These types match the TypeScript/Python SDK permission update structures and can be used to programmatically update tool permissions in sessions.

Update Types

  • :add_rules - Add new permission rules
  • :replace_rules - Replace existing permission rules
  • :remove_rules - Remove specific permission rules
  • :set_mode - Change the permission mode
  • :add_directories - Add directories to allowed paths
  • :remove_directories - Remove directories from allowed paths

Destinations

Permission updates can target different storage locations:

  • :user_settings - User-level settings (persistent)
  • :project_settings - Project-level settings (persistent)
  • :local_settings - Local directory settings (persistent)
  • :session - Session-only settings (temporary)

Examples

# Add a rule to allow Bash commands in session
update = Update.add_rules(
  rules: [RuleValue.new("Bash", "echo *")],
  behavior: :allow,
  destination: :session
)

# Set permission mode for the session
update = Update.set_mode(:accept_edits, destination: :session)

Summary

Types

behavior()

Permission behavior for rules.

destination()

Destination for permission updates.

t()

Permission update struct.

update_type()

Permission update type.

Functions

add_directories(directories, opts \\ [])

Creates an add_directories update.

add_rules(opts \\ [])

Creates an add_rules update.

new(type, opts \\ [])

Creates a new permission update.

remove_directories(directories, opts \\ [])

Creates a remove_directories update.

remove_rules(opts \\ [])

Creates a remove_rules update.

replace_rules(opts \\ [])

Creates a replace_rules update.

set_mode(mode, opts \\ [])

Creates a set_mode update.

to_map(update)

Converts a permission update to a map for the control protocol.

Types

behavior()

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

Permission behavior for rules.

destination()

@type destination() :: :user_settings | :project_settings | :local_settings | :session

Destination for permission updates.

t()

@type t() :: %ClaudeAgentSDK.Permission.Update{
  behavior: behavior() | nil,
  destination: destination() | nil,
  directories: [String.t()] | nil,
  mode: ClaudeAgentSDK.Permission.permission_mode() | nil,
  rules: [ClaudeAgentSDK.Permission.RuleValue.t()] | nil,
  type: update_type()
}

Permission update struct.

update_type()

@type update_type() ::
  :add_rules
  | :replace_rules
  | :remove_rules
  | :set_mode
  | :add_directories
  | :remove_directories

Permission update type.

Functions

add_directories(directories, opts \\ [])

@spec add_directories(
  [String.t()],
  keyword()
) :: t()

Creates an add_directories update.

add_rules(opts \\ [])

@spec add_rules(keyword()) :: t()

Creates an add_rules update.

new(type, opts \\ [])

@spec new(
  update_type(),
  keyword()
) :: t()

Creates a new permission update.

Parameters

  • type - Update type (:add_rules, :replace_rules, :remove_rules, :set_mode, :add_directories, :remove_directories)
  • opts - Options for the update (rules, behavior, mode, directories, destination)

Examples

Update.new(:add_rules,
  rules: [RuleValue.new("Bash", "echo *")],
  behavior: :allow,
  destination: :session
)

remove_directories(directories, opts \\ [])

@spec remove_directories(
  [String.t()],
  keyword()
) :: t()

Creates a remove_directories update.

remove_rules(opts \\ [])

@spec remove_rules(keyword()) :: t()

Creates a remove_rules update.

replace_rules(opts \\ [])

@spec replace_rules(keyword()) :: t()

Creates a replace_rules update.

set_mode(mode, opts \\ [])

@spec set_mode(
  ClaudeAgentSDK.Permission.permission_mode(),
  keyword()
) :: t()

Creates a set_mode update.

to_map(update)

@spec to_map(t()) :: map()

Converts a permission update to a map for the control protocol.

Examples

iex> update = Update.add_rules(
...>   rules: [RuleValue.new("Bash", "echo *")],
...>   behavior: :allow,
...>   destination: :session
...> )
iex> Update.to_map(update)
%{
  "type" => "addRules",
  "rules" => [%{"toolName" => "Bash", "ruleContent" => "echo *"}],
  "behavior" => "allow",
  "destination" => "session"
}