[FEATURE] clear_context_uses: cache-aware eviction of used context (skills / files / memories / tool results), generalizing clear_tool_uses

I built a working reference implementation and a cost model for this, to show
the demand is concrete and that there's a cache-correct design behind it.
Summary below; the repo is linked at the end.

The problem

When a Skill is invoked, its entire SKILL.md body enters the conversation and
stays there for the rest of the session. That's the right behavior for a
behavioral or persona skill you want active throughout. But for a knowledge
skill (one that loads reference material or a procedure the model consumes once
and then moves on), the body becomes dead weight: re-sent and re-attended on
every later request, never used again.

There's no way to drop a single, finished skill. The only existing relief is
global auto-compaction, which is lossy, triggered by a token budget rather than
by "this skill is done," and re-attaches skills anyway. Tool results already have
a targeted mechanism for exactly this shape of problem
(clear_tool_uses_20250919); skills have no equivalent.

And the cost isn't only tokens. A large skill body stranded in the middle of the
prompt also dilutes attention for the rest of the session.

The proposal

clear_skill_uses is the skill analogue of clear_tool_uses. Once a skill has
been used, the harness replaces its body with a short placeholder and keeps the
record that it ran, so the model still sees the skill was used and can reload it
on demand. Everything else in the prompt stays untouched.

It's opt-in per skill (default off), behind a strict safety gate: behavioral and
persona skills are never evictable — not by policy, not by an explicit target.
Only a deliberate human override can drop them. So a finished knowledge skill
stops costing tokens, while the instructions that govern how the model behaves
are never touched.

Eviction is deterministic and harness-driven, exactly like clear_tool_uses
— it is not a tool the model calls. (An earlier version of this proposal included
a model-invocable clear_skill tool; see "Why not a model-invoked tool" below for
why I dropped it.)

Why this needs a real design, not just a button

Dropping a skill from the middle of the prompt isn't free: it breaks the
prompt-prefix cache at the cut. The prefix above stays warm, but the span below
it must be reprocessed once. So whether eviction is a net win is arithmetic, not
instinct:

• you save cheap cache-reads of the skill body on every remaining request, and
• you pay a one-time reprocess of the work done while the skill was live.

Eviction wins for skills that are large, long-lived, and evicted early (before
that reprocessed span grows). Formally, with cache-read price ρ and cache-write
price ω, evict when ρ·s·M > ω·X: the reads saved over the remaining tail beat
the one-time reprocess. The same logic is exactly why behavioral skills should
not be evicted: they're cheap to keep and you want them all session. The repo
derives this with real prefix-cache pricing and validates it against measured
cache-token deltas.

Why not sub-agents or forks?

Two existing tools also shed a skill's tokens, but they solve a different
problem, because both work by isolating or discarding the whole working context
rather than by trimming one consumed instruction out of the live one.

• Sub-agents run the skill in a separate context window and hand back only a

summary. That sheds the skill body, but it also sheds the actual work done
with it: the file reads, the tool results, and the reasoning never enter the
main thread, and the sub-agent runs on its own prefix cache rather than the
parent's. You delegate the whole task away and get back only what the
sub-agent chose to summarize.

• Forks (context: fork) run the skill in a throwaway branch that is

discarded afterward, which keeps nothing: you lose the skill and the work
produced while it was active.

Both also have to be chosen up front, before the work happens. clear_skill_uses
is the opposite: you stay in one context window, on one warm prefix cache, do the
work, keep all of it (the reads, the results, the chat), and the harness drops
only the one instruction body once it has been used. The eviction is triggered by
the skill actually being consumed, not by a routing choice you commit to in
advance.

Proposed shape

• Opt-in frontmatter on a skill: an ephemeral flag (default off), a trigger

for when to evict (e.g. once the skill has been used), and a small budget for
the placeholder it leaves behind.

• A clear_skill_uses strategy under the existing

context-management-2025-06-27 beta, symmetric with clear_tool_uses: applied
automatically by the harness, fired by the frontmatter trigger or a token
threshold — never a tool the model invokes.

Each eviction leaves the placeholder, marks the skill so auto-compaction won't
resurrect it, and reports how many tokens it freed versus reprocessed.

Why not a model-invoked tool

An earlier draft of this proposal added a model-invocable clear_skill tool for
agentic self-pruning. I've dropped it, and the reason is what keeps the design
honest: clear_tool_uses has no model-invoked mode — it is a context-management
strategy, applied by the harness on a trigger, not a button the model presses.
The faithful skill analogue is the same: deterministic, harness-driven eviction
(the frontmatter trigger plus the token threshold). In the reference
implementation a model-driven clear also behaved badly in practice — the model
fired it mid-turn before it had finished using the skill, or redundantly on a
skill the frontmatter trigger already owned, with no coverage the automatic
triggers didn't already provide. So eviction stays a harness decision; the
model's only skill-related action is loading one with invoke_skill.

Related requests

This revives #21583 ("Remove skills from context when not in use", closed as
stale) and consolidates the partial asks in #39749 (load-time enable/disable),
#45091 (/clear before execution), #35150 (programmatic clear + continuation),
and #17283 (context: fork on the Skill tool). None of these specify a
cache-correct, single-skill, after-use mechanism.

Scope

Core context-management behavior is sensitive and the interactive harness isn't
community-owned, so this is an RFC plus a working reference, not a merge request.
It's something concrete to react to. Happy to reshape toward whatever native form
fits — the most natural landing is purely as a new context-management strategy
type, symmetric with clear_tool_uses.

Repo: https://github.com/lkzppm/ephemeral-context