leos-agent 10.6.0 → 10.7.0

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())

package/scripts/dispatch_log.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""dispatch_log: the append-only record of every subagent dispatch the guard saw.
+
+WHY A LOG AT ALL. dispatch_guard.py decides one call at a time and can never see
+a fan-out, so the signals that need a second dispatch to interpret -- was a block
+followed by a compliant re-dispatch, was a small brief one of five siblings --
+are recorded here and resolved at read time. Judgment that lives in the reader
+costs nothing on the hot path and can be revised without a Codex /hooks
+re-approval.
+
+NEVER PROMPT TEXT. This file sits in a home directory forever and would otherwise
+accumulate briefs about whatever Leo works on. Prompts and working directories
+are stored as truncated SHA-256, which is enough to notice the same brief
+re-dispatched after a block and useless to anyone reading the file. Raw text only
+under LEOS_AGENT_DISPATCH_LOG_PROMPTS=1, truncated, and documented as debug-only.
+
+The file is ${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}/dispatch.jsonl,
+beside routing.json and the handoffs -- data lives with the data, never inside
+the plugin, so an upgrade or an uninstall cannot take it.
+
+  dispatch_log.py report [--limit N] [--json]   what the guard has been seeing
+  dispatch_log.py path                          the log's path
+
+Exit codes: 0 ok, 2 on bad usage.
+"""
+import argparse
+import collections
+import hashlib
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+# Same data root and the same lock discipline as every other machine-local file.
+# _locked takes any path (it locks a sibling .lock), which is why a .jsonl can
+# use it even though state_file() would force a .json suffix.
+from state import _data_root, _locked  # noqa: E402
+
+LOG_NAME = "dispatch.jsonl"
+
+# One megabyte, one generation. ~230 bytes per record is roughly 4,500 dispatches
+# per file and 9,000 retained -- months of history, bounded at 2 MiB forever, with
+# no cron job and nothing to configure.
+MAX_BYTES = 1 << 20
+
+RECORD_VERSION = 1
+
+
+def path():
+    return os.path.join(_data_root(), LOG_NAME)
+
+
+def digest(text):
+    """A short, irreversible stand-in for text we refuse to store."""
+    if not text:
+        return None
+    return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:12]
+
+
+def _keep_prompts():
+    return os.environ.get("LEOS_AGENT_DISPATCH_LOG_PROMPTS") == "1"
+
+
+def record(dispatch, decision, reason, harness, session=None, cwd=None, trivial=0):
+    """The on-disk shape for one dispatch. Pure; writes nothing."""
+    entry = {
+        "v": RECORD_VERSION,
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "harness": harness,
+        "session": digest(session),
+        # Parallel dispatches from one assistant message land in the same
+        # two-second bucket, which is how `report` tells a fan-out from a
+        # sequence of lone spawns without the hot path ever reading the log.
+        "burst": "%s:%d" % (digest(session) or "-", int(time.time() // 2)),
+        "project": digest(cwd),
+        "decision": decision,
+        "reason": reason,
+    }
+    if dispatch is not None:
+        entry.update({
+            "tool": dispatch.tool,
+            "agent": dispatch.agent,
+            "model": dispatch.model,
+            "trivial": trivial,
+            "prompt_bytes": dispatch.prompt_bytes,
+            "prompt_lines": dispatch.prompt_lines,
+            "paths": dispatch.path_count,
+            "prompt": dispatch.prompt_hash,
+        })
+        if _keep_prompts():
+            entry["prompt_text"] = dispatch.prompt_head
+    return entry
+
+
+def append(entry):
+    """Append one record. Rotates at MAX_BYTES. Raises only on real I/O trouble.
+
+    Callers must treat a failure here as cosmetic: the guard's decision is made
+    before this is called and emitted after it, so a read-only home or a full
+    disk costs a log line, never a dispatch.
+    """
+    target = path()
+    with _locked(target):
+        try:
+            if os.path.getsize(target) > MAX_BYTES:
+                os.replace(target, target + ".1")
+        except OSError:
+            pass  # absent, or unstattable; either way there is nothing to rotate
+        # 0600 explicitly: open("a") yields 0644 under a default umask, which is
+        # the wrong mode for a file that indexes Leo's projects even in hashes.
+        fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a") as fh:
+            fh.write(json.dumps(entry, sort_keys=True) + "\n")
+
+
+def read(limit=None, target=None):
+    """Records, oldest first. Tolerates a truncated final line from a crash."""
+    out = []
+    for candidate in ((target,) if target else (path() + ".1", path())):
+        try:
+            with open(candidate, encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                    except ValueError:
+                        continue  # a half-written last line, or a foreign line
+                    if isinstance(entry, dict):
+                        out.append(entry)
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            sys.exit("dispatch_log: %s: %s" % (candidate, exc.strerror or exc))
+    return out[-limit:] if limit else out
+
+
+def summarise(entries):
+    """The read-time judgment: burst collapse, tiers, and block conversion."""
+    # Only dispatches that actually ran count toward a burst. A block and the
+    # re-dispatch it forced land in the same two-second bucket, and counting
+    # both would let every blocked retry pose as a fan-out of two.
+    bursts = collections.Counter(
+        e.get("burst") for e in entries if e.get("decision") not in ("block", "error")
+    )
+
+    tiers = collections.Counter()
+    for entry in entries:
+        agent = entry.get("agent") or ""
+        if agent.startswith("leo-"):
+            tiers[agent] += 1
+        elif entry.get("model"):
+            tiers["explicit model"] += 1
+        elif entry.get("decision") == "block":
+            tiers["blocked"] += 1
+        else:
+            tiers["inherited"] += 1
+
+    # A trivial-looking brief that was one of several in the same burst is a
+    # fan-out, which the policy wants. Only a lone small spawn is a finding --
+    # and only one that actually ran: a blocked dispatch spent nothing, so it
+    # cannot also be an over-delegation.
+    trivial = [
+        e for e in entries
+        if e.get("trivial", 0) >= 2
+        and e.get("decision") not in ("block", "error")
+        and bursts.get(e.get("burst"), 0) < 2
+    ]
+
+    # Did a block actually change anything? A blocked brief whose hash comes back
+    # naming a tier is the guard working; one that never returns was abandoned.
+    blocked = {e.get("prompt") for e in entries if e.get("decision") == "block"}
+    blocked.discard(None)
+    converted = {
+        e.get("prompt") for e in entries
+        if e.get("prompt") in blocked and e.get("decision") != "block"
+    }
+
+    return {
+        "records": len(entries),
+        "window": [entries[0].get("ts"), entries[-1].get("ts")] if entries else [],
+        "harnesses": dict(collections.Counter(e.get("harness") for e in entries)),
+        "decisions": dict(collections.Counter(e.get("decision") for e in entries)),
+        "tiers": dict(tiers),
+        "errors": sum(1 for e in entries if e.get("decision") == "error"),
+        "blocked": len(blocked),
+        "converted": len(converted),
+        "trivial_lone_spawns": len(trivial),
+        "agents": dict(collections.Counter(
+            "%s @ %s" % (e.get("agent") or "-", e.get("model") or "inherited")
+            for e in entries
+        )),
+    }
+
+
+def render(summary):
+    lines = []
+    # Errors lead. Conflating "the guard crashed" with "the guard allowed" is how
+    # a dead guard goes unnoticed for months, so a nonzero count is the headline.
+    if summary["errors"]:
+        lines.append("!! %d guard error(s) -- the guard failed open this many times" % summary["errors"])
+    if not summary["records"]:
+        lines.append("no dispatches recorded yet (%s)" % path())
+        return "\n".join(lines)
+
+    lines.append("%d dispatch(es)  %s .. %s" % (summary["records"], summary["window"][0], summary["window"][1]))
+    lines.append("  harnesses   " + ", ".join("%s %d" % kv for kv in sorted(summary["harnesses"].items())))
+    lines.append("  tiers       " + ", ".join("%s %d" % kv for kv in sorted(summary["tiers"].items())))
+    if summary["blocked"]:
+        lines.append("  blocks      %d, of which %d re-dispatched with a tier named" % (
+            summary["blocked"], summary["converted"]))
+    lines.append("  lone small spawns  %d  (fan-outs excluded)" % summary["trivial_lone_spawns"])
+    lines.append("  agent @ model:")
+    for name, count in sorted(summary["agents"].items(), key=lambda kv: (-kv[1], kv[0])):
+        lines.append("    %-44s %d" % (name, count))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="dispatch_log.py", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    report = sub.add_parser("report", help="what the guard has been seeing")
+    report.add_argument("--limit", type=int, default=None, help="only the most recent N records")
+    report.add_argument("--json", action="store_true", help="machine-readable summary")
+    sub.add_parser("path", help="the log file's path")
+
+    args = parser.parse_args(argv)
+    if args.command == "path":
+        print(path())
+        return 0
+
+    summary = summarise(read(limit=args.limit))
+    print(json.dumps(summary, indent=1, sort_keys=True) if args.json else render(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())