/delegating-with-context

name: delegating-with-context
description: Delegates work to a subagent or spawned session by writing only the task, while a PreToolUse hook pages the parent transcript through Jev and appends the chunks that task needs. Use before writing any Agent tool prompt or create_session prompt, and when asked to delegate this, hand this off, use a subagent, spawn an agent, run agents in parallel, or brief a subagent on what we have done so far.
metadata:
  version: 0.2.2

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

| In the prompt | Effect | |---|---| | `[no-context]` | Hook skips; the prompt goes as written | | `[context-budget: N]` | Token budget for appended context (default 20000) | | `subagent_type: "fork"` | Hook skips; a fork already inherits the parent context |

When NOT to use this skill

| Situation | Use instead | |---|---| | The subagent needs nothing from this session (fresh research, a standalone lookup) | Add `[no-context]` and write the prompt normally | | The subagent must reason over the whole session (review everything we did) | `subagent_type: "fork"`; it inherits the full context | | Many small per-item judgments (label 400 rows) | Jev or Gemini directly, per `docs/delegation.md` in claude-workspace; a subagent costs ~32k tokens before it reads its prompt | | Choosing which model or agent type should run the work | `agent-routing` | | Parallel API fan-out from claude.ai, where hooks do not run | `orchestrating-chat-agents` | | A long job relayed through many fresh subagents that must carry a running result (a tally, a register, a board) | Have each step maintain a compact state file and check its invariants in the harness after every step. Kept chunks hold facts, not a running count: once the events outgrow the budget the count is gone (`oaustegard/experiments/clm-relay-needles`) |

Earned exceptions to "write only the task"

| Restating background is | when | |---|---| | banned | the fact appears in the transcript as a tool result, a user message or your own reply | | earned | the fact exists only in your reasoning (thinking is not in the transcript), a decision you made silently, or a constraint nobody wrote down | | earned | the preview shows the chunk holding it was not kept |

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*