Agent SDK: strip unused built-in tool definitions from context when allowed_tools is set

Problem

When using the Agent SDK with allowedTools, the parameter only controls execution permissions — it prevents the agent from calling blocked tools but does not strip their definitions from the system prompt. All 18 built-in tool definitions are always included in context regardless of configuration.

Token cost

The /context command reports:

| Category | Tokens | % of 200k |
|----------|--------|-----------|
| System tools | 16,100 | 8.1% |
| System prompt | 2,700 | 1.3% |
| Skills | 742 | 0.4% |
| Custom agents | 152 | 0.1% |
| Total fixed | ~19,700 | ~10% |

The 16.1k token overhead is comparable to a large MCP server (e.g. Jira at ~17k), but unlike MCP servers, the user has no way to opt out — the tool definitions are baked into the binary.

Built-in tools always present (18 tools)

Task, TaskOutput, Bash, Glob, Grep, ExitPlanMode, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, KillShell, AskUserQuestion, Skill, EnterPlanMode, LSP

An agent that only needs Read and Write still pays the full 16.1k — the token cost for all 18 tools when only 2 are required.

Proposed solution

When allowedTools is specified in the SDK, only include tool definitions for the tools that are actually allowed. This is purely an optimization of what gets sent to the model — the execution-blocking behavior should remain as a fallback safety net.

// Current: all 18 tool definitions are sent to the model despite allowedTools
const conversation = query({
  prompt,
  options: {
    allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
    // → system prompt still contains all 18 built-in tool definitions (16.1k tokens)
  },
});

// Desired: only allowed tool definitions are included in context
const conversation = query({
  prompt,
  options: {
    allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
    // → system prompt only contains these 6 tool definitions
  },
});

Why this matters

• Context efficiency: 16.1k tokens is ~8% of the context window, wasted when most tools are unused.
• Agent focus: Fewer tool definitions means less distraction for the model, potentially improving tool selection accuracy.
• No workaround: Tool definitions are embedded in the binary (sdk-tools.d.ts in @anthropic-ai/claude-agent-sdk), so users cannot reduce this cost themselves.
• Parity with MCP: MCP tools are only included when their server is configured. Built-in tools should follow the same principle when allowedTools provides an explicit subset.