Permissions Configuration

Polytoken reads permission rules from permissions and permissions.local files (YAML) in two layers: your global configuration directory and your project. Rules from every layer combine, with global rules first and project rules on top. This page describes the current version: 2 format; older files still load through compatibility migration.

When more than one rule matches a call, the most restrictive outcome wins: deny beats ask, and ask beats allow. A call that no rule matches is asked about. Secret files and words live under the permissions block of your main configuration, not in these rule files; see Application Configuration.

version: 2
allow:
  - tool: shell_exec
    args: { executable: git, subcommand: status }
ask:
  - tool: web_fetch
    args: { url: "https://example.com/private{,/**}" }
deny:
  - tool: shell_exec
    args: { executable: rm, flags_present: ["-rf"] }
filesystem:
  allow:
    - access: [read, write, chdir]
      path: /home/ed/project{,/**}

Full schema: JSON | YAML.

version

Schema version. Always 2.

Tool rules

Each bucket is a list of rules. Every rule names a tool and, optionally, args that narrow what it matches.

Name	Type	Description
allow	rule list	Run matching tool calls without asking.
ask	rule list	Ask before running matching tool calls.
ask-unless-allowed	rule list	Ask before running matching tool calls, unless an allow rule already covers them.
deny	rule list	Refuse matching tool calls.

Rule fields

Name	Type	Description
tool	string	Tool name, glob, or mcp__<server> shorthand that matches every tool from that MCP server.
args	object	Arguments that narrow the match. The keys present determine which category of argument narrowing applies: path for file tools, url for web tools, executable/subcommand/command_tokens/flags_present for shell tools, pattern/include for search tools, and model for model-scoped rules. Omit args for a name-only rule.
message	string	Optional reminder text shown to the model after a tool call matched by this rule completes. Polytoken injects the text as a system reminder after the full tool batch finishes, so it never interrupts tool results. Use this to give the model context about why a rule exists or what to do next when the rule fires. The message only fires when a rule with this verdict is the resolved verdict: an allow rule on an allowed call, or a deny rule on a denied call. If multiple rules with messages match the same call, each one whose verdict matches the resolved outcome fires its message. Ask rules never produce a reminder. Bypass mode skips all messages.

Filesystem rules

Filesystem path-capability rules, using the same buckets.

Filesystem rules use the same buckets, each a list of rules. Every filesystem rule grants access capabilities on a path.

Name	Type	Description
allow	rule list	Grant the listed path capabilities without asking.
ask	rule list	Ask before granting the listed path capabilities.
ask-unless-allowed	rule list	Ask before granting the listed path capabilities, unless an allow rule already covers them.
deny	rule list	Refuse the listed path capabilities.

Filesystem rule fields

Name	Type	Description
access	array	Path capabilities the rule grants: read, write, and chdir.
path	string	Path the rule applies to. The suffix {,/**} means the path and anything under it.