Approval gates, intervention commands, and transparency requirements. Use to classify any agent action as autonomous/notify/approve, respond to override/pause/stop commands, or structure a plan review before the implementation phase begins.
Approval gates, intervention commands, and transparency requirements. Use to classify any agent action as autonomous/notify/approve, respond to override/pause/stop commands, or structure a plan review before the implementation phase begins.
role
orchestrator
user-invocable
true
Human Oversight Protocol
Constraints
Approval gates cannot be skipped; do not proceed past a gate without explicit human sign-off.
Ethical concerns are never auto-resolved; always escalate.
Intervention commands (override, pause, stop) take immediate effect with no debate.
Overrides accumulate; 3+ overrides on the same topic must trigger a config amend.
Plan Review as Primary Quality Gate
The implementation plan is the primary review artifact, not the code. Traditional line-by-line code review is replaced by plan review for AI-generated work — 200 lines of plan is far more reviewable than 2,000 lines of generated code, and if the plan is correct and tests pass, the code is trustworthy.
Plan review checklist
Does the research accurately describe how the system works? (File paths, data flows, dependencies)
Does the plan address the right problem?
Are the specified changes complete — no missing files or edge cases?
Is the test strategy sufficient to verify correctness?
When the plan was ambiguous about implementation details
Approval Gates
Gate classification
Every agent action falls into one of three categories:
Category
Description
Human involvement
Autonomous
Routine work within agent's defined scope
None — deliver output directly
Notify
Significant but within scope; human should be aware
Deliver output + flag what was decided and why
Approve
Outside routine scope or high-impact; human must sign off
Present proposal, wait for explicit approval
Standard approval gates
These actions always require human approval. Every gate below writes an
approval entry to .claude/metrics/config-changelog.jsonl per the Audit trail
schema — proposed, evidence_shown, and risks_surfaced included.
Action
Rationale
Research findings (Phase 1 → 2)
Misunderstanding cascades into bad plans and bad code
Implementation plan (Phase 2 → 3)
Plan correctness determines code correctness
Production deployment
Irreversible, affects users
Architecture change
High-impact, hard to reverse
Database schema migration
Data integrity risk
Security-sensitive code
Vulnerability risk
Scope change
May affect timeline/budget
Add a new external dependency (a package not already in the project)
Supply chain risk — a genuinely new package. A reversible minor/patch version bump of an existing dependency is Medium (decide-and-proceed), not this gate — see Escalation Paths.
Delete files or data
Potentially irreversible
Team structure change
Affects all agents
Agent-specific gates
Each agent defines additional gates in its ## Behavioral Guidelines > Decision Making section. The Orchestrator consolidates these when coordinating multi-agent tasks.
Intervention Mechanisms
1. Feedback (real-time correction)
amend: [modify existing behavior]
learn: [teach something new]
remember: [persist a preference]
forget: [remove a preference]
override: [what was decided] → [what should be done instead]
Stops the current approach; agent adopts the human's decision without debate
Logged as override in the audit trail — proposed records the rejected proposal, description records the substituted decision, evidence_shown/risks_surfaced required
3+ overrides on the same topic should trigger a config amend
3. Pause (temporary halt)
pause
Agent stops and presents current state
Human reviews and either resumes or redirects
No output is discarded
4. Stop (emergency halt)
stop
All agents halt immediately
Current output preserved but not delivered
Orchestrator presents a summary of what was in progress
Decision: [what was decided]
Rationale: [why]
Alternatives considered: [what else was evaluated]
Audit trail
Canonical schema. This section is the single canonical definition of the
gate-decision audit entry — Governance & Compliance
and Feedback & Learning reference it rather than
restating the field definitions.
All oversight events are appended to .claude/metrics/config-changelog.jsonl (one
JSON object per line, append-only — existing entries are never modified, deleted,
or migrated) with:
Field
Required for
Type
Rule
type
all
string
approval | override | pause | stop
trigger
all
string
user
description
all
string
What happened and why. For override, this is the human's substituted decision (see below)
proposed
approval, override — optional for pause/stop
string
One-line statement of what was put before the human — or, for override, what the agent had decided before the human reversed it
evidence_shown
approval, override — optional for pause/stop
array of strings
Artifact pointers only, never prose. Each element is a repo-relative file path (e.g. plans/<slug>.md), commit:<sha>, issue:#N / pr:#N, or .claude/metrics/<file>.jsonl@<line-or-timestamp>. Every pointer must resolve to something that still exists after the session ends — never a chat transcript or ephemeral build/console output. If the evidence exists only as prose, write it to .claude/memory/ first and point at that file.
risks_surfaced
approval, override — optional for pause/stop
array of strings
Risks stated at the gate. [] is valid and explicit — it means "no risks were surfaced," distinguishing a reviewed-and-clear gate from a pre-change entry that omits the field entirely.
Required for approval and override. Optional for pause/stop — those
record an interruption of state, not a decision over a proposal, so there is
often nothing "proposed" or "shown" to record.
For override entries: proposed records the rejected proposal — what the
agent had decided; description records the human's substituted decision,
matching the existing override: [what was decided] → [what should be done instead] grammar. Both fields must be reconstructable from the entry alone.
Non-interactive gates write identically. When a gate auto-proceeds (--yes,
DEV_TEAM_AUTO_APPROVE=1, or no TTY — see /plan and /build), the entry
carries the same three fields; only description/trigger reflect the bypass
(e.g. "description": "Auto-approved (non-interactive) — no human gate").
Unattended approvals are exactly where after-the-fact audit matters most.
Backward compatible, never migrated. Entries written before this schema
existed have no proposed / evidence_shown / risks_surfaced fields and
remain valid — the changelog is append-only. Every consumer (feedback-learning's
rollback lookup, governance-compliance's compliance queries and periodic
checklist) must tolerate both shapes: an absent field means "written before
this schema," not "malformed."
Example — phase-gate approval:
{"timestamp":"2026-07-05T18:02:11Z","type":"approval","trigger":"user","description":"Plan approved for issue #867 (gate-decision audit fields)","proposed":"Implement the gate-decision schema extension per plans/issue-867-gate-decision-audit.md","evidence_shown":["plans/issue-867-gate-decision-audit.md","issue:#867"],"risks_surfaced":[]}
Example — override:
{"timestamp":"2026-07-05T18:10:44Z","type":"override","trigger":"user","description":"override: run the migration script → apply the schema change by hand-editing the two SKILL.md files","proposed":"Agent proposed running scripts/migrate_schema.py to apply the change","evidence_shown":[".claude/memory/build-issue-867.md"],"risks_surfaced":["Hand-editing risks missing a write site the script would have covered"]}
Output
Gate classification (autonomous / notify / approve) with rationale, or escalation summary with severity and recommended action. One decision per output; no restating of protocol rules.
Escalation Paths
Agent → Orchestrator → Human
Agent identifies the issue and flags it to the Orchestrator.
Absorb the uncertainty before escalating it. Investigate within the codebase, run the relevant check, or dispatch the agent best placed to resolve it. Escalate only what investigation cannot settle — a raw unknown is not yet an escalation.
Orchestrator classifies severity:
Low: route to another agent with appropriate expertise; do not involve the human.
Medium — reversible, low-blast-radius, and not one of the Standard approval gates above: decide and proceed. Commit to one path, state the rationale, act, and surface an explicit override — e.g. "Taking X because Y; reply override to change course." Do not hand the human a menu for a decision the agent can own and reverse. A reversible minor/patch version bump of an existing dependency (e.g. to pull a bug fix) is Medium: absorb the uncertainty first (read the changelog delta, run the suite against the bump), then decide and proceed with an override affordance — do not escalate it as a no-recommendation menu. It is distinct from adding a new package, which is the Standard gate below. (The Standard approval gates — adding a new external dependency, schema migration, scope change, deletes, etc. — are never downgraded to Medium; they remain Approve. A major-version bump, or one that pulls a genuinely new transitive package, leans Approve too.)
High — irreversible or high-blast-radius: present to the human with full context, no recommendation (avoid anchoring), and wait. Reserved for genuinely human-only calls: the standard approval gates, ethical concerns, and anything hard to reverse.
Human decides at the High tier (or when a committed Medium decision is overridden).
The decision — or the committed Medium path plus any override — is logged and fed back to the requesting agent.
