Permissions

When the model requests a tool call (reading a file, running a command, fetching a URL), Polytoken decides whether to run it, ask you first, or refuse. The permission system computes that decision. It controls how much Polytoken does on its own and when it stops to check with you.

The approval prompt

When a tool call needs your approval, Polytoken pauses and asks. You choose the scope of the approval:

• Allow: run it this once.
• Allow for session: run it now and for the rest of this session.
• Allow forever for this project: remember the approval for this project.
• Allow forever for this user: remember the approval everywhere you use Polytoken.
• No: refuse it.
• Allow and switch permission mode to: approve the current tool call once, then switch the session to the selected permission mode. By default, Left or [ selects the previous mode, and Right or ] selects the next mode. The row stays disabled when the row names the active mode, so the selector never focuses an already-active mode.

Permission modes

Polytoken has four permission modes. Use /permissions to choose a mode. At the prompt, Ctrl+Shift+P opens the same mode selector by default.

• Standard. Polytoken checks each tool call against your rules and its built-in protections, and asks you about anything not clearly allowed. This is the default.
• Autonomous. A classifier model handles the routine approvals. When a tool call would ask you in Standard mode, the classifier assesses the risk of the action and how permissive you are about it, then derives a decision from those two assessments. Every decision appears as a card in the conversation showing the risk level, permissiveness level, and explanation. When the classifier cannot produce a binding decision, the question tells you why. The reason is one of: the permission model could not be reached, the permission model could not be reached or failed to respond, the permission model could not decide (it answered “unsure”), its reply could not be used for a decision, or the permission model is temporarily unavailable after repeated failures. A successful refusal that Polytoken escalates to you is labeled as such, not as a failure. Polytoken’s built-in protections still apply. See what the classifier sees for the exact Autonomous input context.
• Bypass. Polytoken runs every tool call without permission checks. Use Bypass only when you want no interruptions and accept the risk.
• Bypass+. Like Bypass, but still blocks commands you have explicitly denied in your permission rules. Use it when you want an open mode but need certain commands to stay off-limits.

File path approvals

File tools can work inside the project by default. When a file tool names an absolute path outside the project, Polytoken asks for access to that path before the tool runs. A relative path that reaches the same target through a project-directory symlink receives the same approval prompt as the absolute spelling. Approving the target unblocks either spelling. The approval belongs to the session unless you choose a broader scope in the approval prompt.

Read approval lets a tool read a file, inspect a directory, or search inside an approved directory with tools such as glob and grep. Polytoken also lets the model read the current session’s own plan and goal files without asking you for approval.

Write approval covers creating and overwriting a file, including creating any missing parent directories. Existing-file edits, deletes, and patch updates usually need both read and write approval because the tools inspect existing content. Durable filesystem rules record both capabilities as access: [read, write].

Search tools ask for the root they need to enter, not for every match they may return. If glob has an explicit path, that path is the root. If path is omitted and the pattern includes a literal directory prefix, Polytoken uses the directory before the first wildcard as the root. For example, /path/**/something/*.md asks for read access to /path, then returns matches under that root as absolute paths. An absolute literal glob pattern without wildcards, such as /tmp, checks the literal path instead of broadening to /.

Most file tools ask about one path at a time. Some models edit files by sending a patch that can touch several paths. Before the tool runs, Polytoken parses the patch and asks for the filesystem approvals needed to apply the changes.

How shell commands are checked

Polytoken breaks a shell command into the individual programs it would run and checks each program, subcommand, and flag against your rules. A rule that allows find does not allow the rest of the line.

Directory changes have their own path permission. Literal cd and pushd commands in the shell do not need a shell-command rule just because the command name is cd; Polytoken checks the destination path for chdir permission. Changing directory inside the project needs no approval. For a destination outside the project, Polytoken asks for approval unless a filesystem rule grants chdir access to that directory.

The built-in pushd tool behaves the same way. Pushing into a directory outside the project asks for chdir permission on that directory. Approving the chdir also grants read access to the directory, so you do not get a second prompt when the model follows up with glob, grep, or file_read in that directory. The same applies to the subagent tool’s optional cwd parameter: an external start directory asks for chdir approval and seeds read access on approval.

Polytoken cannot inspect commands that use command substitution ($(...)), piping into xargs, nested shells (eval, bash -c), or inline code evaluation (python -c). Because approving one of these commands grants access to whatever the interpreter runs, Polytoken holds each one for approval in Standard and Autonomous modes unless an allow rule covers the whole tool. A dynamic directory target such as cd "$WORKTREE" also hides the destination. Polytoken holds these for your approval in Standard and Autonomous modes even when an allow rule covers the whole tool; the hidden destination, not the command text, is what you are approving. The permission prompt offers only one-time choices for any command Polytoken cannot inspect: allow, deny, or allow with a permission-mode switch. A rule whose conditions require particular command details cannot approve these commands.

Redirecting one stream onto another with a number (2>&1, >&2, 3>&1) does not hide a command. Polytoken sees through these, so your rules match the command as if the redirect were not there. A redirect whose target is not a plain number (2>&$FD, or a filename written after >&) still counts as a command Polytoken cannot inspect.

In Standard and Autonomous modes, when Polytoken cannot inspect one part of a pipeline, it holds the whole pipeline for approval, even when another part matches an allow rule. The exception is a whole-tool allow: an allow rule that still approves the tool when Polytoken has no command details.

A whole-tool allow qualifies if it has no command conditions and matches the tool by name or matches every tool. Rules whose only conditions exclude particular flags also qualify because Polytoken treats flag exclusions as satisfied when it has no flag details. When Polytoken can see an excluded flag, the allow does not approve the command.

Polytoken cannot check particular command details against a command it cannot inspect. Rules that require specific text, command words, an executable, a subcommand, or required flags therefore do not qualify as whole-tool allows, even when their conditions would match every command.

Deny rules still apply to commands Polytoken cannot inspect: a deny rule that matches the command text blocks the command in Standard, Autonomous, and Bypass+ modes. Plain Bypass skips rule evaluation entirely.

Shell interpreters can execute arbitrary code. Polytoken therefore treats every direct interpreter invocation as opaque, including bash script.sh, sh -c 'echo hi', zsh --norc, and bare bash. Because the command text Polytoken matches against is the interpreter invocation itself, a rule whose conditions require particular command details cannot approve these commands. A whole-tool allow can approve them. When an interpreter invocation reaches the permission prompt, the permission prompt offers only one-time choices: allow, deny, or allow with a permission-mode switch.

In Autonomous mode, most opaque shell commands still go to the classifier. The classifier reads the full command text and judges the command on that text, so a command the classifier can read and clear runs without stopping you, even when no command-conditioned allow rule covers it.

For dynamic directory changes, you must approve access to the destination directory. Commands such as cd "$WORKTREE" and relative cd calls after an earlier cd go directly to a human prompt.

Protecting secrets

Polytoken keeps two lists that guard sensitive material in Standard and Autonomous modes:

• Secret files. Files you name as sensitive, such as .env. When a command or file read touches a secret file, Polytoken holds the call for your approval. Searches run without a prompt, but Polytoken filters results that would surface a secret file. To lift the secret-file guard, an allow rule must name the exact command or, for file reads and searches, the exact path.
• Secret words. Values you name as sensitive. Polytoken filters matching search results before you or the model see the sensitive values. When Polytoken detects a shell command that directly exposes an environment variable named in permissions.secret_words, such as printf %s "$SECRET", Polytoken refuses the call without offering approval. The same refusal applies when Polytoken detects a Python, Node, Ruby, or Perl environment reader that names a configured secret word.

Configuring permissions

Your configuration defines these rules, along with your secret files and words. For a guide to writing rules that match shell commands, file paths, and URLs, see Permission Rules. For the full format reference, see the permission configuration reference.