docs: expand sub-agent architecture guide#419
Merged
claude-code-best merged 1 commit intoMay 6, 2026
Conversation
Contributor
📝 WalkthroughWalkthroughThe ChangesSub-Agent Documentation Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/agent/sub-agents.mdx (1)
42-50: ⚡ Quick winMake these source entry points clickable.
One of the main values of this guide is “按源码读”，but plain code spans are not navigable and can silently rot. Repo-relative links would make the section much easier to use and give link checking a chance to catch moved files.
✏️ Example approach
-| `src/tools/AgentTool/AgentTool.tsx` | `Agent` 工具定义、路由、同步/异步生命周期 | +| [`src/tools/AgentTool/AgentTool.tsx`](../../src/tools/AgentTool/AgentTool.tsx) | `Agent` 工具定义、路由、同步/异步生命周期 |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/agent/sub-agents.mdx` around lines 42 - 50, 将文中列出的源码入口从普通代码片段改为仓库相对链接：把每个 ``src/...`` 代码片段（例如 `src/tools/AgentTool/AgentTool.tsx`, `src/tools/AgentTool/runAgent.ts`, `src/services/tools/toolExecution.ts`, `src/query.ts`, `src/tasks/LocalAgentTask/LocalAgentTask.tsx`）替换为 Markdown 链接格式 [文件名](../相对路径/到/该文件)（在 docs/agent/sub-agents.mdx 中直接使用相对路径即可），确保链接目标与仓库实际路径一致并在替换后运行链接检查（或 CI 提供的 markdown link checker）以捕获移动或重命名的文件。
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/agent/sub-agents.mdx`:
- Around line 68-75: Clarify that the special teammate branch is taken when both
name and a team context are present, whether the team is provided explicitly via
team_name or inherited from appState.teamContext.teamName; update the text so
readers know that name combined with an inherited current team context also
routes to spawnTeammate() (returning teammate_spawned) rather than the normal
runAgent() local agent path, and explicitly note that only the flattened team
roster prevents nested teammate spawns with a name.
- Around line 463-467: Update the docs to clarify the environment variable
command is PowerShell-only and add a POSIX (bash/zsh) variant: label the
existing example as "PowerShell" and add a second fenced example labeled "bash /
zsh" that uses FEATURE_FORK_SUBAGENT=1 bun run dev; reference the feature name
FEATURE_FORK_SUBAGENT and the command bun run dev so reviewers can find and edit
the existing example.
---
Nitpick comments:
In `@docs/agent/sub-agents.mdx`:
- Around line 42-50: 将文中列出的源码入口从普通代码片段改为仓库相对链接：把每个 ``src/...`` 代码片段（例如
`src/tools/AgentTool/AgentTool.tsx`, `src/tools/AgentTool/runAgent.ts`,
`src/services/tools/toolExecution.ts`, `src/query.ts`,
`src/tasks/LocalAgentTask/LocalAgentTask.tsx`）替换为 Markdown 链接格式
[文件名](../相对路径/到/该文件)（在 docs/agent/sub-agents.mdx
中直接使用相对路径即可），确保链接目标与仓库实际路径一致并在替换后运行链接检查（或 CI 提供的 markdown link
checker）以捕获移动或重命名的文件。
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+68
to
+75
| | 参数 | 类型 | 必填 | 作用 | 影响路径 | | ||
| |------|------|------|------|----------| | ||
| | `name` | `string` | 否 | 给 spawned agent 命名，使其可被 `SendMessage({ to: name })` 定向 | 与 `team_name` 或当前 team context 一起出现时触发 teammate spawn；普通后台子 Agent 中也会注册 `name -> agentId` 方便后续发送消息 | | ||
| | `team_name` | `string` | 否 | 指定要加入或使用的 team | 与 `name` 一起触发 `spawnTeammate()`；省略时可继承当前 `appState.teamContext.teamName` | | ||
| | `mode` | permission mode | 否 | teammate spawn 的权限模式提示 | 当前实现只用于 teammate 的 `plan_mode_required: spawnMode === 'plan'`；它不是普通本地子 Agent 的 `permissionMode` 覆盖 | | ||
|
|
||
| `name + team_name` 是一条独立分支：它不会进入普通 `runAgent()` 本地子 Agent 路径，而是调用 `spawnTeammate()`，返回 `teammate_spawned`。如果在 teammate 内继续带 `name` spawn teammate，会被拒绝，因为 team roster 是扁平结构。 | ||
|
|
Contributor
There was a problem hiding this comment.
Clarify that inherited team context also takes the teammate branch.
This section narrows the special case to name + team_name, but the table just above says name plus an inherited current team context can also route to spawnTeammate(). As written, readers may incorrectly conclude that name alone always stays on the normal runAgent() path.
✏️ Suggested wording
-`name + team_name` 是一条独立分支：它不会进入普通 `runAgent()` 本地子 Agent 路径，而是调用 `spawnTeammate()`，返回 `teammate_spawned`。如果在 teammate 内继续带 `name` spawn teammate，会被拒绝，因为 team roster 是扁平结构。
+`name + team_name`，或 `name` + 当前 team context 继承出来的 team name，是一条独立分支：它不会进入普通 `runAgent()` 本地子 Agent 路径，而是调用 `spawnTeammate()`，返回 `teammate_spawned`。如果在 teammate 内继续带 `name` spawn teammate，会被拒绝，因为 team roster 是扁平结构。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 参数 | 类型 | 必填 | 作用 | 影响路径 | | |
| |------|------|------|------|----------| | |
| | `name` | `string` | 否 | 给 spawned agent 命名，使其可被 `SendMessage({ to: name })` 定向 | 与 `team_name` 或当前 team context 一起出现时触发 teammate spawn；普通后台子 Agent 中也会注册 `name -> agentId` 方便后续发送消息 | | |
| | `team_name` | `string` | 否 | 指定要加入或使用的 team | 与 `name` 一起触发 `spawnTeammate()`；省略时可继承当前 `appState.teamContext.teamName` | | |
| | `mode` | permission mode | 否 | teammate spawn 的权限模式提示 | 当前实现只用于 teammate 的 `plan_mode_required: spawnMode === 'plan'`；它不是普通本地子 Agent 的 `permissionMode` 覆盖 | | |
| `name + team_name` 是一条独立分支：它不会进入普通 `runAgent()` 本地子 Agent 路径，而是调用 `spawnTeammate()`，返回 `teammate_spawned`。如果在 teammate 内继续带 `name` spawn teammate，会被拒绝，因为 team roster 是扁平结构。 | |
| | 参数 | 类型 | 必填 | 作用 | 影响路径 | | |
| |------|------|------|------|----------| | |
| | `name` | `string` | 否 | 给 spawned agent 命名，使其可被 `SendMessage({ to: name })` 定向 | 与 `team_name` 或当前 team context 一起出现时触发 teammate spawn；普通后台子 Agent 中也会注册 `name -> agentId` 方便后续发送消息 | | |
| | `team_name` | `string` | 否 | 指定要加入或使用的 team | 与 `name` 一起触发 `spawnTeammate()`；省略时可继承当前 `appState.teamContext.teamName` | | |
| | `mode` | permission mode | 否 | teammate spawn 的权限模式提示 | 当前实现只用于 teammate 的 `plan_mode_required: spawnMode === 'plan'`；它不是普通本地子 Agent 的 `permissionMode` 覆盖 | | |
| `name + team_name`，或 `name` + 当前 team context 继承出来的 team name，是一条独立分支：它不会进入普通 `runAgent()` 本地子 Agent 路径，而是调用 `spawnTeammate()`，返回 `teammate_spawned`。如果在 teammate 内继续带 `name` spawn teammate，会被拒绝，因为 team roster 是扁平结构。 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/agent/sub-agents.mdx` around lines 68 - 75, Clarify that the special
teammate branch is taken when both name and a team context are present, whether
the team is provided explicitly via team_name or inherited from
appState.teamContext.teamName; update the text so readers know that name
combined with an inherited current team context also routes to spawnTeammate()
(returning teammate_spawned) rather than the normal runAgent() local agent path,
and explicitly note that only the flattened team roster prevents nested teammate
spawns with a name.
Comment on lines
+463
to
467
| fork 默认关闭。需要构建/运行时启用 `FORK_SUBAGENT` feature，例如开发时显式设置： | ||
|
|
||
| ```powershell | ||
| $env:FEATURE_FORK_SUBAGENT='1'; bun run dev | ||
| ``` |
Contributor
There was a problem hiding this comment.
Label this command as PowerShell-only or add a POSIX variant.
$env:FEATURE_FORK_SUBAGENT='1' only works in PowerShell. Without a note, Bash/Zsh users are likely to copy it verbatim and think the feature flag is broken.
✏️ Suggested wording
```powershell
+# PowerShell
$env:FEATURE_FORK_SUBAGENT='1'; bun run dev+bash +# bash / zsh +FEATURE_FORK_SUBAGENT=1 bun run dev +
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
fork 默认关闭。需要构建/运行时启用 `FORK_SUBAGENT` feature，例如开发时显式设置：
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/agent/sub-agents.mdx` around lines 463 - 467, Update the docs to clarify
the environment variable command is PowerShell-only and add a POSIX (bash/zsh)
variant: label the existing example as "PowerShell" and add a second fenced
example labeled "bash / zsh" that uses FEATURE_FORK_SUBAGENT=1 bun run dev;
reference the feature name FEATURE_FORK_SUBAGENT and the command bun run dev so
reviewers can find and edit the existing example.
y574444354
pushed a commit
to y574444354/csc
that referenced
this pull request
May 12, 2026
…-docs docs: expand sub-agent architecture guide
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Need help on this PR? Tag
@codesmithwith what you need.Summary by CodeRabbit