[FEATURE] Hook-writable context block that gets replaced instead of appended

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Ask: let a hook write a size-capped block that sits at the tail of the conversation and gets replaced each turn instead of appended.

Preflight

• [x] Searched existing requests. #26215 asks to expose the context_management API param. This asks for a client-side block Claude Code manages itself. Happy to fold it into that issue if you'd rather.
• [x] Single feature request

Problem

UserPromptSubmit → additionalContext is append-only. Inject a state block every turn and it stacks: N turns × block size, permanently, and it pulls compaction forward.

The only way to keep injected context small today is to inject it rarely. Then it's stale when you need it.

Cache cost

Cache invalidation is the obvious objection. It stays bounded if the block is anchored at the absolute tail, after the user message:

[...cached prefix...][a_N-1][u_N][BLOCK_N]

Drop BLOCK_N next turn and invalidation starts after u_N. You reprocess the last assistant turn, the new prompt, and the new block. Everything earlier is still a cache hit.

Per-turn cost: the last assistant response moves from read price to write price. On tool-heavy turns that's real money. It's also bounded and constant. The alternative today is unbounded growth plus earlier compaction, and compaction reads everything it summarizes.

Notes

• Option to leave a placeholder when a block drops would be nice, the way the context editing API does, so references to it in prior assistant turns don't dangle.
• Shouldn't touch assistant blocks (thinking block signatures).

Proposed Solution

Proposed shape

{
  "hookSpecificOutput": {
    "contextBlock": {
      "id": "state",
      "maxTokens": 2000,
      "content": "..."
    }
  }
}

Same id on the next turn replaces the previous block.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Dynamic context management layered on the skill system: one always-current state block holding active task, recent decisions, and a skill index. The option to have momentary-but-fleeting small memories as the agent works would be extremely helpful for a system I am building for improving agent memory quality in various ways.

The skill index part matters on its own. Skill descriptions aren't re-injected after compaction, so a large skill library goes partly invisible post-compact.

Additional Context

_No response_