Hooks 參考

本文提供 VS Code 中代理程式 hook 設定屬性以及各 hook 事件的輸入與輸出結構參考。如需關於設定與使用 hook 的資訊，請參閱代理程式 Hooks (Agent hooks)。

每個 hook 也會接收一組常見輸入欄位，並可傳回常見輸出格式。事件章節中記錄的欄位是這些常見欄位以外的補充。

Hook 指令屬性

每個 hook 項目必須包含 type: "command" 以及至少一個指令屬性

屬性	類型	說明
`類型`	string	必須為 `"command"`
`命令`	string	要執行的預設指令（跨平臺）
`windows`	string	Windows 專屬的指令覆寫
`linux`	string	Linux 專屬的指令覆寫
`osx`	string	macOS 專屬的指令覆寫
`cwd`	string	工作目錄（相對於存放庫根目錄）
`環境變數`	object	額外的環境變數
`timeout`	number	逾時時間（秒，預設：30）

PreToolUse

PreToolUse hook 會在代理程式叫用工具之前觸發。

PreToolUse 輸入

除了常見欄位之外，PreToolUse hook 還會接收

{
  "tool_name": "editFiles",
  "tool_input": { "files": ["src/main.ts"] },
  "tool_use_id": "tool-123"
}

PreToolUse 輸出

PreToolUse hook 可以透過 hookSpecificOutput 物件來控制工具執行

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by policy",
    "updatedInput": { "files": ["src/safe.ts"] },
    "additionalContext": "User has read-only access to production files"
  }
}

欄位	值	說明
`permissionDecision`	`"allow"`、`"deny"`、`"ask"`	控制工具核准
`permissionDecisionReason`	string	顯示給使用者的原因
`updatedInput`	object	修改後的工具輸入（選用）
`additionalContext`	string	給模型的額外內容

權限決策優先順序：當多個 hook 針對同一個工具叫用執行時，最嚴格的決策會生效

deny（最嚴格）：阻擋工具執行
ask：需要使用者確認
allow（最不嚴格）：自動核准執行

updatedInput 格式：若要確定 updatedInput 的格式，請開啟代理程式記錄檔 (agent logs) 並尋找記錄的工具結構描述 (schema)。如果 updatedInput 不符合預期的結構描述，將會被忽略。

PostToolUse

PostToolUse hook 會在工具成功完成後觸發。

PostToolUse 輸入

除了常見欄位之外，PostToolUse hook 還會接收

{
  "tool_name": "editFiles",
  "tool_input": { "files": ["src/main.ts"] },
  "tool_use_id": "tool-123",
  "tool_response": "File edited successfully"
}

PostToolUse 輸出

PostToolUse hook 可以向模型提供額外的內容，或阻擋後續的處理

{
  "decision": "block",
  "reason": "Post-processing validation failed",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The edited file has lint errors that need to be fixed"
  }
}

欄位	值	說明
`decision`	`"block"`	阻擋後續處理（選用）
`reason`	string	阻擋的原因（顯示給模型）
`hookSpecificOutput.additionalContext`	string	注入對話中的額外內容

UserPromptSubmit

UserPromptSubmit hook 會在使用者提交提示詞時觸發。

UserPromptSubmit 輸入

除了常見欄位之外，UserPromptSubmit hook 還會接收包含使用者所提交文字的 prompt 欄位。

UserPromptSubmit hook 僅使用常見輸出格式。

SessionStart

SessionStart hook 會在新的代理程式工作階段開始時觸發。

SessionStart 輸入

除了常見欄位之外，SessionStart hook 還會接收

{
  "source": "new"
}

欄位	類型	說明
`source`	string	工作階段是如何啟動的。目前一律為 `"new"`。

SessionStart 輸出

SessionStart hook 可以將額外內容注入代理程式的對話中

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project: my-app v2.1.0 | Branch: main | Node: v20.11.0"
  }
}

欄位	類型	說明
`additionalContext`	string	已新增至代理程式對話中的內容

Stop (停止)

Stop hook 會在代理程式工作階段結束時觸發。當範圍限定於自訂代理程式時，Stop hook 也會被視為 SubagentStop。

Stop 輸入

除了常見欄位之外，Stop hook 還會接收

{
  "stop_hook_active": false
}

欄位	類型	說明
`stop_hook_active`	boolean	當代理程式因為先前的 stop hook 而已經在繼續執行時，此欄位為 `true`。請檢查此值以防止代理程式無限期執行。

Stop 輸出

Stop hook 可以防止代理程式停止

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "decision": "block",
    "reason": "Run the test suite before finishing"
  }
}

欄位	值	說明
`decision`	`"block"`	防止代理程式停止
`reason`	string	當 decision 為 `"block"` 時為必填。告訴代理程式它應該繼續執行的原因。

重要

當 Stop hook 阻擋代理程式停止時，代理程式會繼續執行，而額外的回合將會消耗 AI 點數 (AI credits)。務必檢查 stop_hook_active 欄位以防止代理程式無限期執行。

SubagentStart

SubagentStart hook 會在子代理程式建立時觸發。

SubagentStart 輸入

除了常見欄位之外，SubagentStart hook 還會接收

{
  "agent_id": "subagent-456",
  "agent_type": "Plan"
}

欄位	類型	說明
`agent_id`	string	子代理程式的唯一識別碼
`agent_type`	string	代理程式名稱（例如內建代理程式的 `"Plan"` 或自訂代理程式名稱）

SubagentStart 輸出

SubagentStart hook 可以將額外內容注入子代理程式的對話中

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "This subagent should follow the project coding guidelines"
  }
}

欄位	類型	說明
`additionalContext`	string	已新增至子代理程式對話中的內容

SubagentStop

SubagentStop hook 會在子代理程式完成時觸發。

SubagentStop 輸入

除了常見欄位之外，SubagentStop hook 還會接收

{
  "agent_id": "subagent-456",
  "agent_type": "Plan",
  "stop_hook_active": false
}

欄位	類型	說明
`agent_id`	string	子代理程式的唯一識別碼
`agent_type`	string	代理程式名稱（例如內建代理程式的 `"Plan"` 或自訂代理程式名稱）
`stop_hook_active`	boolean	當子代理程式因為先前的 stop hook 而已經在繼續執行時，此欄位為 `true`。請檢查此值以防止子代理程式無限期執行。

SubagentStop 輸出

SubagentStop hook 可以防止子代理程式停止

{
  "decision": "block",
  "reason": "Verify subagent results before completing"
}

欄位	值	說明
`decision`	`"block"`	防止子代理程式停止
`reason`	string	當 decision 為 `"block"` 時為必填。告訴子代理程式它應該繼續執行的原因。

PreCompact

PreCompact hook 會在對話內容被壓縮之前觸發。

PreCompact 輸入

除了常見欄位之外，PreCompact hook 還會接收

{
  "trigger": "auto"
}

欄位	類型	說明
`trigger`	string	壓縮是如何觸發的。當對話對於提示詞預算來說過長時為 `"auto"`。

PreCompact hook 僅使用常見輸出格式。