Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI 17 Aug 2026
One change · claude-code

Create custom subagents changedsub-agents

Nearest release: v2.1.234, published an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+4added
Lines−11removed
From line 164 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits90to this page, all time

The whole hunk

from line 164, old and new numbered
/
lines
from line 164
164164 
165165Project subagents are discovered by walking up from the current working directory, so every `.claude/agents/` between there and the repository root is scanned. As of v2.1.178, when more than one of these nested directories defines the same `name`, Claude Code uses the definition closest to the working directory.
166166 
167Directories added with `--add-dir` are also scanned: a `.claude/agents/` folder inside an added directory loads alongside project subagents. See [Additional directories](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](/docs/en/plugins).
167When you add a directory with `--add-dir` or `/add-dir`, Claude Code also loads its `.claude/agents/` folder, alongside your project subagents. See [Additional directories](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](/docs/en/plugins).
168168 
169169**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.
170170 
from line 233
233233<Note>
234234 Claude Code watches `~/.claude/agents/` and `.claude/agents/`. When you add or edit a subagent file on disk, or ask Claude to write one for you, Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.
235235 
236 Two cases still need a restart:
236 Three cases still need a restart:
237237 
238238 * The watcher covers only directories that existed when the session started, so after creating a scope's first agent file in a new `agents` directory, restart to load it.
239 * Claude Code doesn't watch `.claude/agents/` inside directories added with `--add-dir` or `/add-dir`, so after adding or editing a subagent there, restart to load the change.
239240 * Sessions started with `--disable-slash-commands` don't watch these directories at all.
240241</Note>
241242 
from line 471
470471<Warning>
471472 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval, including writes to `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, and `.mvn`.
472473 
473 Even in this mode, some operations still prompt:
474 
475 * Explicit [`ask` rules](/docs/en/permissions#manage-permissions)
476 * Connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools)
477 * MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool)
478 * Root and home directory removals such as `rm -rf /`
479 * The [`isolatePeerMachines`](/docs/en/settings#available-settings) approval for messages beyond this machine
480 
481 See [permission modes](/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.
474 Even in this mode, the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves) still apply. See [permission modes](/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.
482475</Warning>
483476 
484477If the parent uses `bypassPermissions` or `acceptEdits`, this takes precedence and can't be overridden. If the parent uses [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.
Feedback