Agent Rule Patterns

This page covers the pattern syntax for custom permission rules. For an overview of agent permissions and how to configure them, see the Agent page.

Rule evaluation order

Rules are evaluated in order. Deny rules are checked first, then require approval, then allow. The first matching rule wins.

Pattern basics

Patterns tell the system what to match against. What a pattern matches depends on the tool you selected. Patterns support * as a wildcard and ** for recursive matching.

Shell patterns

Shell patterns match against the command string. Wildcards can appear at any position.

• npm run * matches any command starting with "npm run"
• * --version matches any command ending with "--version"
• git * main matches commands like "git checkout main" or "git merge main"
• terraform fmt * matches "terraform fmt" with or without arguments

The space before * matters. ls * matches ls -la but not lsof, while ls* matches both. The space enforces a word boundary.

Shell patterns that try to constrain URLs or complex arguments can be fragile. For example, curl http://github.com/ * won't match variations like options before the URL, different protocols, redirects, or environment variables. For reliable domain filtering, use web tool rules with domain: instead.

File patterns

File tool patterns (Read, Edit, Write, Glob, Grep) match against file paths using gitignore-style globs.

Path prefixes

Four path prefixes control where the pattern matches from.

Note that /Users/alice/file is not an absolute path. It's relative to the workspace. Use //Users/alice/file for absolute paths.

Wildcards

• * matches within a single directory. *.tf matches main.tf but not modules/main.tf.
• ** matches recursively across directories. **/*.tf matches main.tf, modules/main.tf, and modules/vpc/main.tf.

Examples

• outputs.tf matches any file named outputs.tf regardless of location
• /src/**/*.ts matches all .ts files anywhere under the workspace's src/ directory
• **/*.secret matches .secret files anywhere in the tree
• ~/Documents/*.pdf matches PDF files in your home Documents folder
• //tmp/scratch.txt matches the exact absolute path /tmp/scratch.txt

Web patterns

Web tool patterns use the domain: prefix to match against hostnames.

• domain:github.com matches requests to github.com and its subdomains

MCP tool patterns

MCP tool patterns match against server and tool names.

• mcp__servername matches any tool from that MCP server
• mcp__servername__toolname matches a specific tool on that server

Task patterns

Task patterns match against the subagent name.

• Explore matches delegation to the Explore subagent
• Plan matches the Plan subagent