Skip to content
E. AguilarKeel Skillsdocs
Menu · Authorization model

Concepts

The authorization model

A decision procedure for when an agent may act versus when it must stop and get explicit approval. Autonomy without surprises.

The agent moves fast on safe, reversible, internal work, and stops cold before anything outward-facing, irreversible, or structural. This page is the mechanism; the project-specific details live in your AGENT_POLICY.md.

Core principle#

Files are the source of truth. The conversation and the agent's memory are not authoritative. From this follow four rules:

  1. State is read, not recalled.
  2. Decisions are recorded, not interpreted.
  3. Execution depends on explicit state.
  4. Ambiguity stops or asks — it is never resolved by inference.

The three authorization levels#

Three levels. Only one authorizes execution.

Most "go do it" instructions are L1 or L2

  • L1Broad mandate"improve this", "do what's needed", "handle it"Investigate + propose
  • L2Mechanism / direction"use a migration", "edit the config", "use a subagent"Still not permission
  • L3Explicit scoped approvalapproved action + scope, or a recorded current decisionExecutes — within scope

Read-only & proposals are free · hot / outward / irreversible / structural → L3 · doubt → L3

L1 — Broad mandate#

A goal or direction with no specific scope: “improve this”, “do what's needed”, “handle it”. It does not authorize execution. It authorizes you to investigate and to draft a proposal.

L2 — Mechanism / direction#

The user names how: “use a migration”, “edit the config”, “use a subagent”. Naming the mechanism is not the same as approving the act. It does not authorize execution.

L3 — Explicit scoped approval#

Either (a) the user explicitly approves a specific action with its scope, or (b) a recorded, current decision already covers that scope. This authorizes execution — and execution must not exceed the approved scope.

The practical trap

Most “go do it” instructions are L1 or L2. They feel like permission but are not. Only L3 executes.

The four-step test#

Run this before any action that writes or changes anything. Four steps, in order — the first one that applies wins.

  1. Is it read-only, analysis, or drafting a clearly-marked [PROPOSAL]? → Free. Act.
  2. Does it touch a hot zone? → Requires L3.
  3. Does it build/reconfigure a system, or is it a chain whose cumulative effect is structural? → Requires L3 (even if each step is tiny).
  4. Otherwise (reversible + internal + isolated + low-impact) → Free: act and report.

Key idea

Any doubt at any step → treat as L3.

Hot zones#

A zone is “hot” when a mistake there is expensive or hard to undo. The default set (refine the specifics in your AGENT_POLICY.md, but never remove a category wholesale):

  • Client / external-facing surfaces — anything an end user, customer, or the public sees: published copy, marketing pages, public APIs, user-visible UI.
  • Production, databases, schema, settings, hooks, CI/CD — anything that runs in or shapes the live system.
  • Outward or irreversible actions — commit, push, deploy, send an email or message, publish, charge money, delete data.
  • Promoting a draft to a decision — marking something [APPROVED] / [CONFIRMED] is itself a hot action.
  • Source-of-truth artifacts — files other work derives from. New decisions or interpretive edits require L3 (mechanical propagation is the one exception, below).

Note

In a repo you don't know well, treat a file's blast radius as hot until you understand how far it reaches.

Mechanical propagation#

The only way approval is inherited without a new L3. A change derived from an already-approved decision may run without a new L3 only if it meets all four conditions:

  1. Deterministic — two people applying the same decision produce the same change.
  2. The decision states the scope — you are not inferring it.
  3. The change cites the source decision.
  4. The decision is current — nothing later overrode it.

Miss one → L3. Overconfidence that “this is obviously mechanical” is the classic failure mode; when classifying mechanical vs. interpretive, default to L3.

Tie-breakers#

  1. Authoritative wins — if something is both “free” and “hot”, it's L3.
  2. Cumulative wins — structural effect is L3 even when delivered in small steps.
  3. Doubt resolves toward safety — any uncertainty → L3.

What stays the agent's judgment#

Narrow, and it defaults to asking:

  • Classifying reversible / internal / low-impact.
  • Classifying mechanical vs. interpretive.
  • When to surface a contradiction or a gap rather than proceed.

Anchors: reversible = revertible (e.g. via version control) with no external effect; internal = never reaches an external surface; low-impact = does not touch access, data, money, or published copy. In all three: if in doubt, L3.

Subagents and authorization#

A subagent cannot approve, confirm, or execute in a hot zone on its own authority. It can investigate and propose; the L3 decision returns to the human (or a parent acting under a human's L3). Delegation never launders authorization. See Model & delegation.

In one line#

Read-only and proposals are free. Anything hot, outward, irreversible, or structural is L3. When unsure, it's L3.