amp-permissions

Permissions Reference

source: https://ampcode.com/manual/appendix#permissions-configuration

Amp’s permission system controls every tool invocation before execution. The system uses a single, ordered list of rules that are evaluated sequentially until the first match is found.

How Permissions Work

Before running any tool, Amp evaluates permissions through these steps:

1. Find matching rule: The first rule that matches the tool and its arguments wins
2. Determine action: The matching rule tells Amp to:
   • allow - run the tool silently
   • reject - block the call (optionally with custom message)
   • ask - prompt the operator for approval
   • delegate - delegate decision to an external program
3. Examine builtin rules: If no user rule matches, Amp falls back to built-in rules (e.g., allowing ls via Bash)
4. Default Behavior: If no matching entry is found at all:
   • Main thread: Amp asks the operator
   • Sub-agent: Amp rejects the tool call

Configuration

Rules are defined in the amp.permissions setting. Each rule is a JSON object with these properties:

Key	Type	Required	Description
tool	string (glob)	Yes	Name of the tool this rule applies to. Supports globs (Bash, mcp__playwright__*, **/my-tool)
matches	object	–	Map of tool-argument → condition. If omitted, the rule matches all calls to the tool
action	"allow" / "reject" / "ask" / "delegate"	Yes	What Amp should do if the rule matches
context	"thread" / "subagent"	–	Restrict the rule to the main thread or to sub-agents. Omit to apply everywhere
to	string (program)	only when action = "delegate"	Program that decides. Must be on $PATH
message	string	only when action = "reject"	Message returned to the model. If set, the rejection continues the conversation instead of halting it

Match Conditions

Each matches key corresponds to a tool argument. Values can be:

• string – glob pattern (* = any characters) or regex pattern (/pattern/)
• array – OR of each entry (["rm -rf *", "git commit *"])
• boolean/number/null/undefined – literal value match
• object – nested structure matching

Regular Expression Patterns

Strings that start and end with / are treated as regular expressions:

{
  "tool": "Bash",
  "matches": { "cmd": "/^git (status|log|diff)$/" },
  "action": "allow"
}

This matches exactly git status, git log, or git diff but not git commit.

Value Type Matching

• String patterns only match string values using glob syntax
• Literal values (boolean, number, null, undefined) require exact matches
• Array conditions provide OR logic across multiple patterns
• Nested objects enable deep property matching with dot notation for objects and numeric strings for array indices

Examples

Basic Permission Rules

Allow all Bash commands in main thread, but restrict sub-agents:

{
  "tool": "Bash",
  "action": "allow",
  "context": "thread"
},
{
  "tool": "Bash",
  "matches": { "cmd": ["rm -rf *", "find *", "git commit *"] },
  "action": "reject",
  "context": "subagent"
}
// In text form:
// allow --context thread Bash
// reject --context subagent Bash --cmd "rm -rf *" --cmd "find *" --cmd "git commit *"

Ask before grepping in the home directory:

{
  "tool": "Grep",
  "matches": { "path": "$HOME/*" },
  "action": "ask"
}
// In text form:
// ask Grep --path '$HOME/*'

Forbid editing dotfiles:

{
  "tool": "edit_file",
  "matches": { "path": ".*" },
  "action": "reject"
}
// In text form:
// reject edit_file --path '.*'

Reject destructive git commands with a helpful message (allows the model to continue):

{
  "tool": "Bash",
  "matches": { "cmd": ["*git checkout*", "*git reset*"] },
  "action": "reject",
  "message": "Do not use git checkout or git reset. Use edit_file to make manual changes instead."
}

Delegation

Delegate GitHub CLI calls to external validator:

{
  "tool": "Bash",
  "matches": { "cmd": "gh *" },
  "action": "delegate",
  "to": "my-gh-permission-helper"
}
// In text form:
// delegate --to my-gh-permission-helper Bash --cmd "gh *"

When instructed to delegate, Amp will:

• Execute the program named in to (must be on $PATH, or an absolute path)
• Export AMP_THREAD_ID, AGENT_TOOL_NAME=nameOfInvokedTool and AGENT=amp environment variables
• Pipe tool parameters to stdin as JSON
• Interpret exit status:
  • 0 → allow
  • 1 → ask operator
  • ≥ 2 → reject (stderr is surfaced to the model)

Text Format

For editing many rules conveniently, you can use the text format with amp permissions commands:

<action> [--<action-arg> ...] <tool> [--<match-key>[:<op>] <value>] ...

The text format is designed to be compatible with UNIX shell syntax, allowing you to copy/paste rules from and to the command line without further editing.

# Basic allow/reject rules
allow Bash --cmd 'git *'
reject Bash --cmd 'python *'

# Multiple conditions
allow Bash --cmd 'git diff*' --cmd 'git commit*'

# Delegation
delegate --to amp-git-permissions Bash --cmd '*'

• Single- and double-quoted strings are supported
• unquoted true, false, null and numeric words are interpreted as JSON literals
• Any value containing * must be quoted

Listing Rules

amp permissions list                    # Show user rules
amp permissions list --builtin          # Only built-in rules

Testing Rules

For example, testing if it would ask on a git commit:

$ amp permissions test Bash --cmd "git commit -m 'test'"
tool: Bash
arguments: {"cmd":"git commit -m 'test'"}
action: ask
matched-rule: 12
source: builtin

or testing if it would ask to edit.env in the current directory

$ amp permissions test edit_file --path "$PWD/README.md"
tool: edit_file
arguments: {"path":"/Users/your/project/README.md"}
action: allow
matched-rule: 29
source: builtin

The test subcommand allows you to test permission rules without actually running any tools or hoping that the agent will generate the right parameters.

Editing Rules

You can use $EDITOR to edit rules interactively in the text format:

$ amp permissions edit

And you can edit from STDIN:

$ amp permissions edit <<'EOF'
# Ask before every tool use
ask '*'
EOF

Add Rules

For example, reject all mermaid diagrams:

$ amp permissions add reject mermaid

or ask before searching about node.js or npm packages:

$ amp permissions add ask web_search --query "*node*" --query "*npm*"

Matching multiple tools with a single rule

Tool names support glob patterns for managing groups of tools:

• Bash - matches only the Bash tool
• mcp__playwright__* - matches all Playwright MCP tools

Context Restrictions

Use the context field to restrict rules to the main agent or subagents

• "context": "thread" - only applies in main conversation thread
• "context": "subagent" - only applies to sub-agent tool calls
• Omit context - applies everywhere