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

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

@@ -5,7 +5,45 @@ 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.3] - 2026-06-11
+
+### Added
+
+- `oacp watch --state-id <id>` for per-subscriber cursor files, allowing
+  concurrent watchers of the same agent inbox to receive the same new-message
+  events without sharing a cursor.
+
+### Changed
+
+- Docs: refreshed the runtime capability matrix and prompt-caching guidance
+  for current runtime releases.
+
+### Fixed
+
+- `oacp send --oacp-dir` and `oacp inbox --oacp-dir` now expand `~` through the
+  shared OACP home resolver instead of treating it as a literal path component.
+- Inbox and outbox delivery writes now use same-directory temp files plus
+  atomic replace so readers do not observe partial `.yaml` messages.
+- Memory archive tests now isolate git config while preserving test identities,
+  so local commit-signing settings do not break the suite.
+
+## [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
 
@@ -142,6 +180,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.3]: https://github.com/kiloloop/oacp/compare/v0.3.2...v0.3.3
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -30,6 +30,7 @@ Description-Content-Type: text/markdown
 [![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)
 
 > Coordinate agents *without* the chaos.
@@ -39,7 +40,7 @@ A file-based protocol for multi-agent AI workflows. Two pillars — cross-agent
 [Read the spec →](SPEC.md)
 
 ```bash
-$ pip install oacp-cli
+$ uv tool install oacp-cli
 ```
 
 ## See it in action
@@ -122,12 +123,15 @@ $OACP_HOME/org-memory/                org-wide
 ## 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..."
 ```
 
+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
@@ -140,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:
@@ -241,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 |
@@ -258,7 +270,7 @@ uv tool install .
 
 **`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
 
-**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--show-archived`
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--state-id <id>` for per-subscriber cursors, `--show-archived`
 
 **`oacp doctor`**: `--fix` (auto-fix safe issues), `--memory`, `--json`, `-o/--output`
 

{oacp_cli-0.3.1 → oacp_cli-0.3.3}/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,20 @@ 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. If more than one watcher follows the same agent
+inbox, give each watcher a stable `--state-id` so each subscriber has its own
+cursor:
+
+```bash
+OACP_WATCH_STATE_ID="${OACP_WATCH_STATE_ID:-$(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')}"
+while true; do
+  oacp watch --project my-first-project --agent codex --state-id "$OACP_WATCH_STATE_ID" || true
+  sleep 120
+done
+```
+
 ## 7. Reply
 
 Send a response back:
@@ -146,7 +179,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 +193,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.1 → oacp_cli-0.3.3}/README.md

@@ -4,6 +4,7 @@
 [![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)
 
 > Coordinate agents *without* the chaos.
@@ -13,7 +14,7 @@ A file-based protocol for multi-agent AI workflows. Two pillars — cross-agent
 [Read the spec →](SPEC.md)
 
 ```bash
-$ pip install oacp-cli
+$ uv tool install oacp-cli
 ```
 
 ## See it in action
@@ -96,12 +97,15 @@ $OACP_HOME/org-memory/                org-wide
 ## 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..."
 ```
 
+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
@@ -114,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:
@@ -215,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 |
@@ -232,7 +244,7 @@ uv tool install .
 
 **`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
 
-**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--show-archived`
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--state-id <id>` for per-subscriber cursors, `--show-archived`
 
 **`oacp doctor`**: `--fix` (auto-fix safe issues), `--memory`, `--json`, `-o/--output`
 

{oacp_cli-0.3.1 → oacp_cli-0.3.3}/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
@@ -86,6 +86,9 @@ 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
 
 | Type | Purpose | Response Expected |
@@ -224,6 +227,12 @@ reason_codes:
   - 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`.
@@ -422,7 +431,7 @@ 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:
@@ -438,12 +447,14 @@ relax the safety floor. OACP distinguishes three layers:
    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.
+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
 
@@ -639,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 |

oacp_cli-0.3.3/docs/from-claude-p.md

@@ -0,0 +1,151 @@
+# From `claude -p` to an interactive Claude Code session
+
+On June 15, programmatic Claude usage — `claude -p`, the Agent SDK, Claude Code GitHub Actions, third-party tools — moves onto a separate metered monthly credit. Interactive Claude Code and chat stay on your subscription, unchanged.
+
+It's a reasonable change: programmatic usage is heavier and burstier than a person typing. But if you run agents in automation, it's worth asking a different question than "how do I dodge the meter" — **why is the agent headless and synchronous in the first place?**
+
+This guide is built to be handed to your agent. Read the first half for the *why*; paste the setup block into your Claude Code session for the *how*.
+
+> **Setup is a one-time ~5 minutes. Every task after that is one `oacp send` — async, non-blocking, on your subscription.**
+
+## The shape of `claude -p`
+
+`claude -p "do X"` is synchronous and headless:
+
+- it **blocks** — your script waits for the agent to finish
+- it runs **headless** — no session to glance at, attach to, or steer mid-run
+- after June 15, it's **metered** — programmatic usage draws from the separate credit pool
+
+That shape was always a compromise. You wanted to script an agent, and `claude -p` was the way to do it from a shell. Synchronous-and-headless came along for the ride.
+
+## The other shape
+
+Run the agent as a **standing interactive Claude Code session**, and *send* it work.
+
+```
+Before:  claude -p "do X"
+         blocks · headless · metered after Jun 15
+
+After:   oacp send  →  a standing interactive session picks it up
+         async · you're not blocked · on your subscription
+```
+
+Concretely — the call that replaces `claude -p "do X"`:
+
+```bash
+oacp send my-project --from sender --to claude --type task_request \
+  --subject "do X" --body "...details..."
+```
+
+Same prompt, different delivery. The text you'd have handed to `claude -p` becomes the message `--body`; `oacp send` drops it in the interactive session's inbox, and the session picks it up and runs it. Sending the prompt as an OACP message is the whole trick — it routes the work into a session running in interactive mode instead of a headless `claude -p` call.
+
+The session is a real interactive Claude Code session — so it stays on your subscription. You're not spoofing interactive mode; you're using it, and feeding it a queue.
+
+This isn't only about the credit. Async is the right shape for most automation — a build, an overnight refactor, a research job — none of it needs your script to sit and wait. And once tasks are messages in an inbox, you get real multi-agent coordination — review loops, handoffs, several agents on one project — instead of a pile of blocking shell calls.
+
+## Your options, honestly
+
+Two real choices if June 15 affects you.
+
+**1. Pay the metered credit (or API rates).** Simplest. Low programmatic volume — the included credit may cover you; past that it's API pricing. Already on the API — nothing changes. No new tooling; it just costs money at scale.
+
+**2. OACP — run interactive for real, feed it a queue.** Run a real interactive Claude Code session and send it work. It stays on your subscription because it genuinely *is* an interactive session. Not a one-liner — it's a workflow change. In exchange you get real agent coordination, not just a credit workaround.
+
+Option 1 is the no-effort path that costs money at volume. Option 2 is a one-time workflow change that doesn't. Pick on that.
+
+## What OACP is
+
+OACP isn't a June-15 tool. It's a file-based protocol for coordinating AI agents — inbox/outbox messaging, structured review loops, shared memory — no server, no daemon, just files in a directory. It was built to run a multi-agent fleet; the `claude -p` transition is **one usage** of it. Full picture: the [README](../README.md) and [SPEC](../SPEC.md). The companion [oacp-skills](https://github.com/kiloloop/oacp-skills) repo packages the runtime guidance — skills that teach Claude, Codex, and other agents to operate the protocol.
+
+## Set it up — paste this into your agent
+
+Open Claude Code in the repo you want the agent to work in, and paste this in:
+
+~~~
+Set me up as an async OACP worker for this repo.
+
+1. Install the oacp-cli tool if it isn't already installed — check with
+   oacp --version. Package and docs: https://github.com/kiloloop/oacp
+2. Create an OACP project workspace for this repo, named after the repo.
+   Give it two agents: "claude" (you, the worker) and "sender" (whoever
+   dispatches tasks — my shell, my CI, or another agent).
+3. Wire this repo for the Claude Code runtime against that project (the
+   oacp setup command for the claude runtime).
+4. Install the companion OACP agent skills from
+   https://github.com/kiloloop/oacp-skills — at minimum the check-inbox
+   skill, so you know how to process a task when it lands in your inbox.
+5. Run oacp doctor --project <the project name> and confirm there are
+   no issues — plain oacp doctor only checks the environment; the
+   --project form checks this workspace's inbox, schema, and status.
+6. Start a Monitor that keeps oacp watch re-running for the claude
+   agent on this project. A single oacp watch does one scan and exits,
+   so it has to run on a loop. Use a stable --state-id for that Monitor
+   so concurrent watchers each keep their own cursor. Then tell me the
+   exact oacp send command I use to dispatch a task to you.
+
+Protocol reference: https://github.com/kiloloop/oacp/blob/main/QUICKSTART.md
+~~~
+
+When it finishes, that session is a standing worker, and it has told you your send command. It looks like this (swap `my-project` for whatever it named the project):
+
+```bash
+oacp send my-project --from sender --to claude --type task_request \
+  --subject "do X" --body "...details..."
+```
+
+Run that from your shell, your CI, or another agent — anywhere `claude -p` ran. The watcher fires, the session picks up the task, it runs async while you move on.
+
+<details>
+<summary>Manual setup — no agent, or you want the exact commands</summary>
+
+```bash
+# install
+uv tool install oacp-cli          # or: pipx install oacp-cli
+
+# create a workspace — "claude" does the work, "sender" dispatches
+oacp init my-project --agents claude,sender
+
+# wire this repo for Claude Code
+oacp setup claude --project my-project
+
+# verify the workspace is wired (not just the environment)
+oacp doctor --project my-project
+```
+
+Then, in a Claude Code session, arm the watcher in a Monitor. `oacp watch` does one scan and exits, so it has to run on a loop:
+
+```
+OACP_WATCH_STATE_ID="${OACP_WATCH_STATE_ID:-$(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')}"
+while true; do
+  oacp watch --project my-project --agent claude --state-id "$OACP_WATCH_STATE_ID" || true
+  sleep 120
+done
+```
+
+Keep that loop running — it's now a standing worker, picking up tasks as they land. Send work with the `oacp send` command above.
+
+</details>
+
+**On verbosity.** `oacp send` is explicit by design — typed messages, priorities, threading. If you miss `claude -p "X"`, a shell alias closes the gap:
+
+```bash
+oacp-do() {
+  oacp send my-project --from sender --to claude --type task_request \
+    --subject "$1" --body "${2:-$1}"
+}
+# now: oacp-do "refactor the auth module"
+```
+
+## Where it fits — and where it doesn't
+
+**Fire-and-forget callers** — "build this," "refactor that," an overnight job, a research task. Clean fit. The caller never needed to block; async is strictly better.
+
+**Request-response callers** — CI doing `RESULT=$(claude -p ...)` and using the output inline. Works too, but not a one-liner: the caller also arms `oacp watch --agent sender` to catch the reply. Worth it for a real pipeline — just know it's more than a swap.
+
+**If you just want zero workflow change** and don't care about coordination — keep `claude -p` and pay the meter (option 1). OACP earns its setup cost when you have more than one agent, recurring work, or you want to see and steer what the agent is doing. If that's not you, we'd rather say so.
+
+## Try it
+
+Do the setup above in a repo you actually work in, send one real task, watch the session pick it up.
+
+If something breaks, the setup is rougher than it should be, or the docs are wrong — **[open an issue](https://github.com/kiloloop/oacp/issues)**. That feedback is what we're after; it's more useful than a star.

{oacp_cli-0.3.1 → oacp_cli-0.3.3}/docs/guides/prompt_caching.md

@@ -5,8 +5,8 @@ How to maximize prompt cache hits across Claude, Codex, and Gemini to reduce cos
 ## Why It Matters
 
 Prompt caching avoids reprocessing static context (system prompts, CLAUDE.md, project facts) on every turn. In practice:
-- **Cache read**: 10x cheaper than uncached input ($1.50/MTok vs $15/MTok for Opus)
-- **Cache write**: 1.25x input price (one-time cost, amortized over subsequent reads)
+- **Cache read**: 10x cheaper than uncached input ($0.50/MTok vs $5.00/MTok for Opus 4.8)
+- **Cache write**: 1.25x input price for the default 5-minute TTL, 2x for the 1-hour TTL (one-time cost, amortized over subsequent reads)
 - **Observed savings**: 83-95% cost reduction on cached input in multi-turn agent sessions
 
 ## Claude
@@ -127,13 +127,14 @@ Gemini supports implicit context caching for large prompts. The API automaticall
 
 ## Cost Comparison
 
-Approximate pricing as of early 2026 (per million tokens). Check each provider's current pricing page for up-to-date rates:
+Approximate pricing as of June 2026 (per million tokens). Cache read is 0.1x input; cache write is shown at the default 5-minute TTL (1.25x input) — the 1-hour TTL costs 2x input. Check each provider's current pricing page for up-to-date rates:
 
 | Runtime | Input | Cached Read | Cache Write | Output |
 |---------|------:|------------:|------------:|-------:|
-| Claude Opus | $15.00 | $1.50 | $18.75 | $75.00 |
-| Claude Sonnet | $3.00 | $0.30 | $3.75 | $15.00 |
-| Claude Haiku | $0.80 | $0.08 | $1.00 | $4.00 |
+| Claude Fable 5 | $10.00 | $1.00 | $12.50 | $50.00 |
+| Claude Opus (4.6/4.7/4.8) | $5.00 | $0.50 | $6.25 | $25.00 |
+| Claude Sonnet 4.6 | $3.00 | $0.30 | $3.75 | $15.00 |
+| Claude Haiku 4.5 | $1.00 | $0.10 | $1.25 | $5.00 |
 | Codex | varies | N/A | N/A | varies |
 | Gemini Pro | $1.25 | $0.31 | — | $10.00 |
 
@@ -146,3 +147,4 @@ Approximate pricing as of early 2026 (per million tokens). Check each provider's
    - Injecting timestamps or random IDs into system prompts
    - Reordering tool definitions between turns
    - Changing the user message prefix frequently
+5. **Mind the minimum cacheable prefix** — prefixes below the model minimum silently don't cache (no error; `cache_creation_input_tokens` stays 0). The minimum is 2,048 tokens on Fable 5 and Sonnet 4.6, and 4,096 tokens on Opus 4.8/4.7/4.6 and Haiku 4.5.