How to disable subagents in Claude Code

TLDR

We can use the following methods to disable subagents in Claude Code:

(1) Deny specific subagents (deterministic, recommended)

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

(2) Disable built-in Explore and Plan subagents

CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1

(3) Disable fork subagent mode globally

CLAUDE_CODE_FORK_SUBAGENT=0

(4) Disable all built-in subagents (SDK / non-interactive)

CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1

(5) Quick-and-dirty prompt-based block (not enforced)

Add to the top of your CLAUDE.md:

DO NOT create subagents, ever.

⚠️ Method 5 is a prompt suggestion, not a hard constraint. The model can still ignore it. Use methods 1–4 when you need deterministic enforcement.

How to disable subagents on Claude Code

In Claude Code, "subagents" can be understood on two levels: one refers to specialized AI assistants with independent contexts (such as Explore, code-reviewer, etc.), and the other refers to the "fork subagent" mode that inherits the complete conversation context. You can flexibly disable them through configuration files, command-line flags, or environment variables.

Disable specific subagents

If you only want to prevent Claude from calling certain custom or built-in subagents, you can add denial rules to the project or user settings file (settings.json).

Add the subagent names to be disabled in the permissions.deny array, using the format Agent(subagent-name). This method applies to both built-in and custom subagents.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

You can also specify it temporarily when starting Claude Code using the command-line flag:

claude --disallowedTools "Agent(Explore)"

Disable built-in Explore and Plan subagents

Claude Code comes with read-only subagents specifically designed for codebase exploration and pre-planning. If you want to disable them and have Claude handle related tasks directly in the main conversation, you can set the following environment variable to 1:

CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1

After disabling, Claude will use its own search tools or general-purpose subagents to complete exploration work, and the planning mode will read files directly.

Disable fork subagent mode

Fork subagents are a special mode that inherits the complete conversation context, enabling faster task handling by reusing the parent prompt cache. It is enabled by default in interactive sessions.

If you want to completely disable fork mode in all sessions, set the following environment variable to 0:

CLAUDE_CODE_FORK_SUBAGENT=0

Note: Setting it to 0 will override any server-side rollout configuration and take effect globally.

Disable all built-in subagents (in SDK or non-interactive mode)

If you are using Claude Code in a non-interactive environment or through the Agent SDK and need to remove all built-in subagent types, you can set:

CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1

Disable via CLAUDE.md instruction (prompt-based)

The simplest method is to add a hard instruction at the top of your CLAUDE.md file:

DO NOT create subagents, ever.

Important caveats:

• This is a prompt suggestion, not a runtime constraint. The model can still ignore it, especially in long sessions or complex tasks.
• It does not prevent subagent descriptions from being loaded into the system prompt—those still consume tokens.
• It can be overridden by conflicting instructions later in the file (e.g., "Use subagents for code review").
• Use this method only when you want to reduce subagent spawning, not eliminate it. For real enforcement, use permissions.deny, environment variables, or hooks.

Why the CLAUDE.md approach is weaker than configuration

If subagent spawning has real costs—burning API quota, causing recursive agent explosions, or violating security constraints—use the deterministic methods.

Claude Code subagent example

The following is a typical read-only code review subagent definition, demonstrating how to constrain tool permissions and specify output format:

    ---
    name: code-reviewer
    description: Reviews staged changes for bugs, security issues, and code quality. Use proactively after code changes.
    tools: Read, Grep, Glob, Bash
    model: inherit
    ---

    You are a senior code reviewer. Review the current staged changes.

    Review checklist:
    - Clear and readable code
    - Well-named functions and variables
    - No duplicated logic
    - Proper error handling
    - No exposed secrets or API keys
    - Input validation implemented

    Output format for each issue:
    - File: path/to/file.ts:42
    - Severity: High / Medium / Low
    - Issue: Description
    - Fix: Suggested resolution

Claude Code subagent template

A general-purpose subagent file template is as follows, stored in .claude/agents/ (project level) or ~/.claude/agents/ (user level):

    ---
    name: agent-name
    description: When and why to use this agent. Be specific so Claude routes correctly.
    tools: Read, Grep, Glob
    model: sonnet
    ---

    You are a specialized assistant for [specific domain].

    When invoked:
    1. [First step]
    2. [Second step]

    Guidelines:
    - [Constraint or rule]
    - [Output format expectation]

Key frontmatter fields:

• name: Unique identifier, referenced in deny rules
• description: Claude uses this to decide when to delegate to this subagent
• tools: Tool allowlist; if omitted, inherits all tools
• model: haiku, sonnet, opus, or inherit

Claude Code subagent model

The execution model of a subagent is determined by the following priority order (from highest to lowest):

1. Model passed when Claude spawns the agent
2. model field in the subagent definition file (including inherit)
3. CLAUDE_CODE_SUBAGENT_MODEL environment variable (applies to all subagents without explicitly assigned models)

If you want to force all subagents to run on one specific model, you can set:

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1

This will override the model selection in individual subagent definitions and uniformly apply the model specified by CLAUDE_CODE_SUBAGENT_MODEL.

Pros

Subagents have the following core advantages:

• Context isolation: The intermediate process of subagent exploration, logging, and file reading does not flood the main conversation; only concise summaries are returned, keeping the main context clear
• Tool restriction: You can grant read-only permissions (such as Read, Grep, Glob) to subagents responsible for review or auditing, preventing accidental modifications
• Reusability: User-level subagents (~/.claude/agents/) can be shared across projects, and project-level subagents can be checked into version control for team collaboration
• Cost control: Simple tasks (such as documentation generation, summarization) can be routed to cheaper, faster models like Haiku, reducing token consumption
• Parallel execution: Multiple subagents can run independently, suitable for batch modifications of the same pattern in multiple files

Cons

Subagents also have corresponding costs and limitations:

• Overhead exists: Each subagent starts an independent context, consumes tokens, and introduces additional layers of indirection
• Unable to communicate with each other: Subagents can only report results to the main conversation and cannot coordinate directly between subagents; tasks requiring coordination are better suited for Agent Teams
• Not suitable for same-file parallel editing: Multiple subagents modifying the same file in parallel can lead to conflicts
• Not suitable for simple tasks: For quick fixes or single-file lookups, the overhead of delegating to a subagent may outweigh the benefits
• Description budget limit: The combined descriptions of all subagents must be controlled within 15,000 tokens; too many subagents will reduce the accuracy of automatic delegation
• Prompt-based disabling is unreliable: Adding "DO NOT create subagents" to CLAUDE.md is easily ignored and does not prevent description loading or token consumption