leos-agent 10.2.0 → 10.7.0

package/README.md

@@ -1,28 +1,36 @@
 # leos-agent
 
-Leo's portable agent operating policy, version **10.2.0**, installable on Claude
+Leo's portable agent operating policy, version **10.7.0**, 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, execution, testing, 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. Work runs at one of two
-named tiers: **standard**, the model you are already using, for thinking and
-judging; **economical**, the cheapest sufficient profile where the harness can
-select one. Narrow search, reading, testing, and mechanical work use the runner
-profile; well-specified implementation uses the executor profile.
+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: a setup diagnostic, a session handoff pair, and
-three GitHub skills. The GitHub ones need `gh`, authenticated.
+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 new direct review requests into the session, one notification per pull request, for `review-pr` to handle. 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 |
+| `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 |
@@ -31,14 +39,144 @@ 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 each reviewed pull request under `~/.leos-agent-local/`
-(override with `$LEOS_AGENT_LOCAL_PATH`), so it never surfaces the same one
-twice; `watch_review.py forget <n>` puts one back in play.
+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.0 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 |
+
+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 — only Claude Code's dispatch
+tool is verified, so an unanticipated one degrades to a no-op rather than a
+broken harness. 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
+```
 
-Handoffs live in the same place, under `handoffs/`. 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.
+**Coverage is honest, not uniform.** Claude Code is verified. Codex, Cursor,
+Hermes and OpenCode are wired with the same policy but their dispatch argument
+shapes are unconfirmed; there the guard is best-effort and no-ops rather than
+misfires. Pi has no hook surface and gets nothing. **Codex hash-pins hooks**, so
+upgrading to 10.7.0 — and every later edit to the guard — needs re-approval
+through `/hooks` there. Until you do, Codex silently enforces nothing; zero Codex
+rows in the report is the symptom.
+
+### 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
 
@@ -49,7 +187,7 @@ 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.2.0">
+<leos-agent version="10.7.0">
 ...the payload...
 </leos-agent>
 ```
@@ -67,7 +205,7 @@ exactly the content it exists to protect.
 
 | Harness | Global file the installer writes |
 |---|---|
-| Claude Code | `~/.claude/CLAUDE.md` |
+| 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) |
@@ -118,7 +256,7 @@ that it is already installed and changes nothing.
 Run the installer's uninstall first, while the script is still on disk:
 
 ```bash
-python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py claude --uninstall
+python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.7.0/scripts/leo-install.py claude --uninstall
 ```
 
 ```bash
@@ -149,7 +287,7 @@ Then run the `install` skill in a Codex session (`$leos-agent`, then `install`),
 run the script directly:
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py codex
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.0/scripts/leo-install.py codex
 ```
 
 This writes `~/.codex/AGENTS.md` and installs two economical agents:
@@ -174,7 +312,7 @@ threads only. Re-adding an already-installed plugin is idempotent.
 **Uninstall**
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py codex --uninstall
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.0/scripts/leo-install.py codex --uninstall
 ```
 
 ```bash
@@ -290,8 +428,9 @@ 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.
 
 **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. The
-policy therefore routes all Hermes work to the current model.
+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.
 
 ---
 
@@ -322,7 +461,7 @@ 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.2.0
+pi install git:github.com/foxhatleo/leos-agent@v10.7.0
 ```
 
 Re-run `/skill:install` afterwards.
@@ -361,7 +500,10 @@ python3 ~/.cache/opencode/packages/leos-agent@latest/node_modules/leos-agent/scr
 
 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.
+`/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**
 
@@ -462,8 +604,10 @@ 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. Split a file out only when some run genuinely does not
-read it; moving prose around costs the same tokens.
+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
@@ -537,7 +681,7 @@ claude plugin uninstall leos-agent@leos-agent && claude plugin install leos-agen
 ```
 
 or replace the cachebuster suffix in the Codex manifest with one in the form
-`10.2.0+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
+`10.7.0+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

package/hooks/README.md

@@ -0,0 +1,93 @@
+# Hooks
+
+Both files carry exactly one hook: the dispatch guard, which refuses a subagent
+dispatch that names no model. See [the README](../README.md#the-dispatch-guard).
+
+**v10 shipped these empty on purpose** — policy was enforced through the payload
+and the skills, not by intercepting tool calls. 10.7.0 reversed that for one
+narrow rule, and the reason is worth keeping: the always-loaded budget in
+`scripts/measure_context.py` had 56 bytes of headroom, so the prose could not be
+strengthened, while a hook costs nothing per turn. Moving the mechanical half of
+the routing rule into code let the prose that restated it come *out* of the
+payload. The doctrine still holds for anything a machine cannot check: judgment
+stays in `rules/preferences.md`, where a model can read it.
+
+**Hook scripts live in `scripts/`, not here.** `hooks/` was absent from
+`package.json`'s `files` until 10.7.0, so a script placed here reached nobody who
+installed from npm — and it would have failed silently, since the guard fails
+open. `scripts/check.py` now asserts every hook `command` resolves to a file
+inside a shipped directory. These JSON files are pointers.
+
+**There are two files because the harnesses disagree on the format.** Claude
+Code and Codex use PascalCase event names and no version key; Cursor uses
+camelCase names wrapped in `{"version": 1, ...}`. A single file cannot satisfy
+both, so each manifest points at its own.
+
+| File | Read by | Wired via |
+|---|---|---|
+| `hooks.json` | Claude Code, Codex | auto-discovery — **neither manifest may name it** |
+| `hooks-cursor.json` | Cursor | `.cursor-plugin/plugin.json`, which overrides Cursor's own auto-discovery |
+
+Both Claude Code and Codex load `hooks/hooks.json` on their own. Declaring it in
+the manifest as well is a duplicate: Codex's validator rejects the key outright,
+and Claude Code fails the entire plugin at load time with `Duplicate hooks file
+detected` — which `claude plugin validate` does **not** catch, so only a real
+install reveals it. `scripts/check.py` guards both cases.
+
+Cursor is the exception, and only because its file has a different name: naming
+it explicitly overrides Cursor's auto-discovery, which is what keeps Cursor from
+trying to read the PascalCase `hooks.json` it cannot parse.
+
+Hermes and OpenCode already carry the guard through their own mechanisms, and
+both call into `scripts/dispatch_guard.py` so that one policy has one
+implementation. Hermes hooks are Python callbacks registered from
+`register(ctx)` in `__init__.py` (`pre_tool_call`, `post_tool_call`,
+`on_session_start`, and so on), not JSON. OpenCode's are JavaScript hooks
+returned from the plugin factory in `index.js`. Pi's are extension event
+handlers. All three would be written in code rather than added here.
+
+## Adding one
+
+Claude Code and Codex (`hooks.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/my-check.py\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex exposes the same directory as `${PLUGIN_ROOT}` and accepts
+`${CLAUDE_PLUGIN_ROOT}` as an alias, so one command string serves both. A hook
+script reads the event JSON on stdin and writes its decision to stdout; exit
+code 2 blocks the call, with stderr as the reason.
+
+Cursor (`hooks-cursor.json`) uses the same idea with its own names:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      { "command": "python3 ./scripts/my-check.py", "timeout": 10 }
+    ]
+  }
+}
+```
+
+After editing either file, re-run `python3 scripts/check.py` — it validates
+that both still parse and that Cursor's keeps `version: 1`. Codex additionally
+hash-pins hooks for trust, so a changed hook must be re-approved through
+`/hooks` there.

package/hooks/hooks-cursor.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "python3 ./scripts/dispatch_guard.py",
+        "timeout": 10
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "[Tt]ask|[Aa]gent|[Ss]ubagent|[Dd]ispatch|[Dd]elegate|[Ss]pawn",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/dispatch_guard.py\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/index.js

@@ -1,12 +1,118 @@
 /**
  * OpenCode plugin entry point for leos-agent.
  *
- * Deliberately does nothing at runtime. OpenCode's plugin API registers tools
- * and hooks, not skills or commands, and the payload is installed to disk on
- * demand rather than written at session start. This export exists so that
- * `opencode plugin leos-agent -g` resolves and loads cleanly; the real work
- * happens in scripts/leo-install.py, which the installed `install` skill runs.
+ * One hook: refuse a subagent dispatch that names no model, so a fan-out cannot
+ * silently inherit the parent's expensive model. The decision itself lives in
+ * scripts/dispatch_guard.py -- five harnesses share exactly one policy, and only
+ * the event shape differs per harness.
+ *
+ * OpenCode has no per-tool matcher, so the prefilter is here in JS: without it
+ * every Read, Grep and Bash would pay a python3 spawn, which would be a worse
+ * regression than the one being fixed. The keys below are duplicated from
+ * dispatch_guard.py and pinned equal by tests/test_dispatch_guard.py.
+ *
+ * Everything else in this plugin is installed to disk on demand by
+ * scripts/leo-install.py, which the installed `install` skill runs.
  */
-export const LeosAgent = async () => ({});
+import { spawn } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const AGENT_KEYS = ['subagent_type', 'subagentType', 'agent_type', 'agentType', 'agent', 'subagent', 'profile'];
+const PROMPT_KEYS = ['prompt', 'brief', 'instructions', 'task', 'message', 'input'];
+const GUARD_TIMEOUT_MS = 10_000;
+
+const dataRoot = () => process.env.LEOS_AGENT_LOCAL_PATH || join(homedir(), '.leos-agent-local');
+
+/** A breadcrumb that cannot be written must not itself break the session. */
+function breadcrumb(message) {
+  try {
+    appendFileSync(join(dataRoot(), 'dispatch-guard.log'), `${new Date().toISOString()} ${message}\n`, { mode: 0o600 });
+  } catch {
+    /* nothing left to do; the guard has already failed open */
+  }
+}
+
+const hasKey = (args, keys) => keys.some((k) => typeof args[k] === 'string' && args[k].trim());
+
+/**
+ * Run the shared guard. Resolves to a block reason, or null to allow.
+ * Every infrastructure failure -- missing python3, spawn error, timeout, a
+ * wedged interpreter -- resolves null: the harm guarded against here is money,
+ * and a guard that fails closed would wedge every dispatch in every session.
+ */
+function runGuard(root, event) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('python3', [join(root, 'scripts', 'dispatch_guard.py')], {
+        stdio: ['pipe', 'ignore', 'pipe'],
+        env: { ...process.env, LEOS_AGENT_HARNESS: 'opencode' },
+      });
+    } catch (err) {
+      breadcrumb(`spawn failed: ${err && err.message}`);
+      return resolve(null);
+    }
+
+    let stderr = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      breadcrumb('guard timed out; allowing');
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      finish(null);
+    }, GUARD_TIMEOUT_MS);
+
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    // EPIPE on either pipe means the child exited early. That is an allow, not
+    // an unhandled error event that would take the session down with it.
+    child.stderr.on('error', () => {});
+    child.stdin.on('error', () => {});
+    child.on('error', (err) => {
+      breadcrumb(`guard error: ${err && err.message}`);
+      finish(null);
+    });
+    child.on('close', (code) => finish(code === 2 ? (stderr.trim() || '[leo routing] blocked') : null));
+
+    try {
+      child.stdin.end(JSON.stringify(event));
+    } catch (err) {
+      breadcrumb(`stdin write failed: ${err && err.message}`);
+      finish(null);
+    }
+  });
+}
+
+export const LeosAgent = async (ctx) => {
+  // The factory's ctx is the only place the session directory is available;
+  // tool.execute.before receives just {tool, sessionID, callID}.
+  const directory = (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+  const root = process.env.LEOS_AGENT_ROOT || process.env.PLUGIN_ROOT || new URL('.', import.meta.url).pathname;
+
+  return {
+    'tool.execute.before': async (input, output) => {
+      const args = output && output.args;
+      if (!args || typeof args !== 'object') return;
+      const tool = String((input && input.tool) || '');
+      if (tool.startsWith('mcp__')) return;
+      if (!hasKey(args, AGENT_KEYS) || !hasKey(args, PROMPT_KEYS)) return;
+
+      const reason = await runGuard(root, {
+        tool_name: tool,
+        tool_input: args,
+        session_id: (input && input.sessionID) || '',
+        cwd: directory,
+      });
+      // OpenCode has no deny return value; throwing is how a hook refuses.
+      if (reason) throw new Error(reason);
+    },
+  };
+};
 
 export default LeosAgent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leos-agent",
-  "version": "10.2.0",
+  "version": "10.7.0",
   "description": "Leo's portable agent operating policy: orchestrator main thread, subagent-first execution, cost-tiered model routing.",
   "type": "module",
   "main": "index.js",
@@ -28,6 +28,7 @@
   "files": [
     "commands-claude/",
     "commands/",
+    "hooks/",
     "index.js",
     "payload/",
     "rules/",