claude-code - 💡(How to fix) Fix Allow opt-out of built-in deferred tools via settings to reduce baseline context [2 comments, 2 participants]

Problem Statement

On Claude Code v2.1.123 with a Pro plan (200k cap), a fresh session has a baseline context usage of ~41k tokens before any real work begins. Of that, 20.2k (10.1%) comes from built-in deferred tools — TodoWrite, Cron*, Enter/ExitPlanMode, Enter/ExitWorktree, Monitor, NotebookEdit, PushNotification, RemoteTrigger, TaskOutput, TaskStop, WebFetch, WebSearch, AskUserQuestion. These are listed by name and short description in the system reminder so ToolSearch can discover them.

Listing them by default is a reasonable design choice for discoverability. The problem is there's no way to opt out of the ones I never use.

My workflow:

• Solo Delphi/Firebird development on Windows
• No notebook work → NotebookEdit unused
• No scheduled tasks → Cron*, RemoteTrigger, PushNotification, Monitor, TaskOutput, TaskStop unused
• No worktree usage → Enter/ExitWorktree unused

That's ~10 tools I never invoke, each contributing to the 20.2k baseline. Combined with built-in MCP integrations (~21k more) and plugins (~10k), the working budget shrinks meaningfully — re-caching after the 5-minute prompt cache TTL costs more, and autocompact triggers earlier in long sessions.

This is distinct from #48680 (claude.ai marketplace MCP instruction blocks loading unconditionally) and #47645 (ToolSearch env var bug, closed as duplicate). Both cover MCP-side issues. This request is specifically about built-in tools shipped with the binary — there's no MCP config to remove and no extension to disable for these.

Proposed Solution

A ~/.claude/settings.json field to opt out of built-in deferred tools by name:

{
  "disabledBuiltinTools": [
    "CronCreate",
    "CronDelete",
    "CronList",
    "Monitor",
    "NotebookEdit",
    "PushNotification",
    "RemoteTrigger",
    "TaskOutput",
    "TaskStop"
  ]
}

Behavior:

• Listed tools are removed from the system reminder entirely (not just hidden from ToolSearch)
• ToolSearch cannot discover them
• Calling them returns the standard "tool not available" error
• Wildcards (Cron*) optional but convenient
• Default behavior unchanged — opt-in only

Alternative shape with allowlist mode:

{
  "deferredTools": {
    "mode": "allowlist",
    "include": ["TodoWrite", "WebSearch", "WebFetch"]
  }
}

Either shape works. The key requirement is that the tool's name and description are removed from the system reminder, not just deferred — that's what reduces baseline tokens.

Alternative Solutions

• Disabled the Chrome extension to drop the Claude_in_Chrome MCP — works for that specific MCP, but doesn't help with built-in system tools.
• Removed unused plugin marketplaces from settings.json — saves ~500 tokens, marginal.
• Set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 to avoid the 1M tier — separate issue (#30033), but related theme of context inflation.
• /clear, /compact, end-session more frequently — manages active context but doesn't change the baseline floor.

None of these address the built-in tools surface. The only "workaround" today is to accept the 20k tax.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Scenario: starting a long debugging session on a legacy Delphi codebase.

1. Open Claude Code in the project directory.
2. /context shows 41k baseline (20.2k from built-in deferred tools, of which I use only TodoWrite, WebSearch, and WebFetch).
3. Working budget after the 33k autocompact buffer is ~125k.
4. After 30 minutes of active debugging, I'm near the autocompact threshold and lose conversational context I'd rather keep.

With disabledBuiltinTools configured to drop the ~10 tools I never use:

1. /context shows ~21k baseline (50% reduction in deferred tools).
2. Working budget grows to ~145k.
3. Autocompact triggers later or not at all in a typical session.
4. Re-caching after the 5-minute TTL is cheaper because the cache prefix is smaller.

The same pattern helps users on Free/Pro plans with tighter caps, and users with many memory files or MCPs who are already close to limits.

Additional Context

Screenshot of /context on a fresh session (one greeting exchange) showing the 20.2k cost of built-in deferred system tools — see image attached below.

Related issues:

• #48680 — claude.ai marketplace MCP instructions inject regardless of Tool Search (different mechanism)
• #47645 — ToolSearch env var ignored, MCP tools load eagerly (closed as duplicate)
• #41809 — disabled MCP servers still appear in deferred list
• #38365 — feature request for lazy MCP initialization
• #44653 — Plan mode ExitPlanMode not available via ToolSearch (evidence of edge cases in the deferred tools system)
• #30033 — 1M context bug v2.1.63 (similar UX of silent context inflation)

Environment:

• Claude Code: v2.1.123
• Platform: Windows 11
• Plan: Pro
• Plugins: caveman, context-mode, skill-creator
• Note: Chrome extension was disabled before taking the screenshot, but MCP tools (deferred) is still ~21k from other built-in MCPs (Claude_Preview, ccd_*, mcp-registry, scheduled-tasks, plugin MCPs).

Happy to provide repro logs, test a prototype, or refine the proposed schema if helpful.