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

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

@@ -5,7 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.2] - 2026-05-26
+
+### Added
+
+- Receiver autonomy scope-envelope evaluator with side-effect booleans,
+  threshold-checkpoint instrumentation, taxonomy pinning, and default-off
+  continuation grants.
+- `cursor` runtime support for agent profiles, agent cards, status validation, sender inference via `OACP_RUNTIME=cursor`, `oacp add-agent --runtime cursor`, and `oacp setup cursor`.
+- `oacp setup cursor --project <project>` now provisions the project-side Cursor agent directory and writes a repo-local `.cursor/rules/oacp.todo.mdc` placeholder while Cursor-owned rules and memory hooks remain deferred.
+
+### Changed
+
+- `oacp init` now defaults to `claude,codex,cursor`; Gemini remains supported through `--agents` and `oacp setup gemini`.
+- Receiver autonomy docs and templates now use the current
+  `agents/<receiver>/config.yaml` schema.
+- Docs: added an asynchronous `claude -p` on-ramp guide and refreshed the
+  quickstart for the current CLI surface.
+
+## [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
 
@@ -131,6 +158,8 @@ 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.2]: https://github.com/kiloloop/oacp/compare/v0.3.1...v0.3.2
+[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.2}/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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.3.0
+Version: 0.3.2
 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,30 +24,115 @@ 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)
 [![Claude Code](https://img.shields.io/badge/Runtime-Claude_Code-6B4FBB.svg)](https://claude.ai/code)
 [![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)
+[![Cursor](https://img.shields.io/badge/Runtime-Cursor-222222.svg)](https://cursor.com/)
 [![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
+$ uv tool 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
 
 ```bash
-pip install oacp-cli
+uv tool install oacp-cli
 oacp init my-project --agents alice,bob
 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.
+By default, `oacp init my-project` creates `claude`, `codex`, and `cursor`
+agents. Pass `--agents` to include Gemini or custom agent names.
+
+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
 
@@ -59,6 +144,14 @@ When running inside a configured agent runtime, `--from` can be omitted — OACP
 - **Agent safety defaults** — baseline rules for git, credentials, and scope discipline
 - **Runtime-agnostic** — works with any runtime that reads/writes files
 
+## Coming from `claude -p`?
+
+`claude -p` runs an agent synchronously and headless — your script blocks while it works, and as of June 15 programmatic usage draws from a separate metered credit.
+
+OACP routes the same work to a **standing interactive Claude Code session** instead: `oacp send` queues the task, the session picks it up and runs it async, you're not blocked — and because it's a real interactive session, it stays on your subscription.
+
+**[From `claude -p` to an interactive Claude Code session →](docs/from-claude-p.md)** — paste-into-your-agent setup, the honest tradeoffs, and where it fits.
+
 ## Try It Now
 
 After installing, run `oacp doctor` to verify your environment is wired up:
@@ -67,6 +160,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:
@@ -148,7 +253,7 @@ uv tool install .
 |---------|-------------|
 | `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |
 | `oacp add-agent` | Add an agent to an existing project workspace |
-| `oacp setup` | Generate runtime-specific config files (Claude, Codex, etc.) |
+| `oacp setup` | Generate runtime-specific config files (Claude, Codex, Cursor, Gemini) |
 | `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |
 | `oacp inbox` | List pending messages across agents (table or `--json`) |
 | `oacp watch` | Emit inbox delta events for one agent across selected projects |

{oacp_cli-0.3.0 → oacp_cli-0.3.2}/QUICKSTART.md

@@ -34,10 +34,10 @@ pipx install oacp-cli
 Every project gets its own workspace with agent inboxes, shared memory, and packet directories.
 
 ```bash
-oacp init my-first-project --agents claude,codex,gemini --repo /path/to/repo
+oacp init my-first-project --agents claude,codex,cursor --repo /path/to/repo
 ```
 
-Or with defaults (agents: claude, codex, gemini):
+Or with defaults (agents: claude, codex, cursor):
 
 ```bash
 oacp init my-first-project
@@ -54,7 +54,7 @@ $OACP_HOME/projects/my-first-project/
 │   ├── codex/
 │   │   ├── inbox/
 │   │   └── outbox/
-│   └── gemini/
+│   └── cursor/
 │       ├── inbox/
 │       └── outbox/
 ├── memory/
@@ -72,24 +72,37 @@ $OACP_HOME/projects/my-first-project/
 
 ## 4. Connect Your Runtime
 
-Tell your agent runtime where the OACP workspace lives.
+Run the runtime setup command from the repo you want the agent to work in:
 
-**Claude Code** — add the OACP workspace path to your project's `CLAUDE.md`:
+```bash
+cd /path/to/repo
+oacp setup <runtime> --project my-first-project
+```
+
+For Claude Code:
 
-```markdown
-## OACP
-OACP workspace: $OACP_HOME/projects/my-first-project/
-Check inbox: ls $OACP_HOME/projects/my-first-project/agents/claude/inbox/
+```bash
+oacp setup claude --project my-first-project
 ```
 
-**Codex** — add the workspace path to your repo's `AGENTS.md`:
+This creates or updates:
+
+- `.claude/agents/my-first-project.md`
+- `.claude/skills/`
+- `.claude/hooks/oacp-memory-pull.sh`
+- `.claude/hooks/oacp-memory-push.sh`
+- `.claude/settings.json`
 
-```markdown
-## OACP
-OACP workspace: $OACP_HOME/projects/my-first-project/
+For other supported runtimes, use the same shape:
+
+```bash
+oacp setup codex --project my-first-project
+oacp setup cursor --project my-first-project
+oacp setup gemini --project my-first-project
 ```
 
-**Other runtimes** — point your agent's system prompt at the workspace path and instruct it to read the standard `memory/` files at session start.
+Cursor support is scaffold-only until Cursor-owned rules land. Cursor sessions
+must set `OACP_RUNTIME=cursor` or pass `--from` explicitly when sending messages.
 
 For full runtime setup (role templates, guardrails, skills), see [docs/guides/setup.md](docs/guides/setup.md).
 
@@ -112,6 +125,12 @@ This writes a YAML file to `agents/codex/inbox/` and a copy to `agents/claude/ou
 
 See what's waiting for an agent:
 
+```bash
+oacp inbox my-first-project --agent codex
+```
+
+Or inspect the inbox directory directly:
+
 ```bash
 ls "$OACP_HOME/projects/my-first-project/agents/codex/inbox/"
 ```
@@ -136,6 +155,17 @@ body: |
   Add POST /login with JWT auth. See docs/api-spec.md for details.
 ```
 
+To watch for new messages from a standing runtime or Monitor, use `oacp watch`.
+A single `oacp watch` run scans once and exits, so keep re-running it when you
+want a persistent worker:
+
+```bash
+while true; do
+  oacp watch --project my-first-project --agent codex || true
+  sleep 120
+done
+```
+
 ## 7. Reply
 
 Send a response back:
@@ -146,7 +176,7 @@ oacp send my-first-project \
   --type notification \
   --subject "Re: Implement login endpoint" \
   --body "Accepted. Starting implementation on branch codex/login-endpoint." \
-  --parent-message-id "msg-20260311T120000Z-claude-a1b2"
+  --in-reply-to "msg-20260311T120000Z-claude-a1b2"
 ```
 
 ## 8. Validate Messages
@@ -160,13 +190,21 @@ oacp validate \
 
 ## 9. Run Health Checks
 
-Verify your environment and workspace are set up correctly:
+Verify your environment first:
 
 ```bash
 oacp doctor
+```
+
+Then check the workspace you just created:
+
+```bash
 oacp doctor --project my-first-project
 ```
 
+Plain `oacp doctor` checks global environment health. The `--project` form also
+checks the project workspace, inboxes, schemas, and agent status files.
+
 ## What's Next?
 
 - **Review loop** — Set up structured code review between agents. See [docs/protocol/review_loop.md](docs/protocol/review_loop.md).

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

@@ -1,27 +1,112 @@
-# 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)
 [![Claude Code](https://img.shields.io/badge/Runtime-Claude_Code-6B4FBB.svg)](https://claude.ai/code)
 [![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)
+[![Cursor](https://img.shields.io/badge/Runtime-Cursor-222222.svg)](https://cursor.com/)
 [![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
+$ uv tool 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
 
 ```bash
-pip install oacp-cli
+uv tool install oacp-cli
 oacp init my-project --agents alice,bob
 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.
+By default, `oacp init my-project` creates `claude`, `codex`, and `cursor`
+agents. Pass `--agents` to include Gemini or custom agent names.
+
+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
 
@@ -33,6 +118,14 @@ When running inside a configured agent runtime, `--from` can be omitted — OACP
 - **Agent safety defaults** — baseline rules for git, credentials, and scope discipline
 - **Runtime-agnostic** — works with any runtime that reads/writes files
 
+## Coming from `claude -p`?
+
+`claude -p` runs an agent synchronously and headless — your script blocks while it works, and as of June 15 programmatic usage draws from a separate metered credit.
+
+OACP routes the same work to a **standing interactive Claude Code session** instead: `oacp send` queues the task, the session picks it up and runs it async, you're not blocked — and because it's a real interactive session, it stays on your subscription.
+
+**[From `claude -p` to an interactive Claude Code session →](docs/from-claude-p.md)** — paste-into-your-agent setup, the honest tradeoffs, and where it fits.
+
 ## Try It Now
 
 After installing, run `oacp doctor` to verify your environment is wired up:
@@ -41,6 +134,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:
@@ -122,7 +227,7 @@ uv tool install .
 |---------|-------------|
 | `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |
 | `oacp add-agent` | Add an agent to an existing project workspace |
-| `oacp setup` | Generate runtime-specific config files (Claude, Codex, etc.) |
+| `oacp setup` | Generate runtime-specific config files (Claude, Codex, Cursor, Gemini) |
 | `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |
 | `oacp inbox` | List pending messages across agents (table or `--json`) |
 | `oacp watch` | Emit inbox delta events for one agent across selected projects |

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

@@ -3,7 +3,7 @@
 **Version**: 0.2.0
 **License**: Apache-2.0
 
-This document is the protocol specification for OACP (Open Agent Coordination Protocol) — a file-based coordination layer for multi-agent engineering workflows. It defines the message formats, state machines, review processes, and safety rules that enable agents on different runtimes (Claude, Codex, Gemini, or any future runtime) to collaborate asynchronously through a shared filesystem.
+This document is the protocol specification for OACP (Open Agent Coordination Protocol) — a file-based coordination layer for multi-agent engineering workflows. It defines the message formats, state machines, review processes, and safety rules that enable agents on different runtimes (Claude, Codex, Cursor, Gemini, or any future runtime) to collaborate asynchronously through a shared filesystem.
 
 OACP is not a framework or SDK. It is a set of conventions, YAML schemas, and shell scripts that any agent runtime can implement.
 
@@ -47,7 +47,7 @@ $OACP_HOME/
     │   │   ├── inbox/
     │   │   ├── outbox/
     │   │   └── ...
-    │   └── gemini/
+    │   └── cursor/
     │       └── ...
     ├── memory/                      # Shared durable memory
     │   ├── project_facts.md
@@ -79,7 +79,15 @@ 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.
+
+Receiver autonomy is defined by `agents/<receiver>/config.yaml` and the
+scope-envelope contract in [`docs/protocol/autonomy.md`](docs/protocol/autonomy.md).
 
 ### Message Types
 
@@ -164,7 +172,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 +210,29 @@ 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
+```
+
+Autonomy audit results use a stable terminal-state taxonomy
+(`done`, `paused`, `blocked`, `superseded`, `error`) plus
+`completion_kind` for detailed outcomes. Post-acceptance scope drift is recorded
+through the threshold checkpoint described in
+[`docs/protocol/autonomy.md`](docs/protocol/autonomy.md).
+
 ### Brainstorm Lifecycle
 
 Brainstorm messages follow a simpler lifecycle: `received` → `researching` → `report_delivered`. No PR, no review loop. The dispatcher sees: `Sent` → `In progress` → `Responded`.
@@ -400,7 +431,30 @@ Credential scoping: [`docs/protocol/credential_scoping.md`](docs/protocol/creden
 
 ### Baseline Rules
 
-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.
+These defaults apply to all agents (Claude, Codex, Cursor, 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 destructive command tokens
+(`rm -rf`, `--force`, `--no-verify`, `--dangerously-skip-permissions`) and on
+actual requests for external side effects or sensitive scope: push, deploy,
+merge, publish, credential rotation, dependency install, auth/config/secrets,
+public repos, pricing/commercial content, or memory SSOT. Profileless message
+types that are explicitly allowed for auto-review may log incidental
+side-effect verb mentions as notes instead of hard stops, but destructive tokens
+and real side-effect requests still pause.
 
 #### Git Safety
 
@@ -596,6 +650,7 @@ Scripts marked **CLI** are exposed as `oacp` subcommands. Scripts marked **scrip
 | `init_org_memory.py` | Scaffold org-level memory directory | CLI: `oacp org-memory` |
 | `write_event.py` | Write timestamped events to org-memory | CLI: `oacp write-event` |
 | `oacp_doctor.py` | Environment and workspace health check (flutter-doctor-style) | CLI: `oacp doctor` |
+| `autonomy_gate.py` | Evaluates receiver autonomy scope-envelope decisions and checkpoint drift | script-only |
 | `validate_message.py` | Validates inbox/outbox message YAML | CLI: `oacp validate` |
 | `session_lifecycle_hooks.py` | Session init and close hooks (`init_session`, `close_session`) | CLI-wrapped |
 | `codex_session_init.py` | Codex startup protocol loader | CLI-wrapped |
@@ -677,6 +732,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) |