Permissions and Approval: a Three-State Rule Set, Matching by Tool and Path, and the Boundaries of Auto Mode

Three states, not two: ask is where "it depends" lives

First, why there must be three states.

A system with only allow and deny forces every "it depends" operation into one side. Put them in allow and they never reach a human; put them in deny and the user finds the Agent cannot do real work, so the first thing they do is loosen the rules — quite possibly all the way.

The third state, ask, gives "context decides" a place to live. Should editing a file under src be allowed? It depends which file, into what, and what task is underway. A rule table cannot answer that; a human answers it at a glance.

Each state's semantics must be spelled out, especially the third:

The difference between deny and ask is not only strictness but whether to disturb the human. You do not want the Agent editing test files, and you also do not want it asking every time — that shifts the judgment cost onto you. Deny's correct semantics are "this road is closed, find another."

And one rule finally pays off today: read-only tools pass by default. That is the point of the read-only flag added to tool definitions on day three — the gate need not know any specific tool, only ask "will you change something?"

What to match: tool name, path pattern, command prefix, and who wins

Rules must express three kinds of condition: tool name (edit_file), path pattern (test/**) and command prefix (node --test*). Writing that is easy; the hard part is who wins when several match.

The obvious approach is by order, first match wins. Do not. It turns the rule table's order into implicit semantics: you append a more specific rule at the end and some broad rule above eats it, and the error is "nothing happened" — an especially painful class of problem to diagnose when rules come from several places (the default table, user configuration, this session's temporary approvals).

This course has one rule: the more specific rule wins; at equal specificity, the stricter wins.

/** More conditions and fewer wildcards mean more specific */
function specificity(rule: Rule): number {
  let score = 0
  if (rule.tool && rule.tool !== '*') score += 2
  if (rule.path) score += rule.path.includes('*') ? 2 : 3
  if (rule.command) score += rule.command.includes('*') ? 2 : 3
  return score
}
 
const STRICTNESS: Record<Decision, number> = { deny: 3, ask: 2, allow: 1 }
 
export function decide(tool: ToolDef, subject: Subject, state: PermissionState): Verdict {
  if (tool.readOnly) return { decision: 'allow', reason: 'read-only tools pass by default' }
 
  const hits = state.rules.filter((rule) => matches(rule, subject))
  // With no rule matched, a write defaults to ask, never to allow
  if (hits.length === 0) {
    return { decision: 'ask', reason: 'no rule matched; writes need confirmation by default' }
  }
 
  const winner = hits.reduce((best, rule) => {
    const bySpec = specificity(rule) - specificity(best)
    if (bySpec !== 0) return bySpec > 0 ? rule : best
    return STRICTNESS[rule.decision] > STRICTNESS[best.decision] ? rule : best
  })
  return { decision: winner.decision, reason: winner.why ?? 'matched a rule', rule: winner }
}

STRICTNESS = {"deny": 3, "ask": 2, "allow": 1}
 
 
def specificity(rule: Rule) -> int:
    """More conditions and fewer wildcards mean more specific"""
    score = 0
    if rule.tool and rule.tool != "*":
        score += 2
    if rule.path:
        score += 2 if "*" in rule.path else 3
    if rule.command:
        score += 2 if "*" in rule.command else 3
    return score
 
 
def decide(tool: ToolDef, subject: Subject, state: PermissionState) -> Verdict:
    if tool.read_only:
        return Verdict("allow", "read-only tools pass by default")
 
    hits = [rule for rule in state.rules if matches(rule, subject)]
    # With no rule matched, a write defaults to ask, never to allow
    if not hits:
        return Verdict("ask", "no rule matched; writes need confirmation by default")
 
    # The sort key is the rule itself: specificity first, then strictness
    winner = max(hits, key=lambda r: (specificity(r), STRICTNESS[r.decision]))
    return Verdict(winner.decision, winner.why or "matched a rule", winner)

Both versions do the same thing, and the Python one states the rule more directly: the sort key is the priority definition. Expressing policy as one comparable key is far more maintainable than a chain of ifs — adding a condition class just adds one component to the key.

One easily missed detail: with no rule matched, a write's default verdict must be ask. A gate that allows by default is no gate, and that mistake only surfaces on the day something goes wrong. The starter's default implementation gets this wrong (defaulting to allow), and three self-test items fail.

Here is what the course's default rule table looks like, a decent example rather than an industry standard:

run_command command=node --test*  -> allow   running tests is a read-only verification
run_command command=git status*   -> allow
edit_file   path=test/**          -> deny    tests are the acceptance criterion; do not edit them green
edit_file   path=**/*lock*        -> deny    lock files should be generated by the package manager
other writes: ask by default | read-only tools: allow by default

That "do not edit tests" rule deserves a sentence: models really do tend to edit tests until they pass, because that is the shortest path to the goal "all tests green." That is not bad character; you wrote the goal as "make the tests pass" rather than "make the code correct." The rule table closes that shortcut for you.

Approval is a pause inside the loop, not an exception

Now today's most important design decision. The gate sits before tool execution and has exactly two outcomes:

• Pass: the loop executes the tool as usual.
• Not pass: return a tool result explaining why it did not run.

The second is the key. A refused call looks exactly like a failed tool execution in the message array: an assistant message carrying the requested call, and a tool message carrying the reason for failure. So the model reroutes as it would after any failure — you need invent no new message type for approval, and need not touch yesterday's working loop.

/** null means pass; returning a result means "this call does not execute" */
export async function passGate(
  call: ToolCall,
  tool: ToolDef,
  options: GateOptions
): Promise<ToolResult | null> {
  const subject = subjectOf(tool.name, call.args)
  const verdict = decide(tool, subject, options.state)
 
  if (verdict.decision === 'allow') return null
  if (verdict.decision === 'deny') return denied(tool, verdict.reason)
 
  // With no channel to ask (CI, a pipe, another Agent's shell), treat it as refused.
  // A gate that auto-approves in an unattended environment is no gate.
  if (!options.approve) return denied(tool, 'confirmation is required, but this environment cannot ask')
 
  // This await is the pause inside the loop: the model waits, the tool has not run, nothing happened
  const answer = await options.approve({ call, tool, subject, verdict })
  if (!answer.approved) return denied(tool, answer.note ?? 'the user refused this operation')
 
  remember(subject, answer.scope, options)
  return null
}

async def pass_gate(call: ToolCall, tool: ToolDef, options: GateOptions) -> ToolResult | None:
    """None means pass; returning a result means "this call does not execute" """
    subject = subject_of(tool.name, call.args)
    verdict = decide(tool, subject, options.state)
 
    if verdict.decision == "allow":
        return None
    if verdict.decision == "deny":
        return denied(tool, verdict.reason)
 
    # With no channel to ask (CI, a pipe, another Agent's shell), treat it as refused
    if options.approve is None:
        return denied(tool, "confirmation is required, but this environment cannot ask")
 
    # This await is the pause inside the loop: the model waits, the tool has not run
    answer = await options.approve(ApprovalRequest(call, tool, subject, verdict))
    if not answer.approved:
        return denied(tool, answer.note or "the user refused this operation")
 
    remember(subject, answer.scope, options)
    return None

Consider the cost of implementing refusal as a thrown exception: you catch it outside the loop, decide whether the turn continues, and still add a tool result message (or the next request is invalid, since every call needs a matching result). All the complexity piles onto the error path, which is the hardest place to test. The loop's change today is five lines precisely because the gate was designed to return a result.

Two more disciplines in the implementation:

• An unrecognizable answer counts as refusal. A bare newline, an "okay," or input simply ending must not count as consent.
• The approval prompt must say why you are being asked. The user cannot see the rule table; the two lines on their terminal are their entire basis for judgment. The lab's prompt reads:

Confirmation needed: edit_file src/calc.js
Reason: no rule matched; writes need confirmation by default
Allow? y this once / a this whole session / w write it into the config / n no

After a refusal: feed the reason back as a result and the model reroutes itself

The wording of a refusal decides what the model does next. This is the same principle as day four's "a failure message is the model's next action," but more visible here.

Write "permission denied" and the model retries the same call in place (it assumes a transient failure). Write "tests are the acceptance criterion; do not edit them green, change the code under test" and it takes another route. The lab shows this directly — the offline script deliberately takes the shortcut first:

The quickest way is to change that test case.
> edit_file({"path":"test/calc.test.js","old_string":"test('divide by zero should throw', ()...)
x edit_file fed back 115 chars - this edit_file call did not run: tests are the acceptance criterion and must not be edited green. Change the code under test.
I cannot change the tests, so I will change the code - adding a divide-by-zero guard.
> edit_file({"path":"src/calc.js","old_string":"export function divide(a, b) {\n  return a /...)
Confirmation needed: edit_file src/calc.js
Reason: no rule matched; writes need confirmation by default

Of five tool calls, one was stopped by deny, one paused to ask, and three passed straight through. That is what this gate should look like: the things worth asking got asked, and nothing else disturbed anyone.

A general suggestion on wording: a refusal has three parts — what was refused, why, and which route is available instead. The third is the most often omitted and the most useful.

Remembering the choice: this turn, this session, or persistently

By the fifth time the same operation is queried, the user is pressing yes without thinking. So remembering is a necessary feature of the gate, not a nicety. The three scopes have distinct semantics:

They differ in where they are recorded: this turn goes into a one-shot set cleared at the start of each turn; this session appends an allow rule to the rule table; persistent appends and also writes to disk. Once persisted, it participates in matching alongside the default table under the same "more specific wins" rule, needing no extra logic.

The clearing moment for "this turn" is worth noting: it follows a user task, not the session. When a user says "this once," they mean the thing they just asked for, not the rest of this terminal's life. So clearing happens at the start of each run.

Which configuration file to write to and how layered configuration merges is day twenty-one's packaging subject; today only demonstrates the semantics of remembering.

The three preconditions for auto mode

Finally, the unavoidable question: can we just make it fully automatic?

Yes, conditionally. Turning full auto on is responsible if and only if all three of the following hold, and with any one missing it should stay off:

1. A sandbox. What it can touch is bounded: a temporary directory or a container, a limited file scope, no network access it should not have. The test is "in the worst case, you can accept what it can damage."
2. Rollback. You can undo with one action after a mistake. The test is not "we have git" but "uncommitted changes are protected too" — which is why day fourteen's snapshots and rollback are auto mode's real precondition.
3. Observability. There is a complete record of what it did, reviewable line by line afterwards. Day seven's event log is this one.

Taken together, they yield a perhaps counterintuitive conclusion: auto mode is not a switch but the result of a whole stack of infrastructure. Turning off the approval gate without the first two is not auto mode, it is unsupervised.

And yesterday's command blacklist now has a clearer place: it is the last line against slips, not an isolation mechanism. Real isolation is the first precondition.

Source Reading

Hands-On Lab

Today changes none of the six tools; everything changes in the step just before tool execution. The starter leaves four exercises, two of which (the default verdict, and what to do with no channel to ask) are the "wrong code raises no error and surfaces only on the bad day" kind. Unmodified it passes three of nine.

1. Implement the rule table and matcher supporting tool name, path pattern and command prefix, with priority by "more specific wins, stricter wins at equal specificity."
2. Insert the gate into the tool execution path: read-only tools pass, write and command tools stop and ask; confirm that with no channel to ask the result is refusal.
3. Implement the three memory scopes and add the "why you are being asked" line to the approval prompt.
4. Turn refused calls into fed-back tool results, and watch the model reroute to the code under test after being stopped from editing the tests.
5. Run the self-test: MOCK=1 SELFTEST=1 pnpm start should print 9/9 passed, with the call sequence and the number of questions both reproducible.

Acceptance is five ticks: the self-test prints 9/9 passed; read-only tools never trigger approval; editing tests is stopped by deny and the model reroutes; answering y applies the change while answering n leaves the file byte-identical; and all three memory scopes visibly work (asked once this turn, never again this session, and the persistent one written to a file).

Interview Questions

Today's three questions test permission-model design judgment, not recited security knowledge:

1. Designing an Agent's permission model, which states do you need? What do rules match on?
2. When a user refuses a tool call, how should the loop continue? Why not simply throw?
3. Under what circumstances may an Agent run in fully automatic mode? Which preconditions would you require?

Full bilingual prompts, analyses and key points are in this course's day-five question bank. Question two discriminates most — it appears to ask about exception handling and actually asks whether you have thought about what a refused call looks like inside the message array.

Checklist and Tomorrow

• I can state each of the three verdicts' semantics, especially that deny versus ask is not only about strictness
• I can explain why rule priority follows specificity rather than order
• I know an unmatched write must default to ask, and what to do with no channel to ask
• I can say what "approval is a pause, not an exception" saves in the implementation
• I know where each memory scope is recorded, and what the clearing of "this turn" follows
• I can name auto mode's three preconditions and which day of the course each corresponds to

Tomorrow is D6, "Error Handling and Self-Correction: Feeding Failures Back, Backoff Retries, Loop Detection and Cancellation." Over five days we have met several failure classes piecemeal: a stream cut mid-way, arguments that are not valid JSON, an original that does not match, a hung command, a refusal by the user. Tomorrow puts them together into one taxonomy with a single criterion: feed back the errors the model can fix, and raise only the rest to the user. It also settles two debts from today — backoff retries with jitter, and the full cancellation chain from keypress all the way to the child process.