Delegating with context

Writing a background brief for a subagent costs output tokens, generation time, and fidelity: exact paths, error strings and numbers get paraphrased or dropped, and the brief omits what the orchestrator did not know mattered. The context_hook.py PreToolUse hook removes the need. It reads the session transcript, asks Jev which chunks the task needs, and appends those chunks to the subagent's prompt verbatim. The hook fires after the prompt is written, so it cannot save a brief you already wrote. The saving happens here, before the tool input exists.

Procedure

1. Check the hook is live. test -s ~/.claude/context-filter-log.jsonl && tail -1 ~/.claude/context-filter-log.jsonl shows the last filtered delegation. No file on a first delegation is normal; the hook's reply after your first Agent call confirms it (step 5). Where the hook is not wired (claude.ai, a machine without the settings entry), stop here and write a normal brief.

2. Preview what the filter would pass. One call, all tasks at once:

   python3 /mnt/skills/user/delegating-with-context/scripts/preview.py \
     --task "Write the xr latency note for the follow-up memory" \
     --task "Draft the closing status for both PRs"

   Each task prints the kept chunk ids with a one-line gist. This is the check: find the chunk that holds the fact the subagent must not miss. It takes one to two seconds and costs a fraction of a cent.

3. Write only the task. What to do, the deliverable, its format, and any constraint that was never written down in the session. Name things the way the transcript names them ("the Sniff Test benchmark table", "PR #812"): Jev reads literally, and a named thing matches its chunk while "that thing we discussed" matches nothing.
4. Add only what the preview missed. If a needed fact is in no kept chunk, state that one fact in the prompt, or raise the budget with [context-budget: 40000] in the prompt text. Do not restate facts the preview already showed.
5. Spawn, then read the hook's reply. The hook answers with context-filter: appended N of M parent-session chunks (...) and the kept ids. context-filter FAILED (...) means the subagent got your prompt alone: send it the missing facts with SendMessage or re-delegate with them stated.

The hook also covers create_session from any MCP server (mcp__*__create_session). The spawned session receives the task, a line saying the chunks below are reference data from the parent session, the chunks, and the task again at the end. Give it provenance anyway (issue link, parent session id) per docs/delegation.md rule 1 in claude-workspace: a long first message from a parent still looks like injection to a careful delegate.

Markers the hook reads

When NOT to use this skill

Earned exceptions to "write only the task"

Abandon the procedure when

• The hook reports FAILED twice in a row: the transport or key is broken, and every further delegation silently runs without context. Write briefs and fix the transport (Failure modes below).
• The subagent's reply says a fact was missing that the preview showed as kept: the chunk was clipped (a kept chunk is capped at ~6k tokens). Send the fact directly.

Common failure modes

• No context-filter: line after an Agent call → the hook is not wired or crashed before printing. Check .claude/settings.json for the PreToolUse entry and run echo '{}' | python3 .../context_hook.py; it must exit 0 silently.
• no Jev transport → neither CF_ACCOUNT_ID + CF_API_TOKEN (the TypeSafe key is stored in the Cloudflare AI Gateway, CF_GATEWAY_ID routes to it) nor TYPESAFE_API_KEY is set in the hook's environment.
• Preview keeps many chunks that all mention the session's main topic → the scores are compressed because everything looks related. Rename the task with the distinctive nouns of the thing you want; rank, not threshold, is what selects.
• HTTP 429 Rate limited, code 2003 → the AI Gateway's own limit. The filter runs 2 calls at a time and honours Retry-After; parallel delegations each run their own filter, so stagger a fan-out of more than ~4 spawns.
• blocked_chunks above 0 in the log, or HTTP 402 "Payment error from model using BYOK" → not billing. TypeSafe's edge WAF rejected the request bytes (shell commands and curl lines in a transcript read as attack payloads). The filter bisects the window and scores each blocked chunk 0.5, so it can still be kept on rank. If a chunk you need is blocked, state its fact in the prompt.
• A kept chunk states something a later chunk corrected → each chunk is scored on its own merits. User messages are force-kept (clipped) because they carry corrections; if a correction lives in a tool result, state it.

Verification

After the subagent returns: its reply must not say a needed fact was missing, and tail -1 ~/.claude/context-filter-log.jsonl must show the delegation with kept_ids and no error key. A bad success looks like a fluent deliverable with a plausible but wrong number: compare one specific figure against the chunk it came from before relaying it.

Diagnosed failures

• 2026-09-22: the first selection rule force-kept every user-role message. Skill bodies and stop-hook feedback are user-role (isMeta) turns, and on a 181-chunk session they filled the whole 20k budget before any tool result was considered; the chunk holding the answer was dropped. Fixed: isMeta turns are scored like tool results, and real user messages are clipped and capped at a quarter of the budget.
• 2026-09-22: a single condensed window (every chunk clipped to ~1k chars) ranked the key chunk 6th because the fact sat mid-result, outside the clip. Paging at 4x view (five ~27k windows, 1.6 s) ranked it 1st. The filter defaults to the paged view.
• 2026-11-02, hierarchical selection (after DecisionRAG, arXiv 2610.35868): score transcript segments first, then only the chunks inside the top 40% of segments, at 8x view. Over 52 delegations from 16 archived sessions (19 to 581 chunks) it was never worse than the flat 4x filter and better on 3 (+2.7% fact recall, CI +0.0% to +6.4%), at a median 31% fewer Jev tokens. It is the default; CONTEXT_FILTER_MODE=flat restores the flat filter.
• 2026-11-02: on sessions of ~500+ chunks the global-state loop never terminated and the hook timed out at 120 s, passing no context (fixed in 0.2.3).
• 2026-09-23, eval over 32 delegations from 8 archived sessions: written briefs lost every fact on 5 tasks by telling the subagent to look the fact up ("check the pr-workflow config entry") instead of stating it; neither the filter nor the full transcript ever did. That is what step 3 prevents.
• 2026-09-23, first real create_session probes: two Haiku cloud sessions received the appended context (their first-turn token counts match) and stalled at need-input, one saying the message looked truncated, the other that no request had arrived. The context ended the message and the task sat above ~20k tokens of transcript. Labelling the block as reference data and repeating the task after it, the next probe answered correctly first time.

Scripts

• scripts/chunking.py: transcript JSONL to chunks (user, assistant, harness, tool call + result), with secret values and token patterns redacted before anything leaves the machine.
• scripts/jevfilter.py: windows under Jev's limits (32k state plus longest question, 64k state plus all questions), one Noul per chunk, rank into the budget.
• scripts/hierfilter.py: the default selector. Level 1 scores segments (a new one at each user message and every 8 chunks) from short digests; level 2 scores the chunks of the kept segments with jevfilter's windows and packs them with its select.
• scripts/context_hook.py: the PreToolUse hook. Fails open and says so. CONTEXT_FILTER_MODE=flat switches it to jevfilter.build_context.
• scripts/preview.py: step 2.

Install as a plugin (the hook wires itself; hooks/hooks.json):

claude plugin marketplace add oaustegard/claude-skills
claude plugin install delegating-with-context@oaustegard-claude-skills

Or wire it by hand in .claude/settings.json, guarded so a missing file exits 0 (python3 on a missing path exits 2, which blocks the tool call):

{"matcher": "Agent|Task|mcp__.*__create_session", "hooks": [{"type": "command", "timeout": 120,
  "command": "f=/mnt/skills/user/delegating-with-context/scripts/context_hook.py; test -f \"$f\" || exit 0; exec python3 \"$f\""}]}

Evidence: with ~20k tokens of selected chunks a fresh subagent found 99/105 required facts, against 102/105 with the whole ~81k-token transcript and 82/105 with a written brief; method and caveats in oaustegard/experiments/subagent-context-filter/RESULTS.md.

Related evidence, 2026-10-01: relaying a long stream through one fresh call per chunk, Jev keeping lines verbatim kept 835/835 required lines exactly, while a subagent copying them into its own notes retyped one with an invented hash; for a running register the subagent's in-place table won (oaustegard/experiments/clm-relay-needles).