oacp-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-05-12
+
+### Added
+
+- `auto_review` autonomy mode — an opt-in receiver-side autonomy profile that classifies inbound messages into auto-accept, pause, or hard-stop bands using clean / ambiguous / hard-stop trigger predicates. Configured via `receiver_config.autonomy_mode: auto_review` with `auto_review_profile` selecting `standard` or `tight`. Off by default; existing receivers continue to behave as `always_pause` unless they opt in. Ships with a conformance fixture suite under `tests/conformance/autonomy/` covering clean tasks, ambiguous scope, hard-stop triggers, and malformed config handling.
+
+### Changed
+
+- README: refreshed with a hero image and three screenshots illustrating inbox flow, doctor output, and the multi-agent workspace layout. Hub README copy, install path, and command table aligned with the current CLI surface.
+- Docs: link to companion oacp-skills repo from the README and onboarding pages so readers can find the skill library that pairs with the protocol.
+
 ## [0.3.0] - 2026-04-29
 
 ### Added
@@ -131,6 +142,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.3.1]: https://github.com/kiloloop/oacp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/kiloloop/oacp/compare/v0.2.3...v0.3.0
 [0.2.3]: https://github.com/kiloloop/oacp/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/kiloloop/oacp/compare/v0.2.1...v0.2.2

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/CONTRIBUTING.md

@@ -73,6 +73,7 @@ make preflight ARGS="--full"
 - Packet naming follows `<YYYYMMDD>_<topic>_<owner>_r<round>`.
 - Scripts use `python3` and avoid external dependencies beyond the standard library (exception: `pyyaml`).
 - Shell scripts use POSIX-compatible constructs where possible; bash-specific features require bash 3.2+.
+- README images should stay under ~500KB each. Use `docs/img/` for all README assets.
 
 ## Commit Messages
 

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp
@@ -24,7 +24,7 @@ Requires-Python: >=3.9
 Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 
-# OACP — Open Agent Coordination Protocol
+# OACP
 
 [![PyPI](https://img.shields.io/pypi/v/oacp-cli)](https://pypi.org/project/oacp-cli/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
@@ -32,11 +32,92 @@ Description-Content-Type: text/markdown
 [![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/kiloloop/oacp/pulls)
 
-> **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.
+> Coordinate agents *without* the chaos.
 
-**Coordinate agents without the chaos.**
+A file-based protocol for multi-agent AI workflows. Two pillars — cross-agent communication and persistent shared memory. Across runtimes, projects, and machines. No daemons. No central server. Just files.
 
-A file-based protocol for multi-agent engineering workflows. OACP defines the message formats, review processes, and safety rules that let AI agents on different runtimes collaborate through a shared filesystem. Not a framework or SDK — just conventions, YAML schemas, and scripts that any runtime can implement.
+[Read the spec →](SPEC.md)
+
+```bash
+$ pip install oacp-cli
+```
+
+## See it in action
+
+<p align="center">
+  <img src="docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
+</p>
+
+The CLI ships structured tasks between agents and lets you watch the conversation in real time.
+
+## Live agent fleet
+
+<p align="center">
+  <img src="docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
+</p>
+
+Every multi-agent thread is a sequence of typed messages — `review_request`, `review_feedback`, `review_addressed`, `review_lgtm` — with explicit quality gates.
+
+<details>
+<summary>Text version (terminal browsing / grep / a11y)</summary>
+
+```
+PROJECT · my-app                                   ● live
+
+  C  claude   code           drafting PR #42
+  X  codex    cli            reviewing
+  G  gemini   api            idle
+
+  claude  →  review_request    "auth refactor"      [codex]
+  codex   →  review_feedback   2 minor, 0 blocking  [claude]
+  claude  →  review_addressed                       [codex]
+  codex   →  review_lgtm                            [merge]
+
+  thread #42 · 4 msgs · 8m                  quality gate ✓
+```
+
+</details>
+
+## Filesystem as protocol
+
+<p align="center">
+  <img src="docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
+</p>
+
+Everything is plain files in `$OACP_HOME`. Agents have `inbox/`, `outbox/`, `dead_letter/`. Projects have shared `memory/` (durable) and per-thread `artifacts/`, `checkpoints/`, `packets/`. Org-wide knowledge lives in `$OACP_HOME/org-memory/`.
+
+<details>
+<summary>Text version (terminal browsing / grep / a11y)</summary>
+
+```
+$OACP_HOME/projects/my-app/                  ● writing
+
+  agents/
+    claude/
+      inbox/         3 msgs           [in]
+      outbox/        12 sent          [out]
+      dead_letter/   empty            [dl]
+    codex/
+      inbox/         +1 new           [in]
+
+  memory/                             shared durable
+    project_facts.md     2.4 kb       [md]
+    decision_log.md      edited 3s ago [md]
+    open_threads.md      1.1 kb       [md]
+    known_debt.md        812 b        [md]
+
+  artifacts/                          build · research
+  checkpoints/                        progress
+  packets/                            review findings
+  workspace.json                      metadata        [json]
+
+$OACP_HOME/org-memory/                org-wide
+  recent.md            auto-loaded    [⌘]
+  rules.md             12 rules       [⌘]
+  decisions.md         org decisions  [⌘]
+```
+
+</details>
 
 ## Quick Start
 
@@ -47,7 +128,7 @@ oacp send my-project --from alice --to bob --type task_request \
   --subject "Implement feature X" --body "Details here..."
 ```
 
-When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough.
+When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough. Or try the [5-minute quickstart →](examples/quickstart/) to send your first message to a real AI agent.
 
 ### What you get
 
@@ -67,6 +148,18 @@ After installing, run `oacp doctor` to verify your environment is wired up:
 oacp doctor
 ```
 
+## Agent Skills
+
+OACP has companion agent skills that teach Claude, Codex, and other
+runtimes how to use the CLI and protocol in real workflows.
+
+Install or browse them here:
+
+- https://github.com/kiloloop/oacp-skills
+
+The core `oacp-cli` package remains the protocol/tooling kernel,
+while `oacp-skills` contains runtime guidance and workflows.
+
 ## Why OACP?
 
 When multiple AI agents work on the same codebase, they need a way to:

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/README.md

@@ -1,4 +1,4 @@
-# OACP — Open Agent Coordination Protocol
+# OACP
 
 [![PyPI](https://img.shields.io/pypi/v/oacp-cli)](https://pypi.org/project/oacp-cli/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
@@ -6,11 +6,92 @@
 [![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/kiloloop/oacp/pulls)
 
-> **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.
+> Coordinate agents *without* the chaos.
 
-**Coordinate agents without the chaos.**
+A file-based protocol for multi-agent AI workflows. Two pillars — cross-agent communication and persistent shared memory. Across runtimes, projects, and machines. No daemons. No central server. Just files.
 
-A file-based protocol for multi-agent engineering workflows. OACP defines the message formats, review processes, and safety rules that let AI agents on different runtimes collaborate through a shared filesystem. Not a framework or SDK — just conventions, YAML schemas, and scripts that any runtime can implement.
+[Read the spec →](SPEC.md)
+
+```bash
+$ pip install oacp-cli
+```
+
+## See it in action
+
+<p align="center">
+  <img src="docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
+</p>
+
+The CLI ships structured tasks between agents and lets you watch the conversation in real time.
+
+## Live agent fleet
+
+<p align="center">
+  <img src="docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
+</p>
+
+Every multi-agent thread is a sequence of typed messages — `review_request`, `review_feedback`, `review_addressed`, `review_lgtm` — with explicit quality gates.
+
+<details>
+<summary>Text version (terminal browsing / grep / a11y)</summary>
+
+```
+PROJECT · my-app                                   ● live
+
+  C  claude   code           drafting PR #42
+  X  codex    cli            reviewing
+  G  gemini   api            idle
+
+  claude  →  review_request    "auth refactor"      [codex]
+  codex   →  review_feedback   2 minor, 0 blocking  [claude]
+  claude  →  review_addressed                       [codex]
+  codex   →  review_lgtm                            [merge]
+
+  thread #42 · 4 msgs · 8m                  quality gate ✓
+```
+
+</details>
+
+## Filesystem as protocol
+
+<p align="center">
+  <img src="docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
+</p>
+
+Everything is plain files in `$OACP_HOME`. Agents have `inbox/`, `outbox/`, `dead_letter/`. Projects have shared `memory/` (durable) and per-thread `artifacts/`, `checkpoints/`, `packets/`. Org-wide knowledge lives in `$OACP_HOME/org-memory/`.
+
+<details>
+<summary>Text version (terminal browsing / grep / a11y)</summary>
+
+```
+$OACP_HOME/projects/my-app/                  ● writing
+
+  agents/
+    claude/
+      inbox/         3 msgs           [in]
+      outbox/        12 sent          [out]
+      dead_letter/   empty            [dl]
+    codex/
+      inbox/         +1 new           [in]
+
+  memory/                             shared durable
+    project_facts.md     2.4 kb       [md]
+    decision_log.md      edited 3s ago [md]
+    open_threads.md      1.1 kb       [md]
+    known_debt.md        812 b        [md]
+
+  artifacts/                          build · research
+  checkpoints/                        progress
+  packets/                            review findings
+  workspace.json                      metadata        [json]
+
+$OACP_HOME/org-memory/                org-wide
+  recent.md            auto-loaded    [⌘]
+  rules.md             12 rules       [⌘]
+  decisions.md         org decisions  [⌘]
+```
+
+</details>
 
 ## Quick Start
 
@@ -21,7 +102,7 @@ oacp send my-project --from alice --to bob --type task_request \
   --subject "Implement feature X" --body "Details here..."
 ```
 
-When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough.
+When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough. Or try the [5-minute quickstart →](examples/quickstart/) to send your first message to a real AI agent.
 
 ### What you get
 
@@ -41,6 +122,18 @@ After installing, run `oacp doctor` to verify your environment is wired up:
 oacp doctor
 ```
 
+## Agent Skills
+
+OACP has companion agent skills that teach Claude, Codex, and other
+runtimes how to use the CLI and protocol in real workflows.
+
+Install or browse them here:
+
+- https://github.com/kiloloop/oacp-skills
+
+The core `oacp-cli` package remains the protocol/tooling kernel,
+while `oacp-skills` contains runtime guidance and workflows.
+
 ## Why OACP?
 
 When multiple AI agents work on the same codebase, they need a way to:

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/SPEC.md

@@ -79,7 +79,12 @@ Messages are YAML files. Filename convention: `<timestamp>_<from>_<type>.yaml`
 | `subject` | string | Subject line |
 | `body` | string | Message content (multi-line markdown) |
 
-**Optional fields:** `expires_at`, `channel`, `related_packet`, `related_pr`, `conversation_id`, `parent_message_id`, `context_keys`
+**Optional fields:** `expires_at`, `channel`, `autonomy_hint`, `related_packet`, `related_pr`, `conversation_id`, `parent_message_id`, `context_keys`
+
+`autonomy_hint` is an advisory sender hint, such as `auto_proceed`. Receivers
+remain authoritative: local autonomy config, message content, safety defaults,
+and runtime/tool permissions determine whether a message can be accepted without
+interactive human confirmation.
 
 ### Message Types
 
@@ -164,7 +169,7 @@ received → accepted → working → pr_opened → in_review → done
 
 ### Key Transitions
 
-- **`received` → `accepted`**: Agent reads and accepts the task. Ack recommended for P0/P1.
+- **`received` → `accepted`**: Agent reads and accepts the task. Ack recommended for P0/P1. When accepted by autonomy policy, this transition is preserved and records `accepted_by`, `human_confirmed`, `autonomy_mode`, `policy_ref`, `policy_hash`, and `reason_codes`.
 - **`working` → `pr_opened`**: Agent opens a PR. **Notification required** with `WIP:` subject prefix.
 - **`pr_opened` → `in_review`**: Agent requests cross-agent review via `review_request`.
 - **`in_review` → `done`**: PR merged after review approval. Guard: `pr_merged AND review_approved`.
@@ -202,6 +207,23 @@ The dispatcher (e.g., an orchestrator agent) tracks dispatches from its perspect
 - **Non-PR tasks**: done = deliverable provided or question answered
 - Final notification must include `merge_sha` (PR tasks) or `results_summary` (non-PR tasks)
 
+### Acceptance Metadata
+
+Receivers must not collapse `received → accepted`, even when a task is
+auto-accepted. Transition metadata records who or what accepted the task:
+
+```yaml
+transition: received_to_accepted
+accepted_by: autonomy_policy   # human | autonomy_policy | --autonomous-flag
+human_confirmed: false
+autonomy_mode: auto_review
+policy_ref: agents/codex/config.yaml
+policy_hash: sha256:...
+reason_codes:
+  - task_profile_present
+  - risk_threshold_passed
+```
+
 ### Brainstorm Lifecycle
 
 Brainstorm messages follow a simpler lifecycle: `received` → `researching` → `report_delivered`. No PR, no review loop. The dispatcher sees: `Sent` → `In progress` → `Responded`.
@@ -402,6 +424,27 @@ Credential scoping: [`docs/protocol/credential_scoping.md`](docs/protocol/creden
 
 These defaults apply to all agents (Claude, Codex, Gemini) unless a project-level config explicitly overrides a specific rule. Safety defaults can only be made **stricter** by project rules, never relaxed.
 
+Autonomy introduces a separate receiver acceptance policy layer; it does not
+relax the safety floor. OACP distinguishes three layers:
+
+1. **Safety defaults** — non-negotiable baseline constraints, such as no
+   unapproved push/deploy/merge/publish, no destructive commands, no secrets,
+   and disciplined staging. Projects may make these stricter, never looser.
+2. **Receiver acceptance policy** — configurable rules for whether a receiver
+   may move a message from `received` to `accepted` without interactive human
+   confirmation. This is governed by `agents/<receiver>/config.yaml` and
+   [`docs/protocol/autonomy.md`](docs/protocol/autonomy.md).
+3. **Runtime/tool safety** — runtime-specific permission gates that still apply
+   after acceptance, such as editor edit approval, shell sandboxing, or Codex
+   approval modes. OACP acceptance never grants runtime tool permissions.
+
+Regardless of autonomy mode, receivers must pause on any of: destructive command
+tokens (`rm -rf`, `--force`, `--no-verify`,
+`--dangerously-skip-permissions`), external side effects
+(push/deploy/merge/publish/rotate/install), or modifications to auth, config,
+secrets, dependencies, public repos, pricing/commercial content, or memory SSOT,
+unless explicitly authorized by a separate safety-default exception.
+
 #### Git Safety
 
 - No push/deploy without explicit approval from the user or dispatcher
@@ -677,6 +720,7 @@ scripts/init_packet.sh <project> <packet_id>  # (no CLI wrapper yet)
 | Shared workspace | [`docs/protocol/multi_agent_shared_workspace.md`](docs/protocol/multi_agent_shared_workspace.md) |
 | Cross-runtime sync | [`docs/protocol/cross_runtime_sync.md`](docs/protocol/cross_runtime_sync.md) |
 | Session init | [`docs/protocol/session_init.md`](docs/protocol/session_init.md) |
+| Receiver autonomy | [`docs/protocol/autonomy.md`](docs/protocol/autonomy.md) |
 | Safety defaults | [`docs/protocol/agent_safety_defaults.md`](docs/protocol/agent_safety_defaults.md) |
 | Credential scoping | [`docs/protocol/credential_scoping.md`](docs/protocol/credential_scoping.md) |
 | Runtime capabilities | [`docs/protocol/runtime_capabilities.md`](docs/protocol/runtime_capabilities.md) |

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/docs/protocol/agent_safety_defaults.md

@@ -30,6 +30,21 @@ Follow `credential_scoping.md` in this directory for:
 - Per-agent credential boundaries
 - Rotation and revocation procedures
 
+## Autonomy Hard Stops
+
+Receiver autonomy controls only whether a message can move from `received` to
+`accepted` without interactive human confirmation. It does not relax this safety
+floor.
+
+Regardless of autonomy mode, receivers must pause on any of:
+
+- Destructive command tokens: `rm -rf`, `--force`, `--no-verify`, `--dangerously-skip-permissions`
+- External side effects: push, deploy, merge, publish, credential rotation, dependency install
+- Sensitive scope: auth, config, secrets, dependencies, public repos, pricing/commercial content, memory SSOT
+
+The only exception is an explicit, separate safety-default exception. The
+Phase 1 autonomy RFC does not introduce any such exception.
+
 ## Scope Discipline
 
 - **Do not edit files outside the requested scope** — if a task says "fix X in file Y", do not refactor file Z.

oacp_cli-0.3.1/docs/protocol/autonomy.md

@@ -0,0 +1,210 @@
+# Receiver Autonomy Policy
+
+## Purpose
+
+OACP autonomy controls whether a receiver may move an inbox message from
+`received` to `accepted` without interactive human confirmation. It does not
+grant runtime tool permissions, and it does not relax agent safety defaults.
+
+Phase 1 ships two modes:
+
+| Mode | Behavior |
+|------|----------|
+| `always_pause` | Default. Receiver pauses for human review before accepting work. |
+| `auto_review` | Receiver may auto-accept only messages that pass the deterministic gates below. |
+
+Sender trust is messenger-bound and is not part of OACP autonomy v1/v2. Sender
+fields may be logged in audit events for traceability, but sender identity does
+not gate Phase 1 decisions.
+
+## Receiver Config
+
+Receiver policy lives at `agents/<receiver>/config.yaml`:
+
+```yaml
+autonomy:
+  default_mode: always_pause
+  auto_review_thresholds:
+    max_estimated_minutes: 30
+    max_expected_files_touched: 5
+    destructive_ops: pause
+    external_side_effects: pause
+    auth_config_or_secrets: pause
+    dependency_changes: pause
+    public_visibility: pause
+    git_push_or_deploy: pause
+  allow_without_task_profile:
+    - brainstorm_request
+```
+
+When config is absent, receivers behave as `always_pause`. Malformed config
+causes a pause and should be surfaced by `oacp doctor`.
+
+## Message Fields
+
+Messages may include top-level `autonomy_hint: auto_proceed`. This is advisory
+only; the receiver's config and local evaluator are authoritative.
+
+For `auto_review`, `task_request` and `question` messages require a
+machine-parseable `task_profile` block in `body`:
+
+```yaml
+task_profile:
+  estimated_minutes: 20
+  risk_tier: P3
+  expected_files_touched: 3
+  destructive_ops: false
+  external_side_effects: false
+  touches_auth_config_or_secrets: false
+  touches_dependencies: false
+  public_visibility: false
+```
+
+Missing `task_profile` pauses with `task_profile_missing`. An unparsable or
+schema-invalid profile pauses with `task_profile_unparsable`; it is not a fatal
+message-schema error. Message types listed in `allow_without_task_profile`, such
+as `brainstorm_request`, may auto-accept without the block.
+
+## Four-Gate Evaluator
+
+If any required gate is missing or uncertain, the receiver pauses.
+
+1. **Message integrity**
+   - Message validates against OACP schema.
+   - Message is not expired.
+   - Raw YAML hash is recorded as `message_sha256` before processing.
+   - Message ID has not already been auto-accepted by this receiver.
+   - `autonomy_hint`, if present, remains advisory only.
+2. **Declared task profile**
+   - Required for `task_request` and `question`.
+   - Cross-checks `estimated_minutes`, `expected_files_touched`, and boolean
+     risk fields against `auto_review_thresholds`.
+3. **Receiver classification**
+   - Pause unconditionally on destructive command tokens: `rm -rf`, `--force`,
+     `--no-verify`, `--dangerously-skip-permissions`.
+   - Pause when the body asks for deploy, push to main, merge, publish,
+     credential rotation, or dependency install.
+   - Pause when the body touches auth, config, secrets, dependencies, public
+     repos, pricing/commercial content, or memory SSOT.
+   - Pause when file scope is ambiguous or broader than the declared profile.
+4. **Runtime/workspace**
+   - Worktree is clean or the task can be isolated to a fresh branch.
+   - No conflicting active task exists on the same repo.
+   - Required tools are available.
+
+LLM judgment may reduce false positives after deterministic gates pass. It
+cannot override hard stops.
+
+## Hard-Stop Override
+
+Regardless of autonomy mode, receivers must pause on any of: destructive command
+tokens (`rm -rf`, `--force`, `--no-verify`,
+`--dangerously-skip-permissions`), external side effects
+(push/deploy/merge/publish/rotate/install), or modifications to auth, config,
+secrets, dependencies, public repos, pricing/commercial content, or memory SSOT,
+unless explicitly authorized by a separate safety-default exception.
+
+## Audit Events
+
+Every autonomy decision writes one YAML file:
+
+`agents/<receiver>/audit/autonomy_decisions/YYYYMMDDTHHMMSSZ_<message-id>.yaml`
+
+```yaml
+schema_version: 1
+spec_version: "0.3.0"
+created_at_utc: "2026-05-12T13:23:25Z"
+receiver: codex
+sender: iris
+message_id: msg-20260512132325-iris-de62
+message_type: task_request
+message_subject: "Small docs cleanup"
+message_path: agents/codex/inbox/20260512132325_iris_task_request.yaml
+message_sha256: "..."
+decision: auto_accepted
+mode: auto_review
+policy_path: agents/codex/config.yaml
+policy_sha256: "..."
+reason_codes:
+  - task_profile_present
+  - risk_threshold_passed
+thresholds:
+  max_estimated_minutes: 30
+  max_expected_files_touched: 5
+task_profile:
+  estimated_minutes: 20
+  expected_files_touched: 3
+  destructive_ops: false
+runtime:
+  agent: codex
+  model: gpt-5
+result:
+  final_state: done
+  reply_message_id: msg-...
+  artifacts: []
+```
+
+`policy_path` and `policy_sha256` may be null when the pause is caused by
+missing or malformed config. `sender` is logged only for traceability.
+
+## State Transition Metadata
+
+Auto-acceptance preserves the `received -> accepted` transition and records why:
+
+```yaml
+transition: received_to_accepted
+accepted_by: autonomy_policy
+human_confirmed: false
+autonomy_mode: auto_review
+policy_ref: agents/codex/config.yaml
+policy_hash: sha256:...
+reason_codes:
+  - task_profile_present
+  - risk_threshold_passed
+```
+
+## Mental Model
+
+`auto_review` is OACP's analogue to Claude Code's `acceptEdits` mode: class-based
+pre-approval within a local trust domain, bounded by bright-line hard stops.
+
+The analogy is about user contract, not mechanism. OACP decides pre-execution
+from message content and declared `task_profile`; runtime tools still enforce
+their own permissions at action time.
+
+## Worked Example
+
+A receiver configured with `default_mode: auto_review` receives:
+
+```markdown
+## Task
+Clean up the build directory: `rm -rf dist/ && rebuild`.
+
+task_profile:
+  estimated_minutes: 5
+  expected_files_touched: 1
+  destructive_ops: false
+```
+
+Decision trace:
+
+- Gate 1 passes: schema valid, not expired, hash recorded.
+- Gate 2 passes: profile present and within thresholds.
+- Gate 3 fails: body matches `rm -rf`.
+- Decision: `paused`.
+- Reason codes: `hard_stop_destructive_command`.
+- Audit event includes `matched_pattern: "rm -rf"`.
+
+The receiver must pause before any action runs. No autonomy mode can override
+the hard stop.
+
+## Threshold-Exceeded Checkpoint
+
+Receivers self-pause if work expands beyond the declared `task_profile` after
+acceptance:
+
+- `Blocked: autonomy threshold exceeded — files_touched expected 3, now 12`
+- `Blocked: autonomy threshold exceeded — prompt was docs-only, now requires credential access`
+- `Blocked: autonomy threshold exceeded — task expanded into untyped/unconfigured capability`
+
+The canonical fixture set lives in `tests/conformance/autonomy/`.

{oacp_cli-0.3.0 → oacp_cli-0.3.1}/docs/protocol/dispatch_states.yaml

@@ -109,6 +109,26 @@ agent_transitions:
     to: "accepted"
     trigger: "Agent reads and accepts the task_request"
     role: "agent"
+    metadata_fields:
+      transition: "received_to_accepted"
+      accepted_by:
+        description: "Acceptance actor: human | autonomy_policy | --autonomous-flag"
+        required: true
+      human_confirmed:
+        description: "Whether a human explicitly confirmed acceptance"
+        required: true
+      autonomy_mode:
+        description: "Receiver autonomy mode, e.g. always_pause or auto_review"
+        required: false
+      policy_ref:
+        description: "Receiver policy path, e.g. agents/codex/config.yaml"
+        required: false
+      policy_hash:
+        description: "sha256 of receiver policy when available"
+        required: false
+      reason_codes:
+        description: "List of acceptance or pause reason codes"
+        required: false
 
   - from: "received"
     to: "rejected"