When Claude Code finds subagent definitions with the same name in managed settings, `--agents`, project, user and plugin scopes, which one runs?
answer
- five sources, one winner
- organisation outranks everything
- session flag beats files on disk
- project beats personal
- plugins rank last and are namespaced
basics
~10 sThe highest-priority source wins: managed settings, then the --agents flag, then the project's .claude/agents/, then ~/.claude/agents/, then plugins. Among nested project directories, the definition closest to the working directory wins.
solid answer
~40 sClaude Code ranks subagent sources: managed settings (organisation-wide) first, the `--agents` JSON flag (this session only) second, the project's `.claude/agents/` third, your `~/.claude/agents/` fourth, and a plugin's `agents/` directory last. The highest-priority definition with a given `name` runs. Project agents are found by walking up from the working directory, and the closest `.claude/agents/` wins between nested ones. Two files with the same `name` in one directory tree is undefined: one loads by filesystem order, and `/doctor` reports it. A user or project file named `Explore` overrides the built-in Explore. Plugin agents also get a scoped name such as `my-plugin:reviewer`, and they ignore `hooks`, `mcpServers` and `permissionMode` for security.
code
bash · 8 linesclaude --agents '{
"security-reviewer": {
"description": "Reviews changed code for injection and authorization flaws.",
"prompt": "You are a security reviewer. Report findings as file:line, severity, fix.",
"tools": ["Read", "Grep", "Glob"],
"model": "sonnet"
}
}'go deeper
Know the two file locations and that a project agent beats a personal one with the same name.
Recite the five-source order, the closest-directory rule for nested projects, and why a duplicate name in one directory tree is a defect.
Use precedence on purpose: a managed agent nobody can shadow, --agents for one-run overrides, and plugin agents reached by scoped name with their ignored fields understood.
Design the naming and ownership scheme for agents across an organisation so mandated agents stay authoritative and personal ones never silently replace team ones.
## Why precedence matters A subagent's **`name`** is its identity: it is what Claude delegates to, what an @-mention resolves, and what a `SubagentStart` hook matches. Teams quickly end up with the same name in several places, a `reviewer` in the repository, another in someone's home directory, a third shipped by a plugin. Claude Code resolves that clash by **source priority**, not by which file is newer or more specific in content. ## The five sources | Priority | Source | Scope | How it gets there | |---|---|---|---| | 1 (highest) | **Managed settings** | Organisation-wide | Markdown files in `.claude/agents/` inside the managed settings directory, deployed by administrators | | 2 | **`--agents` flag** | Current session only | JSON passed when launching Claude Code; never written to disk | | 3 | **Project** `.claude/agents/` | One repository | Committed with the code | | 4 | **User** `~/.claude/agents/` | All your projects | Personal files | | 5 (lowest) | **Plugin** `agents/` | Wherever the plugin is enabled | Installed with the plugin | Read the table as two rules: the **organisation beats the session, the session beats files**, and among files the **project beats the person**. A developer cannot shadow a managed `security-reviewer` with a personal copy, and a project's shared `reviewer` beats the same name in your home directory. ## Ties inside one scope Priority settles clashes **between** sources. Inside a source: - **Nested project directories.** Claude Code walks up from the working directory to the repository root and scans every `.claude/agents/` on the way. When two define the same `name`, the one **closest to the working directory** wins, which lets a package in a monorepo specialise a repository-wide agent. - **The same directory tree.** Directories are scanned recursively, and subfolders do not change identity. If two files under one `.claude/agents/` declare the same `name`, only one loads, chosen by **filesystem read order**, which is not a documented precedence. Treat it as a defect; `/doctor` reports such files and proposes keeping one. - **Added directories.** A directory added with `--add-dir` contributes its own `.claude/agents/` alongside your project agents. ## Built-ins and plugins **Built-in agents** can be shadowed: a user or project subagent named `Explore` **overrides** the built-in Explore and keeps its own fields, which is the documented way to run exploration on a cheaper model. **Plugin agents** are different in two ways: 1. They also register under a **scoped identifier**, `plugin-name:agent-name` (with subfolders included, such as `my-plugin:review:security`), so you can always reach a specific plugin's agent even when a bare name is taken. 2. For security, Claude Code **ignores `hooks`, `mcpServers` and `permissionMode`** in a plugin agent's frontmatter. If you need them, copy the file into `.claude/agents/` or `~/.claude/agents/`, where the fields apply. How plugins are packaged and installed belongs to the plugin material; the point here is what the definition can and cannot carry. ## The `--agents` flag in practice `--agents` takes a JSON object whose keys are agent names and whose values are definitions. The **`prompt`** field plays the role of the Markdown body; the other keys are the same frontmatter fields (`description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `memory`, `effort`, `isolation` and the rest), while `color` and `experimental` are ignored there. Because it outranks project and user files, it is a clean way to **override a team agent for one run** (a script, an experiment, a CI job) without editing anything on disk. Claude Code validates the value at startup and exits on an invalid one. ## How the winner shows up elsewhere Only the winning definition is visible to the rest of Claude Code. The @-mention typeahead lists your local agents by `name` and plugin agents by their scoped name, and you can type `@agent-<name>` by hand. `SubagentStart` and `SubagentStop` hooks match on the same identifiers: the frontmatter `name` for project and user agents, the scoped identifier for plugin agents. Because a scoped name contains a colon, a hook matcher for it is read as a regular expression, so anchor it as `^my-plugin:db-agent$` to match only that agent. ## Practical guidance - Use **managed** definitions for agents the organisation must control, such as a mandated security reviewer. - Commit **project** agents the team relies on, and give them names unlikely to collide with personal ones. - Keep **user** agents for personal workflow, knowing a project file of the same name will hide yours in that repository. - Use **`--agents`** for throwaway or automated overrides. - Expect **plugin** agents to lose to anything local, and reach them by scoped name when you need a specific one.
- Your team's plugin ships a `db-migrator` agent with a `PreToolUse` hook, but the hook never fires. Why?Claude Code ignores `hooks`, `mcpServers` and `permissionMode` in plugin subagents for security. Copy the agent file into `.claude/agents/` or `~/.claude/agents/`, where the hook applies, or have the plugin ship the hook in its own hooks configuration so it applies whenever the plugin is enabled.
- In a monorepo, `packages/api/.claude/agents/` and the root `.claude/agents/` both define `reviewer`. Which runs when you start Claude in `packages/api`?The one in `packages/api/.claude/agents/`. Project agents are discovered by walking up from the working directory, and between nested directories the definition closest to the working directory wins.
- Project subagents beat managed ones because the closest scope wins.
- A file in ~/.claude/agents/ overrides the project's agent with the same name.
- Putting a project agent in agents/review/ changes the name you call it by.
- A plugin subagent's hooks and permissionMode apply like any other agent's.
- Definitions passed with --agents are saved for later sessions.