6.6 KiB
name, description, depth, links
| name | description | depth | links | |||
|---|---|---|---|---|---|---|
| Core Approvals Submodule Spec | Specification for :core:approvals – tiered approval system | 2 |
|
:core:approvals module specification
version: 0.1-draft status: foundational specification
1. purpose
:core:approvals defines the risk-aware approval system that decides whether operations beyond pre‑configured thresholds may proceed.
It is the authoritative subsystem for:
- approval tier semantics
- approval mode enforcement
- approval request/decision lifecycle
- escalation rules
- steering injection
- approval history (immutable audit trail)
Approvals are the primary human‑in‑the‑loop safety mechanism. They are not a simple pop‑up; they gate execution by checking tiers and policies, and they record every decision.
2. responsibilities
:core:approvals owns:
- approval tier definitions (T0–T4)
- approval mode configurations (prompt, auto, deny, yolo)
- approval event contracts
- escalation rules
- session‑scope approval grants
- steering‑aware approval injection
- approval part of validation pipeline integration
- immutable approval ledger
3. non-responsibilities
:core:approvals MUST NOT own:
- the validation pipeline itself (that's
:core:validation) - artifact generation
- transition execution
- policy enforcement (policies may be evaluated, but the engine is separate)
- UI rendering of approval prompts
- persistence implementations
4. architectural role
:core:approvals acts as:
- human/system checkpoint authority
- risk boundary for mutable operations
- audit trail for sensitive decisions
All tool or stage escalation that exceeds the configured auto‑approved tier passes through this subsystem.
5. design principles
5.1 tiers enforce risk boundaries
Every tool and operation has a declared tier. By default, only T0 and T1 may be auto‑approved. Higher tiers require explicit human approval unless the session is in an elevated mode.
5.2 approvals are immutable
An approval decision, once recorded, cannot be changed. Corrections require a new decision that supersedes the previous one within the audit log.
5.3 steering is first‑class
Approval decisions may include steering instructions: natural language suggestions injected into the next context pack. This bridges human guidance into the execution loop without breaking replay.
5.4 replay-safe
Approval events are replayed deterministically. In replay, approval decisions are re‑applied from history, not re‑requested from the user.
6. tier model
T0 – inference only (read model outputs)
T1 – read‑only tool access
T2 – reversible mutation (e.g., git commit, file create)
T3 – external/network access
T4 – destructive (e.g., rm -rf, database drop)
Each tool, stage, or even artifact category may declare a tier requirement.
7. approval modes
Mode can be changed per session or per approval gate.
- prompt – always ask user
- auto – approve automatically if tier ≤ configured threshold
- deny – automatically reject
- yolo – bypass all checks (logging only); for sandboxed experimentation
8. approval request lifecycle
- An artifact or tool invocation triggers an
ApprovalRequiredevent from the validation pipeline. :core:approvalsevaluates:- tier vs. current session mode
- any explicit denials
- session‑scoped grants (e.g., “auto‑approve all T2 for this session”)
- If decision can be made automatically, emit
ApprovalGranted/Automatic. - If human input needed, pause orchestration and emit
ApprovalPending. - User supplies decision (approve/reject/steer). Decision is recorded, orchestration resumes.
9. steering injection
When user approves with a steering message, the approval event carries that text. The context processor later picks it up and injects it as additional instruction for the next stage, with proper delimiting (e.g., “User guidance: …”).
10. event ownership
:core:approvals owns:
ApprovalRequiredApprovalPendingApprovalGranted/ApprovalGrantedAutoApprovalRejectedApprovalEscalatedApprovalSessionGrantAddedApprovalModeChanged
All carry causation back to the originating artifact or tool event.
11. consumed events
Consumes:
ArtifactValidated(when approval layer decides escalation)ToolAboutToExecute(for tool-level approvals)UserInput(approval decision)
12. invariants
- Approval history is append-only.
- No operation above its tier may execute without a matching
ApprovalGrantedevent. - Session grants are ephemeral and must be replay‑reconstructed from events.
- Steering text is preserved verbatim.
13. replay semantics
During replay, :core:approvals replays decisions from the event log. No user interaction occurs. If a decision is missing (e.g., corrupted log), replay fails explicitly.
14. threading/concurrency
Approval handling is sequential within a session. The orchestration coroutine suspends until a decision is available. Timeout mechanisms exist for approval expiration.
15. failure semantics
If an approval request times out or the user refuses, the corresponding artifact or tool execution is rejected, and a failure event is emitted. The session may transition to a recovery or failed state according to transition rules.
16. observable requirements
Must expose:
- approval request frequency
- approval response latency
- rejection rates per tier
- active session grants
17. security boundaries
Approvals are a trust boundary. Untrusted plugins cannot circumvent approval checks. The approval engine runs inside core with no external dependencies.
18. extension model
Plugins cannot alter tier definitions but may add custom escalation logic or additional constraints (e.g., “never approve network access after 10pm”).
19. forbidden patterns
- silent escalation without event
- mutable approval records
- approval decisions that bypass tier checks
- replay that re‑prompts the user
- granting broad permissions without session scope
20. testing requirements
- tier enforcement across modes
- auto‑approve/deny logic
- steering injection hygiene
- replay of approval sequences
- timeout and cancellation behavior
21. philosophy
Approvals translate bounded autonomy into practice. They are the harness’s way of saying “you may go this far without me, but not further”, with a clear audit trail and the ability to inject human judgment exactly where it’s needed.