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 three 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 decides whether to allow it instead. 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.

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

A shell command is not treated 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 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.

Some shell constructs hide from this matching what they will actually run: command substitution with $(...) or <(...), piping into xargs, delegating to another shell with eval or bash -c, and running inline code with python -c. A dynamic directory target such as cd "$WORKTREE" also hides the destination. Your allow rules cannot match a part Polytoken cannot read statically, so that part is never auto-approved by a rule.

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. See the permission configuration reference for the format.