danieldekay/ai-ops/lean-ctx-subagent

LeanCTX Subagent Dispatch (v2 — measured)

Subagents in the Pi harness get no `ctx_*` MCP tools and no `lean_ctx` tool — CLI only. The harness (subagent tool, runs.run/runs.all) owns orchestration; lean-ctx owns context + state. Coordination tools (ctx_agent, ctx_task, ctx_workflow, ctx_share, ctx_handoff) are hidden local-compat substrate — do not build dispatch on them.

Measured ground truth (2026-09-27, do not re-litigate without new evidence)

The dispatch recipe

1. Parent: curate the brief (before spawning)

Before any dispatch, the parent must provide a concrete brief that is read from disk and contains:

• allowed_files: the exact file set the child may read or edit. No broader exploratory write set is implied.
• write_policy: no_new_files, edit_only, or allowed_new_files:<list>; default is no_new_files.
• tool_capability: shell: true|false, git: true|false, network: true|false, and which tools the child actually has.
• gate_command: the exact verification command that proves the task and whether the parent or child runs it.
• owner: who is responsible for each gate or side-effect step.

Parent preflight REQUIRED:

1. Read the brief targets from disk before the child starts.
2. Run git status --porcelain once before dispatch.
3. Compare every intended path against allowed_files. If a path is outside the list, reject the brief; do not delegate.
4. If shell: false, the brief must explicitly name the parent as the only runner for shell/gate commands.
5. If shell: true, the brief must say which commands the child may run, and the child must not invent additional shell actions.

The child must confirm the effective capabilities in its first reply: allowed_files=..., shell=<true|false>, gate_owner=<parent|child>, write_policy=<...>, and git_status_checked=<true|false>.

3.11 update (measured 2026-10-21, lean-ctx 3.11.4): first-class agent

identities now exist on the CLI: `lean-ctx agent register --id <id> --role

coder --owner daniel@kaesmayr.net → agent suspend|decommission <id>`.

The old ground truth "CLI agent commands do not exist" expired with 3.11.

The AGENTS.md child carve-out was updated accordingly (2026-10-21): children

register at session start and decommission at exit — unregistered children

show as "unknown" in the AGENTS panel. The MCP coordination tools

(ctx_agent/ctx_task) remain hidden substrate and stay off-limits for

dispatch.

Run ctx_overview(task) and/or ctx_compose(task) yourself — you have the MCP tools and they are 10× cheaper than the child's CLI equivalents. Extract:

• a fresh agent id for the child: pi-<agent-name>-<6char> (e.g. pi-worker-shell-a1b2c3)

• 2–4 vetted file paths (verify they exist and are the RIGHT ones — a wrong brief

costs the child one targeted grep, not a fail)

• one targeted search hint (exact symbol/regex, scoped path)
• the quality-gate or verification command, if the task mutates code

2. Child prompt template

Task: <one-paragraph task>
 
Pre-vetted file list from the parent (start here, do not explore widely):
- <path1>
- <path2>
If none fit, search narrowly (grep <exact symbol> in <scoped path>) before widening.
 
CLI discipline (you have no MCP ctx_* tools):
- cd to the project root first — CLI writes bind to the daemon session root, not cwd
- Do NOT run `lean-ctx session task` — the parent owns session.task
- Reads: lean-ctx read <file> [-m map|signatures|lines:N-M]; full only for edit prep
- Shell: lean-ctx -c "<cmd>"; exact output: lean-ctx raw "<cmd>"
- Search: lean-ctx grep <pattern> <path>
- Report findings for parallel siblings: lean-ctx knowledge remember "<finding>" (short-term only)
- Durable conclusions: report them back in your output — the parent files them in the wiki
Verify your own work — run the gate tool before reporting DONE.
 
Identity (3.11+): register your agent id as your first step and decommission at exit:
lean-ctx agent register --id <agent-id-from-parent> --role coder --owner daniel@kaesmayr.net
lean-ctx agent decommission <agent-id>   # on completion; `agent suspend <id> --reason` on early exit

Each run gets a fresh id; never reuse ids across runs. If agent register does not exist in the installed lean-ctx (< 3.11), skip silently.

3. Parent: verify

Subagent claims are not evidence. Re-run the gate tool yourself (ruff, basedpyright, pytest --co), check git diff for scope creep and over-deletion, and grep for references to any moved/deleted symbol.

Two hardened rules (2026-10-22, repeat warden corrections):

• Relayed causal claims need own reproduction. A child's root-cause/diagnosis

statement ("pre-existing bug", "env gap", "load-order issue") is a claim, not a finding. Reproduce it with your own command, quote your own output, and mark anything you did not check as unverified with the reason. Detect the refined version of the claim too — e.g. "pre-existing" is only provable back to the last change you actually inspected, not to the bug's true onset.

• Brief claims must be read from disk before dispatch. Do not characterize

changes/flags (e.g. "declares skip_specs", file paths, task counts) from list output or impressions; read the change dirs/files and verify every factual statement in the brief. Wrong brief facts cost a supervisor round-trip or a blocked child.

Memory routing

• Long-term/durable → LLM wiki: parent files child findings via wiki_observe

/ wiki_retro. Never ctx_knowledge.

• Short-term, session/feature-scoped, parallel-agent exchange → `ctx_knowledge`:

children may lean-ctx knowledge remember intermediate findings for siblings and the parent to recall. Treat as ephemeral — it decays and gets polluted.

• Session state → `ctx_session`/`lean-ctx session`: parent-owned. Children only

append finding/decision values if instructed, never task.

Context packages (ctx_pack) — current status

ctx_pack (MCP-only) creates versioned .ctxpkg packages from the live knowledge store. Measured caveats: silently embeds the full knowledge graph even when the graph layer is not requested (summary said "Graph nodes: 0", file had 26,874 nodes); auto-load has no observable effect on overview; no CLI install path for children. Do not use as the subagent session-start mechanism until the export is scoped and a real consumption path exists. If a portable handoff is needed, write a markdown brief file and pass its path in the child prompt.

Anti-patterns (all measured)

Shell-boundary discipline

• One command per tool call. Do not bundle multiple commands into a single shell line.
• Never use inline interpreters to do one-off logic: no node -e, python3 -c, perl -0pi, or similar one-liners as a substitute for a proper script or tool call.
• No speculative chained commands (&&, ||, or shell globbing) unless the brief explicitly authorizes the exact sequence and the result is required for the task.
• After a BLOCKED result or repeated failure on the same command pattern, stop retrying variants of the same failed approach. Change the method, narrow the probe, or use a structured tool.
• Prefer a structured tool (read/search/edit/runner) over ad-hoc shell pipelines when the tool can answer the question directly.
• If the task requires shell access, the brief must say so up front and the child must name its effective shell: true|false state before editing.

• ❌ Mandating lean-ctx overview in a scoped child task — 15K tok of tree, zero task signal
• ❌ Child runs lean-ctx session task — clobbers the parent's triage signal
• ❌ Telling a child to call ctx_share/ctx_compile/ctx_agent — tools don't exist there
• ❌ Building dispatch on ctx_agent/ctx_task/ctx_workflow — hidden Research substrate, disabled
• ❌ Recording durable facts with lean-ctx knowledge remember — store is noise-polluted; use wiki
• ❌ Running lean-ctx knowledge consolidate (or --all) after cleaning the knowledge store — it re-imports the session diary as new facts and re-creates the junk (measured: 0 facts → 7 immediately). If a clean is needed, remove items and skip consolidate; never consolidate as a "tidy-up" step.
• ❌ Trusting "DONE" without re-running the gate tool yourself
• ❌ Telling a child to switch to the NATIVE edit tool after it read files with ctx_read

(measured 2026-10-23, tmd_core lane): native edit requires a prior NATIVE read of that exact path, so a lean-ctx-first child deadlocks in a retry loop on "RETRYABLE — Edit without read". Reads through ctx_read/lean-ctx read do NOT satisfy it. Brief children to edit with ctx_edit (no read requirement, replace_all: true for repeated patterns), or to call the native read immediately before a native edit. Same applies to ctx_patch anchored ops, which want anchors from ctx_read(mode="anchored").

• ❌ Dispatching without the task field present in the call (validated 2026-10-21,

7 occurrences in one session): async single-child calls arrive with an EMPTY task ("Task:" signature, taskHash sha256("")) when the field is omitted or the call shape is fumbled (e.g. agent passed where workflow: true was intended). The child correctly refuses to improvise and blocks. Recovery: deliver the real brief via subagent_supervisor reply to the child's supervisor ask — that channel worked every time. Prevention: include task in EVERY dispatch, and verify the child's fork first-message is the real brief before waiting (probe-first below is mandatory, not advisory).

Fallback

No lean-ctx CLI available in the child → same recipe minus the CLI lines: brief in prompt, native tools, verify gates yourself. The brief is the mechanism; lean-ctx CLI in the child is a compression aid, not the handoff channel.

Parallel-lane implementation (measured 2026-10-06, kg-parallel-ingest)

For multi-lane implementation in one checkout, partition by FILE OWNERSHIP and run disjoint lanes in parallel — no worktrees needed: