feat(core): tool output masking service for context reclamation

[netbrah]

What

ToolOutputMaskingService — a pre-turn pass that replaces older bulky tool outputs with preview snippets while preserving full output on disk. Includes synchronous token estimation and telemetry.

Why

In long agentic sessions, old tool outputs are the largest consumers of context budget. The model doesn't need the full content of a file read from 20 turns ago — but it still occupies thousands of tokens. Chat compression helps but requires an LLM call. Tool output masking is zero-cost context reclamation that runs synchronously before each turn.

The approach: protect the newest tool outputs (configurable budget), mask everything older with a preview snippet, save full output to disk (recoverable). Exempt tools that carry semantic state (skill, memory, ask_user_question) are never masked.

Architecture

Before each turn:
  1. Scan history newest → oldest
  2. Accumulate tool output tokens until protection threshold exceeded
  3. Everything past the threshold → candidate for masking
  4. If total prunable tokens > minimum threshold → run masking pass
  5. For each candidate: write full output to disk, replace with preview
  6. Log telemetry (tokens saved, count masked)

Supporting components

• tokenCalculation.ts — Synchronous token estimation with ASCII/non-ASCII heuristic, media estimates, function response handling. Fast enough to run every turn.
• ToolOutputMaskingEvent — Telemetry event for monitoring savings across sessions.
• Shell output preview formatter — Extracts structured sections (Output, Error, Exit Code) from shell results for meaningful previews.

Configuration

Under experimental.toolOutputMasking:

Setting	Default	Description
enabled	true	Master switch
toolProtectionThreshold	50000	Token budget for newest unmasked outputs
minPrunableTokensThreshold	30000	Minimum prunable before masking runs
protectLatestTurn	true	Shield most recent turn

Test Plan

24 tests across 2 files:

tokenCalculation.test.ts (8 tests):

• Plain text, non-ASCII, function response, empty array, long strings, image tokens, recursion depth, multiple parts

toolOutputMaskingService.test.ts (8 tests):

• Disabled config, empty history, below-threshold no-op, above-threshold masking, latest-turn protection, exempt tools (skill/memory), already-masked skip, masking indicator tag presence

Plus existing client.test.ts and mcp-client.test.ts mock updates for config compatibility.

Demo

N/A — internal context management. Observable via telemetry events showing token savings and reduced compression frequency in long sessions.

Fixes #2567