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: send a one-time allow for the current tool call, then switch the session to the selected permission mode. Use Left and Right to cycle through modes. The row stays disabled when it names the mode that already runs, so the selector never focuses an already-active mode.

Permission modes

Polytoken has four permission modes. Switch between them with the /permissions command.

• 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 is unsure, or after repeated refusals, the decision comes back to you. 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 checking. Nothing is gated; use it 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 lets a tool change the path. File-editing tools usually need both read and write permission because they inspect existing content before changing it. Durable filesystem rules store those capabilities explicitly, such 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 /.

Write approval covers creates and overwrites for that path. Existing-file edits, deletes, and patch updates usually need both read and write approval. Creating a file can also create the missing parent directories needed for that file.

Most file tools ask about one path at a time. Some models edit files by sending a patch that can touch several paths. Polytoken parses the patch before it runs and asks for the filesystem approvals the patch needs before applying it. Updating or deleting a file requires both read and write, usually stored as access: [read, write].

How shell commands are checked

Polytoken does not treat a shell command as a single action. Polytoken reads the command, breaks it into the individual programs it would run, and weighs each one against your rules by the program, its subcommand, and its flags. 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 is allowed by default. Changing directory outside the project asks for approval unless a filesystem rule grants chdir there.

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. An allow with no command conditions qualifies if it matches the tool by name or matches every tool. An allow whose only conditions exclude particular flags also qualifies, 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. An allow rule that approves only commands with particular details, such as specific text, command words, an executable, a subcommand, or required flags, does not qualify even when its conditions would match every command. Polytoken cannot check those details against a command it cannot inspect. 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.

Invoking a shell interpreter directly is always opaque. Commands like bash script.sh, sh -c 'echo hi', zsh --norc, or even bare bash can execute arbitrary code, so a rule whose conditions require particular command details cannot approve these commands. A whole-tool allow can approve them. When Polytoken holds one of these commands for approval, 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.

Dynamic directory changes are stricter: cd "$WORKTREE" and relative cd calls after an earlier cd go directly to a human prompt because the destination path is the capability being granted.

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 one, Polytoken holds the call for your approval. A search runs without a prompt, and Polytoken filters any results that would surface one. Each hold stays in place unless an allow rule names that exact command or, for file reads and searches, that exact path. A broad allow rule does not lift the secret-file guard; only an exact one does.
• Secret words. Values you name as sensitive. When a search would surface them, Polytoken filters them from the result before you or the model see them.

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.