leos-agent 10.2.0 → 10.7.0

package/rules/preferences.md

@@ -7,58 +7,62 @@ alwaysApply: true
 ## The main thread is an orchestrator
 
 Keep the main thread minimal: understand the request, decide the approach,
-dispatch subagents, integrate what they return, report to Leo. Bulk work belongs
-in subagents.
+dispatch subagents, integrate what they return, report to Leo.
 
-Delegate work whose byproducts you do not want to keep: many files read, long
-output, several attempts before it lands — investigation, code search,
-debugging, execution, test runs. Only the conclusion comes back; the rest dies
-with it.
+Delegate work that floods your context to reach one answer: many files read,
+several attempts before it lands, open-ended search — investigation, code
+search, debugging. Only the conclusion comes back.
 
-Keep it inline when delegating costs more than it saves. Your context is already
-cached; a subagent starts cold and pays a full cache write on its system prompt
-and brief before reading anything. That write, not a screenful of output, is the
-break-even — one known file or a one-line edit never clears it.
+A single command you can filter at the shell runs inline: a `grep` or `tail`
+pipe costs nothing, so noisy output is never the trigger. Test runs, linters,
+and builds are inline by default.
 
-Do not spawn a subagent to avoid thinking. If you are a subagent, this section
-does not apply — do the work yourself.
+Below that bar, delegating costs more than it saves. Your context is cached; a
+subagent starts cold and pays a full cache write on its system prompt and brief
+— roughly $3 at Opus prices, $1 at Sonnet. That write is the break-even;
+one known file or a one-line edit never clears it.
+
+Never delegate to avoid thinking. As a subagent, do not delegate at all — do
+the work yourself.
 
 ## Briefing a subagent
 
 Spawn with clean context: on Codex pass `fork_turns="none"`; elsewhere request
-a fresh child where supported. Report the gap if history inheritance cannot be
-prevented. Write the brief to stand alone:
+a fresh child. Write the brief to stand alone:
 
 - State the goal and what "done" looks like.
-- Name the files, paths, symbols, and commands it should start from.
+- Name the files, paths, symbols, and commands to start from.
 - Include settled decisions, so it does not relitigate them.
-- Where supported, grant only the skills and tools it needs; extra schemas cost
-  context and invite wandering.
+- Grant only the skills and tools it needs; extra schemas invite wandering.
+- Say it does the work itself and spawns nothing further; it sees only the
+  brief.
 - Say what to return: the finding, the diff, the verdict — not a transcript.
 
 Prefer several narrow subagents over one broad one, run independent ones
 concurrently, and ask for uncertainty explicitly.
 
-## Model routing
-
-Every brief names one of two tiers; there is no third.
+Cap the scope: a brief that could plausibly run past ~50 turns gets split. A
+subagent's own context grows turn over turn, so one broad brief re-creates the
+expensive-prefix problem inside the child — a single measured agent ran 231
+turns and took a third of a day's subagent spend.
 
-**Standard** is the model Leo is running now, inherited with no override.
+## Model routing
 
-**Economical** is min(current model, the cheapest sufficient profile): runner =
-Haiku on Claude Code or `gpt-5.6-luna`/low on Codex; executor = Sonnet or
-`gpt-5.6-terra`/medium. Elsewhere use the current model. Never upgrade a cheaper
-session; report when routing cannot be applied.
+- 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 → name the inherited model outright.
 
-Match the tier to the kind of work, not to the size of the request.
+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.
 
-**Thinking work runs standard** — investigation, debugging, adjudication, and
-orchestration. A weak diagnosis makes every later step wasteful.
+<!-- 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 -->
 
-**Doing work runs economical** — runner for tests, reading, search, logs,
-codemods, and every fan-out; executor for an approved plan or well-specified
-code change. On Codex these are `leo-runner` and `leo-executor`. Wide standard
-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

@@ -110,7 +110,9 @@ def main():
 	# 5. Skills and commands exist and carry the portable frontmatter subset.
 	skills = sorted((ROOT / "skills").glob("*/SKILL.md"))
 	check(len(skills) >= 1, "skills/: no SKILL.md found; the plugin must ship at least one skill")
-	for skill in skills:
+	# skills-claude/ ships through .claude-plugin/plugin.json on the same terms, so
+	# it is validated on the same terms -- an unguarded tree is where conventions rot.
+	for skill in skills + sorted((ROOT / "skills-claude").glob("*/SKILL.md")):
 		text = skill.read_text(encoding="utf-8")
 		check(text.startswith("---\n"), f"{skill.relative_to(ROOT)}: missing frontmatter")
 		fm = text.split("---", 2)[1] if text.count("---") >= 2 else ""
@@ -145,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,
@@ -161,6 +208,80 @@ def main():
 		if path.is_file():
 			check(installer.PROVENANCE in path.read_text(encoding="utf-8"), f"{rel}: must contain {installer.PROVENANCE!r} so the installer recognises its own copy")
 
+	# 5a-agents. Claude Code auto-discovers agents/ at the plugin root. The set
+	# must stay in lockstep with the Codex profiles (same names, one policy), and
+	# each definition needs the frontmatter Claude reads — a missing model field
+	# would silently inherit the parent model, which is the failure this tier
+	# exists to prevent.
+	claude_agents = sorted((ROOT / "agents").glob("*.md"))
+	check(
+		sorted(p.stem for p in claude_agents) == sorted(installer.CODEX_AGENTS),
+		f"agents/: expected exactly the Claude twins of {installer.CODEX_AGENTS}, found {[p.stem for p in claude_agents]}",
+	)
+	for agent in claude_agents:
+		rel = agent.relative_to(ROOT)
+		text = agent.read_text(encoding="utf-8")
+		check(text.startswith("---\n"), f"{rel}: missing frontmatter")
+		fm = text.split("---", 2)[1] if text.count("---") >= 2 else ""
+		name_match = re.search(r"^name:\s*(\S+)", fm, re.MULTILINE)
+		check(name_match is not None and name_match.group(1) == agent.stem, f"{rel}: frontmatter name must be {agent.stem!r}")
+		check(re.search(r"^description:", fm, re.MULTILINE) is not None, f"{rel}: needs description")
+		check(re.search(r"^model:\s*\S", fm, re.MULTILINE) is not None, f"{rel}: needs an explicit model")
+		check(re.search(r"^tools:\s*\S", fm, re.MULTILINE) is not None, f"{rel}: needs an explicit tools allowlist")
+
+	# 5a-routing. The routing region is what makes the economical tier
+	# configurable per machine. Rendering must be total (every harness gets a
+	# stanza), deterministic (or a second install would not report "unchanged"),
+	# and cheaper than the multi-harness prose it replaced.
+	prefs_body = installer.payload_body(ROOT)
+	for marker in (installer.ROUTING_OPEN, installer.ROUTING_CLOSE):
+		check(prefs_body.count(marker) == 1, f"rules/preferences.md: expected exactly one {marker}")
+	check(
+		prefs_body.find(installer.ROUTING_OPEN) < prefs_body.find(installer.ROUTING_CLOSE),
+		"rules/preferences.md: the routing region's closer precedes its opener",
+	)
+	for harness in installer.HARNESSES:
+		rendered = installer.payload_body(ROOT, harness, {})
+		check(bool(installer.routing.stanza(harness, {}).strip()), f"routing: {harness} renders an empty stanza")
+		check(
+			installer.ROUTING_OPEN not in rendered and installer.ROUTING_CLOSE not in rendered,
+			f"routing: {harness}'s rendered payload still carries the region markers",
+		)
+		check(
+			rendered == installer.payload_body(ROOT, harness, {}),
+			f"routing: rendering {harness} twice is not byte-identical",
+		)
+		check(
+			len(rendered.encode("utf-8")) < len(prefs_body.encode("utf-8")),
+			f"routing: {harness}'s rendered payload is not smaller than the unrendered file",
+		)
+	# The rule is only ever installed when cursor routing is configured, so the
+	# provenance requirement is checked on a configured render.
+	configured_cursor = {"cursor": {"runner": {"model": "example-model", "effort": None}}}
+	check(
+		installer.PROVENANCE in installer.cursor_routing_rule("cursor", configured_cursor),
+		f"routing: the Cursor rule must contain {installer.PROVENANCE!r} so the installer recognises its own copy",
+	)
+
+	# 5c. Plugin-root references. Skill and command text points at plugin files
+	# through the <plugin-root> placeholder, and the OpenCode installer bakes the
+	# absolute root into its copies — so every referenced path must actually
+	# exist, or an install ships a command that can only fail.
+	for base in ("skills", "skills-claude", "commands", "commands-claude"):
+		for doc in sorted((ROOT / base).rglob("*.md")):
+			text = doc.read_text(encoding="utf-8")
+			for ref in sorted({r.rstrip(".") for r in re.findall(r"<plugin-root>/([\w./-]+)", text)}):
+				check((ROOT / ref).exists(), f"{doc.relative_to(ROOT)}: <plugin-root>/{ref} does not exist")
+
+	# The OpenCode copy of the install skill is renamed to leo-install by a
+	# targeted regex in the installer; if the source name ever changes, that
+	# regex would silently no-op and ship a dir/name mismatch.
+	install_fm = (ROOT / "skills" / "install" / "SKILL.md").read_text(encoding="utf-8").split("---", 2)[1]
+	check(
+		re.search(r"(?m)^name:\s*install\s*$", install_fm) is not None,
+		"skills/install/SKILL.md: frontmatter name must stay 'install' — leo-install.py's OpenCode rename keys on it",
+	)
+
 	# 5b. Invocation split: a skill is either user-invoked (and hidden from the
 	# model's always-loaded skill listing) or deliberately model-invocable. Claude
 	# reads the SKILL.md flag; Codex reads the sibling agents/openai.yaml policy.

package/scripts/dispatch_guard.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""dispatch_guard: refuse a subagent dispatch that names no model.
+
+WHY THIS EXISTS IN CODE RATHER THAN PROSE. The policy already said every dispatch
+must name a model, and the policy was forgotten. Prose enforcement also costs
+always-loaded bytes on every turn of every session, and the budget in
+measure_context.py is nearly spent -- so the rule that a machine can check moved
+into a hook, which costs nothing, and the payload kept only the judgment a hook
+cannot make. Moving it out of the payload was what paid for the move.
+
+WHAT IT REFUSES, AND WHAT IT DELIBERATELY DOES NOT. A dispatch that selects an
+agent, carries a brief, names no model, and runs on a harness that can express
+one per spawn is refused -- because on that path the harness silently inherits
+the parent's expensive model, which is the failure this file exists to prevent.
+Everything else is allowed. The guard NEVER picks a model: it cannot force a
+cheap tier onto work that needed an expensive one, so it cannot cause a quality
+regression, only an explicit choice. That is also why the block stays narrow. A
+false block costs one re-dispatch turn; a caught inherited fan-out saves the cold
+prefix of every child it would have spawned. The margin is wide precisely because
+the rule refuses to make judgment calls, and every widening spends it.
+
+SHAPE-BASED, NOT NAME-BASED. Only Claude Code's dispatch tool is verified; the
+argument shapes on Codex, Cursor, Hermes and OpenCode are not. So the decision
+turns on the arguments -- an agent-selection field plus a brief -- and an
+unanticipated tool degrades to a no-op rather than a broken harness. The hook
+manifests still carry a name matcher, but only as a cheap prefilter: without one,
+every Read and Grep would pay a python3 spawn.
+
+FAILS OPEN, LOUDLY. The harm here is money, not data loss. A guard that fails
+closed on a broken interpreter wedges every dispatch on every harness, which is
+far worse than the miss it prevents -- and on Claude Code a timed-out hook is
+non-blocking anyway, so fail-closed is not even expressible there. Every internal
+error allows the call and leaves a breadcrumb with decision "error", kept
+rigorously distinct from a decision to allow.
+
+  LEOS_AGENT_DISPATCH_GUARD  on (default) | warn (log, never block) | off | verbose
+  LEOS_AGENT_HARNESS         overrides harness detection
+
+Exit codes: 0 allow, 2 block (reason on stderr).
+"""
+import collections
+import json
+import os
+import re
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+Dispatch = collections.namedtuple(
+    "Dispatch",
+    "tool agent model prompt_bytes prompt_lines path_count prompt_hash prompt_head",
+)
+
+# The agent-selection field is mandatory, and that is the whole trick. A rule
+# keyed on "has a prompt" would refuse unrelated tools -- spawn_task takes
+# {prompt, title, tldr} and nothing else -- and "has a model" is weaker still.
+# Only naming an agent means "I am choosing who runs this".
+AGENT_KEYS = ("subagent_type", "subagentType", "agent_type", "agentType", "agent", "subagent", "profile")
+PROMPT_KEYS = ("prompt", "brief", "instructions", "task", "message", "input")
+MODEL_KEYS = ("model", "model_id", "modelId", "model_name")
+
+TOOL_KEYS = ("tool_name", "toolName", "tool", "name")
+INPUT_KEYS = ("tool_input", "toolInput", "arguments", "args", "input", "params", "parameters")
+
+# Third-party MCP tools are not routed by this policy and never will be, and
+# their argument namespaces are outside our control forever. One prefix test
+# removes the entire class of false positives they would otherwise create.
+SKIP_PREFIXES = ("mcp__",)
+
+# Seeded empty on purpose: populate from field reports, not from guesses.
+SKIP_TOOLS = frozenset()
+
+ALLOW, BLOCK = "allow", "block"
+
+# Path-ish tokens in a brief. Scanning is capped at the first 8 KiB -- the
+# feature does not improve past that and a hot path should not read a novel.
+PATH_SCAN_BYTES = 8192
+PATH_RE = re.compile(r"[\w.-]+/[\w./-]+|[\w-]+\.[A-Za-z]{1,5}\b")
+
+
+def _first_str(source, keys):
+    for key in keys:
+        value = source.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+def _first_dict(source, keys):
+    for key in keys:
+        value = source.get(key)
+        if isinstance(value, dict):
+            return value
+    return None
+
+
+def harness(event):
+    """Which harness this event came from. Best effort, and logged either way.
+
+    The env var is the override the in-process adapters set. Otherwise the
+    transcript path is the only hint a command hook gets; when it says nothing,
+    assume Claude Code, the one harness whose dispatch tool is verified.
+    """
+    named = os.environ.get("LEOS_AGENT_HARNESS", "").strip().lower()
+    if named:
+        return named
+    hint = ""
+    if isinstance(event, dict):
+        hint = _first_str(event, ("transcript_path", "transcriptPath", "cwd"))
+    for name in ("codex", "cursor", "hermes", "opencode"):
+        if "/." + name in hint or "/" + name + "/" in hint:
+            return name
+    return "claude"
+
+
+def normalize(event, _harness=None):
+    """event -> Dispatch, or None when this is not a subagent dispatch.
+
+    Never raises. Five harnesses' envelopes are unverified, and a KeyError here
+    would turn a routing guard into an outage.
+    """
+    if not isinstance(event, dict):
+        return None
+    tool = _first_str(event, TOOL_KEYS)
+    if tool in SKIP_TOOLS or any(tool.startswith(p) for p in SKIP_PREFIXES):
+        return None
+    args = _first_dict(event, INPUT_KEYS)
+    if args is None:
+        return None
+
+    agent = _first_str(args, AGENT_KEYS)
+    prompt = _first_str(args, PROMPT_KEYS)
+    if not agent or not prompt:
+        return None
+
+    from dispatch_log import digest  # local: a no-op call must not pay for this
+
+    head = prompt[:PATH_SCAN_BYTES]
+    return Dispatch(
+        tool=tool or "-",
+        agent=agent,
+        model=_first_str(args, MODEL_KEYS) or None,
+        prompt_bytes=len(prompt.encode("utf-8", "replace")),
+        prompt_lines=prompt.count("\n") + 1,
+        path_count=len(set(PATH_RE.findall(head))),
+        prompt_hash=digest(prompt),
+        prompt_head=prompt[:200],
+    )
+
+
+def triviality(dispatch):
+    """0..3. A features-only score; it never changes the exit code.
+
+    Say plainly what this can and cannot see: a trivial spawn has small *work*,
+    and tool input only shows the *brief*. The two failure modes happen to
+    collapse -- a short brief is either work too small to deserve a cold context
+    or work that is under-briefed, and the policy forbids both -- but roughly one
+    in six legitimate runner dispatches will still score here. That rate is fine
+    for a log line and disqualifying for a block, which is why this is only ever
+    a log line.
+    """
+    if dispatch is None:
+        return 0
+    score = 0
+    if dispatch.prompt_bytes < 220:
+        score += 2
+    elif dispatch.prompt_bytes < 450:
+        score += 1
+    if dispatch.path_count == 1:
+        score += 1
+    if dispatch.prompt_lines == 1:
+        score += 1
+    return min(score, 3)
+
+
+def routable(name):
+    """Can this harness name a model per spawn?
+
+    Claude Code's dispatch tool takes one, and any harness Leo has configured in
+    routing.json has a model to name. Everywhere else the payload itself says to
+    inherit and say so -- blocking there would demand something the harness
+    cannot do, a false positive by construction.
+    """
+    if name == "claude":
+        return True
+    try:
+        import routing
+        return name in routing.load()
+    except BaseException:
+        # routing.py exits on a malformed config. A hook must never inherit that.
+        return False
+
+
+def decide(dispatch, name, is_routable):
+    """(action, reason). The entire policy, and deliberately four lines of it."""
+    if dispatch is None:
+        return ALLOW, "not-a-dispatch"
+    if dispatch.agent.startswith("leo-"):
+        return ALLOW, "leo-tier"          # the agent definition carries the model
+    if dispatch.model:
+        return ALLOW, "explicit-model"    # a choice was typed; cheap or not
+    if not is_routable:
+        return ALLOW, "harness-cannot-route"
+    return BLOCK, "no-model"
+
+
+def render_block(dispatch):
+    """The refusal. It must name the remedies, or it costs a turn to discover them."""
+    return (
+        '[leo routing] BLOCKED - dispatch to agent "%s" names no model, so it would\n'
+        "silently inherit the parent's. Re-dispatch with one of:\n"
+        '  subagent_type "leo-runner"    reading, search, tests, logs, codemods, fan-out\n'
+        '  subagent_type "leo-executor"  an approved plan or a specified change\n'
+        '  model: "<name>"               investigation/debugging - naming it IS the reason\n'
+        "Set LEOS_AGENT_DISPATCH_GUARD=off to disable, =warn to log only."
+    ) % dispatch.agent
+
+
+def render_notice(dispatch):
+    return (
+        "[leo routing] %d-byte brief to %s: a fresh agent context is uncached and "
+        "costs more than an inline read. Inline it when one file answers it."
+    ) % (dispatch.prompt_bytes, dispatch.agent)
+
+
+def _log(entry):
+    """Best effort, always. A breadcrumb that cannot be written must not break a
+    dispatch, so every failure here is swallowed -- including a missing module."""
+    try:
+        import dispatch_log
+        dispatch_log.append(entry)
+    except Exception:
+        pass
+
+
+def evaluate(event, name=None):
+    """(action, reason, dispatch, trivial) for one event. Shared by every adapter.
+
+    An in-process adapter knows which harness it is and passes `name`; detection
+    exists only for the command hooks, which get no say.
+    """
+    name = name or harness(event)
+    dispatch = normalize(event, name)
+    action, reason = decide(dispatch, name, routable(name))
+    return action, reason, dispatch, triviality(dispatch)
+
+
+def main(argv=None):
+    mode = os.environ.get("LEOS_AGENT_DISPATCH_GUARD", "on").strip().lower()
+    if mode == "off":
+        return 0
+
+    try:
+        raw = sys.stdin.buffer.read().decode("utf-8", "replace")
+        event = json.loads(raw) if raw.strip() else None
+    except Exception:
+        return 0
+
+    name = harness(event if isinstance(event, dict) else {})
+    try:
+        action, reason, dispatch, trivial = evaluate(event)
+    except Exception as exc:
+        # The guard broke. Allow, and say so distinctly -- an "error" row is the
+        # only way a dead guard is ever noticed.
+        _breadcrumb(name, exc)
+        return 0
+
+    if dispatch is None:
+        return 0
+
+    session = _first_str(event, ("session_id", "sessionId")) if isinstance(event, dict) else ""
+    cwd = _first_str(event, ("cwd", "workspace", "directory")) if isinstance(event, dict) else ""
+
+    try:
+        import dispatch_log
+        entry = dispatch_log.record(dispatch, action, reason, name, session, cwd, trivial)
+        _log(entry)
+    except Exception:
+        pass
+
+    if action == BLOCK and mode != "warn":
+        sys.stderr.write(render_block(dispatch) + "\n")
+        return 2
+
+    # A notice is user-facing only. systemMessage reaches Leo's transcript and
+    # never the model's context, so a false positive here costs zero tokens.
+    # verbose additionally spends ~60 tokens putting it in front of the model;
+    # it stays off until the log says the problem is frequent enough to be worth
+    # paying for.
+    if trivial >= 2:
+        payload = {"systemMessage": render_notice(dispatch)}
+        if mode == "verbose":
+            payload["hookSpecificOutput"] = {
+                "hookEventName": "PreToolUse",
+                "additionalContext": render_notice(dispatch),
+            }
+        sys.stdout.write(json.dumps(payload) + "\n")
+    return 0
+
+
+def _breadcrumb(name, exc):
+    try:
+        import dispatch_log
+        dispatch_log.append({
+            "v": dispatch_log.RECORD_VERSION,
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "harness": name,
+            "decision": "error",
+            "reason": "%s: %s" % (type(exc).__name__, exc),
+        })
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())