feat(protocol): observable external actions with declared guarantee levels

[FScigliano93]

Summary

Define a tool-independent protocol for observable external actions — any call leaving the local process boundary (another LLM/API, message/email, issue/PR, payment, external mutation). The protocol specifies required observable state transitions (intent before the action, result/unresolved state after) rather than tool-specific rules, with declared guarantee levels so an implementation never claims more durability than it structurally provides.

Originates from a four-checkpoint review cycle (codex outbox idea → claude critique → codex v2 capability-contract → claude final consolidation). Full converged design with per-decision rationale:
.agents/checkpoints/2026-06-23T173242_claude_observable-external-actions-final.md

Core contract

Before an externally relevant action is attempted, its intent must become observable at a declared guarantee level. After the attempt, its result or unresolved state must also become observable. Recovery claims must not exceed the declared guarantee level.

Guarantee levels (graded by guarantee, not intention)

• G0 — best-effort (discretionary): agent writes the record; observability only, not recovery.
• G1 — wrapper-enforced: approved tool/CLI/hook/API client writes the record automatically before send; first real recovery level.
• G2 — durable/transactional: external orchestrator owns the outbox, idempotency keys, retries, approval gates.

Key design rules (corrections folded in)

1. Three levels, not four — graded by guarantee delivered, not by "was the agent told to log".
2. G1 enforcement must be technical — closed egress path or detectable bypass; otherwise declare G0.
3. Conservative classification — if uncertain whether an action has side effects, treat as side-effecting; consult a known-mutating registry before agent judgment. Only analysis-only calls may sit at G0.
4. Correlation marker at G1+ — idempotency key or embedded tag recorded at planned, so unknown_external_state is reconcilable (search the external system for the marker) instead of degrading to "ask a human".

Status vocabulary

planned · sent_or_waiting · completed · failed · unknown_external_state · acknowledged_deferred

Storage

Reuse existing infra: cross-session discoverability via sessions/active_sessions.md; append-only events.jsonl with status derived from last event (matches the append-at-tail / decisions.jsonl grain). No new parallel outbox/ tree.

Honesty clause — current effective level

Claude Code and Codex run in IDE/CLI contexts with no enforceable egress wrapper today, so the effective guarantee in this project is G0 for all external actions. The protocol must state this so the spec does not advertise G1/G2 capabilities the runtime cannot deliver.

Promotion plan

1. Add §1 principle + honesty clause to PROTOCOL_RULES.md.
2. Define the three guarantee levels + G1 enforcement test.
3. Conservative classification + known-mutating registry.
4. Require correlation marker at G1+.
5. Status vocabulary + events.jsonl schema under schemas/.
6. Wire storage into sessions/active_sessions.md discoverability.
7. Declare project effective level (G0) + close-time acknowledged_deferred rule.
8. Tooling later: schema validation + stale-sent_or_waiting detector.

Open decision

Confirmed direction: capability-level contract. Remaining maintainer call: ship G1 in the first edit as specified-but-unavailable, or defer until a reference wrapper exists. Design recommends specifying all three levels now (portability) while declaring project effective level as G0.