leos-agent 10.7.0 → 10.7.2

package/README.md

@@ -1,6 +1,6 @@
 # leos-agent
 
-Leo's portable agent operating policy, version **10.7.0**, installable on Claude
+Leo's portable agent operating policy, version **10.7.2**, installable on Claude
 Code, Codex, Cursor, Hermes, Pi, and OpenCode through each harness's own plugin
 system.
 
@@ -119,7 +119,7 @@ their global instruction file.
 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,
+this policy has. From 10.7.2 that half of the rule is enforced by a hook instead,
 and the prose it replaced came out of the always-loaded payload — enforcement in
 code costs **zero** context per turn, so the guard paid for itself in bytes
 before saving a cent.
@@ -134,17 +134,21 @@ can name one. Three ways to comply, all of them one word:
 | a generic agent, no model | `subagent_type: "leo-executor"` | an approved plan, a well-specified change |
 | a generic agent, no model | `model: "<name>"` | investigation and debugging — naming it *is* the stated reason |
 
+A plugin install namespaces the type — dispatch `leos-agent:leo-runner` rather
+than `leo-runner`; the guard accepts either.
+
 It never picks a model for you. It cannot force cheap work onto an expensive
 problem, so it cannot cause a quality regression — only an explicit choice. It
 is also deliberately narrow: a false block costs one re-dispatch, while a caught
 inherited fan-out saves the cold prefix of every child, so the margin only holds
 while the rule refuses to make judgment calls.
 
-Detection is by **argument shape**, not tool name — 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.
+Detection is by **argument shape**, not tool name: a dispatch is a call that
+selects an agent and carries a brief. A shape the guard does not recognise is
+left alone, so a harness it has never met keeps working. MCP tools are never
+guarded. Anything that goes wrong inside the guard allows the call and records
+`decision: "error"`, kept distinct from a decision to allow, because a guard
+that dies quietly is worse than no guard.
 
 ```
 LEOS_AGENT_DISPATCH_GUARD=on       block (default)
@@ -154,13 +158,17 @@ LEOS_AGENT_DISPATCH_GUARD=on       block (default)
 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.
+**Per harness.** Claude Code dispatches `Agent` with `subagent_type`, and a
+plugin install namespaces it — both forms are tiers. Codex dispatches
+`spawn_agent`, which selects behaviour by `model` and `reasoning_effort` rather
+than by naming an agent, so there the guard requires `model`; its `message` is
+encrypted, so the over-delegation heuristic and block-conversion tracking do not
+apply on Codex. Hermes and OpenCode run the same policy in-process, blocking by
+directive and by throw respectively. Pi has no hook surface.
+
+**Codex hash-pins hooks.** A new version of the guard enforces nothing there
+until it is re-approved through `/hooks`, and the symptom is silence — zero
+Codex rows in `dispatch_log.py report`.
 
 ### What it records
 
@@ -187,7 +195,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.7.0">
+<leos-agent version="10.7.2">
 ...the payload...
 </leos-agent>
 ```
@@ -256,7 +264,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.7.0/scripts/leo-install.py claude --uninstall
+python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py claude --uninstall
 ```
 
 ```bash
@@ -287,7 +295,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.7.0/scripts/leo-install.py codex
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py codex
 ```
 
 This writes `~/.codex/AGENTS.md` and installs two economical agents:
@@ -312,7 +320,7 @@ threads only. Re-adding an already-installed plugin is idempotent.
 **Uninstall**
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.0/scripts/leo-install.py codex --uninstall
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.7.2/scripts/leo-install.py codex --uninstall
 ```
 
 ```bash
@@ -461,7 +469,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.7.0
+pi install git:github.com/foxhatleo/leos-agent@v10.7.2
 ```
 
 Re-run `/skill:install` afterwards.
@@ -681,7 +689,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.7.0+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
+`10.7.2+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
 reach a **new** session or thread.
 
 `--check` exits non-zero when a file is out of date, and `--force` replaces a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leos-agent",
-  "version": "10.7.0",
+  "version": "10.7.2",
   "description": "Leo's portable agent operating policy: orchestrator main thread, subagent-first execution, cost-tiered model routing.",
   "type": "module",
   "main": "index.js",

package/scripts/dispatch_guard.py

@@ -49,7 +49,7 @@ 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",
+    "tool agent model prompt_bytes prompt_lines path_count prompt_hash prompt_head opaque",
 )
 
 # The agent-selection field is mandatory, and that is the whole trick. A rule
@@ -71,6 +71,19 @@ SKIP_PREFIXES = ("mcp__",)
 # Seeded empty on purpose: populate from field reports, not from guesses.
 SKIP_TOOLS = frozenset()
 
+# Dispatch tools that select behaviour by model rather than by naming an agent,
+# so the agent-key rule alone would never see them. Exact names only, and only
+# ones observed in a real rollout: Codex's spawn_agent takes
+# {task_name, message, fork_turns, model, reasoning_effort} -- task_name is a
+# free-text label, so `model` is the entire routing decision there.
+DISPATCH_TOOLS = ("spawn_agent",)
+
+# Tools whose brief does not arrive as readable text. Codex encrypts `message`,
+# so its length is a proxy at best and its hash changes on every re-send. Both
+# the size heuristic and the conversion hash are suppressed rather than reported
+# as if they meant something.
+OPAQUE_BRIEF_TOOLS = ("spawn_agent",)
+
 ALLOW, BLOCK = "allow", "block"
 
 # Path-ish tokens in a brief. Scanning is capped at the first 8 KiB -- the
@@ -131,21 +144,26 @@ def normalize(event, _harness=None):
 
     agent = _first_str(args, AGENT_KEYS)
     prompt = _first_str(args, PROMPT_KEYS)
-    if not agent or not prompt:
+    known = tool in DISPATCH_TOOLS
+    if not prompt or not (agent or known):
         return None
 
     from dispatch_log import digest  # local: a no-op call must not pay for this
 
+    opaque = tool in OPAQUE_BRIEF_TOOLS
     head = prompt[:PATH_SCAN_BYTES]
     return Dispatch(
         tool=tool or "-",
-        agent=agent,
+        # A model-routed dispatch names no agent; label it by its tool so the log
+        # reads sensibly without inventing a tier that was never selected.
+        agent=agent or tool,
         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],
+        prompt_bytes=0 if opaque else len(prompt.encode("utf-8", "replace")),
+        prompt_lines=0 if opaque else prompt.count("\n") + 1,
+        path_count=0 if opaque else len(set(PATH_RE.findall(head))),
+        prompt_hash=None if opaque else digest(prompt),
+        prompt_head="" if opaque else prompt[:200],
+        opaque=opaque,
     )
 
 
@@ -160,7 +178,7 @@ def triviality(dispatch):
     for a log line and disqualifying for a block, which is why this is only ever
     a log line.
     """
-    if dispatch is None:
+    if dispatch is None or dispatch.opaque:
         return 0
     score = 0
     if dispatch.prompt_bytes < 220:
@@ -182,7 +200,9 @@ def routable(name):
     inherit and say so -- blocking there would demand something the harness
     cannot do, a false positive by construction.
     """
-    if name == "claude":
+    # Both take a model per spawn: Claude Code on its dispatch tool, Codex as
+    # spawn_agent's `model` argument.
+    if name in ("claude", "codex"):
         return True
     try:
         import routing
@@ -192,11 +212,21 @@ def routable(name):
         return False
 
 
+def _is_tier(agent):
+    try:
+        from dispatch_log import is_tier
+        return is_tier(agent)
+    except Exception:
+        # Never let a missing sibling module turn a compliant dispatch into a
+        # refusal: fall back to allowing anything that looks like a tier.
+        return bool(agent) and agent.rsplit(":", 1)[-1].startswith("leo-")
+
+
 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-"):
+    if _is_tier(dispatch.agent):
         return ALLOW, "leo-tier"          # the agent definition carries the model
     if dispatch.model:
         return ALLOW, "explicit-model"    # a choice was typed; cheap or not
@@ -205,13 +235,26 @@ def decide(dispatch, name, is_routable):
     return BLOCK, "no-model"
 
 
-def render_block(dispatch):
-    """The refusal. It must name the remedies, or it costs a turn to discover them."""
+def render_block(dispatch, name=None):
+    """The refusal. It must name the remedies, or it costs a turn to discover them.
+
+    The remedies differ by harness: Codex routes by `model` on spawn_agent and
+    has no agent to name, so offering it a subagent_type would be advice it
+    cannot take.
+    """
+    if dispatch.tool in DISPATCH_TOOLS or name == "codex":
+        return (
+            "[leo routing] BLOCKED - %s names no model, so it would silently inherit\n"
+            "the parent's. Re-dispatch with `model` set (and `reasoning_effort` with it),\n"
+            "naming the economical tier's model for narrow work.\n"
+            "Set LEOS_AGENT_DISPATCH_GUARD=off to disable, =warn to log only."
+        ) % dispatch.tool
     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'
+        '    (a plugin install namespaces these: "leos-agent:leo-runner")\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
@@ -280,7 +323,7 @@ def main(argv=None):
         pass
 
     if action == BLOCK and mode != "warn":
-        sys.stderr.write(render_block(dispatch) + "\n")
+        sys.stderr.write(render_block(dispatch, name) + "\n")
         return 2
 
     # A notice is user-facing only. systemMessage reaches Leo's transcript and

package/scripts/dispatch_log.py

@@ -47,6 +47,23 @@ MAX_BYTES = 1 << 20
 RECORD_VERSION = 1
 
 
+TIER_PREFIX = "leo-"
+
+
+def is_tier(agent):
+    """Is this one of the economical-tier agents?
+
+    Match the bare name after any namespace. A plugin install namespaces the
+    type -- Claude Code dispatches `leos-agent:leo-runner`, not `leo-runner` --
+    and a raw prefix test rejects that, which blocked the exact path the refusal
+    message recommends. That is the worst false positive this guard can have, so
+    the one place that decides it is shared rather than repeated.
+    """
+    if not agent:
+        return False
+    return agent.rsplit(":", 1)[-1].rsplit("/", 1)[-1].startswith(TIER_PREFIX)
+
+
 def path():
     return os.path.join(_data_root(), LOG_NAME)
 
@@ -149,7 +166,7 @@ def summarise(entries):
     tiers = collections.Counter()
     for entry in entries:
         agent = entry.get("agent") or ""
-        if agent.startswith("leo-"):
+        if is_tier(agent):
             tiers[agent] += 1
         elif entry.get("model"):
             tiers["explicit model"] += 1

package/scripts/usage_scan.py

@@ -336,6 +336,16 @@ def scan_guard():
         return {"error": "%s: %s" % (type(exc).__name__, exc)}
 
 
+def _is_tier(agent):
+    """Shared with the guard, so the report cannot disagree with enforcement
+    about what counts as a tier -- namespaced plugin types included."""
+    try:
+        import dispatch_log
+        return dispatch_log.is_tier(agent)
+    except Exception:
+        return bool(agent) and agent.rsplit(":", 1)[-1].startswith("leo-")
+
+
 def routing_compliance(dispatches):
     """Problem (c), quantified: how many dispatches named a tier, and how many
     let the parent's model ride along."""
@@ -343,7 +353,7 @@ def routing_compliance(dispatches):
     inherited_bytes = 0
     for d in dispatches:
         agent = d.get("agent") or "-"
-        if agent.startswith("leo-"):
+        if _is_tier(agent):
             tiers[agent] += 1
         elif d.get("model"):
             tiers["explicit model"] += 1