[FEATURE] Mods: let turn.step set context_management (clear_tool_uses) on the model request

Problem

A mod cannot turn on the API's server-side context editing (context_management with clear_tool_uses_20250919) for the requests Claude Code sends.

turn.step is the hook on each model request. Its TurnStepInput lets a hook rewrite only model and effort. Everything else is pinned, and nothing on it, or anywhere else in the mod API, reaches the request's context_management field or its beta headers. Checked against the types the engine writes on 2.1.289 (.claude-plugin/types/claude-code/index.d.ts): no context_management, clear_tool_uses or betas field exists.

Why it matters

I maintain a compaction mod: a session.compact hook that trims old tool inputs and outputs and keeps the conversation's text. It cut compaction time from 24 to 66 s down to under 30 ms in real sessions. Its limit is that it only acts at compaction time. Between compactions, stale tool results stay in every request.

clear_tool_uses is the right tool for that gap: it clears old tool results on the server, keeps the record that the call happened, and is cache-aware. Research on agent context (JetBrains, "The Complexity Trap", arXiv 2508.21433) finds that masking old tool observations matches or beats LLM summarization at lower cost. A mod is the natural place to opt in, but it has no way to do so.

Ask

Let a turn.step hook set the request's context editing config, the same way it can rewrite model and effort. For example:

on('turn.step', async function* ($, e, next) {
  yield* next({
    ...e,
    contextManagement: {
      edits: [{ type: 'clear_tool_uses_20250919', trigger: { type: 'input_tokens', value: 80_000 }, keep: { type: 'tool_uses', value: 6 } }],
    },
  })
})

The engine would add the matching beta header. A settings key would also work, but the hook form lets a mod pick per loop (main vs subagent) and per model.

A smaller step that would still help: a read-only flag on TurnStepInput saying whether context editing is on for the step, so mods that compact can avoid doing the same work twice.

Related

• #84756: a hook to transform the message array before each request. Context editing would cover the most common reason for it, with no client-side rewrite and no cache break.
• #69627: clear_context_uses, generalizing clear_tool_uses (closed).
• #91870: the Mods thread; one comment there asks for the composed request on TurnStepInput.

Claude Code 2.1.289, macOS.