Per-tool permission rules are permissions.deny, ask and allow in any config file, each a tool with an optional pattern; every scope's are kept together rather than replaced, the most specific inside one file and the strictest across files deciding a call; the harness refuses on a deny, asks on an ask whatever auto_approve or an allow for the session says, and runs an allow unasked unless a person must answer, the branch of a saved comment, or managed_permission_rules_only holds it; an untrusted project's allow is held; an organisation enforces rules as a fourth kind, rules, that adds rather than holds¶
Decision 907 · accepted · 2026-10-16 · issue #658 · supersedes 869
Issue #658's last part (slices 1 and 2 were Decisions 887 and 894): per-tool permission rules as configuration, merged across the organisation, user, project and local scopes with the strictest winning, applied by the harness and shown with where each came from.
The shape¶
permissions:
deny: ["shell(git push)", "read_file(secrets/**)"]
ask: ["mcp(github.create_*)"]
allow: ["shell(mix test)", "write_file(lib/**)"]
Three lists of strings, one per action, rather than a list of {tool, pattern, action}
maps or a map of tool to pattern to action. A rule is a tool's name, alone or with a
pattern in brackets: the form Claude Code's settings use, so a rule copied from there reads
the same, and the strict reader says what to write where it does not (Bash(npm test) is
refused with "Troupe's is shell"). Three lists keep each rule one line and fit the schema's
existing types ({:list, :rule} under an object), so the JSON Schema, the generated
reference, --explain and troupe config validate cover them with no new machinery.
A pattern means what the tool's arguments allow (Troupe.Protocol.PermissionRule):
shell: a command prefix, on word boundaries (shell(git push)matchesgit push origin, notgit pushx);git push *the same;git push*the characters.*may only end it, and:*, Claude Code's prefix mark, is refused with what to write.- the file tools (
read_file,write_file,edit_file,list_files,grep,glob,git_read): a path glob against the call'spath(the workspace where none is given), relative to the workspace unless written absolute or from~;*a name,**any directories,?a character, and a path with no wildcard that path and everything under it...is resolved andsession:/read as the workspace first, so neither walks around a rule; on Windows the comparison folds case, as the file system does. mcp:server.toolwith*, or a server alone. It matches a person's client's own servers' tools (client.<server>.<tool>) as well as the workspace's and the pod's (mcp.<server>.<tool>): an organisation'sdeny: [mcp(github.*)]is meant for GitHub however it is reached.- every other tool takes no pattern; one given is refused.
Rules live in Troupe.Protocol, not the core, because the plane checks an organisation's
rules when an administrator sets them and does not depend on the core (Decision 894's
reason for ProviderTypes). Matching is the core's (Troupe.Config.Permissions).
Merging: kept together, not replaced¶
Every other key is RFC 7396-merged, a higher file's value replacing a lower one's.
Rules are not: a project's deny must not erase the user's, and "strictest wins" is
meaningless once one list has replaced another. Troupe.Config.Layers collects each file's
rules with its layer and path into Layers.Result.rules (the organisation's defaults:
as org, its enforced: as enforced, then user, project, local), beside the
merge; Troupe.Config puts those that apply on config.permissions.
Strictest across files; most specific inside one. For a call, each file gives at most
one verdict: of its rules that match, the most specific (a pattern over none, then the
longer pattern counting what it spells out rather than its wildcards), and of two as
specific the stricter. Across files the strictest verdict holds, deny over ask over
allow, whatever the files, and the rule named is the highest file's of that kind
(enforced, org, user, project, local). So deny: [shell] beside allow:
["shell(git status)"] in one file allows git status alone, which is the reason for
specificity inside a file, and no file loosens another's rule: an enforced ask beats a
person's allow. A file is the scope, not the layer: two organisation documents are two
scopes.
A shell line is its commands. Split at &&, ||, ;, |, & and new lines outside
quotes, leading NAME=value assignments dropped: a deny or ask holds when it matches
any command, so ls && git push is refused; an allow covers the line only when it
covers every command. A line that substitutes ($(...), backticks, <(...), a subshell)
is never covered by an allow, since what it runs is not readable in advance, and the
commands inside it are read too, so a deny reaches echo $(git push). This is a reading
of the line, not a sandbox: sh -c, a script or an alias runs what no rule sees, and the
documentation says so. Not chosen: a shell parser, whose last mile (eval, functions,
xargs) is the same gap.
Trust, and the switches¶
- A project's
allow(.troupe/config.yaml,config.local.yaml) applies only in a trusted workspace and never on a pod, as every key that lets something run unasked (Decision 686, the gate-check's first row): a clone must not grant itselfshell. Itsdenyandaskapply everywhere, since narrowing is what any file may do (as Decision 825 holds a workspace agent'sautoand not itsask). The held rule is kept and marked with the same reason a gated key is (ignored: a project's file sets it only in a trusted workspace ...), so--explainshows it. The schema markspermissions.allowtrustedfor the reference; the hold is where rules are read, not the key's gate, which would drop the file'sdenywith it. managed_permission_rules_only, already a switch an organisation enforces ("a session may not allow a tool for itself"), now also holds everyallowrule but the organisation's (org,enforced), with that reason. It is Claude Code'sallowManagedPermissionRulesOnlynarrowed to what loosens: a person's owndenyandaskstill apply.
The harness¶
Troupe.Tools.authorize/4 takes the call's arguments and refuses a call a deny matches,
for every tool, a todo_write or a delegate that runs inside the agent included, with
Result.describe({:denied_by_rule, tool, rule}): "This call to shell was refused by the
rule deny shell(git push), from what your organisation enforces (/etc/troupe/managed.yaml).
It did not run. ...". run_task/4 then combines the rules with what was there:
- the agent definition's
denystill denies (the tool is not the agent's at all); - a rule's
denyrefuses with its sentence; - a rule's
askasks as a must-answer call does (always: true, Decision 823): neitherauto_approvenor an earlierallow_sessionanswers it, so an organisation'sask: [shell(git push)]is not answered by "allow shell for the session" given tols. The request carries the rule (approval_requested'srule) for the clients to show; - a must-answer call still asks whatever an
allowsays; - a rule's
allowruns the call unasked, over the tool's defaultaskand an agent'sask; - with no rule, the call goes as before.
approvals: deny. An allow runs under it, as an agent's auto does: approvals
says what a call that asks does with nobody attached, and an allowed call does not ask.
An ask rule's call is refused there for want of anyone to ask, like every other asking
call. This is how an unattended session is given exactly the commands it may run.
A branch a saved comment started (hold_auto, Decision 844) holds every allow, as
it holds an agent's own auto and a server's permission: auto: any process that writes
a file can write a comment. Troupe.Session.build_opts/1 drops them from that branch's
configuration.
An ask or allow for a tool that runs inside the agent (todo_write, finish,
show) does nothing, since those never ask; the reader warns so, and a name near a
built-in's that is none (shel) warns "did you mean shell?". Both are kept: a host may add
a tool of that name. A rule names no {env:VAR}: rules are written out.
The organisation: a fourth kind, rules¶
Decision 869 allowed three kinds of enforced key, each a limit a value is held to. Rules
are not held to anything: they are added. Troupe.Protocol.Organisation lists
permissions with kind :rules and type :rules, after managed_permission_rules_only;
check/1 checks each rule with PermissionRule.check_set/1 and refuses with the rule's own
sentence; exceeds?/3 is never true for it, so Troupe.Config.Org.hold/2 holds nothing,
and the reader takes the enforced permissions out of the enforced set into the rules,
with the document's path or the plane's URL as their source. That is the part of 869 this
replaces: "only :ceiling, :order and :fixed" is now four kinds. Rules under an
organisation's defaults: are read the same way and hold the same, since no rule can be a
default a person replaces; the two differ in how --explain names them. On a plane,
client_enforced takes them as JSON (admin.setting.put), and the console's enforced-set
editor, which builds its fields from the plane's enforceable list, writes an object-typed
key as JSON text: a few lines in Organisation.tsx, the console's page.
Governs: apps/troupe_protocol/lib/troupe/protocol/permission_rule.ex, apps/troupe_core/lib/troupe/config/permissions.ex, apps/troupe_core/lib/troupe/config/layers.ex, apps/troupe_core/lib/troupe/config.ex, apps/troupe_core/lib/troupe/tools.ex