context-optimization

Apply observation masking first to replace verbose tool outputs with compact retrievable references, then trigger compaction when utilization exceeds 70%. Structure prompts with stable prefixes to maximize KV-cache reuse, and partition work across sub-agents only when a single window cannot hold the task.

Observation masking replaces verbose tool outputs with compact references like '[Obs:{ref_id} elided. Key: {summary}]' once their purpose is served. The full content is stored externally and remains retrievable, achieving 60-80% reduction in masked observations with under 2% quality impact.

Place stable content first in the prompt: system prompt, tool definitions, templates, then conversation history, with dynamic content last. Remove timestamps, session IDs, and counters from the system prompt, since even a single whitespace change invalidates the cached prefix downstream.

Trigger compaction when context utilization exceeds 70-80%, not at 90% or higher. Compacting under extreme pressure degrades summary quality, causing loss of task goals and user constraints. Target 50-70% token reduction with less than 5% quality degradation.

Avoid partitioning when the task has fewer than 3 independent subtasks, because each sub-agent requires its own system prompt, tool definitions, and coordination messages. For small tasks, this coordination overhead often exceeds the context savings.

Masking error outputs hides stack traces and failure details the agent needs in later turns to diagnose issues. During active debugging, suspend masking for all error-related observations until the issue is resolved.