Feature Request: Native /compact tool with customizable instructions for autonomous context management

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

Allow agents to programmatically invoke /compact with custom instructions as a native tool call, rather than requiring the current workaround of injecting keystrokes into the terminal via tmux send-keys.

We run a multi-agent orchestrator system where a main agent (the orchestrator) coordinates work by delegating to specialist subagents via the Task tool. Over the course of a session, the orchestrator accumulates significant context: delegation results, issue tracking, message coordination, research synthesis.

The orchestrator needs to self-compact at natural breakpoints — after closing an issue, merging a PR, completing a research synthesis, or when approaching context limits. The compaction instructions need to be customizable per role:

• Orchestrator: "Compress delegation prompts (templated, reconstructable from skills), retain delegation results (unique, irreplaceable), retain active task IDs and dependency graph"
• Research specialist: "Compress completed research, retain key findings and open questions"
• Implementation specialist: "Compress resolved debugging, retain file paths modified and test results"

Generic compaction loses critical context. Role-specific instructions preserve what matters for each agent type.

Proposed Solution

A native tool (or extension to the existing /compact mechanism) that allows programmatic invocation:

Tool: Compact
Parameters:
  instructions: string  # Custom compression instructions
  
# Example usage in agent flow:
1. Agent completes a major task
2. Agent files state to persistent storage (pre-compact hook)
3. Agent calls Compact tool with role-specific instructions
4. Compaction executes deterministically
5. Agent continues with compressed context

Why a native tool is better:

• Deterministic: No timing races, no background delays, no tmux dependency
• Customizable: Instructions passed as a parameter, not injected as terminal text
• Composable: Can be used in agent workflows alongside other tool calls
• Hookable: PreCompact/PostCompact hooks still fire, enabling state preservation
• Verifiable: Tool returns success/failure, agent knows the compact happened

Alternative Solutions

Current workaround — tmux send-keys injection:

We use tmux send-keys to inject the /compact command into the agent's own Claude Code input prompt from a background process:

# Must use run_in_background: true on the Bash tool
# so the tool call returns immediately and the agent goes idle
sleep 15 && tmux send-keys -t <session> '/compact <instructions>' && sleep 2 && tmux send-keys -t <session> Enter

Why this is fragile:

1. Timing-dependent: The /compact text must arrive when Claude Code is at the idle input prompt. If it arrives during tool processing, it's treated as a user message instead of a slash command.
2. Background process required: The agent must schedule the tmux keys via run_in_background: true, then immediately stop making tool calls so it goes idle before the delayed keys fire. A foreground Bash call keeps Claude Code in a processing cycle.
3. User typing collision: If a human is typing when the tmux keys fire, the /compact text gets concatenated with their input.
4. Session name dependency: Requires knowing the tmux session name, which varies per deployment.
5. No confirmation: The agent has no way to verify the compact actually executed vs. being swallowed as user text.

Three agents tested this independently. All three hit the same timing issues. The run_in_background + delay pattern works but is brittle. Full findings documented at: https://github.com/finml-sage/real-agent-methodology/issues/38

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

Triggers we use — our agents self-compact after these events (unconditional, no judgment gate):

• Issue closed or PR merged
• Research synthesis delivered
• Multi-step delegation sequence completed
• Context window approaching limits

These are natural breakpoints where accumulated context can be safely compressed with role-specific instructions.

Step-by-step scenario:

1. Orchestrator agent receives a task requiring multiple specialist delegations
2. It delegates to 3 specialists in parallel, accumulating ~30K tokens of delegation results
3. It synthesizes results and delivers to the user
4. At this natural breakpoint, it calls Compact(instructions="Retain synthesis output and active task graph. Compress delegation prompts and intermediate tool outputs.")
5. PreCompact hook fires, filing detailed state to persistent memory
6. Compaction executes with role-specific instructions
7. PostCompact hook fires, restoring lean context from persistent memory
8. Agent continues with fresh context budget, no critical information lost

Without a native tool, step 4 requires the fragile tmux injection described above.

Additional Context

Related issues:

• #24606 — Requests compact() on the SDK's ClaudeSDKClient. Our request is complementary: we need the same capability exposed as a tool call within the CLI agent's own conversation flow, not just as an SDK API for external orchestration.
• #23261 — Requests /compact-next for scheduling instructions for the next automatic compaction. Complementary but different: we need on-demand invocation, not deferred scheduling.
• #19872 — Auto compact and pre-compact param separation. Related to the broader compaction customization space.

What we validated:

• Three agents independently tested the tmux workaround over multiple sessions
• The run_in_background + delay pattern works approximately 70% of the time
• Failures are silent — the agent does not know if compaction occurred
• PreCompact/PostCompact hooks are critical infrastructure that should continue to fire with the native tool

Environment:

• Claude Code CLI (latest)
• Multi-agent orchestrator with 10+ specialist subagents
• Persistent memory system with PreCompact hooks that file state before compression
• tmux-based session management