Permissions Configuration

Polytoken reads permission rules from dedicated permissions files. Your secret files and words are listed separately, in your main configuration. For runtime approval behavior, see Permissions.

Where permission rules live

Polytoken reads permissions and permissions.local files from two layers: your global configuration directory and your project. The files are written in YAML. Rules from every layer combine, with your global rules first and your project rules added on top.

The rule buckets

A permission file holds up to four lists of rules. Each rule names a tool and, optionally, args that narrow what it matches.

Bucket	Meaning
allow	Run a matching tool call without asking.
ask	Ask before running a matching tool call.
ask-unless-allowed	Ask, unless an allow rule already covers it.
deny	Refuse a matching tool call.

When more than one rule matches, the most restrictive outcome wins: deny beats ask, and ask beats allow. A tool call that no rule matches is asked about.

A rule’s tool is a tool name or a glob. Its args narrow the match further: for example, a path for a file tool, or, for a shell command, the program, its subcommand, or its flags. (Polytoken reads each shell command and matches the individual programs it runs; see Permissions for how shell commands are handled.)

String argument values can be exact strings or globs. For path and URL rules, the suffix {,/**} means “this path and anything under it.” For example, /home/ed/tmp{,/**} matches both /home/ed/tmp and /home/ed/tmp/foo.md. When Polytoken recommends a filesystem permission for a file path, Polytoken usually recommends the parent directory in this form so approving one file in that directory also covers the next file there.

Filesystem rules

Permission files can also hold filesystem rules. A filesystem rule grants one or more path capabilities under access. Filesystem rules use the same allow, ask, ask-unless-allowed, and deny buckets as tool rules:

Capability	Meaning
read	Read file contents or inspect directory contents.
write	Create or overwrite files, and provide the write side of edits, deletes, or moves. Existing-file changes usually also need read.
chdir	Change a shell command’s working directory to the path.

access is an array of kebab-case capability names. Write access: [read, write] when a rule should cover both reading and writing. write by itself does not grant read.

Directory read rules also cover file discovery and text search inside that directory. For example, glob and grep can use a read-granted external directory as their search root. If glob is called with an absolute pattern and no explicit path, Polytoken derives the root from the literal directory prefix before the first wildcard; /path/**/something/*.md is checked against /path{,/**}.

version: 2
filesystem:
  allow:
    - access: [read, write, chdir]
      path: /home/ed/project{,/**}

Polytoken writes filesystem recommendations with the current format. Older permission files still load: version 1 write filesystem rules become access: [read, write], and legacy path-scoped cd and pushd shell rules also add matching chdir filesystem rules.

Secret files and words

Two lists live under the permissions block of your main configuration, not in the rule files:

Setting	Meaning
secret_words	A list of values to keep out of search results.
secret_files	A list of file paths to treat as sensitive. A command that reads a listed file is held for your approval unless an allow rule names that exact command.

Configuration

version: 2
allow:
  - tool: shell_exec
    args:
      executable: git
      subcommand: status
ask:
  - tool: web_fetch
    args:
      url: https://example.com/private{,/**}
ask-unless-allowed:
  - tool: shell_exec
    args:
      executable: npm
deny:
  - tool: shell_exec
    args:
      executable: rm
      flags_present: ["-rf"]

filesystem:
  allow:
    - access: [read, write, chdir]
      path: /home/ed/project{,/**}
  ask:
    - access: [read]
      path: /home/ed/secrets{,/**}
  ask-unless-allowed:
    - access: [write]
      path: /tmp{,/**}
  deny:
    - access: [read, write, chdir]
      path: /etc{,/**}