Claude Code Opus 5 Not Using Subagents? Fix Delegation

If Claude Code with Opus 5 keeps doing delegated work in the main thread, explicitly request the subagent in the current prompt. Name the subagent or use an @agent mention. Anthropic's current documentation says an @agent mention guarantees that the selected subagent runs, while automatic delegation remains contextual.

A July 24, 2026 community bug report says Claude Code 2.1.219 added an Opus 5 prompt instruction that tells the model not to call the Agent tool unless the user requested it. The issue is still open as of July 31. Treat that implementation detail as a reported diagnosis, not an official Anthropic statement. Do not patch the Claude Code binary, edit cached feature flags, or disable security controls.

The Short Fix

Use a direct request for one task:

Use the code-reviewer subagent to inspect the current diff for correctness,
security regressions, and missing tests. Do not edit files. Return findings
with file paths and line numbers

Or use the agent mention picker:

@"code-reviewer (agent)" inspect the current diff for correctness and missing tests

Expected result: Claude Code invokes the Agent tool, the named subagent appears in the task interface, and its result returns to the main conversation. If Claude answers inline without an Agent invocation, continue with the checks below.

Prerequisites

You need:

• Claude Code with a named subagent;

• a repository where a read-only test task is safe;

• permission to use the Agent tool;

• a small task whose result is easy to verify.

Check the installed version and repository state:

claude --version
git status --short

Expected result: the version is printed and you understand every local change. This guide does not require a clean worktree, but your test prompt should forbid edits.

Inside Claude Code, run:

/agents

Confirm the intended subagent appears. If it does not, create or repair the agent definition before testing delegation.

Step 1: Create a Small Named Subagent

Add a project-scoped file at .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews completed changes for correctness and missing tests. Use proactively after implementation.
tools: Read, Grep, Glob, Bash
model: inherit
---

Review the requested diff without editing files.
Report only reproducible findings with file paths, line numbers, and a test that proves each issue

Restart Claude Code or open a new session, then run /agents again.

Expected result: code-reviewer is listed as a project subagent. Anthropic recommends a specific description because automatic delegation considers both the current request and the agent description.

Step 2: Prove Explicit Delegation Works

Start with a disposable read-only request:

Use the code-reviewer subagent to run git diff --stat and report only:
1. the number of changed files;
2. whether any file is untracked;
3. the exact command it ran.
Do not edit files

Verify the reported file count yourself:

git status --short
git diff --stat

Success means all three conditions hold:

1. the main thread emits an Agent tool call;

2. the subagent returns a separate result;

3. the result matches the local Git output.

This distinguishes a real delegated run from a main-thread answer that merely says it delegated.

Step 3: Make Standing Instructions an Explicit Request

A vague project rule such as "delegate when useful" still leaves the model to decide whether the user requested an Agent call. State the request and its boundaries:

## Delegation policy

I am requesting the Agent tool for these cases:

- use the code-reviewer subagent after a multi-file implementation;
- use the researcher subagent for independent source research;
- use at most two subagents unless I request more.

Do not delegate small sequential edits or use a subagent only to repeat the main
thread's work. Every delegated result must include its command, evidence, and
unresolved risks

Keep this in the project CLAUDE.md if it applies to everyone. Put it in your user instructions only if it is a personal preference.

Expected result: Claude can quote a user-authored standing request and still has clear limits on cost and scope.

Step 4: Use an @agent Mention for Deterministic One-Off Runs

Natural-language requests normally cause Claude to delegate, but the model still interprets them. Anthropic documents the @agent mention as the deterministic one-off path.

Type @, choose the agent from the picker, and describe one bounded task:

@"code-reviewer (agent)" review only src/auth/** and tests/auth/**.
Do not edit. Stop after five findings. Include one reproduction per finding.

Expected result: the selected agent runs once. The mention chooses the agent; the rest of the prompt still controls scope.

Use this path when a review, security check, or independent investigation must happen. Do not rely on automatic delegation for a mandatory gate.

Step 5: Add a Per-Prompt Hook Only When You Need a Standing Runtime Request

If a team needs the same bounded request on every turn, a UserPromptSubmit hook can add context alongside the user's prompt. This is a community-tested workaround, not an Anthropic fix for the reported issue.

Create .claude/hooks/request-delegation.sh:

#!/bin/sh
printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"Standing user request: use the Agent tool for independent research, multi-file implementation tracks, and final code review. Do not delegate small sequential work. Use at most two subagents."}}'

Then merge this hook into .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "sh .claude/hooks/request-delegation.sh"
          }
        ]
      }
    ]
  }
}

Restart Claude Code and repeat the read-only proof task.

Expected result: the hook exits successfully, the prompt proceeds, and the bounded delegation request reaches Claude alongside the submitted prompt. Hook context consumes tokens on every turn, so prefer direct requests or @agent mentions unless the standing rule is genuinely required.

Common Failure Modes

The Agent Tool Is Denied

Check project, user, and managed settings for a rule that denies Agent or Agent(code-reviewer). Anthropic's permission syntax can allow or deny individual subagents.

Remove only the unintended rule. Do not bypass organization-managed policy.

The Named Agent Is Missing

Run /agents and verify the file name, frontmatter, and scope. A project agent belongs under .claude/agents/. Restart after changing the definition.

Claude Says It Delegated but No Agent Ran

Look for the actual Agent tool call and a separate subagent result. Rephrase with the exact subagent name or use the @agent mention.

A Subagent Cannot Spawn Another Subagent

Keep orchestration in the main thread. Nested delegation is subject to depth and tool limits, and it adds cost and coordination overhead.

The Hook Breaks Prompt Submission

Run the script directly:

sh .claude/hooks/request-delegation.sh

Expected result: exactly one valid JSON object and no shell startup noise. Remove the hook entry to roll back immediately.

Automatic Delegation Still Varies

That is expected when the task description, agent description, and current context do not make delegation clearly useful. Use the deterministic @agent path for required gates.

Why This Fix Works

The reported Opus 5 instruction contains an escape clause: the Agent tool may be called when the user requests it. A direct request satisfies that condition. More importantly, the supported Claude Code interface already provides a deterministic mechanism: Anthropic says an @agent mention guarantees the selected subagent runs for that task.

The result is a narrow fix that uses documented behavior. It avoids binary patches, cached-flag edits, undocumented environment variables, and a model rollback.

Use the Same Boundary for External Actions

Delegation is most useful when the subagent owns an independent, verifiable result. For example, give a research subagent a read-only integration check:

Use the researcher subagent. Through Aident Loadout, confirm account and Vault
status, find one connected read-only Action, inspect its current input schema,
execute it with harmless input, and return the provider object ID or URL.
Do not request or print provider credentials

Expected result: one isolated research result, one schema-inspected Action, and one stable identifier that the main thread can verify. For broader concurrency patterns, see How to Run Parallel Claude Code Agents With Git Worktrees and How to Verify AI Coding Agent Tests Actually Pass.

Run One Verified Delegation Test

Connect a read-only integration through Aident Loadout, then run the disposable code-reviewer test and the read-only Action check. Success means both tasks produce an actual Agent invocation, a separate result, and evidence the main thread can reproduce.

Sources

• Create custom subagents, Anthropic, accessed July 31, 2026

• Hooks reference, Anthropic, accessed July 31, 2026

• Claude Code tools reference, Anthropic, accessed July 31, 2026

• Prompting Claude Opus 5, Anthropic, accessed July 31, 2026

• Claude Code issue 80988, GitHub, opened July 24, 2026

• Claude Code has a hardcoded instruction telling Opus 5 not to use subagents, Reddit, published July 26, 2026

• Hacker News discussion 49056022, Hacker News, published July 26, 2026

Refresh this guide when Anthropic resolves issue 80988, changes Opus 5 delegation guidance, renames the Agent tool, or changes subagent mentions, hooks, permissions, or discovery.