Skip to content
E. AguilarKeel Skillsdocs
Menu · Permission model

Concepts

The permission model

A way to decide when an agent may act versus when it must stop and get a clear yes. Speed without surprises.

The agent moves fast on safe, undoable, internal work, and stops cold before anything outward-facing, hard to undo, or system-rebuilding. This page is the how-to-decide; 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. From this follow four rules:

  1. State is read, not remembered.
  2. Decisions are written down, not guessed at.
  3. Acting depends on what the files actually say.
  4. When something is unclear, stop and ask — never fill the gap by guessing.

What looks like permission — and what is#

Three things get confused with “yes, go ahead.” Only one of them is.

Three things look like permission. Only one means go.

Most "go do it" instructions are just a goal or a method

  • GoalA goal"improve this", "do what's needed", "handle it"Investigate + propose
  • MethodA method"use a migration", "edit the config", "use a subagent"Still not permission
  • Green lightA green lighta clear yes to this exact action, or a recorded current decisionActs — within scope

Read-only & proposals are free · risky / outward / undoable / system-rebuilding → ask · doubt → ask

A goal#

A direction with no specific scope: “improve this”, “do what's needed”, “handle it”. This is not a green light. It's permission to look into it and come back with a plan.

A method#

The user says how: “use a migration”, “edit the config”, “use a subagent”. Naming the method is not the same as approving the action. Still not a green light.

A green light#

Either (a) the user clearly approves a specific action with its scope, or (b) a written-down, still-current decision already covers it. This is the only thing that means go — and you must not go beyond what was approved.

The practical trap

Most “go do it” instructions are just a goal or a method. They feel like permission but aren't. Only a green light means go.

The four-step check#

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, looking into something, or drafting a clearly-labeled [PROPOSAL]? → Free. Do it.
  2. Does it touch a hot zone? → Needs a green light.
  3. Does it build/reconfigure a system, or is it a chain whose combined effect rebuilds something? → Needs a green light (even if each step is tiny).
  4. Otherwise (undoable + internal + isolated + low-impact) → Free: do it and report.

Key idea

Any doubt at any step → treat it as needing a green light.

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):

  • Anything users or the public see — 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.
  • Actions that reach outside or can't be undone — commit, push, deploy, send an email or message, publish, charge money, delete data.
  • Turning a draft into a decision — marking something [APPROVED] / [CONFIRMED] is itself a risky action.
  • Source-of-truth files — files other work depends on. New decisions or meaning-changing edits need a green light (following through is the one exception, below).

Note

In a repo you don't know well, treat a file's reach as risky until you understand how far it goes.

Following through on a green light#

The only way a green light carries over to a new change without asking again. A change that comes straight out of an already-approved decision may run without a new green light only if it meets all four conditions:

  1. No judgment needed — two people applying the same decision produce the same change.
  2. The decision states the scope — you're not guessing it.
  3. The change points back to the source decision.
  4. The decision is still current — nothing later overrode it.

Miss one → ask for a green light. Being too sure that “this is obviously just following through” is the classic failure mode; when deciding following through vs. a new call, default to asking.

Tie-breakers#

  1. Risk wins — if something is both “free” and “hot”, it needs a green light.
  2. The whole picture wins — a system-rebuilding effect needs a green light even when delivered in small steps.
  3. Doubt means stop — any uncertainty → ask.

What stays the agent's call#

Narrow, and it defaults to asking:

  • Judging undoable / internal / low-impact.
  • Judging just following through vs. a new call.
  • When to surface a contradiction or a gap rather than push ahead.

Anchors: undoable = can be reversed (e.g. via version control) with no outside effect; internal = never reaches anyone outside; low-impact = doesn't touch access, data, money, or published copy. In all three: if in doubt, ask.

Subagents and permission#

A subagent cannot approve, confirm, or do anything risky in a hot zone on its own say-so. It can look into things and propose; the green light returns to the human (or a parent acting under a human's green light). Delegation never creates permission out of thin air. See Model & delegation.

In one line#

Read-only and proposals are free. Anything risky, outward, undoable-only-with-pain, or system-rebuilding needs a green light. When unsure, ask.