leos-agent 10.7.2 → 12.2026090800.0

package/README.md

@@ -1,718 +1,287 @@
 # leos-agent
 
-Leo's portable agent operating policy, version **10.7.2**, installable on Claude
-Code, Codex, Cursor, Hermes, Pi, and OpenCode through each harness's own plugin
-system.
-
-The policy it carries is short: **the main thread is an orchestrator.**
-Investigation, brainstorming, debugging, and mechanical work all run in briefed
-subagents, so the main thread never fills up with the files, retries, and logs
-that produced an answer — only the answer. A single command you can filter at
-the shell stays inline. Work runs at one of two named tiers: **standard**, the
-model you are already using, for thinking and judging; **economical**, two
-named agent profiles — `leo-runner` for narrow search, reading, testing, and
-mechanical work, `leo-executor` for well-specified implementation — shipped as
-first-class agent definitions on both Claude Code (`agents/`, Haiku and Sonnet)
-and Codex (installed TOML profiles), so the cheaper model is baked into the
-agent type rather than chosen per dispatch. Every other harness inherits unless
-a machine-local [routing config](#per-machine-model-routing) names models for it.
-
-## What it ships
-
-Beyond the preferences payload: the two economical-tier agent definitions
-(`agents/` for Claude Code, `payload/codex-agents/` for Codex), a setup
-diagnostic, a routing tuner, a session handoff pair, and three GitHub skills.
-The GitHub ones need `gh`, authenticated.
-
-| Skill | What it does | Where |
-|---|---|---|
-| `review-pr` | Reviews a pull request and stages inline comments as a **pending** review — visible only to you until you submit or discard on GitHub. Never submits. Resolves the originating ticket (Linear, Jira, GitHub issue) from the PR's title, body, or branch when one is named, and adds a spec lens that checks the diff against it. | every skill-loading harness |
-| `watch-review` | Arms a watcher that streams direct review requests into the session for `review-pr` to handle, and re-streams one when its head moves. Never surfaces a pull request someone else has approved. Polling is a shell script (`scripts/watch_review.py`), not a model loop: an idle tick is one `gh` call and zero tokens. | **Claude Code only** — built on its Monitor tool |
-| `doctor` | Diagnoses this harness's setup, read-only: whether the `<leos-agent>` block is injected and current, what else is loaded into every session (global instruction file, memories, settings, skills), and whether a local checkout passes `scripts/check.py`. Run it with `/doctor`. | every skill-loading harness |
-| `tune-routing` | Picks the concrete models behind `leo-runner` and `leo-executor` on this machine, writes them to `~/.leos-agent-local/routing.json`, re-renders the install, and proves the choice with one live dispatch — model strings are never checked against a known-model list, so a typo surfaces at dispatch time and nowhere earlier. Run it with `/tune-routing`. | every skill-loading harness |
-| `review-usage` | Reads many sessions across every harness on this machine — a time window, not one session — and reports where the tokens went and how well the policy actually held: routing compliance, guard blocks and whether they were re-dispatched, over- and under-delegation, cache health. The scan is a script, not a prompt, so it costs a second rather than a model's worth of transcript reading. Run it with `/review-usage`. | every skill-loading harness |
-| `handoff` | Writes this session's context — goal, what landed, what is next, key files, decisions, gotchas — to a markdown document under `~/.leos-agent-local/handoffs/`, so a later session can pick the work up. Pointers, not contents: it names files rather than pasting them. Run it with `/handoff`. | every skill-loading harness |
-| `handon` | Loads a handoff written earlier — in this harness or a different one — and resumes from it, reporting any drift first when the directory, branch, or HEAD has moved since. Loading never consumes a handoff. Run it with `/handon <name>`. | every skill-loading harness |
-| `attach-pr` | Attaches the current desktop session to an existing pull request so the app shows its PR card. Creates nothing and pushes nothing. | **Claude Code only** — it drives that app's card |
-
-The Claude-only pair live in `skills-claude/` and `commands-claude/`, listed in
-`.claude-plugin/plugin.json` and nowhere else. Hermes receives the preferences
-payload but no skills — it has no skill loader.
-
-The watcher records the **head commit** it reviewed each pull request at, under
-`~/.leos-agent-local/` (override with `$LEOS_AGENT_LOCAL_PATH`), so a pull
-request comes back when someone pushes to it and stays quiet otherwise;
-`watch_review.py forget <n>` puts one back in play at its current head. Two
-gates keep a continuous watch from being expensive: a pull request another user
-has already approved is never surfaced at all, and a new head must hold still
-for `--settle` seconds (default 120) before it is emitted, so a burst of pushes
-costs one review rather than one per commit.
-
-Handoffs live in the same place, at
-`~/.leos-agent-local/handoffs/<name>.md` — a fixed path that needs no plugin
-root, so `/handon` reads one with a single `cat` rather than going looking for
-it. Nothing there is ever pruned automatically: `handoff.py list [--all]` shows
-what exists and `handoff.py rm <name>` is the only way one goes away. The
-directory is deliberately outside the plugin, so upgrading or reinstalling can
-never take state with it.
-
-## Per-machine model routing
-
-The economical tier only ever had teeth on Claude Code and Codex, because those
-are the two harnesses whose model names the payload could hardcode. Everywhere
-else, every fan-out ran at the current model — the most expensive shape the
-policy has. Which models a harness offers varies by machine and by what an IT
-department allows, so the mapping is machine-local config rather than something
-the plugin can ship:
-
-```jsonc
-// ~/.leos-agent-local/routing.json  (override the directory with $LEOS_AGENT_LOCAL_PATH)
-{
-  "cursor":   {"runner": "grok-code-fast-1", "executor": "claude-sonnet-4.6"},
-  "opencode": {"runner": "anthropic/claude-haiku-4-5"},
-  "codex":    {"runner": {"model": "gpt-5.6-luna", "effort": "low"}}
-}
-```
-
-Keys are harness names; each holds `runner` and/or `executor`, independently —
-configuring only `runner` is the common case, since it is the fan-out that
-costs. A bare string is shorthand for `{"model": ...}`. Model strings are
-free-form and never checked against a known-model list: whatever the harness
-accepts goes in verbatim. A misspelled *key*, though, is a hard error, because a
-typo that silently left a harness on the expensive model is the one failure this
-is here to prevent.
-
-**Nothing reads it at run time.** `leo-install.py` renders the result into the
-`<leos-agent>` block it already writes, so a session pays nothing to know its own
-routing — no config read, no extra turn. It costs *less* than before: each
-machine now carries only its own harness's dispatch line instead of all of them,
-which took the installed payload from 4497 bytes to 4315–4344 depending on the
-harness. `scripts/measure_context.py` prints the per-harness figure and fails if
-an unconfigured harness ever grows past the old one.
-
-Edit the file — by hand, or with `routing.py set --harness <h> --runner
-<model>`, which [`/tune-routing`](#what-it-ships) drives end to end — then
-re-run the installer to re-render; `leo-install.py <harness> --check` reports
-"out of date" until you do, and `/doctor` surfaces it. Installing is
-idempotent: same config, same version, same bytes, so a second run reports
-`unchanged`.
-
-**The config is yours, never the installer's.** `leo-install.py` only ever reads
-it, and never creates, migrates, rewrites, or removes it, including under
-`--uninstall`; it lives outside the plugin so an upgrade cannot take it. The one
-thing that writes it is `routing.py set` / `unset`, run because you asked: it
-creates the file if it is missing, replaces the one role you named, validates
-the whole document before writing, and leaves every other harness's entry —
-including the bare-string shorthand — exactly as you wrote it. `routing.py show`
-prints what is configured; with no file at all, every harness uses its shipped
-default and behaviour is exactly what it was before this existed.
-
-Delivery differs by harness only in the last mile: Claude Code gets a `model:`
-override alongside `subagent_type:` (the plugin-owned `agents/*.md` are never
-rewritten), Codex gets the models substituted into its installed profile TOMLs,
-Cursor gets its own `~/.cursor/rules/leos-agent-routing.mdc` because its rules
-come straight out of the plugin directory, and the rest get the rendered line in
-their global instruction file.
-
-## The dispatch guard
-
-The payload has always said that a subagent dispatch must name a model. Prose
-alone did not hold: a forgotten dispatch inherits the parent's expensive model
-and pays a cold cache write per child, which is the single most expensive shape
-this policy has. From 10.7.2 that half of the rule is enforced by a hook instead,
-and the prose it replaced came out of the always-loaded payload — enforcement in
-code costs **zero** context per turn, so the guard paid for itself in bytes
-before saving a cent.
-
-`scripts/dispatch_guard.py` runs before a subagent dispatch and refuses exactly
-one thing: an agent selected with a brief, **no model named**, on a harness that
-can name one. Three ways to comply, all of them one word:
-
-| Instead of | Use | For |
-|---|---|---|
-| a generic agent, no model | `subagent_type: "leo-runner"` | reading, search, tests, logs, codemods, fan-out |
-| a generic agent, no model | `subagent_type: "leo-executor"` | an approved plan, a well-specified change |
-| a generic agent, no model | `model: "<name>"` | investigation and debugging — naming it *is* the stated reason |
-
-A plugin install namespaces the type — dispatch `leos-agent:leo-runner` rather
-than `leo-runner`; the guard accepts either.
-
-It never picks a model for you. It cannot force cheap work onto an expensive
-problem, so it cannot cause a quality regression — only an explicit choice. It
-is also deliberately narrow: a false block costs one re-dispatch, while a caught
-inherited fan-out saves the cold prefix of every child, so the margin only holds
-while the rule refuses to make judgment calls.
-
-Detection is by **argument shape**, not tool name: a dispatch is a call that
-selects an agent and carries a brief. A shape the guard does not recognise is
-left alone, so a harness it has never met keeps working. MCP tools are never
-guarded. Anything that goes wrong inside the guard allows the call and records
-`decision: "error"`, kept distinct from a decision to allow, because a guard
-that dies quietly is worse than no guard.
-
-```
-LEOS_AGENT_DISPATCH_GUARD=on       block (default)
-                          warn     record, never block
-                          off      disabled entirely
-                          verbose  also put the over-delegation notice in front of the model
-LEOS_AGENT_DISPATCH_LOG_PROMPTS=1  debug only: keep 200 chars of brief text in the log
-```
-
-**Per harness.** Claude Code dispatches `Agent` with `subagent_type`, and a
-plugin install namespaces it — both forms are tiers. Codex dispatches
-`spawn_agent`, which selects behaviour by `model` and `reasoning_effort` rather
-than by naming an agent, so there the guard requires `model`; its `message` is
-encrypted, so the over-delegation heuristic and block-conversion tracking do not
-apply on Codex. Hermes and OpenCode run the same policy in-process, blocking by
-directive and by throw respectively. Pi has no hook surface.
-
-**Codex hash-pins hooks.** A new version of the guard enforces nothing there
-until it is re-approved through `/hooks`, and the symptom is silence — zero
-Codex rows in `dispatch_log.py report`.
-
-### What it records
-
-`~/.leos-agent-local/dispatch.jsonl`, one line per dispatch, mode `0600`,
-rotated at 1 MiB with one generation kept — bounded at 2 MiB forever.
-
-It stores **no prompt text and no paths.** Prompts, sessions and working
-directories are truncated SHA-256. The prompt hash is what makes the report
-meaningful: a blocked brief whose hash comes back naming a tier is a block that
-worked, and one that never returns was abandoned work rather than a saving.
-Delete it whenever you like — nothing depends on its history.
-
-```bash
-python3 scripts/dispatch_log.py report
-python3 scripts/usage_scan.py --since 7d
-```
-
-## How it works
-
-The payload lives in exactly one file: [`rules/preferences.md`](rules/preferences.md).
-
-Cursor reads that file natively as an always-apply rule. Every other harness
-gets it through its global instruction file, written by
-[`scripts/leo-install.py`](scripts/leo-install.py) into a marker block:
-
-```
-<leos-agent version="10.7.2">
-...the payload...
-</leos-agent>
-```
-
-Updating replaces that block and nothing else, so anything you wrote in those
-files by hand survives an upgrade untouched. The script writes only when the
-bytes actually differ, so running it twice is a no-op, and it writes through a
-temporary file and an atomic rename, so an interrupted run cannot leave a
-half-written instruction file behind.
-
-If it ever finds markers it cannot pair — an opener with no closer, a stray
-closer, two blocks — it refuses to touch that file and tells you what to fix.
-Guessing there would mean deleting whatever sits between the markers, which is
-exactly the content it exists to protect.
-
-| Harness | Global file the installer writes |
-|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` (the `leo-runner` / `leo-executor` agents need no installer step — the plugin's `agents/` directory delivers them) |
-| Codex | `~/.codex/AGENTS.md` (plus `~/.codex/agents/leo-runner.toml` and `leo-executor.toml`) |
-| Cursor | none — the plugin's always-apply rule delivers it |
-| Hermes | `~/.hermes/SOUL.md` (edited only if it already exists) |
-| Pi | `~/.pi/agent/AGENTS.md` |
-| OpenCode | `~/.config/opencode/AGENTS.md` (plus copied skills and commands) |
-
-**The installer is per-harness and manual.** Running it inside Codex installs Codex and
-nothing else; it never writes to another harness's files behind your back, and
-it never runs on its own at session start. Install the plugin, then run the
-installer once in that harness.
-
-Requires Python 3.9+ and macOS, Linux, or WSL. No symlinks are used anywhere —
-installs are real clones and copies.
-
----
-
-## Claude Code
-
-**Install**
-
-```bash
+Cost-aware delegation and portable workflows for Claude Code, Codex, Cursor,
+OpenCode, Hermes, and Pi. Version **12.2026090800.0**.
+
+The main agent handles small work directly and delegates substantial, bounded
+work to the cheapest competent tier. The policy separates **whether to delegate**
+from **which model to use**. Native adapters check model costs where the harness
+exposes enough information, while skills load detailed procedures on demand.
+
+This is a useful direction when expensive parents otherwise do large amounts of
+routine work or spawn expensive children by inheritance. It can cost more when
+briefing, duplicated context, verification, and retries exceed the work saved.
+There is no claim of universal token reduction or measured savings without a
+comparable task baseline. Optimizing dollars can mean spending more tokens on
+a cheaper model while preserving quality.
+
+## Routing and cost
+
+| Tier | Appropriate work | Claude default | Codex default |
+|---|---|---|---|
+| Cheap | Bounded factual checks, mechanical work, known procedures | Haiku | GPT-5.6 Luna |
+| Standard | Investigation, implementation, diagnosis, ordinary review | Sonnet | GPT-5.6 Terra |
+| Parent-level | Work requiring the parent's capability | Current parent | Current parent |
+
+Native profiles are `leo-cheap`, `leo-standard`, `leo-parent`, and
+`leo-reviewer`. `leo-runner` and `leo-executor` remain legacy aliases. Review
+may use nested read-only lenses; ordinary workers do not delegate. Small
+reviews run locally, and larger reviews divide independent areas rather than
+requiring every lens to reread everything.
+
+The tier name is not a price ordering. For example, the bundled reference
+catalog prices Terra output above Sol output; the ceiling therefore replaces
+that selection with the current parent where supported. Input/output crossover
+rates, unknown IDs, and ambiguous catalog matches are allowed with diagnostics,
+as configured by this project's policy. Thus the ceiling prevents **known**
+overselection, not every possible billing outcome.
+
+Prices come from the public [OpenRouter model catalog](https://openrouter.ai/docs/guides/overview/models),
+including Claude, GPT, DeepSeek, Kimi, GLM, and Qwen families. Exact IDs and
+recognized aliases are preferred. Nearby versions of the same variant can use
+an explicitly labeled estimate; sizes, cheap/pro variants, and free endpoints
+are not conflated. A price alias never changes the identifier sent to a harness.
+Public prices do not establish account access, model availability, negotiated
+rates, or subscription-credit accounting.
+
+Refresh runs in ordinary code at installation/update and, when used, at most
+daily. It is bounded and runs separately from dispatch. Failed refreshes keep
+the last catalog and record a diagnostic. No dispatch performs network I/O or
+asks a model to look up prices. Set `LEOS_AGENT_PRICE_REFRESH=off` for offline
+operation.
+
+## Harness capabilities
+
+| Harness | Policy delivery | Model control | Important limit |
+|---|---|---|---|
+| Claude Code | SessionStart, including forks | Agent/Task argument correction; native profiles | Forced settings and provider/org substitutions can affect execution; observe child transcripts. |
+| Codex | Separate native SessionStart hook | Tier-enforcing explicit spawn selection; model-free native profiles | Hooks need native trust. Other/customized profiles can still override spawn settings. |
+| Cursor | Native always-apply rule | Installed user agents; resolved subagentStart model ceiling | No invented Task model argument; hook diagnostics distinguish planned models from completion. |
+| OpenCode | One registered rendered instruction | Native agent selection, confirmed through the SDK | Task has no model field; source/config paths must remain valid. |
+| Hermes | Frozen system-prompt section | Global native delegation-model ceiling when parent/model are observable | Native delegation has one global model, not separate per-task tiers. |
+| Pi | Extension caches rendered body per session | Advisory policy and extension-dependent dispatch checks | No native per-spawn model guarantee for third-party subagent tools. |
+
+Portable skills are registered on all six. Native capability differences are
+reported rather than presented as full enforcement parity. Policy, pricing,
+routing decisions, and installation rendering share ordinary code; thin
+adapters implement only supported controls. See [hook contracts](hooks/README.md).
+
+## Install and upgrade
+
+Requires macOS or Linux, Python 3.9+, and a current public harness. GitHub workflows need
+authenticated `gh`. JavaScript harnesses supply their own Node/Bun runtime.
+No OpenAI or Anthropic marketplace submission is needed: use this repository
+as your own plugin source or a local checkout.
+
+Install **only the harness you intend to configure**. Native plugin discovery
+and the integration installer are separate steps. Run the installer again
+after upgrades or model-mapping changes, because native profiles and copied
+OpenCode resources may need refreshing.
+
+### Claude Code
+
+```sh
 claude plugin marketplace add foxhatleo/leos-agent
-```
-
-```bash
 claude plugin install leos-agent@leos-agent --scope user
 ```
 
-Then, in a Claude Code session, run `/install` (or ask it to use the `install`
-skill). That writes the block into `~/.claude/CLAUDE.md`.
-
-**Upgrade**
-
-```bash
-claude plugin marketplace update leos-agent
-```
+Then invoke the plugin's `install` skill in Claude. To upgrade, refresh the
+marketplace and plugin through Claude's plugin manager, then run `install`
+again and start a new session. Third-party marketplace auto-update settings may
+be disabled; do not assume every client updates itself.
 
-```bash
-claude plugin install leos-agent@leos-agent --scope user
-```
-
-Re-run `/install` afterwards to refresh the block, then start a new session.
-Both commands are safe to repeat; installing an already-current version reports
-that it is already installed and changes nothing.
-
-**Uninstall**
-
-Run the installer's uninstall first, while the script is still on disk:
-
-```bash
-python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py claude --uninstall
-```
+### Codex
 
-```bash
-claude plugin uninstall leos-agent@leos-agent
-```
-
-Optionally drop the marketplace too:
-
-```bash
-claude plugin marketplace remove leos-agent
-```
-
----
-
-## Codex
-
-**Install**
-
-```bash
+```sh
 codex plugin marketplace add foxhatleo/leos-agent
-```
-
-```bash
-codex plugin add leos-agent@leos-agent
-```
-
-Then run the `install` skill in a Codex session (`$leos-agent`, then `install`), or
-run the script directly:
-
-```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py codex
-```
-
-This writes `~/.codex/AGENTS.md` and installs two economical agents:
-`leo-runner` (`gpt-5.6-luna`, low effort) for narrow repeatable work and
-`leo-executor` (`gpt-5.6-terra`, medium effort) for well-specified
-implementation. Codex plugins cannot ship agent definitions themselves, which
-is why the installer writes them.
-
-**Upgrade**
-
-```bash
-codex plugin marketplace upgrade leos-agent
-```
-
-```bash
 codex plugin add leos-agent@leos-agent
 ```
 
-Re-run the installer, then start a new thread — Codex picks up plugin changes on new
-threads only. Re-adding an already-installed plugin is idempotent.
+Invoke the plugin's `install` skill to install native agent TOMLs. Review the
+current hook definitions in `/hooks`; enabling a plugin does not trust its
+hooks automatically. On upgrade, refresh the marketplace/plugin, rerun
+`install`, and review any changed hook definition. The project does not bypass
+that native trust boundary.
 
-**Uninstall**
+### Cursor
 
-```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py codex --uninstall
-```
+Add this repository through Cursor's plugin UI, or use its local-plugin setup:
 
-```bash
-codex plugin remove leos-agent@leos-agent
-```
-
-```bash
-codex plugin marketplace remove leos-agent
-```
-
----
-
-## Cursor
-
-Cursor has no on-disk global rules file — its User Rules live in your synced
-Cursor account — so there is nothing for the installer to write. The plugin ships the
-payload as an always-apply rule instead, which takes effect as soon as the
-plugin is installed.
-
-**Install** — either through the UI, or as a local clone.
-
-In the IDE: open the **Customize** sidebar, add the marketplace
-`foxhatleo/leos-agent`, and install **Leo's Agent** at user scope.
-
-Or clone it into Cursor's local plugin directory (a clone, not a symlink):
-
-```bash
+```sh
 git clone https://github.com/foxhatleo/leos-agent ~/.cursor/plugins/local/leos-agent
+python3 ~/.cursor/plugins/local/leos-agent/scripts/leo-install.py cursor
 ```
 
-Cursor does not currently expose a reliable non-interactive per-plugin install
-command, so those two paths are the supported ones.
-
-**Upgrade**
-
-Refresh the marketplace from the Customize panel, or for a local clone:
-
-```bash
-git -C ~/.cursor/plugins/local/leos-agent pull
-```
-
-**Uninstall**
-
-Remove the plugin from the Customize panel, or delete the clone:
-
-```bash
-rm -rf ~/.cursor/plugins/local/leos-agent
-```
-
-There is no block to remove — nothing was written outside the plugin directory.
-
----
-
-## Hermes
-
-**Install**
-
-If the plugin resolves through the community index:
-
-```bash
-hermes plugins install leos-agent
-```
-
-Otherwise clone it into the Hermes plugin directory:
-
-```bash
-git clone https://github.com/foxhatleo/leos-agent ~/.hermes/plugins/leos-agent
-```
-
-Hermes plugins are opt-in, so enable it by adding `leos-agent` to
-`plugins.enabled` in `~/.hermes/config.yaml`:
-
-```yaml
-plugins:
-  enabled:
-    - leos-agent
-```
-
-**Run Hermes once before installing.** The payload goes into `~/.hermes/SOUL.md`,
-the agent's identity prompt, and Hermes writes its own starter version of that
-file on first run. The installer deliberately never creates it — if `SOUL.md` is
-missing it reports `skipped` and leaves Hermes' bootstrap alone. Once it exists:
-
-```bash
-/leo-install
-```
-
-**Upgrade**
+Confirm the plugin in Customize and inspect Hooks diagnostics. Set explicit
+models available to your Cursor account, then rerun the installer. Profiles
+are written under `~/.cursor/agents`; `~/.cursor/rules` is not assumed to be a
+supported global rule location. Upgrade a local clone with `git pull --ff-only`,
+rerun the installer, and reload the plugin.
 
-```bash
-hermes plugins update leos-agent
-```
+### OpenCode
 
-or, for a clone:
+A stable checkout avoids versioned package-cache paths:
 
-```bash
-git -C ~/.hermes/plugins/leos-agent pull
+```sh
+git clone https://github.com/foxhatleo/leos-agent ~/.local/share/leos-agent
+python3 ~/.local/share/leos-agent/scripts/leo-install.py opencode
 ```
 
-Then re-run `/leo-install`.
+The installer registers the checkout's plugin URI, one rendered instruction,
+native agent profiles, and skill/reference copies. It preserves JSONC comments
+and unrelated configuration. Upgrade that checkout with `git pull --ff-only`
+and rerun the same command. The npm package is also published as `leos-agent`;
+if using a package cache, resolve its actual root and rerun the installer when
+that path changes. Do not assume a fixed cache directory layout.
 
-**Uninstall**
+### Hermes
 
-```bash
-python3 ~/.hermes/plugins/leos-agent/scripts/leo-install.py hermes --uninstall
-```
-
-```bash
-hermes plugins remove leos-agent
-```
+Use Hermes's local-plugin directory under your active HERMES_HOME/profile to
+install this repository as `plugins/leos-agent`, then enable it through Hermes's
+plugin manager. Run the registered `leo-install` command. The native plugin
+registers portable skills, one frozen policy section, and dispatch diagnostics.
+Hermes supports the policy for deciding whether to delegate, but not per-task
+model tiers. The installer preserves its native delegation-model setting;
+saved cheap/standard mappings are not applied. The guard can still check known
+child/parent prices when both models are observable.
 
-Remove the `leos-agent` entry from `plugins.enabled`, and delete the clone if
-you made one. Your own `SOUL.md` content is left intact — only the block goes.
+### Pi
 
-**Note on model routing:** Hermes applies a single `delegation.model` to every
-child of a `delegate_task` call, so it cannot vary the model per spawn. A
-routing config still renders a stanza for it, and the stanza says to inherit and
-say so where a per-spawn model is not available.
-
----
-
-## Pi
-
-**Install**
-
-```bash
+```sh
 pi install git:github.com/foxhatleo/leos-agent
 ```
 
-Then run the install skill in a pi session:
-
-```
-/skill:install
-```
-
-Pi pins the git ref it installed and records the package in
-`~/.pi/agent/settings.json`; re-running install is idempotent.
-
-**Upgrade**
-
-```bash
-pi update git:github.com/foxhatleo/leos-agent
-```
-
-Pinned refs are reconciled, never silently advanced — to move to a new tag,
-install it explicitly:
-
-```bash
-pi install git:github.com/foxhatleo/leos-agent@v10.7.2
-```
-
-Re-run `/skill:install` afterwards.
-
-**Uninstall**
-
-```bash
-python3 ~/.pi/agent/git/github.com/foxhatleo/leos-agent/scripts/leo-install.py pi --uninstall
-```
-
-```bash
-pi remove git:github.com/foxhatleo/leos-agent
-```
-
----
-
-## OpenCode
+Invoke the installed `install` skill for `pi`, then start a new session.
+Package metadata provides skill discovery once; the extension does not register
+the same skills a second time. Upgrade through Pi's package manager and rerun
+`install`. A subagent extension is required for delegation; this project does
+not pretend that every such extension accepts model overrides.
 
-OpenCode loads plugins as npm packages, so this one is published to npm as
-`leos-agent`.
+### Installer controls
 
-**Install**
-
-```bash
-opencode plugin leos-agent -g
-```
-
-That adds the package to the `plugin` array in `~/.config/opencode/opencode.json`
-(or `.jsonc`) and caches it. Bootstrap the installer once by running the script from
-the cache — OpenCode's plugin API cannot register skills or commands, so the
-first run has to come from the package itself:
-
-```bash
-python3 ~/.cache/opencode/packages/leos-agent@latest/node_modules/leos-agent/scripts/leo-install.py opencode
-```
+From the resolved plugin root:
 
-That writes `~/.config/opencode/AGENTS.md` and copies the skills and commands into
-`~/.config/opencode/skills/` and `~/.config/opencode/commands/`. From then on
-`/leo-install` works inside OpenCode. The copies are installed with the plugin
-root already resolved to an absolute path — OpenCode sets no resolution env var,
-and the copies live apart from the scripts they invoke — so re-run the installer
-after clearing or moving the package cache to point them at the new location.
-
-**Upgrade**
-
-```bash
-opencode plugin leos-agent -g -f
-```
-
-If the cache holds a stale copy, clear it and let OpenCode refetch:
-
-```bash
-rm -rf ~/.cache/opencode/packages/leos-agent@*
-```
-
-Re-run the bootstrap install command above to refresh the copied files.
-
-**Uninstall**
-
-```bash
-python3 ~/.cache/opencode/packages/leos-agent@latest/node_modules/leos-agent/scripts/leo-install.py opencode --uninstall
-```
-
-OpenCode has no plugin-remove command, so delete the `"leos-agent"` entry from
-the `plugin` array in `~/.config/opencode/opencode.json` **by hand**. The installer
-never edits that file: it is JSONC, with your comments in it, and rewriting it
-would destroy them. Then clear the cache:
-
-```bash
-rm -rf ~/.cache/opencode/packages/leos-agent@*
+```sh
+python3 scripts/leo-install.py <harness> --dry-run
+python3 scripts/leo-install.py <harness> --check
+python3 scripts/leo-install.py <harness> --rollback
+python3 scripts/leo-install.py <harness> --uninstall
 ```
 
----
+Normal installation stages and validates all changes first, writes a private
+backup, and rolls back earlier writes if an operation fails. Rollback refuses
+intervening edits and can recover a partially applied installation. Only owned
+entries/files are managed. Unchanged legacy copies are recognized by complete
+content hashes; edited or unrelated files are preserved. `--force` is for a
+specific conflict you explicitly intend to replace.
 
-## Migrating from v8
+Run `--uninstall` before removing the native plugin/source. It removes owned
+integration artifacts, not routing preferences, handoffs, or logs. Supported
+config overrides include CODEX_HOME, CLAUDE_CONFIG_DIR, HERMES_HOME,
+PI_CODING_AGENT_DIR, OPENCODE_CONFIG_DIR, OPENCODE_CONFIG, and XDG_CONFIG_HOME.
 
-Version 10 renames the plugin from `leo` to `leos-agent`, so the old install
-does not upgrade in place — remove it first. Most skills that were invoked
-as `leo:<name>` are gone; v10 ships a deliberately lean payload plus the three
-GitHub skills above, now unprefixed (`review-pr`, not `leo:review-pr`). The
-watcher no longer runs under `/loop`: it is a shell process streaming into
-Claude Code's Monitor tool, so idle polling costs nothing.
+## Per-machine model routing
 
-**Claude Code.** The old plugin will show as `failed to load` once the
-marketplace points at v10 (`Plugin leo not found in marketplace leos-agent`).
-Remove it:
+Data lives in `~/.leos-agent-local`, or LEOS_AGENT_LOCAL_PATH, outside versioned
+plugin caches. Configure concrete provider/harness IDs rather than assuming
+that a familiar alias exists everywhere:
 
-```bash
-claude plugin uninstall leo@leos-agent
+```sh
+python3 scripts/routing.py set --harness claude --cheap haiku --standard sonnet
+python3 scripts/routing.py set --harness codex --cheap gpt-5.6-luna --standard gpt-5.6-terra
+python3 scripts/routing.py show
+python3 scripts/leo-install.py <harness>
 ```
 
-**Codex.** The v8 marketplace entry is pinned to an old commit, and Codex
-refuses to re-add a marketplace from a different source. Remove and re-add:
+`routing.json` accepts `cheap` and `standard` as strings or objects containing
+`model` and optional `effort`. Legacy `runner`/`executor` keys remain readable.
+Unknown model identifiers are retained and diagnosed, not silently corrected
+to a different dispatch ID. Parent-level always means the current parent.
 
-```bash
-codex plugin marketplace remove leos-agent && codex plugin marketplace add foxhatleo/leos-agent
-```
-
-**OpenCode.** The existing `"leos-agent"` plugin entry stays valid; clear the
-cache so it refetches v10.
+Guard modes are `LEOS_AGENT_DISPATCH_GUARD=on` (default), `warn` (log proposed
+corrections/blocks), and `off`. Unrelated tools and third-party MCP tools are
+not routed. Failures are logged distinctly and fail open; this is not a
+security boundary. Native or organization-level model substitutions may still
+require investigation of actual execution.
 
-**Leftover files.** v8 wrote `*.leo-backup` files next to the instruction files
-it touched. v10 does not create backups — the block replacement is surgical, and
-`--dry-run` shows you any change before it happens. These are safe to delete:
+## Workflows and diagnostics
 
-```bash
-rm -f ~/.claude/CLAUDE.md.leo-backup ~/.codex/AGENTS.md.leo-backup ~/.config/opencode/AGENTS.md.leo-backup
-```
-
----
-
-## Extending it
-
-The repo root is the plugin. Each harness reads its own manifest from the same
-tree, and the three payload directories are shared between them.
-
-**Skills** live in `skills/<name>/SKILL.md`, or `skills-claude/<name>/SKILL.md`
-for one only Claude Code can use; commands mirror that with `commands/` and
-`commands-claude/`. The two `-claude` directories are listed in
-`.claude-plugin/plugin.json` and nowhere else. Keep the frontmatter of a
-portable skill to `name` and `description`, plus
-`disable-model-invocation: true` on a skill that must never fire on its own.
-Codex uses the matching sibling `agents/openai.yaml` with
-`policy.allow_implicit_invocation: false`; harnesses without a control for it
-get the constraint stated in the description. That subset is what all five skill-loading harnesses accept, and
-anything richer will parse on Claude Code and be ignored or rejected elsewhere.
-Claude Code, Codex, Cursor, and Pi load `skills/` straight from their manifests;
-OpenCode gets a copy from the installer.
-
-**Commands** live in `commands/<name>.md`. Claude Code and Cursor read the
-directory from their manifests; OpenCode gets a copy. Codex dropped custom
-prompts in favour of skills, so add a skill there instead.
-
-### Two conventions, both enforced by `scripts/check.py`
-
-**Progressive disclosure.** `SKILL.md` is the *dispatch contract* — what the
-main thread does. The procedure a subagent follows goes in
-`skills/<name>/reference/*.md`, which the brief points at by path. `review-pr`
-is the worked example: the main thread loads a 3.2 KB contract, the reviewer
-subagent reads `reference/procedure.md`, and the lens sub-subagents read
-`reference/lenses.md` that the reviewer itself never loads. Before the split the
-main thread and the reviewer each loaded the same 21 KB file, and every turn
-after that re-read it. `tune-routing` does the same with its per-harness model
-discovery, in `reference/harnesses.md`, which only a run that actually tunes
-ever loads. Split a file out only when some run genuinely does not read it;
-moving prose around costs the same tokens.
-
-**Invocation split.** A skill is either *user-invoked* — reached by typing its
-slash command, and carrying `disable-model-invocation: true` — or *deliberately
-model-invocable*, reached when the model decides the task fits. On Claude Code
-the flag also drops the skill's description from the always-loaded skill
-listing, which is the larger saving: a description is context in every session,
-invoked or not. Only `review-pr` and `handon` are model-invocable here, because
-they are the two you would phrase in words ("review PR 41", "pick up where I
-left off") rather than by name; `check.py` fails the build on any other skill
-that omits the flag. A user-invoked skill may invoke a model-invoked one, but
-never chains another user-invoked skill.
-
-A description says **when to reach for this** and **what it is not** — never how
-the skill works. The mechanism is what the body is for, and every word of it in
-the description is paid for in sessions that never invoke the skill.
-
-**Hooks** live in `hooks/`, wired but empty — v10 enforces its policy through
-the payload rather than by intercepting tool calls. There are two files because
-the formats genuinely differ: `hooks.json` (PascalCase events) serves Claude
-Code and Codex, which both auto-load it and must never name it in their
-manifests, and `hooks-cursor.json` (camelCase, `version: 1`) serves Cursor,
-which does name it. See [`hooks/README.md`](hooks/README.md) for how to add one,
-including the Hermes, OpenCode, and Pi equivalents, which are code rather than
-JSON.
-
-## Development
-
-Run the checks:
-
-```bash
+| Skill | Purpose |
+|---|---|
+| install | Configure this harness's native artifacts; preview/check/uninstall/rollback. |
+| doctor | Check installation, pricing, model references, and runtime evidence without paid calls. |
+| tune-routing | Configure tiers and diagnose actual native model selection. |
+| review-usage | Mechanical usage scan with reference-cost estimates and explicit gaps. |
+| review-pr | Review a pinned GitHub PR; stage comments/replies as pending. |
+| handoff / handon | Save concise context pointers and resume after checking drift. |
+| watch-review | Claude Monitor watcher: code polls GitHub; models run only for eligible reviews. |
+| attach-pr | Claude-specific attachment of an existing PR to the desktop session. |
+
+Only small routing instructions and necessary metadata are always present.
+Detailed review procedures remain in deferred reference files. Duplicate
+slash-command wrappers are removed; native skills provide invocation. Explicit
+invocation controls do not universally imply hidden metadata—measure both.
+
+```sh
+python3 scripts/doctor.py --harness claude --json
+python3 scripts/usage_scan.py --since 7d --harness claude --json
+python3 scripts/dispatch_log.py report
+python3 scripts/measure_context.py --check
+python3 scripts/pricing.py resolve claude-sonnet-5
+```
+
+Default policy bodies are about 1.8–2.0 KB, with a 2.2 KB component budget.
+Measurement counts metadata separately and treats bytes/4 only as a rough
+prose-token proxy. Harness wrappers, history, tools, cache behavior, and child
+work are outside that static measurement. No assertion is made that instruction
+overhead always pays for itself.
+
+Usage scanning handles Claude streaming duplicates, Codex cumulative/cache
+accounting, and OpenCode message-time usage. Cursor/Hermes/Pi usage schemas are
+currently unsupported and reported that way. Reference prices are not bills;
+unknown cache/model costs remain explicit. Compaction pre-context counts are
+not discarded tokens. Requested/corrected/blocked dispatches are distinct from
+observed child models. Missing/rotated logs do not prove a broken install.
+
+PR review pins the full head SHA; it never silently moves line anchors or
+retries old findings against a new head. Replacing a pending review requires
+an unchanged ownership receipt and saves recovery data. New comments/replies
+remain pending. Only verified addressed threads rooted by the authenticated
+user can be auto-resolved; resolution is public and requires SHA-bound evidence.
+Watchers use cross-process leases, bounded retries, and completion reports;
+emission alone never records a PR as reviewed.
+
+Logs omit prompt text by default and rotate at 1 MiB plus one retained file.
+`LEOS_AGENT_DISPATCH_LOG_PROMPTS=1` is an explicit debug option that retains
+brief excerpts; avoid it for sensitive work. Installation backups and handoffs
+stay local. Handoff names are validated, reservations avoid collisions, and
+symlink escapes are refused by the helper.
+
+## Development and releases
+
+```sh
+LEOS_AGENT_PRICE_REFRESH=off PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests
+node --test tests/js/*.test.js
 python3 scripts/check.py
-```
-
-The structural check asserts that the version matches across every manifest,
-the marketplace entry, and this README; that each manifest carries what its
-harness requires and every declared path exists; that both hook files parse in
-their own format; and that injection is idempotent, uninstall round-trips, and
-malformed markers are refused.
-
-Run the behavioral tests:
-
-```bash
-python3 -m unittest discover -s tests -v
-```
-
-Measure the repository-controlled static prompt footprint and enforce its
-committed ceilings:
-
-```bash
 python3 scripts/measure_context.py --check
 ```
 
-The measurement is a byte-based proxy for always-listed or dispatch-loaded
-text. It deliberately does not claim to measure total task tokens or credits,
-which also depend on conversation history, cache state, tool output, and the
-number and model of spawned agents.
-
-Preview any install without writing:
-
-```bash
-python3 scripts/leo-install.py <harness> --dry-run
-```
-
-**Both Claude Code and Codex cache a plugin by version**, so reinstalling while
-the version is unchanged is a no-op and quietly leaves the old code in place —
-you will be testing the previous build without being told. While iterating,
-either uninstall and reinstall:
-
-```bash
-claude plugin uninstall leos-agent@leos-agent && claude plugin install leos-agent@leos-agent --scope user
-```
-
-or replace the cachebuster suffix in the Codex manifest with one in the form
-`10.7.2+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
-reach a **new** session or thread.
-
-`--check` exits non-zero when a file is out of date, and `--force` replaces a
-copied file that something else has since overwritten.
-
-To release: bump the version in `package.json`, the three `plugin.json` files,
-`.claude-plugin/marketplace.json`, `plugin.yaml`, and every mention in this
-README (the uninstall commands embed it in cache paths — `check.py` fails on any
-stale one); run `scripts/check.py`; then push a `v`-prefixed tag.
-
-Pushing that tag is the whole release. `.github/workflows/release.yml` runs the
-tests and both checks, refuses a tag that disagrees with `package.json`,
-inspects the tree npm would ship, and publishes to npm for OpenCode. It
-authenticates by OIDC trusted publishing, so there is no token in the repository
-— npm's configuration names this workflow by path, and renaming the file breaks
-publishing until npm is updated to match. Publishing is idempotent: a version
-already on the registry is a no-op, and a lookup that fails for any reason other
-than a confirmed 404 aborts rather than assuming the version is absent.
-
-Check what a publish would contain, without publishing:
-
-```bash
-python3 scripts/publish-npm.py --dry-run
-```
-
-MIT licensed.
+Tests use fixtures and mock provider events; CI makes no paid model calls.
+Native live smoke tests are separate, explicitly authorized, and budgeted.
+Static/adapter tests establish contracts, not complete end-to-end parity on
+all six installed harnesses.
+
+Commits run validation only. Release versions use `12.YYYYMMDDXX.0`, with a UTC
+calendar date and a two-digit serial from 00 to 99. Run `scripts/bump.py` only
+when preparing a release, validate all manifests/package contents, commit on
+main, and publish the matching tag through the release workflow. npm publishing
+uses its existing trusted-publishing workflow. An ordinary code commit never
+automatically changes versions or stages unrelated files.
+
+Native references: [Claude subagents](https://code.claude.com/docs/en/sub-agents),
+[Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents),
+[Codex hooks](https://learn.chatgpt.com/docs/hooks),
+[Cursor plugins](https://cursor.com/docs/reference/plugins),
+[OpenCode plugins](https://opencode.ai/docs/plugins/),
+[Hermes hooks](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/hooks.md),
+[Pi extensions](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md).