agent-composer 0.3.1 → 0.4.0

package/README.md

@@ -1,265 +1,580 @@
-# Composer — multi-agent orchestration for Claude Code
+# Composer — multi-agent orchestration for daily coding
 
-[![npm](https://img.shields.io/badge/npm-agent--composer-blue)](#install) [![tests](https://img.shields.io/badge/vitest-435%20passing-brightgreen)](#contributing) [![license](https://img.shields.io/badge/license-MIT-lightgrey)](#license)
+[![npm](https://img.shields.io/badge/npm-agent--composer-blue)](#install) [![MCP](https://img.shields.io/badge/MCP-Claude%20Code%20server-purple)](#architecture) [![license](https://img.shields.io/badge/license-MIT-lightgrey)](#license)
 
-> **Claude orchestrates. GLM, Codex, and `agy` execute — and *apply* — off your Claude quota.** Composer is an MCP server + Claude Code plugin that lets the most-capable model hold the plan while worker models generate *and write* the code in their own context. Because the executors apply files themselves (instead of returning text the main session must re-ingest), composer keeps the orchestrator's context lean and every change reviewable.
+> **Claude Code stays the main brain. Composer routes planning, coding, research, review, and safety gates to the right worker model.**
 
-## What it is
+Composer is an MCP server plus Claude Code plugin for people who want the strongest model to hold the product and architecture context, while cheaper or more specialized models do the mechanical work. It keeps the main Claude session focused on intent, integration, and decisions instead of spending tokens on raw code generation, patch application, repeated research, or long review logs.
 
-Two coordinated artefacts:
+## Why this exists
 
-| Artefact | Purpose |
-|---|---|
-| **`agent-composer`** (this npm package) | MCP server exposing `composer_handoff_create`, `composer_research`, `composer_code`, `composer_code_chain`, `composer_code_cli`, `composer_review`, and `composer_review_claude`. Wraps GLM (via Anthropic-compatible endpoint) and CLI executors such as Codex, `agy`, or bounded `claude -p`. |
-| **`composer-mastermind`** (Claude Code plugin) | Orchestrator skill + haiku-wrapped subagents (`coder`, `researcher`, `reviewer`, optional `reviewer-claude`) + `boundary_guard` PreToolUse hook + `/evolve` slash command. |
+Modern LLM development gets expensive and messy when one chat session does everything:
 
-Combined, they turn the main Claude session into a coordinator that never writes code or edits files directly. The main session may use Bash for inspection and verification, while code changes are dispatched through Composer MCP tools. The boundary hook fails closed if a denied file-mutating tool is requested.
+- planning the feature,
+- searching docs,
+- editing files,
+- debugging failures,
+- reviewing the diff,
+- remembering local workflow rules,
+- and enforcing commit gates.
 
-## Tools
+Composer separates those jobs.
 
-Seven MCP tools, all routing work off the main Claude session:
+| Need                                  | Composer answer                                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Keep the best model as the strategist | Claude Code orchestrates; optional ChatGPT Pro via Oracle acts as a slow co-oracle for hard planning/review/debugging.          |
+| Save Claude Code tokens               | Codex, GLM, `agy`, and bounded `claude -p` calls run outside the main Claude context and return compact summaries.              |
+| Let workers edit locally              | `composer_code_cli` lets Codex or another CLI executor generate **and apply** code directly in the repo.                        |
+| Avoid copy/paste between agents       | `composer_handoff_create` writes shared packets under `.composer/handoffs/`.                                                    |
+| Add quality gates                     | Review lanes, Codex pre-commit review, Claude Code hooks, terminal git hooks, and doctor checks make failures visible.          |
+| Improve over time                     | The `composer-mastermind` skill and `/evolve` loop let routing guidance improve from real failures, with manual promotion only. |
 
-| Tool | Executor | What it does |
-|---|---|---|
-| `composer_handoff_create` | Composer server | Writes a compact shared packet under `.composer/handoffs/`; pass `handoffPath` to Codex, GLM, agy, researcher, and reviewer calls so every worker shares the same objective and constraints. |
-| `composer_code_cli` | Codex CLI or agy | **Default for code edits.** The configured CLI executor generates **and applies** files itself off-CC, from the MCP server root, then returns a bounded summary. Use Codex here for complex coding work. |
-| `composer_code_chain` | GLM authors → server applies | GLM fallback. GLM writes the complete files off-CC (`FILE: <path>` + fenced blocks); the MCP server applies them deterministically off-CC; the orchestrator only relays a summary. ~71% fewer total-CC tokens on multi-file tasks. |
-| `composer_code` | GLM | Legacy patch-only lane. Use only when you explicitly need GLM diff/text output instead of an apply-capable lane. |
-| `composer_research` | Codex CLI search | Direct docs/web/current-context lane → bounded structured summary. Runs Codex with live web search and a read-only sandbox. |
-| `composer_review` | agy | Direct diff-review lane. Ask it to run repo-appropriate targeted checks off-CC; use a reviewer model different from the author for cross-model rigor (e.g. GLM writes → agy reviews). |
-| `composer_review_claude` | Claude Code CLI | Premium second-opinion review for high-risk/security-sensitive diffs or explicit user requests. Default config runs bounded `claude -p --model opus` with read/test tools only and `--max-budget-usd 0.50`. |
+## Real-world scenarios
 
-**Why "off-CC" matters:** GLM (z.ai), Codex, and agy run on *separate* quotas. Generating and *applying* code in their own context — not returning text the main Claude session must re-ingest — is what actually preserves your Max5 quota. The eval harness scores on **total-CC tokens** (every Claude model in a run = real Max5 burn), with a correctness gate (tsc/tests) and N-run averaging.
+### 1. Build a feature without burning the main context
 
-## Install
+```text
+You describe the feature
+→ Claude Code creates a compact handoff
+→ Codex implements with composer_code_cli
+→ agy reviews with composer_review
+→ Claude Code integrates only the summary and decisions
+```
+
+### 2. Use ChatGPT Pro only when it is worth the wait
+
+```text
+Architecture unclear?       → composer_oracle_plan(mode="deep")
+Hard root cause?            → composer_oracle_plan(mode="debug")
+Large risky diff?           → composer_oracle_plan(mode="review")
+Long research, not urgent?  → composer_oracle_job_start + composer_oracle_job_result
+Routine docs lookup?        → composer_research, not Oracle
+```
+
+Oracle is deliberately opt-in. It drives a real ChatGPT Pro browser session through `steipete/oracle`, so it is slower and should be used for high-value reasoning, not every small question.
+
+### 3. Keep commits gated
+
+```text
+Claude-issued git commit      → PreToolUse pre-commit gate can deny
+Manual terminal git commit    → install the real .git/hooks/pre-commit bridge
+CI / protected branch         → recommended final backstop
+```
+
+### 4. Recover when a bug fight stalls
+
+```text
+1 failed fix          → inspect locally and retry normally
+2+ failed attempts    → Codex lifecycle/rescue or Oracle debug
+Patch produced        → composer_review before reporting done
+```
+
+## Quick start
+
+### Install
 
 ```bash
-# 1. Install the MCP server
 npm install -g agent-composer
+```
+
+### Recommended global setup
 
-# 2. Bootstrap a project (creates composer.config.json + .env.json template +
-#    .gitignore + .claude/settings.json with mcpServers.composer entry)
+Use this when you want Composer available from many projects.
+
+```bash
+agent-composer init --global
+$EDITOR ~/.config/composer/.env.json
+agent-composer doctor
+```
+
+Then launch Claude Code from any repo:
+
+```bash
+claude
+```
+
+### Project-local setup
+
+Use this when a repo needs its own provider routing or stricter gates.
+
+```bash
 cd your-project
 agent-composer init
+$EDITOR .env.json
+agent-composer doctor
+```
 
-# 3. Fill credentials
-$EDITOR .env.json    # ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN
+### Optional ChatGPT Pro / Oracle setup
 
-# 4. Install the plugin (manual until Claude Code plugin marketplace lands)
-mkdir -p ~/.claude/plugins
-git clone <this-repo> /tmp/composer
-cp -R /tmp/composer/plugin/composer-mastermind ~/.claude/plugins/
+Oracle is not enabled by default.
 
-# 5. Launch
-claude
+```bash
+cd your-project
+agent-composer init --oracle
+scripts/oracle-pro-safe.sh --mode quick -- "Say OK."
+agent-composer doctor
+```
+
+The first real Oracle run may open a browser for login. Complete the ChatGPT login once, then rerun the smoke test. The adapter probes optional Oracle browser flags before using them, so it should degrade gracefully across compatible Oracle builds.
+
+## Cheat sheet
+
+### User prompts
+
+| What you want                      | Say this                                                     |
+| ---------------------------------- | ------------------------------------------------------------ |
+| Normal code change                 | “Implement this using Composer.”                             |
+| Multi-file feature                 | “Create a handoff, implement via Codex, then review.”        |
+| Current docs or API lookup         | “Use `composer_research` first.”                             |
+| Hard architecture planning         | “Use `composer_oracle_plan` with mode `deep`.”               |
+| Risky diff review                  | “Run `composer_review`, then Oracle review if risk remains.” |
+| Stuck debugging                    | “Use Oracle debug after the failed attempts.”                |
+| Do not block while Oracle thinks   | “Start an async Oracle job and poll it later.”               |
+| Premium Claude review              | “Escalate to `composer_review_claude`.”                      |
+| Toggle Composer enforcement        | `/composer disable` (this session) · `/composer enable` · `/composer status` |
+
+### MCP tools
+
+| Tool                              | Use it for                                                                |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| `composer_handoff_create`         | Create a compact shared packet for multi-agent work.                      |
+| `composer_research`               | Fast docs/current-context lookup through the researcher role.             |
+| `composer_code_cli`               | Default code-edit lane. Codex/CLI executor writes files directly.         |
+| `composer_code_chain`             | GLM writes complete file blocks; Composer applies them deterministically. |
+| `composer_code`                   | Legacy patch/text-only GLM lane. Rare fallback.                           |
+| `composer_review`                 | Default diff review lane.                                                 |
+| `composer_review_claude`          | Expensive second-opinion review.                                          |
+| `composer_oracle_plan`            | Synchronous ChatGPT Pro planning/review/debug lane.                       |
+| `composer_oracle_job_start`       | Non-blocking Oracle job for long work.                                    |
+| `composer_oracle_job_result`      | Poll/read an Oracle job result.                                           |
+| `composer_codex_lifecycle_decide` | Cheap policy decision: skip, ask, or run Codex.                           |
+| `composer_codex_lifecycle_run`    | Run an advisory Codex lifecycle checkpoint.                               |
+| `composer_codex_lifecycle_result` | Read a lifecycle checkpoint result.                                       |
+| `composer_route_decide`           | Choose the next Composer lane for a task.                                 |
+| `composer_workflow_plan`          | Produce an ordered workflow plan for multi-step work.                     |
+| `composer_audit_record`           | Append a structured audit event.                                          |
+| `composer_audit_read`             | Read recent audit events for project context.                             |
+| `composer_audit_summary`          | Summarize recent routing, review, test, and outcome audit events.         |
+| `composer_session_get`            | Inspect the current Composer session settings.                            |
+| `composer_session_set`            | Update session-local mode, oracle, or profile settings.                   |
+| `composer_status`                 | Read config, integration, activity, and recommendation status.            |
+| `composer_goal_start`             | Start one project goal with objective, condition, checks, and budget.     |
+| `composer_goal_status`            | Inspect active or named goal state and next advisory action.              |
+| `composer_goal_step`              | Advance the advisory goal loop from deterministic check results.          |
+| `composer_goal_clear`             | Cancel or clear a project goal record.                                    |
+| `composer_config_get`             | Inspect active/project/global Composer config.                            |
+| `composer_config_set`             | Safely patch lifecycle and review-gate settings.                          |
+
+### Oracle force tags
+
+Use these when you want deterministic routing inside an Oracle prompt or wrapper:
+
+```text
+[oracle:quick]      Small sanity check through ChatGPT web.
+[oracle:standard]   Moderate design question.
+[oracle:deep]       Feature planning, architecture, migration design.
+[oracle:plan]       Same as deep, but semantically a plan.
+[oracle:review]     High-risk design or diff review.
+[oracle:debug]      Hard root-cause analysis.
+[oracle:research]   Slow research/synthesis.
+[oracle:async]      Orchestrator hint: use the async Oracle job tools.
+[codex]             Keep it on the cheaper Codex lane.
 ```
 
-Verify the orchestrator skill loaded:
+## Daily workflows
+
+### Feature work
 
+```text
+1. composer_handoff_create
+2. composer_research if current docs/API context is needed
+3. composer_oracle_plan(mode="deep") only if architecture is unclear
+4. composer_code_cli to implement
+5. composer_review on the diff
+6. targeted tests / typecheck
+7. optional composer_review_claude for high-risk changes
 ```
-/composer-mastermind
+
+### Hard debugging
+
+```text
+1. Capture the smallest failing command/output.
+2. Try the obvious local fix once.
+3. After repeated failure, call composer_oracle_plan(mode="debug") or Codex rescue.
+4. Feed the diagnosis to composer_code_cli.
+5. Run tests and composer_review.
 ```
 
-Smoke-test the self-evolution loop:
+### Review before merge
 
+```text
+Routine diff         → composer_review
+Large/risky diff     → composer_review + composer_oracle_plan(mode="review")
+Security-sensitive   → composer_review + composer_review_claude, optionally Oracle review
 ```
-/evolve --eval-mode synthetic
+
+### Long research
+
+```text
+Blocking decision     → composer_oracle_plan(mode="research")
+Useful but not urgent → composer_oracle_job_start(mode="research"), then poll result
+Routine lookup        → composer_research
 ```
 
+## Architecture
+
+```mermaid
+flowchart TD
+    U[You] --> CC[Claude Code main session<br/>orchestrator: plan, integrate, decide]
+    CC -->|MCP tools| MCP[Composer MCP server]
+    MCP --> R[composer_research → researcher]
+    MCP --> CODE[composer_code_cli / code_chain → coder / coderCli]
+    MCP --> REV[composer_review / review_claude → reviewer]
+    MCP --> HO[composer_handoff_create → .composer/handoffs/]
+    MCP --> OR[composer_oracle_plan / job_* → oraclePlanner]
+    R --> P1[Codex / GLM research]
+    CODE --> P2[Codex / GLM apply files in repo]
+    REV --> P3[agy / Claude review]
+    OR --> P4[ChatGPT Pro via steipete/oracle browser]
+    P2 -->|bounded summary| CC
+    P3 -->|verdict| CC
+    P4 -->|advisory plan| CC
+    CC --> G[Gates: boundary_guard · codexReview · git hook · doctor]
+```
+
+### Main components
+
+| Path                          | Purpose                                                               |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `src/server.ts`               | Registers Composer MCP tools.                                         |
+| `src/providers/`              | Provider adapters: CLI, Anthropic-compatible, mock.                   |
+| `src/util/`                   | Handoffs, lifecycle jobs, Oracle jobs/locks, dispatch hints, helpers. |
+| `plugin/composer-mastermind/` | Claude Code plugin: skill, subagents, hooks, `/evolve`.               |
+| `scripts/`                    | Oracle adapters, review hooks, release/dev helpers.                   |
+| `docs/adr/`                   | Architecture decisions and append-only contracts.                     |
+| `tests/`                      | Vitest, hook tests, script tests.                                     |
+
+### Execution model
+
+Composer has one invariant:
+
+> The main Claude session coordinates. Worker lanes execute. Review gates decide whether work is good enough.
+
+That means:
+
+- Claude Code should plan, inspect, verify, and integrate.
+- File writes should go through `composer_code_cli` or `composer_code_chain`.
+- Review should run through a different model/provider than the author whenever practical.
+- Oracle is advisory only; it never edits files.
+- Background jobs are persisted as state records, but Oracle async jobs are server-lifetime, not OS-detached workers.
+
+### Bounded execution
+
+Every dispatch the main Claude session awaits has a hard deadline and is cancellable; no lane can block the brain indefinitely.
+
+| Surface | Bound |
+| ------- | ----- |
+| Providers | Internal default timeout plus the caller's `AbortSignal`. CLI providers bound total wall-clock across retries and kill the child process tree on timeout. |
+| Background jobs | Oracle, review, and Codex lifecycle jobs run under wall-clock deadlines, propagate brain cancellation, and flush to a terminal state on server `SIGTERM`. |
+| Status | Persistence is async and best-effort, off the event loop. Startup prunes stale in-flight entries after `COMPOSER_ACTIVE_RUN_TTL_MS` (default 2h). |
+| Hooks | `boundary_guard`, `dispatch_guard`, precommit, and `learn` run with bounded timeouts and fail closed. |
+| Config | Role `timeoutMs` values in `composer.config.json` override sane defaults. |
+
+### Live status
+
+Active Composer runs are tracked in `~/.composer/state/active-runs.json`, enriched with the tool, provider label/role, phase, detail, and start time. Two surfaces consume it:
+
+- `composer_status` reports in-flight runs with elapsed time, provider, and phase.
+- `scripts/composer-statusline-segment.mjs` renders a compact statusline segment (e.g. `⚡composer: review(glm) 2m`) for the terminal status bar.
+
 ## Configuration
 
-Two files at the consumer-project root, both gitignored or partially gitignored:
+Composer reads config from the active project first, then from the global Composer config when no project config exists.
 
-**`composer.config.json`** (committed) — provider routing + spend caps:
+`composer.config.json` is hot-reloaded on every provider dispatch, so role, lifecycle, and review-gate edits take effect without restarting the MCP server.
+
+| File                    | Purpose                                                                    |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `composer.config.json`  | Provider roles, lifecycle policy, review-gate settings. Usually committed. |
+| `.env.json`             | Provider credentials. Never commit.                                        |
+| `.claude/settings.json` | Claude Code MCP server wiring and hooks.                                   |
+
+### Minimal provider roles
 
 ```json
 {
   "roles": {
-    "researcher": { "provider": "cli", "cli": ["codex", "--search", "--ask-for-approval", "never", "exec", "--ephemeral", "--sandbox", "read-only"], "timeoutMs": 180000, "retries": 0 },
-    "coder":      { "provider": "anthropic", "baseUrl": "https://api.z.ai/api/anthropic", "apiKeyEnv": "ANTHROPIC_AUTH_TOKEN" },
-    "coderCli":   { "provider": "cli", "cli": ["codex", "exec", "--ephemeral", "--sandbox", "workspace-write", "-c", "approval_policy=\"never\"", "-c", "model_reasoning_effort=\"medium\""], "timeoutMs": 900000, "retries": 0 },
-    "reviewer":   { "provider": "cli", "cli": ["agy", "--dangerously-skip-permissions", "--print-timeout", "90s", "-p"], "timeoutMs": 120000, "retries": 0 },
-    "reviewerClaude": {
+    "researcher": {
+      "provider": "cli",
+      "cli": ["codex", "--search", "--ask-for-approval", "never", "exec", "--ephemeral", "--sandbox", "read-only"],
+      "timeoutMs": 180000,
+      "retries": 0
+    },
+    "coder": {
+      "provider": "anthropic",
+      "baseUrl": "https://api.z.ai/api/anthropic",
+      "apiKeyEnv": "ANTHROPIC_AUTH_TOKEN"
+    },
+    "coderCli": {
       "provider": "cli",
-      "model": "claude-opus-review",
-      "cli": ["claude", "-p", "--model", "opus", "--permission-mode", "bypassPermissions", "--setting-sources", "project", "--disable-slash-commands", "--no-session-persistence", "--max-budget-usd", "0.50", "--tools", "Read,Glob,Grep,Bash", "--allowedTools", "Read,Glob,Grep,Bash(npx tsc --noEmit),Bash(npm test),Bash(npm run test:*),Bash(npx vitest*)"],
-      "timeoutMs": 300000,
+      "cli": ["codex", "exec", "--ephemeral", "--sandbox", "workspace-write", "-c", "approval_policy=\"never\"", "-c", "model_reasoning_effort=\"medium\""],
+      "timeoutMs": 900000,
       "retries": 0
+    },
+    "reviewer": {
+      "provider": "cli",
+      "cli": ["agy", "--dangerously-skip-permissions", "--print-timeout", "110s", "-p"],
+      "timeoutMs": 120000,
+      "retries": 1
     }
-  },
-  "spendAuthorization": {
-    "mode": "interactive",
-    "maxUsdPerCall": 0.50,
-    "maxUsdPerSession": 5.00
   }
 }
 ```
 
-For the old agy-only coding path, set `coderCli.cli` back to
-`["agy", "--dangerously-skip-permissions", "-p"]`. For the old agy-only
-research path, set `researcher.cli` to the same agy argv. The provider
-contract does not change; Codex is piloted as the existing CLI executor.
-When `coderCli` or `researcher` use `codex ... exec`, Composer captures
-Codex's final message with `--output-last-message` automatically, so the
-main session receives a short outcome instead of raw event output. Composer
-refuses explicit `codex exec --sandbox danger-full-access` and
-`--dangerously-bypass-approvals-and-sandbox` configs by default; set
-`COMPOSER_ALLOW_DANGEROUS_CODEX=1` only inside an external sandbox.
-The default Codex coding lane sets `timeoutMs` to 15 minutes and overrides
-the nested Codex run to `model_reasoning_effort="medium"` so it does not
-inherit slower global high-effort settings intended for the main orchestrator.
-Keep `reviewer` as the default gate. Use `reviewerClaude` only when the user
-asks for Claude review or when a risky diff needs an expensive second opinion.
-
-### Fast direct-tool mode
-
-Composer keeps the CLI executor path, but the plugin now treats it more like a
-small SDK harness:
-
-- `composer_code_cli` is the default edit lane; the legacy `coder` subagent is
-  only for rare patch-only GLM fallback.
-- `composer_research`, `composer_review`, and `composer_review_claude` can be
-  called directly because their providers already run off the main Claude Code
-  context and return bounded summaries.
-- The `researcher`, `reviewer`, and `reviewer-claude` subagents remain available
-  when raw upstream output is expected to be large enough to need an isolated
-  wrapper context.
-- CLI calls append best-effort timing records to
-  `/tmp/composer-cli-usage.jsonl`; GLM calls append timing/cache records to
-  `/tmp/composer-glm-usage.jsonl`. These files contain durations and character
-  counts plus success/error status, not prompts.
-
-**`.env.json`** (NEVER commit) — credentials only:
+Currently wired provider IDs are `mock`, `anthropic`, and `cli`. The schema reserves `openai_compatible`, but the runtime does not yet implement that adapter.
+
+### Optional Oracle role
+
+Created by `agent-composer init --oracle`:
 
 ```json
 {
-  "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
-  "ANTHROPIC_AUTH_TOKEN": "<your-glm-or-anthropic-compatible-token>"
+  "roles": {
+    "oraclePlanner": {
+      "provider": "cli",
+      "cli": ["bash", "scripts/oracle-plan-mcp.sh", "--mode", "auto", "--"],
+      "timeoutMs": 1200000,
+      "retries": 0,
+      "maxResultChars": 14000
+    }
+  }
+}
+```
+
+Keep `researcher` on Codex. Oracle is for opt-in planning/review/debugging, not routine search.
+
+### Codex lifecycle policy
+
+`codexLifecycle` controls advisory Codex participation at lifecycle points such as post-plan, post-code, test failure, or repeated failed attempts.
+
+```json
+{
+  "codexLifecycle": {
+    "enabled": true,
+    "mode": "ask",
+    "execution": "background",
+    "model": "gpt-5.4-mini",
+    "triggers": {
+      "postPlan": true,
+      "postCodeApply": true,
+      "postTestFailure": true,
+      "afterFailedAttempts": true,
+      "preCommit": false,
+      "stopWarm": false
+    },
+    "thresholds": {
+      "minScore": 60,
+      "minExpectedOutputTokens": 500,
+      "minChangedFiles": 2,
+      "minDiffLines": 80,
+      "failedAttempts": 2
+    },
+    "fallback": {
+      "enabled": true,
+      "order": ["reviewerClaude", "reviewer", "coder"]
+    }
+  }
 }
 ```
 
-The MCP server reads `.env.json` via `fs.readFileSync` — it is **never** exposed to the orchestrator session.
+Lifecycle runs are advisory. They should not silently mutate files; apply suggestions through the normal code lane and review them.
+
+### Codex review gate
 
-### Soft-disable Composer
+`codexReview` controls optional cross-LLM review and pre-commit gating.
+`codexReview.preCommitHook.maxConsecutiveBlocks` is an escape hatch for review-gate oscillation. Keep it unset by default. When set to `N` (> 0), after `N` consecutive blocks on the same branch the gate allows the commit once, emits an audited `allow-cap` event, and resets the counter.
 
-Composer hooks can be disabled without editing Claude Code settings:
+```json
+{
+  "codexReview": {
+    "enabled": true,
+    "preCommitCommand": "adversarial-review",
+    "scope": "auto",
+    "model": "gpt-5.5",
+    "preCommitHook": {
+      "enabled": true,
+      "blockOnSeverity": "high",
+      "timeoutMs": 900000,
+      "failClosed": true
+    },
+    "warmCache": {
+      "enabled": true,
+      "maxAgeMinutes": 30
+    }
+  }
+}
+```
+
+To gate manual terminal commits, install the real Git hook bridge:
 
 ```bash
-# Disable for one launch
-COMPOSER_ENABLED=0 claude
+printf '#!/usr/bin/env bash\nexec "$(git rev-parse --show-toplevel)/scripts/precommit_codex_review.sh" --git-hook\n' \
+  > .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+`git commit --no-verify` still bypasses local Git hooks. Use CI and branch protection when every commit path must be enforced.
+
+### Spend and consent policy
 
-# Disable globally for already-configured hooks
-touch ~/.claude/composer.disabled
+`spendAuthorization` is a routing/consent policy exposed to the orchestrator and config tools.
 
-# Re-enable globally
-rm -f ~/.claude/composer.disabled
+```json
+{
+  "spendAuthorization": {
+    "mode": "interactive",
+    "maxUsdPerCall": 0.5,
+    "maxUsdPerSession": 5.0
+  }
+}
 ```
 
-Project-local disable is also supported with `touch .composer-disabled`.
-For scripts or tests, set `COMPOSER_DISABLED_FILE=/path/to/sentinel`.
-This disables Composer hooks immediately. To fully suppress skill autoload,
-also set `"composer-mastermind": "off"` in Claude Code `skillOverrides` and
-restart CC.
+CLI providers such as Codex and `agy` are billed by their own authentication and do not share a universal billing meter with Composer. Keep provider budgets conservative and use `agent-composer doctor` before relying on gates.
 
-## How dispatch works
+### Config tools
 
-Inside a Claude Code session, dispatch flow:
+Inside Claude Code, prefer MCP config tools over hand-editing JSON:
 
+```text
+composer_config_get(scope="active")
+composer_config_set(scope="project", codexLifecycle={...})
+composer_config_set(scope="project", codexReview={...})
 ```
-User asks for code work
-   ↓
-Composer-mastermind SKILL.md picks a direct MCP tool or fallback subagent
-   ↓
-Direct MCP call → composer_code_cli / composer_research / composer_review
-or Task fallback → coder.md / researcher.md / reviewer.md / reviewer-claude.md
-   ↓
-MCP server routes to GLM (anthropic) or Codex/agy CLI per composer.config.json
-   ↓
-Provider returns bounded summary; orchestrator integrates
+
+`composer_config_set` intentionally accepts narrow patches for lifecycle and review-gate settings, validates the result, and refuses implicit writes to the global fallback path.
+
+## Trust, security, and limits
+
+Composer is designed for supervised local development.
+
+### Global enforcement
+
+The boundary_guard hook is installed once at the user level and applies in every repository. The main Claude session cannot call `Edit`/`Write`/`Update`/`NotebookEdit` directly anywhere — those route through `composer_code_cli` / `composer_code_chain`. Enforcement defaults to ON and is gated only by kill switches, read fresh on every tool call (no restart needed):
+
+| Switch | Scope | Effect |
+| ------ | ----- | ------ |
+| `~/.claude/composer.disabled` | Global | Suspends enforcement in all repos. Toggle with `/composer disable` / `/composer enable`. |
+| `$CLAUDE_PROJECT_DIR/.composer-disabled` | Per-repo | Opts a single repo out of enforcement. |
+| `COMPOSER_DANGEROUSLY_BYPASS_PERMISSIONS=1` | Process env | Lets authorized headless jobs/workers author files directly. Dev-only escape hatch. |
+
+The `/composer` slash command (`enable` / `disable` / `status`) flips `~/.claude/composer.disabled` live. It affects hook enforcement only — it does not stop or reconfigure the MCP server.
+
+### What is mechanically enforced
+
+- `boundary_guard.sh` denies main-thread file mutation tools and MCP write/edit/exec wrappers in every repo (global user-level hook), fails closed on malformed input, and canonicalizes paths via the nearest existing ancestor so new-directory writes are not false-gated.
+- `composer_code_chain` rejects path traversal and symlink escapes before applying files.
+- `CLIProvider` uses argv arrays, not shell interpolation, and refuses dangerous Codex sandbox configs by default.
+- Codex pre-commit gates can fail closed in Claude Code hook mode and terminal git-hook mode.
+- Oracle browser runs are protected by a single-holder lock and stored under local Composer state / `.composer/oracle/` artefacts.
+- Provider execution, polling loops, CLI retries, the Codex lifecycle chain, Oracle jobs, and hook/reaper/lock runtimes are all time-bounded with cancellation propagated, so a stuck worker cannot hang the main session.
+
+### What still needs project discipline
+
+- Use branch protection / CI for `git commit --no-verify` or pushes from outside the local workflow.
+- Do not pass secret files to Oracle or any external provider.
+- Treat Oracle browser automation as a personal, supervised workflow, not a high-volume API.
+- Review all code changes before reporting success.
+
+### Local artefacts to keep out of Git
+
+At minimum:
+
+```gitignore
+.env.json
+.composer/handoffs/
+.composer/codex-lifecycle/
+.composer/oracle/
+.composer/results/
+.composer/briefs/
 ```
 
-Composer also emits a deterministic dispatch hint for `Task`/`Agent` calls
-when `scripts/dispatch_guard.sh` is installed. The hint classifies the
-request before the worker starts, so the orchestrator can choose a cheaper
-lane when the task is simple and reserve expensive paths for the cases that
-need isolation or extra reasoning.
-
-| Task shape | Default route |
-|---|---|
-| Tiny rename/comment/non-mutating request | Inline |
-| Small self-contained diff review | Inline review |
-| File mutation with path references | `composer_code_cli` |
-| Research-first implementation | `composer_research`, then `composer_code_cli` |
-| Security or large review | `composer_review` first; escalate to `composer_review_claude` only when needed |
-| Explicit premium/Claude review | `composer_review_claude` |
-
-## Measuring trust
-
-Composer's route-confidence harness compares the same tasks across direct
-Claude, GLM-chain, and Codex-CLI routes. The `cc-only` route removes the
-worktree-local `.claude/` directory before running so the project plugin does
-not bias the baseline. It writes JSONL records with
-success, route adherence, typecheck status, changed-file count, wall time,
-and **total Claude Code tokens** from `modelUsage`.
+## Doctor and validation
+
+Run this whenever setup feels suspicious:
 
 ```bash
-# Build first so the MCP server entry exists.
-npm run build
+agent-composer doctor
+```
 
-# Run one representative task across all routes, three replicas each.
-npm run eval:routes -- --task t8-csv-module --runs 3
+Add `--json` for a machine-readable report (full JSON on stdout; exit 0 = healthy, exit 1 = unhealthy):
 
-# Re-summarize an existing JSONL file without spending more tokens.
-npm run eval:routes -- --summary-only --input /tmp/composer-route-runs.jsonl
+```bash
+agent-composer doctor --json
 ```
 
-The headline checks are: `composer-codex-cli` should preserve or improve
-success/typecheck rate while lowering median total-CC tokens versus
-`cc-only`; `routeHonored` must stay high enough to prove the orchestrator is
-actually using the route under test.
+Useful local checks for contributors:
 
-Five resilience layers ensure unattended `/evolve` runs cannot damage the host repo:
-
-1. **Sandbox isolation** — each per-task eval runs in a throwaway `git worktree` at `/tmp/composer-eval-<pid>-<taskId>`
-2. **Per-task fault isolation** — one task's spawn failure records `score: 0` and continues
-3. **Stat-gate precondition guards** — Wilcoxon paired-test skips when arrays are asymmetric
-4. **Spawn diagnostics** — stderr/stdout tail appended to error messages
-5. **Per-task wall-time bound** — `execFile` `timeout: 180_000` with SIGTERM; absorbed by layer 2
+```bash
+npm run typecheck
+npm run test
+npm run test:hooks
+npm run test:scripts
+npm run schema:lint
+```
 
-## Security model
+Oracle-specific smoke tests:
 
-- **`agent-composer` publish surface**: `dist/`, `plugin/`, `composer.config.schema.json`, `README.md`, `package.json`. No tests, no source, no `.env*` (gitignored). Current npm dry-run package size is 84.4 KB.
-- **Spend caps**: per-call (`maxUsdPerCall`, default $0.50) and per-session (`maxUsdPerSession`, default $5.00) enforced in the runner before any external API call. Configurable per project.
-- **Self-evolution scope** (see ADR 0003): five layers gate any SKILL.md mutation — diff-path regex, text deny-list, stat gate, human-promote-only, audit trail. Auto-promote is permanently off the table.
-- **Boundary hook**: PreToolUse fail-closed denial of `Edit`/`Update`/`Write`/`NotebookEdit` in the orchestrator session, plus MCP write/edit/exec variants. Native Bash is allowed for inspection and verification. The C0.5 subagent tools allowlist is append-only.
+```bash
+scripts/oracle-pro-safe.sh --dry-run --mode quick -- "Smoke test. Say OK."
+scripts/oracle-pro-safe.sh --mode quick -- "Say OK and identify the mode/model."
+```
 
-## Contributing
+## Project layout
+
+```text
+agent-composer/
+├── src/
+│   ├── server.ts                 # MCP tool registration
+│   ├── providers/                # CLI / Anthropic-compatible / mock providers
+│   ├── config/                   # config loader, paths, schema mirror
+│   ├── cli/                      # init, doctor, dispatch hint helpers
+│   └── util/                     # handoffs, jobs, locks, routing, apply helpers
+├── plugin/composer-mastermind/   # Claude Code plugin, skill, subagents, hooks
+├── scripts/                      # Oracle adapters, review gates, release helpers
+├── docs/adr/                     # architecture decisions
+├── tests/                        # Vitest, hook, and script tests
+└── composer.config.schema.json   # user-facing config schema
+```
 
-Clone, install, run tests:
+## Development
 
 ```bash
-git clone <this-repo>
-cd composer
+git clone https://github.com/xicv/agent-composer.git
+cd agent-composer
 npm install
-npx tsc --noEmit                                # type check
-./node_modules/.bin/vitest run                  # 435 tests
-./node_modules/.bin/ajv validate \              # schema lint
-  --strict=false -c ajv-formats \
-  -s composer.config.schema.json \
-  -d composer.config.json
+npm run typecheck
+npm run test
+npm run test:hooks
+npm run test:scripts
+npm run schema:lint
+npm run build
 ```
 
-Per-task layer reference docs (in the source tree):
+Before publishing or merging a large routing change, run a real dogfood task through:
+
+```text
+handoff → code_cli → review → targeted tests → doctor
+```
 
-- `docs/STATUS.md` — current state + dogfood audit log + every /evolve run
-- `docs/multi_agent_orchestration_plan.md` — architecture
-- `docs/tdd_plan.md` — build sequence + quality rubric
-- `docs/self_evolving_composer.md` — autonomous skill evolution (T1/T2/T3)
-- `docs/adr/0001-contracts.md` — frozen C0.1–C0.5 contracts (append-only)
-- `docs/adr/0002-meta-mcp.md` — Wave 4 packaging contract (M0.1–M0.5)
-- `docs/adr/0003-self-evolution.md` — self-evolution mutation scope (S1–S5)
+## Design principles
 
-The `/evolve` loop is a GEPA-style reflective optimizer: it evaluates the parent skill, captures **failing-task transcripts**, and routes them into mutation operators (`add_counterexample` / `add_constraint` / `add_negative_example` / `reflect_and_rewrite`) so each candidate is shaped by real failures. A no-op guard skips mutations that produce no change. Recommended supervised invocation: `--eval-mode real --length-lambda 0.0001 --replicas 3 --tasks <code subset>`. It mutates only the project-local `.claude/skills/composer-mastermind/SKILL.md`, writes `SKILL.candidate.md` for **manual review** (auto-promote is permanently off), and the published plugin install is read-only. Release sync from dev to plugin happens via `scripts/release-sync.mjs --bump <semver>`.
+1. **One brain, many workers.** The orchestrator owns intent; providers own execution.
+2. **Offload complete work, not fragments.** Prefer workers that apply files and return summaries.
+3. **Review with a different model.** Author and reviewer should usually be different providers.
+4. **Keep Oracle rare and valuable.** ChatGPT Pro is for hard reasoning, not routine lookup.
+5. **Make state durable and inspectable.** Handoffs, jobs, answers, and reviews should have paths.
+6. **Prefer opt-in gates.** Strong gates are available, but users choose the strictness per repo.
+7. **Never hide uncertainty.** Failed providers, skipped reviews, and orphaned jobs should surface as records, not disappear.
 
 ## License