30 內建 subagents30 內建 subagents
31</h2>31</h2>
32 32
33Claude Code 包括內建 subagents，Claude 在適當時會自動使用。每個都繼承父對話的權限；大多數以受限的工具集執行。33Claude Code 包括內建 subagents，Claude 在適當時會自動使用。每個都繼承父對話的權限規則；大多數以受限的工具集執行。
34 34
35Explore 和 Plan 會跳過您的 CLAUDE.md 檔案和 git status 快照，以保持研究快速且經濟高效。其他所有內建和[自訂 subagent](#configure-subagents) 都會載入兩者，除非其定義設定 [`omitClaudeMd`](#supported-frontmatter-fields) 欄位以跳過使用者、專案和本機 CLAUDE.md 檔案。如需了解到達 subagent 的完整詳細資訊，請參閱[啟動時載入的內容](#what-loads-at-startup)。35Explore 和 Plan 會跳過您的 CLAUDE.md 檔案和 git status 快照，以保持研究快速且經濟高效。其他所有內建和[自訂 subagent](#configure-subagents) 都會載入兩者，除非其定義設定 [`omitClaudeMd`](#supported-frontmatter-fields) 欄位以跳過使用者、專案和本機 CLAUDE.md 檔案。如需了解到達 subagent 的完整詳細資訊，請參閱[啟動時載入的內容](#what-loads-at-startup)。
36 36
157</Note>157</Note>
158 158
159<h2 id="configure-subagents">159<h2 id="configure-subagents">
160 配置 subagents160 設定子代理
161</h2>161</h2>
162 162
163Subagent 的檔案位置決定了誰可以使用它，其 frontmatter 決定了它可以做什麼。本節涵蓋 subagent 檔案的位置以及它們支援的每個欄位。163子代理的檔案位置決定了誰可以使用它，其 frontmatter 決定了它可以做什麼。本節涵蓋子代理檔案的位置以及它們支援的每個欄位。
164 164
165<h3 id="choose-the-subagent-scope">165<h3 id="choose-the-subagent-scope">
166 選擇 subagent 範圍166 選擇子代理範圍
167</h3>167</h3>
168 168
169根據範圍將 subagent 檔案儲存在不同位置。當多個 subagents 共享相同名稱時，Claude Code 使用來自優先級較高位置的那個。169根據範圍將子代理檔案儲存在不同位置。當多個子代理共享相同名稱時，Claude Code 會使用來自優先級較高位置的子代理。
170 170
171| Location | Scope | Priority | 如何建立 |171| 位置 | 範圍 | 優先級 | 如何建立 |
172| :- | :- | :- | :- |172| :- | :- | :- | :- |
173| 受管設定 | 組織範圍 | 1（最高） | 透過 [managed settings](/docs/zh-TW/settings) 部署 |173| 受管設定 | 組織範圍 | 1（最高） | 透過[受管設定](/docs/zh-TW/settings)部署 |
174| `--agents` CLI 標誌 | 目前工作階段 | 2 | 啟動 Claude Code 時傳遞 JSON |174| `--agents` CLI 旗標 | 目前工作階段 | 2 | 啟動 Claude Code 時傳遞 JSON |
175| `.claude/agents/` | 目前專案 | 3 | 詢問 Claude，或手動建立檔案 |175| `.claude/agents/` | 目前專案 | 3 | 詢問 Claude，或手動建立檔案 |
176| `~/.claude/agents/` | 所有您的專案 | 4 | 詢問 Claude，或手動建立檔案 |176| `~/.claude/agents/` | 您的所有專案 | 4 | 詢問 Claude，或手動建立檔案 |
177| Plugin 的 `agents/` 目錄 | 啟用外掛程式的位置 | 5（最低） | 使用 [plugins](/docs/zh-TW/plugins/overview) 安裝 |177| Plugin 的 `agents/` 目錄 | 啟用 plugin 的位置 | 5（最低） | 與[plugins](/docs/zh-TW/plugins/overview)一起安裝 |
178 178
179**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。179**專案子代理**（`.claude/agents/`）最適合特定於程式碼庫的子代理。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。
180 180
181專案 subagents 是透過從目前工作目錄向上走來發現的，因此會掃描那裡和儲存庫根目錄之間的每個 `.claude/agents/`。當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 使用最接近工作目錄的定義。181專案子代理是透過從目前工作目錄向上走來發現的，因此會掃描該處和儲存庫根目錄之間的每個 `.claude/agents/`。當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 會使用最接近工作目錄的定義。
182 182
183使用 `--add-dir` 或 `/add-dir` 新增的目錄時，Claude Code 也會載入其 `.claude/agents/` 資料夾，與您的專案 subagents 一起。請參閱 [Additional directories](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 以了解哪些其他配置類型從 `--add-dir` 載入。若要跨專案共享 subagents 而不使用 `--add-dir`，請使用 `~/.claude/agents/` 或 [plugin](/docs/zh-TW/plugins/overview)。183當您使用 `--add-dir` 或 `/add-dir` 新增目錄時，Claude Code 也會載入其 `.claude/agents/` 資料夾，以及您的專案子代理。請參閱[其他目錄](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)以了解哪些其他設定類型從 `--add-dir` 載入。若要在不使用 `--add-dir` 的情況下跨專案共享子代理，請使用 `~/.claude/agents/` 或 [plugin](/docs/zh-TW/plugins/overview)。
184 184
185**使用者 subagents**（`~/.claude/agents/`）是在所有專案中可用的個人 subagents。185**使用者子代理**（`~/.claude/agents/`）是在您的所有專案中可用的個人子代理。
186 186
187Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響 subagent 的識別或呼叫方式，因為身份僅來自 `name` frontmatter 欄位。187Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響子代理的識別或叫用方式，因為身份僅來自 `name` frontmatter 欄位。
188 188
189在整個樹中保持 `name` 值唯一：如果一個 `.claude/agents/` 目錄下的兩個檔案（包括其子資料夾）宣告相同的名稱，Claude Code 只會載入其中一個，由檔案系統讀取順序選擇，而不是有文件記載的優先級。在巢狀專案目錄中，最接近工作目錄的定義獲勝，如上所述。[`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查會報告同一目錄中共享名稱的檔案，並建議重新命名或移除除一個以外的所有檔案。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，列出重複項並顯示哪個定義處於活動狀態。189在整個樹中保持 `name` 值唯一：如果同一 `.claude/agents/` 目錄下的兩個檔案（包括其子資料夾）宣告相同的名稱，Claude Code 只會載入其中一個，由檔案系統讀取順序選擇，而不是文件化的優先級。在巢狀專案目錄中，最接近工作目錄的定義獲勝，如上所述。[`/doctor`](/docs/zh-TW/commands#all-commands)設定檢查會報告同一目錄中共享名稱的檔案，並建議重新命名或移除除一個以外的所有檔案。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，列出重複項並顯示哪個定義處於活動狀態。
190 190
191外掛程式 `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，外掛程式 `agents/` 目錄內的子資料夾成為 [scoped identifier](#invoke-subagents-explicitly) 的一部分：外掛程式 `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。191Plugin `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，plugin 的 `agents/` 目錄內的子資料夾成為[範圍識別碼](#invoke-subagents-explicitly)的一部分：plugin `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。
192 192
193**CLI 定義的 subagents** 在啟動 Claude Code 時作為 JSON 傳遞。它們僅存在於該工作階段，不會儲存到磁碟，使其適用於快速測試或自動化指令碼。您可以在單一 `--agents` 呼叫中定義多個 subagents：193**CLI 定義的子代理**在啟動 Claude Code 時作為 JSON 傳遞。它們僅存在於該工作階段，不會儲存到磁碟，使其適合快速測試或自動化指令碼。您可以在單個 `--agents` 呼叫中定義多個子代理：
194 194
195<Tabs>195<Tabs>
196 <Tab title="macOS, Linux, WSL">196 <Tab title="macOS, Linux, WSL">
230 </Tab>230 </Tab>
231</Tabs>231</Tabs>
232 232
233在 [non-interactive mode](/docs/zh-TW/headless) 中，`--agents` 也接受保存相同物件的 JSON 檔案的路徑，用於定義太大而無法在命令列上傳遞的情況。例如，`claude -p --agents ./agents.json "Review my changes"` 從該檔案讀取定義。在互動工作階段中，Claude Code 拒絕檔案路徑。檔案形式需要 Claude Code v2.1.281 或更高版本。233在[非互動模式](/docs/zh-TW/headless)中，`--agents` 也接受保存相同物件的 JSON 檔案的路徑，用於定義太大而無法在命令列上傳遞的情況。例如，`claude -p --agents ./agents.json "Review my changes"` 從該檔案讀取定義。在互動工作階段中，Claude Code 拒絕檔案路徑。檔案形式需要 Claude Code v2.1.281 或更新版本。
234 234
235JSON 中的每個頂級鍵是代理的名稱，其值是該代理的定義。不要以 `-` 開頭的名稱。定義採用這些欄位：235JSON 中的每個頂級鍵是代理的名稱，其值是該代理的定義。不要以 `-` 開頭的名稱。定義採用這些欄位：
236 236
237* **`prompt`**：代理的系統提示，等同於基於檔案的 subagents 中的 markdown 主體。`prompt` 可能為空。如果您選擇一個具有空 `prompt` 且沒有 `memory` 欄位的代理作為工作階段的代理（使用 `--agent`），工作階段的系統提示保持不變。空 `prompt` 需要 Claude Code v2.1.281 或更高版本。237* **`prompt`**：代理的系統提示，等同於檔案型子代理中的 markdown 主體。`prompt` 可能為空。如果您使用 `--agent` 選擇一個具有空 `prompt` 且沒有 `memory` 欄位的代理作為工作階段的代理，工作階段的系統提示保持不變。空 `prompt` 需要 Claude Code v2.1.281 或更新版本。
238* **[Frontmatter 欄位](#supported-frontmatter-fields)**：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。238* **[Frontmatter 欄位](#supported-frontmatter-fields)**：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。
239* **忽略的欄位**：`color` 和 `experimental` 在此不被接受，會被忽略而不是拒絕。239* **忽略的欄位**：`color` 和 `experimental` 在此不被接受，被忽略而不是拒絕。
240 240
241關於 Claude Code 對無法載入的值所做的操作，以及跳過該檢查的標誌和環境變數，請參閱 [`Invalid --agents configuration`](/docs/zh-TW/errors#invalid-agents-configuration)。241有關 Claude Code 對無法載入的值所做的操作，以及跳過該檢查的旗標和環境變數，請參閱[`Invalid --agents configuration`](/docs/zh-TW/errors#invalid-agents-configuration)。
242 242
243**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/docs/zh-TW/managed-settings#delivery-mechanisms) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。243**受管子代理**由組織管理員部署。將 markdown 檔案放在[受管設定目錄](/docs/zh-TW/managed-settings#delivery-mechanisms)內的 `.claude/agents/` 中，使用與專案和使用者子代理相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者子代理。
244 244
245**外掛程式 subagents** 來自您已安裝的 [plugins](/docs/zh-TW/plugins/overview)。它們與您的自訂 subagents 一起自動載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/docs/zh-TW/plugins/components#agents) 以了解建立外掛程式 subagents 的詳細資訊。245**Plugin 子代理**來自您已安裝的 [plugins](/docs/zh-TW/plugins/overview)。它們會自動與您的自訂子代理一起載入，並在 @-mention 預輸入中以其範圍名稱出現。有關建立 plugin 子代理的詳細資訊，請參閱 [plugin 元件參考](/docs/zh-TW/plugins/components#agents)。
246 246
247<Note>247<Note>
248 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。248 出於安全原因，plugin 子代理不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從 plugin 載入代理時，這些欄位被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中新增規則到 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow)，但這些規則適用於整個工作階段，而不僅僅是 plugin 子代理。
249</Note>249</Note>
250 250
251來自任何這些範圍的 subagent 定義也可用於 [agent teams](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates)：當產生隊友時，您可以參考 subagent 類型，Claude Code 會將該定義的部分應用於隊友。請參閱 [agent teams](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates) 以了解在每個顯示模式中應用哪些部分。251來自任何這些範圍的子代理定義也可用於[代理團隊](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates)：當生成隊友時，您可以參考子代理類型，Claude Code 會將該定義的部分應用於隊友。請參閱[代理團隊](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates)以了解在每個顯示模式中應用哪些部分。
252 252
253<h3 id="write-subagent-files">253<h3 id="write-subagent-files">
254 編寫 subagent 檔案254 編寫子代理檔案
255</h3>255</h3>
256 256
257Subagent 檔案使用 YAML frontmatter 進行配置，後面跟著 Markdown 中的系統提示：257子代理檔案使用 YAML frontmatter 進行設定，後面是 Markdown 中的系統提示：
258 258
259<Note>259<Note>
260 Claude Code 監視 `~/.claude/agents/` 和 `.claude/agents/`。當您在磁碟上新增或編輯 subagent 檔案，或要求 Claude 為您編寫一個時，Claude Code 會在幾秒內偵測到變更，下次委派會使用更新的定義，無需重新啟動。260 Claude Code 監視 `~/.claude/agents/` 和 `.claude/agents/`。當您在磁碟上新增或編輯子代理檔案，或要求 Claude 為您編寫一個時，Claude Code 會在幾秒內偵測到變更，下一次委派會使用更新的定義，無需重新啟動。
261 261
262 仍有三種情況需要重新啟動：262 三種情況仍需要重新啟動：
263 263
264 * 監視程式僅涵蓋工作階段開始時存在的目錄，因此在新的 `agents` 目錄中建立範圍的第一個代理檔案後，重新啟動以載入它。264 * 監視程式僅涵蓋工作階段開始時存在的目錄，因此在新 `agents` 目錄中建立範圍的第一個代理檔案後，重新啟動以載入它。
265 * Claude Code 不監視使用 `--add-dir` 或 `/add-dir` 新增的目錄內的 `.claude/agents/`，因此在那裡新增或編輯 subagent 後，重新啟動以載入變更。265 * Claude Code 不監視透過 `--add-dir` 或 `/add-dir` 新增的目錄內的 `.claude/agents/`，因此在那裡新增或編輯子代理後，重新啟動以載入變更。
266 * 使用 `--disable-slash-commands` 啟動的工作階段根本不監視這些目錄。266 * 使用 `--disable-slash-commands` 啟動的工作階段根本不監視這些目錄。
267</Note>267</Note>
268 268
278specific, actionable feedback on quality, security, and best practices.278specific, actionable feedback on quality, security, and best practices.
279```279```
280 280
281Frontmatter 定義 subagent 的中繼資料和配置。主體成為指導 subagent 行為的系統提示。Subagents 只接收此系統提示加上基本環境詳細資訊（如工作目錄），而不是 Claude Code 系統提示。281frontmatter 定義子代理的中繼資料和設定。主體成為指導子代理行為的系統提示。子代理僅接收此系統提示加上基本環境詳細資訊（如工作目錄），而不是 Claude Code 系統提示。
282 282
283在 [non-interactive mode](/docs/zh-TW/headless) 中，傳遞 [`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 以將您的文字附加到每個 subagent 的系統提示末尾，包括巢狀 subagents，除了 [forked subagent](#fork-the-current-conversation)，它重新使用對話自己的提示。需要 Claude Code v2.1.205 或更高版本。如果您的文字太長而無法在命令列上傳遞，請將其儲存到檔案並使用 `--append-subagent-system-prompt-file` 傳遞路徑。檔案標誌需要 Claude Code v2.1.261 或更高版本。283在[非互動模式](/docs/zh-TW/headless)中，傳遞 [`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 以將您的文字附加到每個子代理的系統提示末尾，包括巢狀子代理，除了[分叉子代理](#fork-the-current-conversation)，它重複使用對話自己的提示。需要 Claude Code v2.1.205 或更新版本。如果您的文字太長而無法在命令列上傳遞，請將其儲存到檔案並改為使用 `--append-subagent-system-prompt-file` 傳遞路徑。檔案旗標需要 Claude Code v2.1.261 或更新版本。
284 284
285一個 subagent 在主要對話的目前工作目錄中啟動。在 subagent 內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主要對話的工作目錄。若要改為給 subagent 儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。285子代理在主對話的目前工作目錄中啟動。在子代理內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主對話的工作目錄。若要改為給子代理儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。
286 286
287具有 `isolation: worktree` 的 subagent 在其 worktree 內執行其 Bash 和 PowerShell 命令。一個工作目錄解析到您的主要簽出的命令（例如，因為 subagent 執行時 worktree 目錄被移除）會失敗並出現錯誤。在 v2.1.203 之前，此類命令可能在主要簽出中執行。287具有 `isolation: worktree` 的子代理在其 worktree 內執行其 Bash 和 PowerShell 命令。其工作目錄解析到您的主簽出的命令（例如，因為 worktree 目錄在子代理執行時被移除）會失敗並出現錯誤。在 v2.1.203 之前，此類命令可以在主簽出中執行。
288 288
289此工作目錄檢查涵蓋包含您啟動 Claude Code 的目錄的整個儲存庫。當您的工作階段在其自己的連結 [worktree](/docs/zh-TW/worktrees) 中執行時，檢查也涵蓋該 worktree 連結的主要簽出。在 v2.1.210 之前，檢查僅涵蓋啟動目錄本身。一個工作目錄解析到同一儲存庫中其他地方的命令（例如當您從 monorepo 子目錄啟動 Claude Code 時的儲存庫根目錄）在那裡執行，而不是失敗。289此工作目錄檢查涵蓋包含您啟動 Claude Code 的目錄的整個儲存庫。當您的工作階段在其自己的連結 [worktree](/docs/zh-TW/worktrees) 中執行時，檢查也涵蓋該 worktree 連結的主簽出。在 v2.1.210 之前，檢查僅涵蓋啟動目錄本身。其工作目錄解析到同一儲存庫中其他位置的命令（例如，當您從 monorepo 子目錄啟動 Claude Code 時的儲存庫根目錄）在那裡執行，而不是失敗。
290 290
291對於 Bash 命令，Claude Code 也以兩種方式檢查命令本身：291對於 Bash 命令，Claude Code 也以兩種方式檢查命令本身：
292 292
293* 它阻止將 git 重定向到主要簽出的命令。293* 它阻止將 git 重定向到主簽出的命令。
294* 當它無法從命令文字驗證命令執行的任何 git 都保留在 worktree 內時，它拒絕命令，例如當命令名稱在執行時計算時。294* 當它無法從命令文字驗證命令執行的任何 git 都保留在 worktree 內時，它拒絕命令，例如當命令名稱在執行時計算時。
295 295
296重定向向量和形狀規則列在 [How Claude Code enforces isolation](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation) 下。PowerShell 命令僅獲得工作目錄檢查。296重定向向量和形狀規則列在[Claude Code 如何強制隔離](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation)下。PowerShell 命令僅獲得工作目錄檢查。
297 297
298[Monitor](/docs/zh-TW/tools-reference#monitor-tool) 命令經過與 Bash 命令相同的工作目錄和命令內容檢查。298[Monitor](/docs/zh-TW/tools-reference#monitor-tool) 命令經過與 Bash 命令相同的工作目錄和命令內容檢查。
299 299
300當主要對話本身在 worktree 中隔離執行時，Claude Code 對工作階段和它產生的每個 subagent 應用相同的檢查，包括沒有 `isolation: worktree` 的 subagents；請參閱 [How Claude Code enforces isolation](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation)。300當主對話本身在 worktree 中隔離執行時，Claude Code 對工作階段和它生成的每個子代理應用相同的檢查，包括沒有 `isolation: worktree` 的子代理；請參閱[Claude Code 如何強制隔離](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation)。
301 301
302<h3 id="supported-frontmatter-fields">302<h3 id="supported-frontmatter-fields">
303 Frontmatter 參考303 Frontmatter 參考
304</h3>304</h3>
305 305
306配置 subagent 時，使用 YAML [frontmatter](/docs/zh-TW/glossary#frontmatter) 在檔案頂部的 `---` 標記之間，並在結束 `---` 後將其系統提示寫為 Markdown。只有 `name` 和 `description` 是必需的。306使用 YAML [frontmatter](/docs/zh-TW/glossary#frontmatter) 在檔案頂部的 `---` 標記之間設定子代理，並在結束 `---` 之後將其系統提示寫為 Markdown。只有 `name` 和 `description` 是必需的。
307 307
308多字欄位名稱使用 camelCase，例如 `maxTurns` 和 `disallowedTools`，必須與表格完全相符：Claude Code 忽略它不識別的欄位而不報告錯誤。若要找出 subagent 檔案未載入的原因，請參閱 [Subagent files Claude Code skips](#subagent-files-claude-code-skips)。308多字欄位名稱使用 camelCase，例如 `maxTurns` 和 `disallowedTools`，必須與表格完全匹配：Claude Code 忽略它不識別的欄位而不報告錯誤。若要找出子代理檔案未載入的原因，請參閱[Claude Code 跳過的子代理檔案](#subagent-files-claude-code-skips)。
309 309
310| Field | 必需 | Description |310| 欄位 | 必需 | 描述 |
311| :- | :- | :- |311| :- | :- | :- |
312| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符。名稱不能包含 `:`，這是為 [plugin-scoped identifiers](/docs/zh-TW/plugins/overview) 保留的，例如 `my-plugin:reviewer`。Claude Code 不會載入名稱包含一個的檔案，並將錯誤記錄到除錯日誌。在 v2.1.218 之前，此類名稱被接受 |312| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必匹配。名稱不能包含 `:`，它保留用於[plugin 範圍識別碼](/docs/zh-TW/plugins/overview)，例如 `my-plugin:reviewer`。Claude Code 不載入名稱包含一個的檔案，並將錯誤記錄到偵錯日誌。在 v2.1.218 之前，此類名稱被接受 |
313| `description` | 是 | Claude 何時應委派給此 subagent |313| `description` | 是 | Claude 應何時委派給此子代理 |
314| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作為逗號分隔的字串（例如 `Read, Grep, Bash`）或 YAML 清單。如果省略，繼承 subagents 可用的每個工具。如果清單中沒有條目解析為工具，subagent 通常 [fails to launch](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 並出現命名條目的錯誤。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |314| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，作為逗號分隔的字串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，繼承子代理可用的每個工具。如果列表中沒有條目解析為工具，子代理通常[無法啟動](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)並出現錯誤，命名未解析的條目。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |
315| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除。格式與 `tools` 相同。具有指定符的條目（例如 `Bash(git push *)`）仍然 [removes the whole tool](#available-tools) |315| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的列表中移除。與 `tools` 相同的格式。具有指定符的條目（例如 `Bash(git push *)`）仍然[移除整個工具](#available-tools) |
316| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5-5`）或 `inherit`。當您省略它時，Claude Code 在 [subagent model order](#choose-a-model) 中選擇模型 |316| `model` | 否 | 要使用的[模型](#choose-a-model)：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如 `claude-opus-5-5`）或 `inherit`。當您省略它時，Claude Code 會在[子代理模型順序](#choose-a-model)中選擇模型 |
317| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |317| `permissionMode` | 否 | [權限模式](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更新版本。對於 [plugin 子代理](#choose-the-subagent-scope)被忽略 |
318| `maxTurns` | 否 | subagent 停止前的最大代理轉數。當 subagent 達到限制時，Claude Code 傳回其輸出標記為部分，Claude 可以 [resume it](#resume-subagents) 以繼續。部分標記需要 Claude Code v2.1.246 或更高版本 |318| `maxTurns` | 否 | 子代理停止前的最大代理轉數。當子代理達到限制時，Claude Code 返回其輸出標記為部分，Claude 可以[恢復它](#resume-subagents)以繼續。部分標記需要 Claude Code v2.1.246 或更新版本 |
319| `skills` | 否 | [Skills](/docs/zh-TW/skills) 在啟動時預載入到 subagent 的上下文中。注入完整技能內容，而不僅僅是描述。Subagents 仍然可以透過 Skill 工具呼叫未列出的專案、使用者和外掛程式技能 |319| `skills` | 否 | 在啟動時預載入子代理上下文的[技能](/docs/zh-TW/skills)。注入完整技能內容，而不僅僅是描述。子代理仍然可以透過 Skill 工具叫用未列出的專案、使用者和 plugin 技能 |
320| `mcpServers` | 否 | [MCP servers](/docs/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/docs/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |320| `mcpServers` | 否 | 此子代理可用的 [MCP 伺服器](/docs/zh-TW/mcp)。每個條目要麼是參考已設定伺服器的伺服器名稱（例如 `"slack"`），要麼是內聯定義，伺服器名稱作為鍵，完整 [MCP 伺服器設定](/docs/zh-TW/mcp#installing-mcp-servers)作為值。對於 [plugin 子代理](#choose-the-subagent-scope)被忽略 |
321| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定於此 subagent。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |321| `hooks` | 否 | [生命週期 hooks](#define-hooks-for-subagents) 範圍限於此子代理。對於 [plugin 子代理](#choose-the-subagent-scope)被忽略 |
322| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |322| `memory` | 否 | [持久記憶範圍](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |
323| `background` | 否 | 設定為 `true` 以即使 Claude 要求在前景執行也保持此 subagent 在背景。其中 [fork mode](#turn-fork-mode-on-or-off) 開啟時，Claude Code 已經在 [background](#run-subagents-in-foreground-or-background) 中執行 Claude 產生的 subagents |323| `background` | 否 | 設定為 `true` 以保持此子代理在背景中，即使 Claude 要求在前景中執行它。其中[分叉模式](#turn-fork-mode-on-or-off)開啟時，Claude Code 已經在[背景中](#run-subagents-in-foreground-or-background)執行 Claude 生成的子代理 |
324| `omitClaudeMd` | 否 | 設定為 `true` 以啟動此 subagent 而不使用使用者、專案和本機 CLAUDE.md 檔案；[managed policy files](/docs/zh-TW/memory#how-claude-md-files-load) 仍然載入，除了 [managed subagents](#choose-the-subagent-scope)。將其用於從 [delegation prompt](#what-loads-at-startup) 獲取所需一切的 subagents。當代理透過 `--agent` 或 `agent` 設定作為主工作階段代理執行時被忽略。需要 Claude Code v2.1.271 或更高版本 |324| `omitClaudeMd` | 否 | 設定為 `true` 以啟動此子代理而不使用使用者、專案和本機 CLAUDE.md 檔案；[受管原則檔案](/docs/zh-TW/memory#how-claude-md-files-load)仍然載入，除了[受管子代理](#choose-the-subagent-scope)。將其用於從[委派提示](#what-loads-at-startup)獲取所需一切的子代理。當代理透過 `--agent` 或 `agent` 設定作為主工作階段代理執行時被忽略。需要 Claude Code v2.1.271 或更新版本 |
325| `effort` | 否 | 此 subagent 活動時的努力程度。覆蓋工作階段努力程度。預設：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型 |325| `effort` | 否 | 此子代理活動時的努力級別。覆蓋工作階段努力級別。預設值：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用級別取決於模型 |
326| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/docs/zh-TW/worktrees) 中執行 subagent，為其提供儲存庫的隔離副本，預設從您的 [default branch](/docs/zh-TW/worktrees#choose-the-base-branch) 分支，而不是父工作階段的 `HEAD`。如果 subagent 不進行任何更改，worktree 會自動清理 |326| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/docs/zh-TW/worktrees) 中執行子代理，給它儲存庫的隔離副本，預設從您的[預設分支](/docs/zh-TW/worktrees#choose-the-base-branch)分支，而不是父工作階段的 `HEAD`。如果子代理不進行任何變更，worktree 會自動清理 |
327| `color` | 否 | Subagent 在任務清單和文字中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |327| `color` | 否 | 子代理在任務列表和文字記錄中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |
328| `initialPrompt` | 否 | 當此代理作為主工作階段代理執行時（透過 `--agent` 或 `agent` 設定），自動提交為第一個使用者轉數。[Commands](/docs/zh-TW/commands) 和 [skills](/docs/zh-TW/skills) 會被處理。前置於任何使用者提供的提示。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |328| `initialPrompt` | 否 | 當此代理作為主工作階段代理執行時（透過 `--agent` 或 `agent` 設定），自動提交為第一個使用者轉。[命令](/docs/zh-TW/commands)和[技能](/docs/zh-TW/skills)被處理。前置任何使用者提供的提示。對於 [plugin 子代理](#choose-the-subagent-scope)被忽略 |
329| `experimental` | 否 | 實驗選項的對應。將其 `cacheTtl` 鍵設定為 `5m` 或 `1h` 以選擇此 subagent 請求的 [prompt cache lifetime](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself)，在 [cache lifetime precedence](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself) 中 frontmatter 的位置。Claude Code 忽略任何其他值，在您的 Claude 訂閱使用使用額度時忽略 `1h`，並僅從 subagent 檔案讀取欄位。需要 Claude Code v2.1.248 或更高版本 |329| `experimental` | 否 | 實驗選項的對應。將其 `cacheTtl` 鍵設定為 `5m` 或 `1h` 以選擇此子代理請求的[提示快取生命週期](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself)，在 frontmatter 在[快取生命週期優先級](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself)中的位置。Claude Code 忽略任何其他值，在您的 Claude 訂閱使用使用額度時忽略 `1h`，並僅從子代理檔案讀取欄位。需要 Claude Code v2.1.248 或更新版本 |
330 330
331在 `experimental` 對應內寫入 `cacheTtl`，而不是在 frontmatter 的頂級。331在 `experimental` 對應內寫入 `cacheTtl`，而不是在 frontmatter 的頂級。
332 332
340```340```
341 341
342<h4 id="subagent-files-claude-code-skips">342<h4 id="subagent-files-claude-code-skips">
343 Subagent 檔案 Claude Code 跳過343 Claude Code 跳過的子代理檔案
344</h4>344</h4>
345 345
346Claude Code 跳過專案、使用者或受管 `agents` 目錄中的檔案，或在您使用 `--add-dir` 新增的目錄下的檔案，而不在工作階段中報告它，當 frontmatter 有以下任何問題時：346Claude Code 在專案、使用者或受管 `agents` 目錄中跳過檔案，或在您使用 `--add-dir` 新增的目錄下的檔案，而不在工作階段中報告它，當 frontmatter 有以下任何問題時：
347 347
348* **沒有 `name`**：Claude Code 將檔案視為保存在您的代理旁邊的文件。348* **沒有 `name`**：Claude Code 將檔案視為保存在代理旁邊的文件。
349* **開啟 `---` 不是檔案的第一行**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。349* **不是檔案第一行的開啟 `---`**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。
350* **`name` 以 `-` 開頭或包含 `:`**：Claude Code 跳過檔案並將錯誤寫入除錯日誌。請參閱上表中的 `name` 列。350* **以 `-` 開頭或包含 `:` 的 `name`**：Claude Code 跳過檔案並將錯誤寫入偵錯日誌。請參閱上表中的 `name` 列。
351* **`name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入除錯日誌。351* **有 `name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入偵錯日誌。
352* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入除錯日誌。352* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。
353 353
354若要查看除錯日誌，請使用 `--debug` 執行 Claude Code。354若要查看偵錯日誌，請使用 `--debug` 執行 Claude Code。
355 355
356一個 [plugin subagent](/docs/zh-TW/plugins/components#agents)，其 frontmatter 沒有 `name` 或不解析，仍然在其檔案名稱下載入。356[plugin 子代理](/docs/zh-TW/plugins/components#agents)的 frontmatter 沒有 `name` 或不解析仍然載入，在其檔案名稱下。
357 357
358<h5 id="check-an-agents-directory-before-a-session">358<h5 id="check-an-agents-directory-before-a-session">
359 在工作階段前檢查 `agents` 目錄359 在工作階段前檢查 `agents` 目錄
360</h5>360</h5>
361 361
362若要找到 `agents` 目錄中 frontmatter 不解析的檔案，請針對目錄執行 `claude plugin validate`，例如 `.claude/agents` 或 `~/.claude/agents`。Claude Code 僅檢查 [您命名的目錄](/docs/zh-TW/plugins/cli-reference#validate-a-directory)，並且不會標記 frontmatter 解析但沒有 `name` 的檔案。需要 Claude Code v2.1.233 或更高版本。362若要找出 `agents` 目錄中 frontmatter 不解析的檔案，請針對目錄執行 `claude plugin validate`，例如 `.claude/agents` 或 `~/.claude/agents`。Claude Code 僅檢查[您命名的目錄](/docs/zh-TW/plugins/cli-reference#validate-a-directory)，不標記 frontmatter 解析但沒有 `name` 的檔案。需要 Claude Code v2.1.233 或更新版本。
363 363
364<h3 id="choose-a-model">364<h3 id="choose-a-model">
365 選擇模型365 選擇模型
366</h3>366</h3>
367 367
368`model` 欄位控制 subagent 使用的模型：368`model` 欄位控制子代理使用的模型：
369 369
370* **Model alias**：使用可用的別名之一：`sonnet`、`opus`、`haiku` 或 `fable`370* **模型別名**：使用可用別名之一：`sonnet`、`opus`、`haiku` 或 `fable`
371* **Full model ID**：使用完整模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受與 `--model` 標誌相同的值371* **完整模型 ID**：使用完整模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受與 `--model` 旗標相同的值
372* **inherit**：使用與主要對話相同的模型372* **inherit**：使用與主對話相同的模型
373 373
374當 Claude 呼叫 subagent 時，它也可以為該特定呼叫傳遞 `model` 參數。Claude Code 按此順序解析 subagent 的模型：374當 Claude 叫用子代理時，它也可以為該特定叫用傳遞 `model` 參數。Claude Code 按此順序解析子代理的模型：
375 375
3761. 每次呼叫的 `model` 參數3761. 每次叫用 `model` 參數
3772. Subagent 定義的 `model` frontmatter，其中 `inherit` 選擇主要對話的模型3772. 子代理定義的 `model` frontmatter，其中 `inherit` 選擇主對話的模型
3783. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數，當您將其設定為模型別名或模型 ID 時3783. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數，當您將其設定為模型別名或模型 ID 時
3794. 主要對話的模型3794. 主對話的模型
380 380
381在兩種情況下，家族別名（例如 `opus`）在每次呼叫參數或 frontmatter 中解析為主要對話的模型，而不是 [version the alias points to](/docs/zh-TW/model-config#model-aliases)：381在兩種情況下，每次叫用參數或 frontmatter 中的家族別名（例如 `opus`）解析為主對話的模型，而不是[別名指向的版本](/docs/zh-TW/model-config#model-aliases)：
382 382
383* **主要對話的模型屬於該家族**：subagent 在主要對話的確切模型上執行，包括任何 `[1m]` 後綴，因此它獲得與主要對話相同的 [extended context](/docs/zh-TW/model-config#extended-context) 視窗。383* **主對話的模型屬於該家族**：子代理在主對話的確切模型上執行，包括任何 `[1m]` 尾碼，因此它獲得與主對話相同的[擴展上下文](/docs/zh-TW/model-config#extended-context)視窗。
384* **Claude Code 無法告訴主要對話的模型家族，在 [a provider other than the Anthropic API](/docs/zh-TW/third-party-integrations) 上**：這可能發生在 Amazon Bedrock 上的 [application inference profile ARN](/docs/zh-TW/amazon-bedrock#iam-configuration)，Claude Code 尚未解析為支援模型。此情況僅涵蓋 `opus` 別名，當您設定 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/zh-TW/model-config#environment-variables) 時不適用，因為 `opus` 然後解析為您設定的模型。384* **Claude Code 無法判斷主對話的模型家族，在[Anthropic API 以外的提供者](/docs/zh-TW/third-party-integrations)上**：這可能發生在 Amazon Bedrock 上的[應用程式推論設定檔 ARN](/docs/zh-TW/amazon-bedrock#iam-configuration)，Claude Code 尚未解析為支援模型。此情況僅涵蓋 `opus` 別名，當您設定 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/zh-TW/model-config#environment-variables) 時不適用，因為 `opus` 然後解析為您設定的模型。
385 385
386`CLAUDE_CODE_SUBAGENT_MODEL` 中的別名始終解析為別名指向的版本，即使它命名主要對話的家族。386`CLAUDE_CODE_SUBAGENT_MODEL` 中的別名始終解析為別名指向的版本，即使它命名主對話的家族。
387 387
388設定 `CLAUDE_CODE_SUBAGENT_MODEL` 本身不會改變內建 Explore 和 Plan subagents 執行的模型。若要改變它，請參閱 [Run every subagent on one model](#run-every-subagent-on-one-model)。388單獨設定 `CLAUDE_CODE_SUBAGENT_MODEL` 不會改變內建 Explore 和 Plan 子代理執行的模型。若要改變它，請參閱[在一個模型上執行每個子代理](#run-every-subagent-on-one-model)。
389 389
390在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此順序中排在第一位，並覆蓋每次呼叫參數和 frontmatter，包括 `model: inherit`。390在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此順序中排在第一位，並覆蓋每次叫用參數和 frontmatter，包括 `model: inherit`。
391 391
392將變數設定為 `inherit` 與不設定相同。在 v2.1.196 之前，該值強制 subagents 使用主要對話的模型，並忽略其他來源。392將變數設定為 `inherit` 與不設定它相同。在 v2.1.196 之前，該值強制子代理進入主對話的模型並忽略其他來源。
393 393
394Claude Code 根據您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單檢查每次呼叫參數、frontmatter 和環境變數值。對於被阻止的值，它替換另一個模型：394Claude Code 根據您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單檢查每次叫用參數、frontmatter 和環境變數值。對於被阻止的值，它替換另一個模型：
395 395
396* 當被阻止的值是家族別名（例如 `opus`）時，Claude Code 在允許清單允許的該家族的最新版本上執行 subagent，遵循與 `/model` 相同的 [substitution rules and provider scope](/docs/zh-TW/model-config#restrict-model-selection)。在 v2.1.222 之前，Claude Code 也在被阻止的家族別名的繼承模型上執行 subagent。396* 當被阻止的值是家族別名（例如 `opus`）時，Claude Code 在允許清單允許的該家族的最新版本上執行子代理，遵循與 `/model` 相同的[替換規則和提供者範圍](/docs/zh-TW/model-config#restrict-model-selection)。在 v2.1.222 之前，Claude Code 也在被阻止的家族別名的繼承模型上執行子代理。
397* 對於任何其他被阻止的值，在該替換不操作的提供者上，或當允許清單允許該家族沒有版本時，Claude Code 改為在繼承模型上執行 subagent。如果您設定 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 首先嘗試該模型，在這些相同的規則下。397* 對於任何其他被阻止的值，在該替換不操作的提供者上，或當允許清單允許該家族的沒有版本時，Claude Code 改為在繼承模型上執行子代理。如果您設定 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 首先嘗試該模型，在這些相同的規則下。
398 398
399在互動工作階段中，Claude Code 顯示警告，命名請求的模型和 subagent 執行的模型，對於任一替換。399在互動工作階段中，Claude Code 顯示警告，命名請求的模型和子代理執行的模型，用於任一替換。
400 400
401若要檢查 subagent 執行的模型，請執行 [`/tasks`](/docs/zh-TW/commands)。Claude Code 在 subagent 的列上命名模型，並在 subagent 的定義或它分叉的技能設定 [`effort`](#supported-frontmatter-fields) 時新增 [effort level](/docs/zh-TW/model-config#adjust-effort-level)。需要 Claude Code v2.1.242 或更高版本。401若要檢查子代理執行的模型，請執行 [`/tasks`](/docs/zh-TW/commands)。Claude Code 在子代理的列上命名模型，並在子代理的定義或它分叉的技能設定 [`effort`](#supported-frontmatter-fields) 時新增[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。需要 Claude Code v2.1.242 或更新版本。
402 402
403每次呼叫 `model` 參數也適用於 subagent [resumed or sent a follow-up message](#resume-subagents) 時，因此 subagent 保持在該模型上。在 v2.1.211 之前，恢復會丟棄每次呼叫值，subagent 恢復為其定義的 `model` 欄位或，沒有一個，主要對話的模型。403每次叫用 `model` 參數也適用於子代理[恢復或發送後續訊息](#resume-subagents)時，因此子代理保持在該模型上。在 v2.1.211 之前，恢復會丟棄每次叫用值，子代理恢復為其定義的 `model` 欄位或沒有時的主對話的模型。
404 404
405自 v2.1.198 起，subagents 也繼承主要對話的 [extended thinking](/docs/zh-TW/model-config#extended-thinking) 配置：如果思考在您的工作階段中開啟，它對 subagent 也開啟，如果關閉，它保持關閉。沒有每個 subagent 的思考設定。在 v2.1.198 之前，subagents 執行時禁用擴展思考，無論主要對話的設定如何。405從 v2.1.198 開始，子代理也繼承主對話的[擴展思考](/docs/zh-TW/model-config#extended-thinking)設定：如果思考在您的工作階段中開啟，它對子代理開啟，如果關閉，它保持關閉。沒有每個子代理思考設定。在 v2.1.198 之前，子代理執行時禁用擴展思考，無論主對話的設定如何。
406 406
407<h4 id="run-every-subagent-on-one-model">407<h4 id="run-every-subagent-on-one-model">
408 在一個模型上執行每個 subagent408 在一個模型上執行每個子代理
409</h4>409</h4>
410 410
411`CLAUDE_CODE_SUBAGENT_MODEL` 是預設值，因此 subagent 的定義或 Claude 傳遞的模型仍然優先於它。若要將一個模型應用於每個 subagent、[teammate](/docs/zh-TW/agent-teams#specify-teammates-and-models) 和 [workflow agent](/docs/zh-TW/workflows)，也將 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 設定為 `1`。需要 Claude Code v2.1.257 或更高版本。411`CLAUDE_CODE_SUBAGENT_MODEL` 是預設值，因此子代理的定義或 Claude 傳遞的模型仍然優先於它。若要將一個模型應用於每個子代理、[隊友](/docs/zh-TW/agent-teams#specify-teammates-and-models) 和[工作流代理](/docs/zh-TW/workflows)，也設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 為 `1`。需要 Claude Code v2.1.257 或更新版本。
412 412
413* 如果您設定兩個變數，subagents 在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上執行。413* 如果您設定兩個變數，子代理在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上執行。
414* 如果您僅設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，subagents 在主要對話的模型上執行。414* 如果您僅設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，子代理在主對話的模型上執行。
415 415
416例如，若要在 Haiku 上執行每個 subagent，請在 [settings file](/docs/zh-TW/settings) 的 `env` 區塊中設定兩個變數：416例如，若要在 Haiku 上執行每個子代理，在[設定檔](/docs/zh-TW/settings)的 `env` 區塊中設定兩個變數：
417 417
418```json theme={null}418```json theme={null}
419{419{
424}424}
425```425```
426 426
427若要檢查設定是否生效，請在 subagent 執行時執行 [`/tasks`](/docs/zh-TW/commands)。Subagent 的列顯示它執行的模型。427若要檢查設定是否生效，在子代理執行時執行 [`/tasks`](/docs/zh-TW/commands)。子代理的列顯示它執行的模型。
428 428
429當 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [on](/docs/zh-TW/env-vars) 時，Claude Code 忽略每個 subagent 定義的 `model` 欄位，包括內建 Explore 和 Plan subagents，Claude 無法在啟動 subagent 時傳遞模型。兩種 subagent 仍然在主要對話的模型上執行：429當 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [開啟](/docs/zh-TW/env-vars)時，Claude Code 忽略每個子代理定義的 `model` 欄位，包括內建 Explore 和 Plan 子代理，Claude 無法在啟動子代理時傳遞模型。兩種子代理仍在主對話的模型上執行：
430 430
431* 一個 [fork](#fork-the-current-conversation)431* [分叉](#fork-the-current-conversation)
432* 一個 [skill that runs in a subagent](/docs/zh-TW/skills#run-skills-in-a-subagent)，具有 `model: inherit`432* [在子代理中執行的技能](/docs/zh-TW/skills#run-skills-in-a-subagent)，具有 `model: inherit`
433 433
434當您僅設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 時，內建 Explore subagent 保持其 [model cap](#built-in-subagents)。434當您僅設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 時，內建 Explore 子代理保持其[模型上限](#built-in-subagents)。
435 435
436<h3 id="control-subagent-capabilities">436<h3 id="control-subagent-capabilities">
437 控制 subagent 功能437 控制子代理功能
438</h3>438</h3>
439 439
440您可以透過工具存取、權限模式和條件規則來控制 subagents 可以執行的操作。440您可以透過工具存取、權限模式和條件規則控制子代理可以做什麼。
441 441
442<h4 id="available-tools">442<h4 id="available-tools">
443 可用工具443 可用工具
444</h4>444</h4>
445 445
446Subagents 繼承主要對話中可用的 [built-in tools](/docs/zh-TW/tools-reference) 和 MCP 工具，由兩個過濾器縮小：第一個從每個 subagent 移除工具的簡短清單，第二個減少在 [background](#run-subagents-in-foreground-or-background) 中執行的 subagents 的內建工具集，這是預設值。在 macOS、Linux 和 WSL 上，當主要對話沒有 Glob 和 Grep 工具時，subagent 也可以接收它們，如 [Glob tool behavior](/docs/zh-TW/tools-reference#glob-tool-behavior) 下所述。[Forks](#fork-the-current-conversation) 跳過兩個過濾器，並接收主要對話的確切工具池。第一個過濾器移除這些工具，即使在 `tools` 欄位中列出：446子代理繼承[內建工具](/docs/zh-TW/tools-reference)和主對話中可用的 MCP 工具，由兩個篩選器縮小：第一個從每個子代理移除工具的簡短列表，第二個減少在[背景中](#run-subagents-in-foreground-or-background)執行的子代理的內建工具集，這是預設值。在 macOS、Linux 和 WSL 上，當主對話沒有時，子代理也可以接收 Glob 和 Grep 工具，如[Glob 工具行為](/docs/zh-TW/tools-reference#glob-tool-behavior)下所述。[分叉](#fork-the-current-conversation)跳過兩個篩選器並接收主對話的確切工具池。第一個篩選器移除這些工具，即使在 `tools` 欄位中列出：
447 447
448* `Agent`，當 subagent 在 [depth limit](#let-subagents-spawn-their-own-subagents) 時；在 [fork](#fork-the-current-conversation) 中工具保持列出但傳回錯誤而不是產生448* `Agent`，當子代理在[深度限制](#let-subagents-spawn-their-own-subagents)時；在[分叉](#fork-the-current-conversation)中工具保持列出但返回錯誤而不是生成
449* `AskUserQuestion`449* `AskUserQuestion`
450* `EndConversation`，只能結束主要對話；請參閱 [EndConversation tool behavior](/docs/zh-TW/tools-reference#endconversation-tool-behavior)450* `EndConversation`，只能結束主對話；請參閱[EndConversation 工具行為](/docs/zh-TW/tools-reference#endconversation-tool-behavior)
451* `EnterPlanMode`451* `EnterPlanMode`
452* `ExitPlanMode`，除非 subagent 的 [`permissionMode`](#permission-modes) 是 `plan`452* `ExitPlanMode`，除非子代理的 [`permissionMode`](#permission-modes) 是 `plan`
453* `ScheduleWakeup`453* `ScheduleWakeup`
454* `WaitForMcpServers`454* `WaitForMcpServers`
455* `Workflow`455* `Workflow`
456 456
457第二個過濾器適用於在背景中執行的 subagents。除了 `Agent` 和 `ExitPlanMode`，它們遵循第一個過濾器的條件，無論 subagent 在哪裡執行，背景 subagent 保持每個 MCP 工具，但只有這些內建工具：`Read`、`Grep`、`Glob`、`LSP`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`，加上 [`SubagentHandback`](/docs/zh-TW/tools-reference) 用於透過它報告的 subagent。Claude Code 從背景 subagent 移除每個其他內建工具，無論繼承或在 `tools` 欄位中列出，因此相同的定義可以在前景和背景中解析為不同的工具。移除報告沒有錯誤，除非它使 `tools` 清單 [resolving to nothing](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)。457第二個篩選器適用於在背景中執行的子代理。除了 `Agent` 和 `ExitPlanMode`，它們遵循第一個篩選器的條件，無論子代理在哪裡執行，背景子代理保持每個 MCP 工具，但只有這些內建工具：`Read`、`Grep`、`Glob`、`LSP`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`，加上[`SubagentHandback`](/docs/zh-TW/tools-reference)用於透過它報告的子代理。Claude Code 從背景子代理移除每個其他內建工具，無論繼承或在 `tools` 欄位中列出，因此相同定義可以在前景和背景中解析為不同的工具。移除報告沒有錯誤，除非它使 `tools` 列表[解析為無](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)。
458 458
459在 v2.1.280 之前，背景 subagents 無法使用 `LSP`。459在 v2.1.280 之前，背景子代理無法使用 `LSP`。
460 460
461[`ListAgents`](/docs/zh-TW/cross-session-messaging) 遵循這些過濾器，如同任何內建工具：前景 subagent 在啟用跨工作階段訊息的工作階段中繼承它，背景 subagent 不保持它。461[`ListAgents`](/docs/zh-TW/cross-session-messaging)遵循這些篩選器，如任何內建工具：前景子代理在啟用跨工作階段訊息的工作階段中繼承它，背景子代理不保持它。
462 462
463[agent teams](/docs/zh-TW/agent-teams) 中的隊友另外保持任務工具和 cron 工具：`TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`、`CronCreate`、`CronDelete` 和 `CronList`。463[代理團隊](/docs/zh-TW/agent-teams)中的隊友另外保持任務工具和 cron 工具：`TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`、`CronCreate`、`CronDelete` 和 `CronList`。
464 464
465在 [session without the Task tools](/docs/zh-TW/tools-reference#task-tool-availability) 中，Claude Code 也不向 subagents 提供任務工具，即使 subagent 執行不同的模型。進程內隊友遵循您的工作階段相同的方式，而在其自己的 [split pane](/docs/zh-TW/agent-teams#choose-a-display-mode) 中的隊友作為單獨的 Claude Code 程序執行，因此其自己的模型決定。465在[沒有 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中，Claude Code 也不向子代理提供任務工具，即使子代理執行不同的模型。進程內隊友遵循您的工作階段相同方式，而在其自己的[分割窗格](/docs/zh-TW/agent-teams#choose-a-display-mode)中的隊友作為單獨的 Claude Code 程序執行，因此其自己的模型決定。
466 466
467若要限制工具，請使用 `tools` 欄位作為允許清單或 `disallowedTools` 欄位作為拒絕清單。此範例使用 `tools` 來僅允許 Read、Grep、Glob 和 Bash。Subagent 無法編輯檔案、寫入檔案或使用任何 MCP 工具：467若要限制工具，使用 `tools` 欄位作為允許清單或 `disallowedTools` 欄位作為拒絕清單。此範例使用 `tools` 僅允許 Read、Grep、Glob 和 Bash。子代理無法編輯檔案、寫入檔案或使用任何 MCP 工具：
468 468
469```yaml theme={null}469```yaml theme={null}
470---470---
474---474---
475```475```
476 476
477此範例使用 `disallowedTools` 來繼承 subagent 的工具池，除了 Write 和 Edit。Subagent 保留 Bash、MCP 工具和其餘池：477此範例使用 `disallowedTools` 繼承子代理的工具池，除了 Write 和 Edit。子代理保持 Bash、MCP 工具和其池的其餘部分：
478 478
479```yaml theme={null}479```yaml theme={null}
480---480---
484---484---
485```485```
486 486
487如果兩者都設定，`disallowedTools` 首先應用，然後 `tools` 針對剩餘的池進行解析。同時列在兩者中的工具會被移除。487如果兩者都設定，`disallowedTools` 首先應用，然後 `tools` 針對剩餘池解析。在兩者中列出的工具被移除。
488 488
489當 `tools` 清單中沒有任何內容解析為工具時，例如因為每個條目都拼寫錯誤或命名一個對 subagents 不可用的工具，Claude Code 通常拒絕啟動 subagent，Agent 工具傳回命名未解析條目的錯誤；請參閱 [Agent would be spawned with zero tools](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 以了解訊息以及如何修復每個條目。在 v2.1.208 之前，該 subagent 啟動時沒有工具，可能會傳回空的或令人困惑的結果。489當 `tools` 列表中沒有內容解析為工具時，例如因為每個條目拼寫錯誤或命名子代理無法使用的工具，Claude Code 通常拒絕啟動子代理，Agent 工具返回命名未解析條目的錯誤；請參閱[代理將以零個工具生成](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)以了解訊息以及如何修復每個條目。在 v2.1.208 之前，該子代理以沒有工具啟動，可能返回空或令人困惑的結果。
490 490
491除了確切的工具名稱之外，兩個欄位還接受 MCP 伺服器層級的模式：`mcp__<server>` 或 `mcp__<server>__*` 授予或移除來自命名伺服器的每個工具。在 `disallowedTools` 中，`mcp__*` 也會移除來自任何伺服器的每個 MCP 工具。此範例移除來自 `github` MCP 伺服器的每個工具，同時保留來自其他伺服器的工具和其池中的內建工具：491兩個欄位除了確切工具名稱外還接受 MCP 伺服器級別的模式：`mcp__<server>` 或 `mcp__<server>__*` 授予或移除來自命名伺服器的每個工具。在 `disallowedTools` 中，`mcp__*` 也移除來自任何伺服器的每個 MCP 工具。此範例移除來自 `github` MCP 伺服器的每個工具，同時保持來自其他伺服器和其池中內建工具的工具：
492 492
493```yaml theme={null}493```yaml theme={null}
494---494---
498---498---
499```499```
500 500
501一個 `disallowedTools` 條目具有指定符，例如 `Bash(git push *)`，仍然從 subagent 移除整個工具，而不僅僅是匹配的命令。若要保留 Bash 並阻止特定命令，請在您的設定中新增 [Bash deny rule](/docs/zh-TW/permissions#bash)，例如 `Bash(git push *)` 到 `permissions.deny`。規則適用於主要對話和 subagents。501具有指定符的 `disallowedTools` 條目（例如 `Bash(git push *)`）仍然從子代理移除整個工具，而不僅僅是匹配的命令。若要保持 Bash 並阻止特定命令，在您的設定中新增[Bash 拒絕規則](/docs/zh-TW/permissions#bash)，例如 `Bash(git push *)` 到 `permissions.deny`。規則適用於主對話和子代理。
502 502
503<h4 id="restrict-which-subagents-can-be-spawned">503<h4 id="restrict-which-subagents-can-be-spawned">
504 限制可以產生的 subagents504 限制可以生成的子代理
505</h4>505</h4>
506 506
507當代理以 `claude --agent` 作為主執行緒執行時，它可以使用 Agent 工具產生 subagents。若要限制它可以產生的 subagent 類型，請在 `tools` 欄位中使用 `Agent(agent_type)` 語法。507當代理使用 `claude --agent` 作為主執行緒執行時，它可以使用 Agent 工具生成子代理。若要限制它可以生成的子代理類型，在 `tools` 欄位中使用 `Agent(agent_type)` 語法。
508 508
509<Note>在版本 2.1.63 中，Task 工具已重新命名為 Agent。設定和代理定義中的現有 `Task(...)` 參考仍然作為別名工作。</Note>509<Note>在版本 2.1.63 中，Task 工具被重新命名為 Agent。設定和代理定義中的現有 `Task(...)` 參考仍然作為別名工作。</Note>
510 510
511```yaml theme={null}511```yaml theme={null}
512---512---
516---516---
517```517```
518 518
519這是一個允許清單：只有 `worker` 和 `researcher` subagents 可以產生。如果代理嘗試產生任何其他類型，請求失敗，代理在其提示中只看到允許的類型。若要在允許所有其他類型的同時阻止特定代理，請改用 [`permissions.deny`](#disable-specific-subagents)。519這是允許清單：只有 `worker` 和 `researcher` 子代理可以生成。如果代理嘗試生成任何其他類型，請求失敗，代理僅看到其提示中允許的類型。若要在允許所有其他類型時阻止特定代理，改為使用 [`permissions.deny`](#disable-specific-subagents)。
520 520
521若要允許產生任何 subagent 而不受限制，請使用不帶括號的 `Agent`：521若要允許生成任何子代理而不受限制，使用 `Agent` 不帶括號：
522 522
523```yaml theme={null}523```yaml theme={null}
524tools: Agent, Read, Bash524tools: Agent, Read, Bash
525```525```
526 526
527如果 `Agent` 完全從 `tools` 清單中省略，代理無法產生任何 subagents。527如果您完全從 `tools` 列表中省略 `Agent`，代理無法使用 Agent 工具生成任何子代理。
528 528
529`Agent(agent_type)` 允許清單語法僅適用於以 `claude --agent` 作為主執行緒執行的代理。在 subagent 定義中，在 `tools` 中列出 `Agent` 讓該 subagent 產生自己的 subagents，同時 [depth limit](#let-subagents-spawn-their-own-subagents) 允許它，但括號內的任何類型清單都會被忽略。529`Agent(agent_type)` 允許清單語法僅適用於使用 `claude --agent` 作為主執行緒執行的代理。在子代理定義中，在 `tools` 中列出 `Agent` 讓該子代理在[深度限制](#let-subagents-spawn-their-own-subagents)允許時生成自己的子代理，但括號內的任何類型列表被忽略。
530 530
531<h4 id="scope-mcp-servers-to-a-subagent">531<h4 id="scope-mcp-servers-to-a-subagent">
532 將 MCP 伺服器限定於 subagent532 將 MCP 伺服器範圍限於子代理
533</h4>533</h4>
534 534
535使用 `mcpServers` 欄位為 subagent 提供對主要對話中不可用的 [MCP](/docs/zh-TW/mcp) 伺服器的存取。此處定義的內聯伺服器在 subagent 啟動時連接，受 [trust rule for the agent file's folder](#inline-server-trust) 約束，並在完成時斷開連接。字串參考共享父工作階段的連接。535使用 `mcpServers` 欄位給子代理存取在主對話中不可用的 [MCP](/docs/zh-TW/mcp) 伺服器。此處定義的內聯伺服器在子代理啟動時連接，受[代理檔案資料夾的信任規則](#inline-server-trust)約束，並在完成時斷開連接。字串參考共享父工作階段的連接。
536 536
537<Note>537<Note>
538 `mcpServers` 欄位適用於代理檔案可以執行的兩個上下文：538 `mcpServers` 欄位適用於代理檔案可以執行的兩個上下文：
539 539
540 * 作為 subagent，透過 Agent 工具或 @-mention 產生540 * 作為子代理，透過 Agent 工具或 @-mention 生成
541 * 作為主工作階段，使用 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定啟動541 * 作為主工作階段，使用 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定啟動
542 542
543 當代理是主工作階段時，內聯伺服器定義在啟動時與來自 [`.mcp.json`](/docs/zh-TW/mcp) 和設定檔案的伺服器一起連接，在 [trust rule for the agent file's folder](#inline-server-trust) 下。在 `/mcp` 中，您之前使用過的遠端（HTTP 或 SSE）伺服器可以顯示 [`cached` status](/docs/zh-TW/mcp#managing-your-servers)；Claude Code 在 Claude 首次呼叫其工具之一時連接它。543 當代理是主工作階段時，內聯伺服器定義在啟動時連接，與來自 [`.mcp.json`](/docs/zh-TW/mcp) 和設定檔的伺服器一起，在[代理檔案資料夾的信任規則](#inline-server-trust)下。在 `/mcp` 中，您之前使用過的遠端（HTTP 或 SSE）伺服器可以顯示[`cached` 狀態](/docs/zh-TW/mcp#managing-your-servers)；Claude Code 在 Claude 首次呼叫其工具之一時連接它。
544</Note>544</Note>
545 545
546清單中的每個條目要麼是內聯伺服器定義，要麼是參考工作階段中已配置的 MCP 伺服器的字串：546列表中的每個條目要麼是內聯伺服器定義，要麼是參考工作階段中已設定的 MCP 伺服器的字串：
547 547
548```yaml theme={null}548```yaml theme={null}
549---549---
564 564
565內聯定義使用與 `.mcp.json` 伺服器條目相同的架構，由伺服器名稱鍵入，並支援 `stdio`、`http`、`sse` 和 `ws` 類型。565內聯定義使用與 `.mcp.json` 伺服器條目相同的架構，由伺服器名稱鍵入，並支援 `stdio`、`http`、`sse` 和 `ws` 類型。
566 566
567若要將 MCP 伺服器保持在主要對話之外，並避免其工具描述在那裡消耗上下文，請在此處內聯定義它，而不是在 `.mcp.json` 中。Subagent 獲得工具；父對話不獲得。567若要將 MCP 伺服器完全保留在主對話之外，並避免其工具描述在那裡消耗上下文，在此處內聯定義它，而不是在 `.mcp.json` 中。子代理獲得工具；父對話不。
568 568
569<span id="inline-server-trust" />Claude Code 從您專案的 `.claude/agents/` 目錄中的代理檔案，或在 `--add-dir` 目錄的 `.claude/agents/` 中載入內聯伺服器，僅在您 [trust the folder the agent file came from](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後。在 v2.1.238 之前，Claude Code 載入這些伺服器而不檢查信任。569<span id="inline-server-trust" />Claude Code 從您專案的 `.claude/agents/` 目錄中的代理檔案，或在 `--add-dir` 目錄的 `.claude/agents/` 中載入內聯伺服器，僅在您[信任代理檔案來自的資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後。在 v2.1.238 之前，Claude Code 載入這些伺服器而不檢查信任。
570 570
571* **不計算的信任**：父資料夾的信任，以及 `-p` 或 SDK 工作階段為 [hooks in settings files](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 獲得的自動信任571* **不計算的信任**：父資料夾的信任，以及 `-p` 或 SDK 工作階段為[設定檔中的 hooks](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)獲得的自動信任
572* **直到那時**：Claude Code 跳過該代理檔案中的每個內聯伺服器，並將 `~/.claude.json` 的確切 `projects["<path>"].hasTrustDialogAccepted` 鍵寫入除錯日誌572* **直到那時**：Claude Code 跳過該代理檔案中的每個內聯伺服器，並將 `~/.claude.json` 的確切 `projects["<path>"].hasTrustDialogAccepted` 鍵寫入偵錯日誌
573* **`--add-dir` 目錄**：您受信任工作區儲存庫外的目錄需要其自己的信任條目，因為其 `.claude/agents/` 檔案不繼承您工作區的信任573* **`--add-dir` 目錄**：您受信任工作區儲存庫外的目錄需要自己的信任條目，因為其 `.claude/agents/` 檔案不繼承您工作區的信任
574 574
575Claude Code 載入兩種伺服器而不檢查代理檔案來自的資料夾的信任：575Claude Code 載入兩種伺服器而不檢查代理檔案來自的資料夾的信任：
576 576
577* 參考您已配置的伺服器的名稱577* 參考您已設定的伺服器的名稱
578* 來自 `~/.claude/agents/` 中代理檔案的內聯伺服器，在您使用 `--agents` 或 SDK `agents` 選項傳遞的伺服器中，或受管設定提供的伺服器中578* 來自 `~/.claude/agents/` 中代理檔案的內聯伺服器，在您使用 `--agents` 或 SDK `agents` 選項傳遞的檔案中，或受管設定提供的檔案中
579 579
580適用於主工作階段的 MCP 限制也涵蓋在 subagent frontmatter 中宣告的伺服器：580適用於主工作階段的 MCP 限制也涵蓋在子代理 frontmatter 中宣告的伺服器：
581 581
582* [`--strict-mcp-config`](/docs/zh-TW/cli-reference) 和 [`--bare`](/docs/zh-TW/cli-reference)582* [`--strict-mcp-config`](/docs/zh-TW/cli-reference) 和 [`--bare`](/docs/zh-TW/cli-reference)
583* [Enterprise managed MCP configuration](/docs/zh-TW/managed-mcp)583* [企業受管 MCP 設定](/docs/zh-TW/managed-mcp)
584* [`allowedMcpServers` 和 `deniedMcpServers` 政策](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists)584* [`allowedMcpServers` 和 `deniedMcpServers` 原則](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists)
585 585
586當其中之一阻止伺服器時，Claude Code 會跳過它並顯示警告，命名被阻止的伺服器。586當其中之一阻止伺服器時，Claude Code 跳過它並顯示警告，命名被阻止的伺服器。
587 587
588受管設定限制適用於每個 subagent，無論其如何定義。`--strict-mcp-config` 不會過濾您透過 `--agents` 或 SDK `agents` 選項內聯傳遞的伺服器，因為這些是明確的呼叫者輸入。588受管設定限制適用於每個子代理，無論如何定義。`--strict-mcp-config` 不篩選您透過 `--agents` 或 SDK `agents` 選項內聯傳遞的伺服器，因為那些是明確呼叫者輸入。
589 589
590<h4 id="permission-modes">590<h4 id="permission-modes">
591 權限模式591 權限模式
592</h4>592</h4>
593 593
594設定 `permissionMode` 以選擇 subagent 執行的權限模式。使用模式的配置值，因此手動模式是 `default`。如果您不設定它，subagent 繼承主要對話的 [permission mode](/docs/zh-TW/permission-modes)。594設定 `permissionMode` 以選擇子代理執行的權限模式。使用模式的設定值，因此手動模式是 `default`。如果您不設定它，子代理繼承主對話的[權限模式](/docs/zh-TW/permission-modes)。
595 595
596主要對話的權限模式決定 Claude Code 是否使用您設定的值：596主對話的權限模式決定 Claude Code 是否使用您設定的值：
597 597
598* 當主要對話在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 時，subagent 執行在該相同模式中，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主要對話的阻止和允許規則評估 subagent 的工具呼叫。當 subagent 完成時，分類器也會在報告傳遞前審查其工作和最終報告，如 [How auto mode handles subagents](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所述。598* 當主對話在 `bypassPermissions`、`acceptEdits` 或[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如[自動模式如何處理子代理](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)所述。
599* 當主要對話在 `default`、`dontAsk` 或 `plan` 模式時，subagent 執行在您設定的權限模式中，除了 `bypassPermissions`。宣告 `bypassPermissions` 的 subagent 改為保持主要對話的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。599* 當主對話在 `default`、`dontAsk` 或 `plan` 模式中時，子代理在您設定的權限模式中執行，除了 `bypassPermissions`。宣告 `bypassPermissions` 的子代理保持主對話的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。
600 600
601`permissionMode` 接受這些值，以及 `manual` 作為 `default` 的別名：601`permissionMode` 接受這些值，以及 `manual` 作為 `default` 的別名：
602 602
603| Mode | Behavior |603| 模式 | 行為 |
604| :- | :- |604| :- | :- |
605| `default` | 手動模式：提示權限 |605| `default` | 手動模式：提示權限 |
606| `acceptEdits` | 自動接受檔案編輯和工作目錄或 `additionalDirectories` 中路徑的常見檔案系統命令 |606| `acceptEdits` | 自動接受檔案編輯和工作目錄或 `additionalDirectories` 中路徑的常見檔案系統命令 |
607| `auto` | [Auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：背景分類器審查命令和受保護目錄寫入 |607| `auto` | [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：背景分類器檢查命令和受保護目錄寫入 |
608| `dontAsk` | 自動拒絕權限提示。明確允許的工具仍然工作；`AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器工具（在該設定到達 Claude Code 的工作階段中）會被拒絕，即使您已允許它們 |608| `dontAsk` | 自動拒絕權限提示。明確允許的工具仍然工作；`AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具[您的組織在啟用該設定的工作階段中設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)被拒絕，即使您已允許它們 |
609| `bypassPermissions` | [Skip permission prompts](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)。Subagent 僅在主要對話也處於此模式時才在此模式中執行 |609| `bypassPermissions` | [跳過權限提示](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)。子代理僅在主對話執行此模式時在此模式中執行 |
610| `plan` | Plan mode（唯讀探索） |610| `plan` | Plan 模式（唯讀探索） |
611 611
612<h4 id="preload-skills-into-subagents">612<h4 id="preload-skills-into-subagents">
613 將技能預載入 subagents613 將技能預載入子代理
614</h4>614</h4>
615 615
616使用 `skills` 欄位在啟動時將技能內容注入到 subagent 的上下文中。這為 subagent 提供領域知識，而無需在執行期間發現和載入技能。616使用 `skills` 欄位在啟動時將技能內容注入子代理的上下文。這給子代理領域知識，而不需要它在執行期間發現和載入技能。
617 617
618```yaml theme={null}618```yaml theme={null}
619---619---
627Implement API endpoints. Follow the conventions and patterns from the preloaded skills.627Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
628```628```
629 629
630每個列出的技能的完整內容被注入到 subagent 的上下文中。此欄位控制哪些技能被預載入，而不是 subagent 可以存取哪些技能：沒有它，subagent 仍然可以在執行期間透過 Skill 工具發現和呼叫專案、使用者和外掛程式技能。若要防止 subagent 完全呼叫技能，請從 [`tools`](#available-tools) 清單中省略 `Skill` 或將其新增到 `disallowedTools`。630每個列出的技能的完整內容在啟動時注入子代理的上下文。此欄位控制哪些技能被預載入，而不是子代理可以存取哪些技能：沒有它，子代理仍然可以在執行期間透過 Skill 工具發現和叫用專案、使用者和 plugin 技能。若要防止子代理完全叫用技能，從 [`tools`](#available-tools) 列表中省略 `Skill` 或將其新增到 `disallowedTools`。
631 631
632您無法預載入設定 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能，因為預載入來自 Claude 可以呼叫的相同技能集。這包括捆綁的 `/verify` 技能：只有您可以執行它，因此它也無法被預載入。632您無法預載入設定 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能，因為預載入來自 Claude 可以叫用的相同技能集。這包括捆綁的 `/verify` 技能：只有您可以執行它，因此它也無法被預載入。
633 633
634如果列出的技能遺失或已停用，例如由您的組織政策，Claude Code 會跳過它並將警告記錄到除錯日誌。634如果列出的技能遺失或被禁用，例如由您組織的原則，Claude Code 跳過它並將警告記錄到偵錯日誌。
635 635
636<Note>636<Note>
637 這與 [running a skill in a subagent](/docs/zh-TW/skills#run-skills-in-a-subagent) 相反。使用 subagent 中的 `skills`，subagent 控制系統提示並載入技能內容。使用技能中的 `context: fork`，技能內容被注入到您指定的代理中。兩者都使用相同的基礎系統。637 這與[在子代理中執行技能](/docs/zh-TW/skills#run-skills-in-a-subagent)相反。在子代理中使用 `skills` 時，子代理控制系統提示並載入技能內容。在技能中使用 `context: fork` 時，技能內容被注入您指定的代理。在兩種情況下，子代理啟動時沒有您的對話歷史。
638</Note>638</Note>
639 639
640<h4 id="enable-persistent-memory">640<h4 id="enable-persistent-memory">
641 啟用持久記憶641 啟用持久記憶
642</h4>642</h4>
643 643
644`memory` 欄位為 subagent 提供一個在對話之間存活的持久目錄。Subagent 使用此目錄隨著時間建立知識，例如程式碼庫模式、除錯見解和架構決策。644`memory` 欄位給子代理一個在對話中存活的持久目錄。子代理使用此目錄隨著時間建立知識，例如程式碼庫模式、偵錯見解和架構決策。
645 645
646```yaml theme={null}646```yaml theme={null}
647---647---
656 656
657根據記憶應該應用的廣泛程度選擇範圍：657根據記憶應該應用的廣泛程度選擇範圍：
658 658
659| Scope | Location | 使用時機 |659| 範圍 | 位置 | 使用時機 |
660| :- | :- | :- |660| :- | :- | :- |
661| `user` | `~/.claude/agent-memory/<name-of-agent>/` | subagent 應該記住跨所有專案的學習 |661| `user` | `~/.claude/agent-memory/<name-of-agent>/` | 子代理應該記住跨所有專案的學習 |
662| `project` | `.claude/agent-memory/<name-of-agent>/` | subagent 的知識是特定於專案的，可透過版本控制共享 |662| `project` | `.claude/agent-memory/<name-of-agent>/` | 子代理的知識是專案特定的並可透過版本控制共享 |
663| `local` | `.claude/agent-memory-local/<name-of-agent>/` | subagent 的知識是特定於專案的，但不應簽入版本控制 |663| `local` | `.claude/agent-memory-local/<name-of-agent>/` | 子代理的知識是專案特定的但不應簽入版本控制 |
664 664
665Subagent 記憶是 [auto memory](/docs/zh-TW/memory#auto-memory) 的一部分：如果您關閉自動記憶，使用 `autoMemoryEnabled` 設定或 `CLAUDE_CODE_DISABLE_AUTO_MEMORY`，`memory` 欄位沒有效果，subagent 啟動時沒有記憶說明或下面描述的記憶工具存取。665子代理記憶是[自動記憶](/docs/zh-TW/memory#auto-memory)的一部分：如果您關閉自動記憶，使用 `autoMemoryEnabled` 設定或 `CLAUDE_CODE_DISABLE_AUTO_MEMORY`，`memory` 欄位無效，子代理啟動時沒有記憶指示或下面描述的記憶工具存取。
666 666
667當記憶啟用時：667當記憶啟用時：
668 668
669* Subagent 的系統提示包括讀取和寫入記憶目錄的說明。669* 子代理的系統提示包括讀取和寫入記憶目錄的指示。
670* Subagent 的系統提示還包括記憶目錄中 `MEMORY.md` 的前 200 行或 25KB（以先到者為準），以及如果超過該限制則策劃 `MEMORY.md` 的說明。670* 子代理的系統提示也包括記憶目錄中 `MEMORY.md` 的前 200 行或 25KB（以先到者為準），以及如果超過該限制則策劃 `MEMORY.md` 的指示。
671* Read、Write 和 Edit 工具會自動啟用，以便 subagent 可以管理其記憶檔案。671* Read、Write 和 Edit 工具自動啟用，以便子代理可以管理其記憶檔案。
672 672
673<h5 id="persistent-memory-tips">673<h5 id="persistent-memory-tips">
674 持久記憶提示674 持久記憶提示
675</h5>675</h5>
676 676
677* `project` 是建議的預設範圍。它使 subagent 知識可透過版本控制共享。677* `project` 是推薦的預設範圍。它使子代理知識可透過版本控制共享。
678* 要求 subagent 在開始工作前查閱其記憶："Review this PR, and check your memory for patterns you've seen before."678* 要求子代理在開始工作前查詢其記憶："檢查此 PR，並檢查您的記憶以了解您之前看到的模式。"
679* 要求 subagent 在完成任務後更新其記憶："Now that you're done, save what you learned to your memory." 隨著時間的推移，這會建立一個知識庫，使 subagent 更有效。679* 要求子代理在完成任務後更新其記憶："既然您已完成，將您學到的內容儲存到您的記憶。" 隨著時間推移，這建立了一個知識庫，使子代理更有效。
680* 直接在 subagent 的 markdown 檔案中包括記憶說明，以便它主動維護自己的知識庫：680* 直接在子代理的 markdown 檔案中包括記憶指示，以便它主動維護自己的知識庫：
681 681
682 ```markdown theme={null}682 ```markdown theme={null}
683 Update your agent memory as you discover codepaths, patterns, library683 Update your agent memory as you discover codepaths, patterns, library
690 使用 hooks 的條件規則690 使用 hooks 的條件規則
691</h4>691</h4>
692 692
693為了更動態地控制工具使用，請使用 `PreToolUse` hooks 在執行前驗證操作。當您需要允許工具的某些操作同時阻止其他操作時，這很有用。693為了更動態地控制工具使用，使用 `PreToolUse` hooks 在執行前驗證操作。當您需要允許工具的某些操作同時阻止其他操作時，這很有用。
694 694
695此範例建立一個只允許唯讀資料庫查詢的 subagent。`PreToolUse` hook 在每個 Bash 命令執行前執行 `command` 中指定的指令碼：695此範例建立一個僅允許唯讀資料庫查詢的子代理。`PreToolUse` hook 在每個 Bash 命令執行前執行 `command` 中指定的指令碼：
696 696
697```yaml theme={null}697```yaml theme={null}
698---698---
708---708---
709```709```
710 710
711Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/docs/zh-TW/hooks#pretooluse-input) 給 hook 命令。驗證指令碼讀取此 JSON，提取 Bash 命令，並 [以代碼 2 退出](/docs/zh-TW/hooks#exit-code-2-behavior-per-event) 以阻止寫入操作：711Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/docs/zh-TW/hooks#pretooluse-input)給 hook 命令。驗證指令碼讀取此 JSON，提取 Bash 命令，並[以代碼 2 退出](/docs/zh-TW/hooks#exit-code-2-behavior-per-event)以阻止寫入操作：
712 712
713```bash theme={null}713```bash theme={null}
714#!/bin/bash714#!/bin/bash
732chmod +x ./scripts/validate-readonly-query.sh732chmod +x ./scripts/validate-readonly-query.sh
733```733```
734 734
735若要測試規則，要求 subagent 執行 `UPDATE` 陳述式：指令碼以代碼 2 退出，Claude Code 阻止命令，subagent 看到 `Blocked: Only SELECT queries are allowed` 訊息。735若要測試規則，要求子代理執行 `UPDATE` 陳述式：指令碼以代碼 2 退出，Claude Code 阻止命令，子代理看到 `Blocked: Only SELECT queries are allowed` 訊息。
736 736
737請參閱 [Hook input](/docs/zh-TW/hooks#pretooluse-input) 以了解完整的輸入架構，以及 [exit codes](/docs/zh-TW/hooks#exit-code-output) 以了解退出代碼如何影響行為。在 Windows 上，在 PowerShell 中編寫 hook 指令碼，並在 hook 條目中新增 `shell: powershell`，如 [running hooks in PowerShell](/docs/zh-TW/hooks#windows-powershell-tool) 所示。737請參閱[Hook 輸入](/docs/zh-TW/hooks#pretooluse-input)以了解完整輸入架構，以及[退出代碼](/docs/zh-TW/hooks#exit-code-output)以了解退出代碼如何影響行為。在 Windows 上，在 PowerShell 中編寫 hook 指令碼，並在 hook 條目中新增 `shell: powershell`，如[在 PowerShell 中執行 hooks](/docs/zh-TW/hooks#windows-powershell-tool)所示。
738 738
739<h4 id="disable-specific-subagents">739<h4 id="disable-specific-subagents">
740 禁用特定 subagents740 禁用特定子代理
741</h4>741</h4>
742 742
743您可以透過將 subagents 新增到您的 [settings](/docs/zh-TW/settings-reference#permission-settings) 中的 `deny` 陣列來防止 Claude 使用特定 subagents。使用格式 `Agent(subagent-name)`，其中 `subagent-name` 與 subagent 的 name 欄位相符。743您可以透過在[設定](/docs/zh-TW/settings-reference#permission-settings)中的 `deny` 陣列中新增子代理來防止 Claude 使用特定子代理。使用格式 `Agent(subagent-name)`，其中 `subagent-name` 符合子代理的 name 欄位。
744 744
745```json theme={null}745```json theme={null}
746{746{
750}750}
751```751```
752 752
753這適用於內建和自訂 subagents。您也可以使用 `--disallowedTools` CLI 標誌：753這適用於內建和自訂子代理。您也可以使用 `--disallowedTools` CLI 旗標：
754 754
755```bash theme={null}755```bash theme={null}
756claude --disallowedTools "Agent(Explore)"756claude --disallowedTools "Agent(Explore)"
757```757```
758 758
759請參閱 [Permissions documentation](/docs/zh-TW/permissions#tool-specific-permission-rules) 以了解有關權限規則的更多詳細資訊。759請參閱[權限文件](/docs/zh-TW/permissions#tool-specific-permission-rules)以了解更多有關權限規則的詳細資訊。
760 760
761<h3 id="define-hooks-for-subagents">761<h3 id="define-hooks-for-subagents">
762 為 subagents 定義 hooks762 為子代理定義 hooks
763</h3>763</h3>
764 764
765Subagents 可以定義在 subagent 生命週期期間執行的 [hooks](/docs/zh-TW/hooks)。有兩種方式來配置 hooks：765子代理可以定義在子代理的生命週期期間執行的 [hooks](/docs/zh-TW/hooks)。有兩種方式設定 hooks：
766 766
767* **在 subagent 的 frontmatter 中**：定義只在該 subagent 活動時執行的 hooks767* **在子代理的 frontmatter 中**：定義僅在該子代理活動時執行的 hooks
768* **在 `settings.json` 中**：定義在主工作階段中回應 subagent 生命週期事件的工作階段範圍 hooks。工具事件（例如 `PreToolUse` 和 `PostToolUse`）對 subagent 的工具呼叫的觸發方式與在主要對話中相同，`SubagentStart` 和 `SubagentStop` 在 subagent 啟動或完成時觸發768* **在 `settings.json` 中**：定義也在子代理內觸發的工作階段範圍 hooks。工具事件（例如 `PreToolUse` 和 `PostToolUse`）對子代理的工具呼叫觸發，與它們在主對話中的方式相同，`SubagentStart` 和 `SubagentStop` 在子代理啟動或完成時觸發
769 769
770來自 [settings files、managed policy settings 和 plugins](/docs/zh-TW/hooks#hook-locations) 的 Hooks 都適用於 subagents 內，因此 `settings.json` 中的 `PreToolUse` hook 也在 subagent 使用的每個工具之前執行。770來自[設定檔、受管原則設定和 plugins](/docs/zh-TW/hooks#hook-locations)的 Hooks 都適用於子代理內，因此 `settings.json` 中的 `PreToolUse` hook 也在子代理使用的每個工具之前執行。
771 771
772<h4 id="hooks-in-subagent-frontmatter">772<h4 id="hooks-in-subagent-frontmatter">
773 Subagent frontmatter 中的 Hooks773 子代理 frontmatter 中的 Hooks
774</h4>774</h4>
775 775
776直接在 subagent 的 markdown 檔案中定義 hooks。這些 hooks 只在該特定 subagent 活動時執行，並在完成時清理。776直接在子代理的 markdown 檔案中定義 hooks。這些 hooks 僅在該特定子代理活動時執行，並在完成時清理。
777 777
778<Note>778<Note>
779 Frontmatter hooks 在代理透過 Agent 工具或 @-mention 作為 subagent 產生時觸發，以及當代理透過 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定作為主工作階段執行時觸發。在主工作階段情況下，它們與在 [`settings.json`](/docs/zh-TW/hooks) 中定義的任何 hooks 一起執行。779 Frontmatter hooks 在代理透過 Agent 工具或 @-mention 生成為子代理時觸發，以及當代理透過 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定作為主工作階段執行時。在主工作階段情況下，它們與 [`settings.json`](/docs/zh-TW/hooks) 中定義的任何 hooks 一起執行。
780</Note>780</Note>
781 781
782若要讓專案層級 subagent 的 frontmatter hooks 執行，請接受包含代理檔案的資料夾的 [workspace trust dialog](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。來自 `~/.claude/agents/` 中使用者層級 subagents 的 Hooks 以及來自您使用 `--agents` 傳遞的定義的 Hooks，無需此步驟即可執行。如果您使用 `--add-dir` 從您受信任工作區儲存庫外新增資料夾，單獨信任該資料夾：其 `.claude/agents/` hooks 不繼承工作區的授予。782若要讓專案級子代理的 frontmatter hooks 執行，接受包含代理檔案的資料夾的[工作區信任對話](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。來自 `~/.claude/agents/` 中使用者級子代理的 Hooks 和來自您使用 `--agents` 傳遞的定義的 Hooks 無需此步驟即可執行。如果您從受信任工作區儲存庫外使用 `--add-dir` 新增資料夾，單獨信任該資料夾：其 `.claude/agents/` hooks 不繼承工作區的授予。
783 783
784直到您信任資料夾，subagent 仍然執行，但 Claude Code 跳過其 frontmatter hooks 並將錯誤記錄到除錯日誌，解釋如何信任資料夾。這是比設定檔案中 hooks 的規則更嚴格的規則：信任父資料夾不夠，`-p` 工作階段不計為受信任。[What runs before you trust a folder](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 比較兩者。在 v2.1.218 之前，frontmatter hooks 可以從您未信任的資料夾執行，包括在非互動工作階段中。784直到您信任資料夾，子代理仍然執行，但 Claude Code 跳過其 frontmatter hooks 並將錯誤記錄到偵錯日誌，解釋如何信任資料夾。這是比設定檔中 hooks 的規則更嚴格的規則：信任父資料夾不夠，`-p` 工作階段不計為受信任。[在您信任資料夾前執行的內容](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)比較兩者。在 v2.1.218 之前，frontmatter hooks 可以從您未信任的資料夾執行，包括在非互動工作階段中。
785 785
786支援所有 [hook events](/docs/zh-TW/hooks#hook-events)。subagents 最常見的事件是：786所有[hook 事件](/docs/zh-TW/hooks#hook-events)都被支援。子代理最常見的事件是：
787 787
788| Event | Matcher input | 何時觸發 |788| 事件 | Matcher 輸入 | 何時觸發 |
789| :- | :- | :- |789| :- | :- | :- |
790| `PreToolUse` | Tool name | 在 subagent 使用工具之前 |790| `PreToolUse` | 工具名稱 | 子代理使用工具前 |
791| `PostToolUse` | Tool name | 在 subagent 使用工具之後 |791| `PostToolUse` | 工具名稱 | 子代理使用工具後 |
792| `Stop` | (none) | 當 subagent 完成時（在執行時轉換為 `SubagentStop`） |792| `Stop` | （無） | 子代理完成時（在執行時轉換為 `SubagentStop`） |
793 793
794此範例使用 `PreToolUse` hook 驗證 Bash 命令，並在檔案編輯後使用 `PostToolUse` 執行 linter：794此範例使用 `PreToolUse` hook 驗證 Bash 命令，並使用 `PostToolUse` 在檔案編輯後執行 linter：
795 795
796```yaml theme={null}796```yaml theme={null}
797---797---
802 - matcher: "Bash"802 - matcher: "Bash"
803 hooks:803 hooks:
804 - type: command804 - type: command
805 command: "./scripts/validate-command.sh $TOOL_INPUT"805 command: "./scripts/validate-command.sh"
806 PostToolUse:806 PostToolUse:
807 - matcher: "Edit|Write"807 - matcher: "Edit|Write"
808 hooks:808 hooks:
811---811---
812```812```
813 813
814當代理作為 subagent 呼叫時，frontmatter 中的 `Stop` hooks 會自動轉換為 `SubagentStop` 事件。814當代理作為子代理叫用時，frontmatter 中的 `Stop` hooks 自動轉換為 `SubagentStop` 事件。
815 815
816<h4 id="project-level-hooks-for-subagent-events">816<h4 id="project-level-hooks-for-subagent-events">
817 用於 subagent 事件的專案層級 hooks817 子代理事件的專案級 Hooks
818</h4>818</h4>
819 819
820在 `settings.json` 中配置 hooks，以回應主工作階段中的 subagent 生命週期事件。820在 `settings.json` 中設定 hooks，以回應主工作階段中的子代理生命週期事件。
821 821
822| Event | Matcher input | 何時觸發 |822| 事件 | Matcher 輸入 | 何時觸發 |
823| :- | :- | :- |823| :- | :- | :- |
824| `SubagentStart` | Agent type name | 當 subagent 開始執行時 |824| `SubagentStart` | 代理類型名稱 | 子代理開始執行時 |
825| `SubagentStop` | Agent type name | 當 subagent 完成時 |825| `SubagentStop` | 代理類型名稱 | 子代理完成時 |
826 826
827兩個事件都支援匹配器以按名稱針對特定代理類型。匹配器值是專案層級和使用者層級 subagents 的代理 frontmatter `name`，或 [plugin subagents](/docs/zh-TW/plugins/components#agents) 的外掛程式範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為 [unanchored regular expression](/docs/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅匹配該代理。827兩個事件都支援 matchers 以按名稱針對特定代理類型。matcher 值是專案級和使用者級子代理的代理 frontmatter `name`，或 [plugin 子代理](/docs/zh-TW/plugins/components#agents)的 plugin 範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為[未錨定的正規表達式](/docs/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅符合該代理。
828 828
829此範例僅在 `db-agent` subagent 啟動時執行設定指令碼，並在任何 subagent 停止時執行清理指令碼：829此範例僅在 `db-agent` 子代理啟動時執行設定指令碼，並在任何子代理停止時執行清理指令碼：
830 830
831```json theme={null}831```json theme={null}
832{832{
850}850}
851```851```
852 852
853連字號匹配器（如 `db-agent`）在 Claude Code v2.1.195 或更高版本上精確匹配。在較早的版本上，它被評估為 unanchored regular expression，也會針對任何包含它的代理類型觸發，例如 `prod-db-agent`；在這些版本上使用 `^db-agent$` 錨定它。853請參閱 [Hooks](/docs/zh-TW/hooks) 以了解完整的 hook 設定格式。
854
855請參閱 [Hooks](/docs/zh-TW/hooks) 以了解完整的 hook 配置格式。
856 854
857<h2 id="work-with-subagents">855<h2 id="work-with-subagents">
858 使用 subagents856 使用 subagents
