SubagentStart token-lanes carrier for non-blind subagents (native probe, measured RTK rule)

[seathatflowsinourveins]

Summary

• Adds adoption/hooks/claude/token-lanes-subagent-start.py (stdlib only, fail-open, always exit 0) and its sibling token-lanes-block.md (3,159 bytes, first bytes TOKEN LANES). The hook returns the block as SubagentStart hookSpecificOutput.additionalContext to every subagent whose agent_type does not start with blind-.
• Registers the hook in adoption/templates/claude.settings.template.json as its own SubagentStart group (matcher "", timeout 5) beside ai-memory's, and installs both files through the existing sha256-checked guard step (tools/adoption/install_claude_profile.py HOOKS, adoption/hooks/claude/SHA256SUMS).
• docs/token-session-handbook.md gains "Token lanes carried into subagents", the source of truth the block copies line for line, with sources for each line. The RTK line is the measured RTK 0.50.0 rule: a call containing $(...), backticks, <(...), a file redirect or a heredoc is never rewritten; && chains and multi-line blocks are rewritten segment by segment; in a pipeline only a supported producer feeding cat/head/tail or a final grep/rg stage is rewritten, not gh.
• Receipt evidence/artifacts/token-lanes-subagent-start-20260927/ (native probe and RTK hook checks, sanitized), decision record docs/decisions/2026-09-27-token-lanes-subagent-start.md, three anti-pattern log rows in docs/harness-defaults.md, and bootstrap notes for the guard step and the template.
• Why: the WP1 baseline (evidence/artifacts/child-lane-baseline-20260926/, local integration) found the routing block in 42/42 Agent-tool child prompts and 0/597 Workflow child prompts, and SubagentStart context in 0/639 children.

Verification

Native probe (receipt above; evidence class local_integration; Claude Code 2.1.283; each run one claude -p session in this repository's checkout, main model Opus 5.5, one Haiku 4.5 child launched with the Agent tool; positive runs add a settings file whose SubagentStart group runs this branch's hook, negative runs use the host's live settings, which have no such hook):

Run (UTC, 2026-09-27)	Hook	Child	Child's reply	Child transcript
v2 negative, 02:50:39	none	general-purpose	NOT FOUND	no block
v2 positive, 02:50:57	token-lanes	general-purpose	FOUND, "TOKEN LANES (source: docs/token-session-handbook.md, "Token " (the committed block's exact first 60 characters)	one SubagentStart hook_additional_context attachment; hook exit 0, 3,258 bytes of output (the same count recomputed from the committed files)
v2 blind control, 02:52:25	token-lanes	blind-judge	NOT FOUND	no block
v1 negative, 02:37:40	none	general-purpose	NO	no block
v1 positive, 02:49:08	token-lanes	general-purpose	NO	block attached, as in v2 positive

v1 asked whether a block whose first line starts with TOKEN LANES was present. It answered NO in both arms even though the positive transcript held the block, so v1 did not discriminate; it is kept as a failed design. The likely cause is that Claude Code frames attached context (contextRendering: announced); the child's reasoning was redacted, so that cause is not observed. Provider usage for all five runs, as the CLI reported it: costUSD $1.44; Opus 5.5 input 20, output 2,344, cache read 263,466, cache creation 153,558; Haiku 4.5 input 50, output 4,290, cache read 14,666, cache creation 70,203.

RTK 0.50.0 hook checks (receipt, 03:28Z): 17 inputs through rtk hook check and through the rtk hook claude PreToolUse processor the template runs, with identical results. git status / git diff --stat on two lines → rtk git status / rtk git diff --stat; cd /tmp / git status → cd /tmp / rtk git status; git status && git log -n 3 → rtk git status && rtk git log -n 3; git diff | head -n 5 → rtk git diff | head -n 5; git log -n 20 | grep fix → git log -n 20 | rtk grep fix. Not rewritten: gh pr view 1 | head -n 5, $(...), backticks, <(...), > /tmp/x.txt, a heredoc, a two-line block with $(...) on one line, and echo a / echo b (echo has no RTK rule).

Tests (Python 3.13.15, python -m unittest as CI runs it): the full suite passed on this head, 6,474 tests in 723 s (643 skipped), run with a private TMPDIR outside /tmp. An earlier run of the pre-#374 head reported 16 errors and failures, all in tests.test_data_lake_backfill. That module refused its temporary directories because /tmp had become a git work tree during the run; the repository was gone afterwards, and another unit's full suite was running on the host at the time. Touched modules tests.test_token_lanes_subagent_start, tests.test_install_claude_profile and tests.test_render_config: 9, 50 and 19 tests, all OK; #374's tests.test_context_mode_practice_docs and tests.test_apply_claude_settings also pass (5 and 22).

Discriminating controls, each in a throwaway copy:

• The carrier test passes unmodified (9 tests). It fails with an allowlist instead of the blind skip (11 failures, 2 errors), with no blind skip (4), with the old single-line RTK wording (17), with one block word drifted from the handbook (1), with the block missing (12 failures, 2 errors), with the block over 3,500 bytes (1), and with a fallback to an undocumented agentType field (1 error). After the review repair, a character-counting budget check fails the new regression test, and a block padded to 3,560 bytes (3,360 characters) fails the byte check; the pre-repair character check passed that block.
• The guard and template tests pass unmodified (11 tests). They fail without the two HOOKS entries (2), without the template's token-lanes group (1), and with a wrong block checksum (2 failures, 2 errors).

Cross-family review (GPT-6 gpt-6-astra, effort max, read-only, one round) of the first pushed head 85dd27cd: DEFECTS FOUND, one low finding. The text test counted characters against the 3,500-byte budget. It holds, and commit 2e17bae6 repairs it; the finding table is in a PR comment.

Repository checks on this head (replayed onto 6e53809e, after #376, #354 and #374, with main's manifest re-registered for the eight carried files it lists or that are new under evidence/):

• The 16-check validation bundle returned FAILS=0. It covers scripts/validate.py, scripts/host_receipts.py validate, scripts/release_due.py --strict-if-repinned origin/main, the catalog, foundation, landscape, audit, convergence, verdict, component-matrix, grand-list, gap, ecosystem and evidence-manifest checks, and the workflow sums and node tests.
• The hook SHA256SUMS pass sha256sum --check --strict.
• git diff --check is clean.
• The pre-commit gitleaks scan found no leaks, and the private-content scan passed on the receipt.
• No changed file contains a personal path.
• All 24 pinned GitHub URLs in the new text resolve, and each commit pin equals the release tag the repository pins.
• All 5 cited code.claude.com anchors and all 37 relative links on added lines resolve.

Residuals

• No Workflow subagent has run with the hook: the probe used Agent-tool children. WP1 recorded SubagentStart for 465 workflow-subagent children.
• Empty hook output leaves no trace. The blind-judge control shows that no block reached the blind child, not that the hook ran and skipped; the skip is covered by the subprocess tests.
• A plugin-namespaced blind agent type such as plugin:blind-judge does not start with blind- and would receive the block. This repository installs its blind agents as user agents.
• Handbook conflict with context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374: resolved at this PR's replay onto 6e53809e. context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374 inserted "Context Mode executor and session store" where this branch inserts "Token lanes carried into subagents"; both are kept, context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374's first, and the rest of the handbook is identical to main. The block's Context Mode line ("explicitly cd to the actual working directory") is compatible with context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374's section but less detailed: context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374 says to pass cwd for non-shell ctx_execute code. Changing the block would change the bytes the native probe ran against, so it is left for a follow-up with a re-probe.
• A release is needed: the pinned v2026.09.26.2 lacks the two new files.
• No lane-use, compliance or savings measurement. The decision record's overturn condition repeats the WP1 sweep after adoption.

SOTA sources

• Claude Code hooks reference, SubagentStart: agent_type input; additionalContext added to the subagent's context before its first prompt, kept (with the prompt cache) while an earlier copy is in context, and injected again after auto-compaction; plugin-scoped agent types. Add context for Claude: values over 10,000 characters go to a file with a 2,000-character preview.
• Claude Code CHANGELOG at 7779afb1: SubagentStart added in 2.0.43; hook output over 10,000 characters saved to a file in 2.1.89; command-type-only SubagentStart hooks in 2.1.142; SubagentStart context kept in a resumed subagent's prompt prefix in 2.1.265.
• RTK v0.50.0, tag commit 1d87b8e7: src/hooks/decision.rs L86-88 (a call with an unattestable construct is not rewritten), src/discover/registry.rs L951-1013 (rewrite_multiline_block) and L1087-1345 (pipeline stages and rewrite_compound).
• rtk-ai/rtk#3319 (merged 2026-08-03) and its first commit fc8054eb, which added per-line rewriting of multi-line blocks; both are contained in v0.50.0.
• context-mode 1.0.169 (589d8214): hooks/hooks.json (no SubagentStart hook), routing.mjs L892 (PreToolUse:Agent), sessionstart.mjs L166.
• Tool sources for each handbook line, at the repository's pins: codebase-memory v0.11.0 mcp.c L557, jCodeMunch v1.108.319 server.py, Serena c6fbd1c5, SocratiCode v1.14.0, QMD v2.8.3, ai-memory v2.4.1, TOON v4.1.1, Headroom v0.37.0.
• Local reference implementation: the sha256-checked guard-hook install (adoption/hooks/claude/effort-default-guard.py, tools/adoption/install_claude_profile.py, docs/decisions/2026-09-23-max-effort-default.md).

🤖 Generated with Claude Code

[seathatflowsinourveins]

Cross-family review (GPT-6), one round

• Reviewer: codex exec -m gpt-6-astra -c model_reasoning_effort="max" -c 'web_search="live"' -s read-only --skip-git-repo-check, run on a detached checkout of the first pushed head 85dd27cd with the prompt as an argument, stdin /dev/null, the author's scope file and the PR description. It ran 03:44:41Z to 03:51:57Z and exited 0; Codex reported 103,925 tokens used.
• Verdict: DEFECTS FOUND, with 1 finding: 0 high, 0 medium, 1 low. The reviewer's log also records that its receipt audit found no further defects (hashes, usage totals, baseline counts and retained validation results agree).

#	Severity	Location (reviewed head)	Finding	Triage at source	Repair	Verification
1	low	tests/test_token_lanes_subagent_start.py:120	len(block) counts characters, so the test does not enforce the documented 3,500-byte budget; a 3,280-character, 3,520-byte block passes.	Holds. The decision record states a 3,500-byte budget checked by this test. The committed block is ASCII (3,159 bytes, 3,159 characters), so the gap was latent.	2e17bae6: fits_budget() measures the file's UTF-8 bytes; a new regression test uses the reviewer's 3,280-character, 3,520-byte case.	The repaired module passes (9 tests). Controls in throwaway copies: a character-counting fits_budget fails the regression test; a block padded to 3,560 bytes (3,360 characters) fails the byte check and passed the pre-repair character check.

Re-verification on the final head eb64a38f (rebased onto 5af288d9 after #376 and #354; main's manifest re-registered; manifest commit last):

• validate.sh: 16 of 16 checks ok, FAILS=0.
• Full suite: passed on this head, 6,464 tests in 684 s (643 skipped), run with a private TMPDIR outside /tmp. An earlier run of the same head reported 16 errors and failures, all in tests.test_data_lake_backfill. That module refused its temporary directories because /tmp had become a git work tree during the run; the repository was gone afterwards, and another unit's full suite was running on the host at the time.
• Touched modules: 9, 50 and 18 tests OK.

🤖 Generated with Claude Code

[seathatflowsinourveins]

Replayed onto main after #374

The head is now 3917bc4f: the carrier, receipt and review-repair commits replayed onto 6e53809e (#374), with the manifest registration commit last.

• Conflict: only docs/token-session-handbook.md. context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374 inserted "Context Mode executor and session store" where this branch inserts "Token lanes carried into subagents". Both sections are kept, context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374's first. A script check confirmed both sections are byte-for-byte intact and the rest of the handbook is identical to main. The template, the installer test and bootstrap.md merged cleanly.
• Manifest: main's manifests/evidence.json at 6e53809e, with the eight carried files re-registered. component_matrix and new_host_grand_list were regenerated with no changes to the generated reports.
• Re-verification on 3917bc4f:
  • validate.sh: 16 of 16 checks ok, FAILS=0.
  • Full suite: 6,474 tests OK, 643 skipped (private TMPDIR).
  • Touched modules: 9, 50 and 19 tests OK.
  • context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374's tests.test_context_mode_practice_docs (5) and tests.test_apply_claude_settings (22) pass. context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374 did not change merge_hooks, which the carrier's merge test relies on.
  • Hook SHA256SUMS strict check, git diff --check, gitleaks, relative links and personal-path scan: all clean.
• Follow-up, not in this PR: the block's Context Mode line ("explicitly cd to the actual working directory") is compatible with context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374's section but less detailed, since context-mode alignment: credential twins, order-keeping settings merge and practice docs (fix plan steps 7-8) #374 says to pass cwd for non-shell ctx_execute code. Changing the block would change the bytes the native probe ran against, so it waits for a follow-up with a re-probe.

🤖 Generated with Claude Code