Claude Skill

delegating-with-context

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, ha

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oaustegard-claude-skills-plugins_ai-and-reasoning_skills_delegating-with-context-d154993.zip · 19 KB

Install

skills CLI npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/ai-and-reasoning/skills/delegating-with-context
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
Git git clone https://github.com/oaustegard/claude-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.

README

delegating-with-context

Delegate by writing only the task. A PreToolUse hook reads the session transcript, asks Jev (TypeSafe) which chunks the task needs, and appends them to the subagent's prompt. See SKILL.md for the procedure and the hook entry, and oaustegard/experiments/subagent-context-filter for the eval.

Needs a Jev transport: CF_ACCOUNT_ID + CF_API_TOKEN (+ CF_GATEWAY_ID) for the Cloudflare AI Gateway with a stored TypeSafe key, or TYPESAFE_API_KEY.

Skill manifest

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 → 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).

Files (claude-skills)
  • hooks
    • hooks.json 346 B
      Loading…
  • scripts
    • chunking.py 4.6 KB
      Loading…
    • context_hook.py 5 KB
      Loading…
    • hierfilter.py 5.9 KB
      Loading…
    • jevfilter.py 11 KB
      Loading…
    • preview.py 2.8 KB
      Loading…
  • CHANGELOG.md 2.8 KB
    Loading…
  • README.md 480 B
    # delegating-with-context
    
    Delegate by writing only the task. A PreToolUse hook reads the session
    transcript, asks Jev (TypeSafe) which chunks the task needs, and appends them
    to the subagent's prompt. See `SKILL.md` for the procedure and the hook entry,
    and `oaustegard/experiments/subagent-context-filter` for the eval.
    
    Needs a Jev transport: `CF_ACCOUNT_ID` + `CF_API_TOKEN` (+ `CF_GATEWAY_ID`) for
    the Cloudflare AI Gateway with a stored TypeSafe key, or `TYPESAFE_API_KEY`.
    
  • SKILL.md 11.2 KB
    ---
    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.3.0
    ---
    
    # 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:
    
       ```bash
       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** →
      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`):
    
    ```bash
    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):
    
    ```json
    {"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`).
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.