leos-agent 10.6.0 → 10.7.0

package/README.md

@@ -1,6 +1,6 @@
 # leos-agent
 
-Leo's portable agent operating policy, version **10.6.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.
 
@@ -30,6 +30,7 @@ The GitHub ones need `gh`, authenticated.
 | `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 |
@@ -113,6 +114,70 @@ 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
+```
+
+**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
 
 The payload lives in exactly one file: [`rules/preferences.md`](rules/preferences.md).
@@ -122,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.6.0">
+<leos-agent version="10.7.0">
 ...the payload...
 </leos-agent>
 ```
@@ -191,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.6.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
@@ -222,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.6.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:
@@ -247,7 +312,7 @@ threads only. Re-adding an already-installed plugin is idempotent.
 **Uninstall**
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.6.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
@@ -396,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.6.0
+pi install git:github.com/foxhatleo/leos-agent@v10.7.0
 ```
 
 Re-run `/skill:install` afterwards.
@@ -616,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.6.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.6.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/",

package/rules/preferences.md

@@ -48,22 +48,21 @@ turns and took a third of a day's subagent spend.
 
 ## Model routing
 
-Every subagent dispatch MUST name an explicit model or profile. The harness
-inherits the parent model when you say nothing, so a dispatch with no model and
-no stated reason for inheriting is a bug, not a default.
-
 - Reading, search, tests, logs, codemods, and every fan-out → **leo-runner**.
 - An approved plan or a well-specified code change → **leo-executor**.
-- Investigation, debugging, adjudication, orchestration → inherit the current
-  model, and say that inheriting is intended.
+- Investigation, debugging, adjudication → name the inherited model outright.
+
+Floor and ceiling: a lone brief naming one file should have been inline; work
+whose every file you would not want to read should have been fanned out.
 
 <!-- leos-agent:routing -->
 On Claude Code pass `subagent_type: "leo-runner"` or `"leo-executor"`; on Codex
 the installed profiles carry the models. Elsewhere use the current model.
 <!-- /leos-agent:routing -->
 
-Never upgrade a cheaper session; report when routing cannot be applied. Wide
-inherited fan-out is the policy's most expensive shape.
+A dispatch naming no model is refused, not defaulted.
+Never upgrade a cheaper session; wide inherited fan-out is the policy's
+most expensive shape.
 
 ## Caching
 

package/scripts/check.py

@@ -147,6 +147,51 @@ def main():
 		check(data.get("version") == 1, "hooks/hooks-cursor.json: Cursor requires version 1")
 		check(isinstance(data.get("hooks"), dict), "hooks/hooks-cursor.json: needs a top-level `hooks` object")
 
+	# 6b. The dispatch guard must actually be wired, and reachable once shipped.
+	# A matcher is not decoration: without one the guard spawns a python3 per
+	# Read and per Grep, which costs more than the routing it enforces. And a
+	# command pointing outside package.json's `files` runs fine from a git
+	# checkout and silently does nothing for anyone who installed from npm --
+	# the failure that put this script in scripts/ rather than hooks/.
+	shipped = tuple(entry for entry in json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["files"] if not entry.startswith("!"))
+	pre = (json.loads(shared_hooks.read_text(encoding="utf-8")).get("hooks") or {}).get("PreToolUse") or []
+	check(bool(pre), "hooks/hooks.json: no PreToolUse entry (the dispatch guard is not wired)")
+	cursor_pre = (json.loads(cursor_hooks.read_text(encoding="utf-8")).get("hooks") or {}).get("preToolUse") or []
+	check(bool(cursor_pre), "hooks/hooks-cursor.json: no preToolUse entry (Cursor gets no guard)")
+	for entry in pre:
+		check(bool(entry.get("matcher")), "hooks/hooks.json: PreToolUse needs a matcher, or it spawns on every tool call")
+	commands = [h.get("command", "") for entry in pre for h in entry.get("hooks") or []]
+	commands += [entry.get("command", "") for entry in cursor_pre]
+	for timeout in [h.get("timeout") for entry in pre for h in entry.get("hooks") or []] + [e.get("timeout") for e in cursor_pre]:
+		check(timeout is not None and timeout <= 10, f"hook timeout {timeout!r} exceeds the 10s a harness will wait")
+	for command in commands:
+		match = re.search(r"(?:\$\{[A-Z_]+\}|\./)?/?((?:scripts|hooks)/[\w./-]+\.py)", command)
+		check(match is not None, f"hooks: cannot find a script path in command {command!r}")
+		if match:
+			target = match.group(1)
+			check((ROOT / target).is_file(), f"hooks: command points at {target}, which does not exist")
+			check(any(target.startswith(entry) for entry in shipped), f"hooks: {target} is outside package.json files; npm installs would not get it")
+
+	# The guard's own modules must import cleanly: a hook that cannot even load
+	# fails open on every dispatch, silently, which is the one failure mode that
+	# looks exactly like everything working.
+	for name in ("dispatch_guard", "dispatch_log", "usage_scan"):
+		path = ROOT / "scripts" / f"{name}.py"
+		check(path.is_file(), f"scripts/{name}.py is missing")
+		if path.is_file():
+			try:
+				spec = importlib.util.spec_from_file_location(f"check_{name}", path)
+				module = importlib.util.module_from_spec(spec)
+				spec.loader.exec_module(module)
+			except Exception as exc:
+				check(False, f"scripts/{name}.py does not import: {type(exc).__name__}: {exc}")
+
+	# The one sentence the payload must keep: the guard refuses a dispatch that
+	# names no model, and a model that does not know that wastes a turn finding
+	# out. Prose elsewhere may be trimmed; this line pays for itself.
+	payload_text = (ROOT / "rules" / "preferences.md").read_text(encoding="utf-8")
+	check("refused, not defaulted" in payload_text, "rules/preferences.md: lost the line telling the model a modelless dispatch is refused")
+
 	# Payload files copied by the installer must carry the provenance string, or
 	# it will mistake its own installed copy for a stranger's file and refuse to
 	# upgrade or remove it. The list is derived from the installer's own copy sets,