[FEATURE] Per-model configurable autocompact threshold

[Theurgist]

Preflight Checklist

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

Problem Statement

With the 1M context window now available for Opus, a single global CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is no longer sufficient. Different models benefit from different compaction strategies, and users need per-model control over when autocompact triggers.

Motivation

When using Opus (1M context) as the primary model that spawns Sonnet subagents, the optimal autocompact threshold differs significantly between them:

Use Case Example

• Opus (1M): I may want to compact at ~30% (300K tokens) to keep costs manageable and responses fast, since the full 1M window is rarely needed
• Sonnet subagents: I want them to use a larger portion of their context (e.g., 80-90%) since they handle focused, bounded tasks where more context is useful

Currently, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE applies globally — forcing a single trade-off that can't serve both use cases.

Proposed Solution

Allow per-model autocompact thresholds in settings.json:

{
  "autoCompactThreshold": {
    "default": 80,
    "opus": 30,
    "sonnet": 90,
    "haiku": 95
  }
}

Or alternatively, extend the environment variable approach:

CLAUDE_AUTOCOMPACT_PCT_OPUS=30
CLAUDE_AUTOCOMPACT_PCT_SONNET=90
CLAUDE_AUTOCOMPACT_PCT_HAIKU=95
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80  # fallback default

Why Not Use the Existing Global Override

Scenario	Global at 30%	Global at 90%
Opus (1M) primary session	Good — keeps cost/latency down	Bad — consumes up to 900K tokens before compacting
Sonnet subagents	Bad — compacts too early, loses useful context for focused tasks	Good — maximizes available context

There is no single value that works well for both.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Additional Context

Related Issues

• Auto-compact should trigger earlier / threshold should be configurable #28728 — Auto-compact should trigger earlier / threshold should be configurable
• Feature Request: Configurable Context Window Compaction Threshold #15719 — Configurable Context Window Compaction Threshold
• Feature request: Configurable autocompact buffer size #15435 — Configurable autocompact buffer size

[github-actions]

Found 3 possible duplicate issues:

1. Auto-compact should trigger earlier / threshold should be configurable #28728
2. Feature request: Configurable auto-compaction threshold #25679
3. Allow controlling autocompact when spawning teammates #26764

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Theurgist]

#26764 is closest one, but there are no duplicates.
We could want to have both global per-model and per-agent configuration

[simfor99]

+1 — strong use-case evidence from a multi-agent workflow running daily.

My scenario (Sanctum-OS, ~daily Claude Code use)

Main agent: Opus 4.6 [1M] as orchestrator
Subagents: parallel general-purpose + specialized agents, spawned 4-6 at a time for:

• Codebase analysis (large repos, heavy Read/Grep)
• Parallel web research
• Multi-agent GTM pipelines (6+ agents per wave)

Why the global CLAUDE_AUTOCOMPACT_PCT_OVERRIDE breaks this

• Main at 25-30% works perfectly — keeps Opus 1M responses fast, costs bounded, and I can steer mid-flow
• Same 25% applied to subagents = compact triggers at ~50k (on 200k subagent windows) → subagents die mid-task, work is lost, orchestrator has to restart waves

I had to raise the global override to keep subagents alive, which defeats the purpose for the main agent. There is no value of a single global setting that serves both.

Second dimension beyond "per-model"

Worth considering: the split isn't purely per-model — it's per-role (orchestrator vs. subagent). An Opus orchestrator wants early compact; an Opus subagent on a focused task wants late compact. The proposed autoCompactThreshold.opus wouldn't capture that.

Suggestion: either role-aware (main / subagent) OR both axes (autoCompactThreshold.subagent.opus = 90).

Related: #30396 (subagents hitting limit without compact triggering at all) strongly suggests subagent compact behavior deserves its own config surface.

[simfor99]

Follow-up: per-invocation runtime parameter on Task() calls

Building on my earlier comment — after another day of running this in anger, I want to surface a third axis beyond per-model and per-role: per-invocation overrides on the Task() tool itself.

Why settings-level config alone isn't enough

Even with autoCompactThreshold.subagent.opus = 90, I still can't express "this specific subagent is about to read a 100k-token spec, give it headroom; the next one only needs Grep, keep it tight". Subagent memory pressure is workload-dependent, not just model-dependent.

Proposed API

Extend Task() with optional overrides that win over settings.json:

Task({
  description: "Analyze large architecture doc",
  prompt: "...",
  subagent_type: "general-purpose",
  model: "sonnet",
  autocompact_pct: 92,      // NEW — per-call override
  context_limit: "1M"        // NEW — optional, if model supports it
})

Precedence: Task() args > --settings profile > user settings.json > env var > default.

Why this solves a real problem

• Orchestrator can budget dynamically based on what it's about to ask the subagent to do — same pattern Claude Code already uses for model and mode.
• No proliferation of settings profiles for edge cases.
• Mirrors how CLAUDE_AUTOCOMPACT_PCT_OVERRIDE currently inherits into subagents — this just makes that inheritance overridable per call instead of session-global.

Happy to help test a preview build against my multi-agent pipelines (6+ parallel subagents/wave, mixed Opus/Sonnet) if useful.