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.

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.
• 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. 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. 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). A dynamic directory target such as cd "$WORKTREE" also hides the destination. Because approving one of these grants access to whatever the interpreter runs, Polytoken sends these to you every time. You cannot save a reusable rule for them.

Invoking a shell interpreter directly is always opaque. Commands like bash script.sh, sh -c 'echo hi', zsh --norc, or even bare bash cannot be saved as a reusable permission rule because a shell interpreter can execute arbitrary code. The permission prompt for these commands shows only a one-time allow or deny.

In Autonomous mode, most opaque shell commands still go to the classifier. The classifier reads the full command text and judges it on that, so a command it can read and clear runs without stopping you, even when a rule could not match 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 regardless of mode:

• Secret files. Files you name as sensitive, such as .env. Polytoken holds any command that reads one of them for your approval, unless you have allowed that exact command. A broad allow rule does not lift the secret-file guard; only a rule that names the exact command 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.