Visual Studio Code Agent 鉤子 (預覽)

鉤子可讓您在代理 (Agent) 工作階段的關鍵生命週期點執行自訂 Shell 指令。使用鉤子可以自動化工作流程、強制執行安全策略、驗證操作並與外部工具整合。

關於鉤子如何融入 AI 自訂架構的背景資訊，請參閱自訂概念。

本文說明如何在 VS Code 中設定並使用鉤子。

鉤子的設計適用於各種代理類型，包括本機代理、背景代理和雲端代理。每個鉤子都會接收結構化的 JSON 輸入，並可回傳 JSON 輸出以影響代理的行為。

為什麼要使用鉤子 (hooks)？

鉤子提供確定性的程式碼驅動自動化。與引導代理行為的指令或自訂提示詞不同，鉤子會在特定的生命週期點執行您的程式碼，並具有保證的結果。

• 強制執行安全策略：在危險指令（如 rm -rf 或 DROP TABLE）執行前將其封鎖，無論代理收到的提示詞是什麼。

• 自動化程式碼品質：在檔案修改後自動執行格式化程式、檢查工具或測試。

• 建立稽核追蹤：記錄每一次的工具呼叫、指令執行或檔案變更，以利合規性檢查與偵錯。

• 注入內容：添加專案特定的資訊、API 金鑰或環境詳細資料，以協助代理做出更好的決策。

• 控制核准：自動核准安全的操作，同時對敏感操作要求確認。

快速入門：您的第一個鉤子

下列範例建立了一個鉤子，在每次編輯檔案後執行 Prettier。請在您的工作區中建立一個 .github/hooks/format.json 檔案。

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

儲存此檔案後，VS Code 會自動載入該鉤子。下次代理編輯檔案時，Prettier 就會對變更後的檔案執行。請檢查 GitHub Copilot Chat Hooks 輸出頻道以驗證鉤子是否執行。

若要了解使用自訂指令碼的更複雜鉤子，請參閱使用情境。

鉤子生命週期事件

VS Code 支援八種鉤子事件，會在代理工作階段的特定時間點觸發。

設定鉤子

鉤子是在儲存於工作區或使用者目錄中的 JSON 檔案中進行設定。

鉤子檔案位置

VS Code 會在下列位置搜尋鉤子設定檔：

針對同一事件類型，工作區鉤子的優先順序高於使用者鉤子。

使用 chat.hookFilesLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來自訂要載入哪些鉤子檔案。您可以指定資料夾路徑（VS Code 會載入資料夾中所有的 *.json 檔案）或個別 .json 檔案的路徑。僅支援相對路徑與波浪號 (~) 路徑。

預設值包含這些位置：

"chat.hookFilesLocations": {
  ".github/hooks": true,
  ".claude/settings.local.json": true,
  ".claude/settings.json": true,
  "~/.claude/settings.json": true
}

若要新增自訂位置，請將項目加入此設定。

"chat.hookFilesLocations": {
  "custom/hooks": true,
  "~/my-hooks/security.json": true
}

將路徑設為 false 可停用從該位置載入鉤子（包括預設位置）。例如，若要停止從 Claude Code 設定檔載入鉤子：

"chat.hookFilesLocations": {
  ".claude/settings.json": false,
  ".claude/settings.local.json": false,
  "~/.claude/settings.json": false
}

代理範圍鉤子 (Agent-scoped hooks)

您可以直接在自訂代理的 YAML frontmatter 中定義鉤子。代理範圍鉤子僅在該自訂代理處於作用中狀態（無論是由使用者選取或作為子代理呼叫）時執行。代理範圍鉤子會與針對相同事件設定的工作區或使用者層級鉤子並行執行。

若要啟用代理範圍鉤子，請將 chat.useCustomAgentHooks 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定為 true。

在代理 frontmatter 中新增一個 hooks 欄位，其結構與鉤子設定檔相同：將事件名稱對應至鉤子指令物件的陣列。

---
name: "Strict Formatter"
description: "Agent that auto-formats code after every edit"
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

You are a code editing agent. After making changes, files are automatically formatted.

鉤子設定格式

建立一個包含 hooks 物件的 JSON 檔案，該物件包含每個事件類型的鉤子指令陣列。為了相容性，VS Code 使用與 Claude Code 和 Copilot CLI 相同的鉤子格式。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

鉤子指令屬性

每個鉤子項目必須具有 type: "command" 以及至少一個指令屬性。

作業系統專用指令

為每個作業系統指定不同的指令

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "./scripts/format.sh",
        "windows": "powershell -File scripts\\format.ps1",
        "linux": "./scripts/format-linux.sh",
        "osx": "./scripts/format-mac.sh"
      }
    ]
  }
}

執行服務會根據您的 OS 選擇適當的指令。如果未定義 OS 專用指令，則會回復使用 command 屬性。

鉤子輸入與輸出

鉤子透過標準輸入 (stdin) 和標準輸出 (stdout) 使用 JSON 與 VS Code 進行通訊。

常見輸入欄位

每個鉤子都會透過 stdin 接收一個包含這些常見欄位的 JSON 物件。

{
  "timestamp": "2026-02-09T10:30:00.000Z",
  "cwd": "/path/to/workspace",
  "sessionId": "session-identifier",
  "hookEventName": "PreToolUse",
  "transcript_path": "/path/to/transcript.json"
}

常見輸出格式

鉤子可以透過 stdout 回傳 JSON 來影響代理行為。所有鉤子都支援這些輸出欄位：

{
  "continue": true,
  "stopReason": "Security policy violation",
  "systemMessage": "Unit tests failed"
}

結束代碼 (Exit codes)

鉤子的結束代碼決定了 VS Code 如何處理結果。

選擇回傳資料的方式

鉤子有幾種控制代理行為的方式：結束代碼、頂層輸出欄位 (continue, stopReason) 以及鉤子特定的輸出欄位 (hookSpecificOutput)。請依下列方式組合使用：

• 結束代碼 2 是封鎖操作最簡單的方法。鉤子的 stderr 會作為內容顯示給模型。不需要 JSON 輸出。
• JSON 輸出中的 continue: false 會停止整個代理工作階段。使用 stopReason 告知使用者原因。這比封鎖單一工具呼叫更為嚴厲。
• hookSpecificOutput 提供針對每個鉤子事件的精細控制。例如，PreToolUse 鉤子使用 permissionDecision 來允許、拒絕或要求確認單一工具呼叫，而無需停止工作階段。
• systemMessage 無論其他決定為何，都會在聊天中向使用者顯示警告。

當多種控制機制同時使用時，限制最嚴格的機制會勝出。例如，如果一個鉤子回傳 continue: false 和 permissionDecision: "allow"，工作階段仍然會停止。

PreToolUse (工具使用前)

PreToolUse 鉤子會在代理呼叫工具之前觸發。

PreToolUse 輸入

除了常見欄位外，PreToolUse 鉤子還會接收：

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

PreToolUse 輸出

PreToolUse 鉤子可以透過 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"
  }
}

權限決定優先順序：當多個鉤子針對同一個工具呼叫執行時，限制最嚴格的決定勝出：

1. deny（最嚴格）：封鎖工具執行
2. ask：要求使用者確認
3. allow（限制最少）：自動核准執行

updatedInput 格式：若要判斷 updatedInput 的格式，請開啟代理記錄檔並找到記錄的工具結構描述 (Schema)。如果 updatedInput 不符合預期的結構描述，將會被忽略。

PostToolUse (工具使用後)

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

PostToolUse 輸入

除了常見欄位外，PostToolUse 鉤子還會接收：

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

PostToolUse 輸出

PostToolUse 鉤子可以為模型提供額外內容，或封鎖後續處理。

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

UserPromptSubmit (使用者提交提示)

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

UserPromptSubmit 輸入

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

UserPromptSubmit 鉤子僅使用常見輸出格式。

SessionStart (工作階段開始)

SessionStart 鉤子會在新的代理工作階段開始時觸發。

SessionStart 輸入

除了常見欄位外，SessionStart 鉤子還會接收：

{
  "source": "new"
}

SessionStart 輸出

SessionStart 鉤子可以將額外內容注入到代理的對話中。

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

Stop (停止)

Stop 鉤子會在代理工作階段結束時觸發。當針對自訂代理時，Stop 鉤子也會被視為 SubagentStop。

Stop 輸入

除了常見欄位外，Stop 鉤子還會接收：

{
  "stop_hook_active": false
}

Stop 輸出

Stop 鉤子可以防止代理停止。

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

SubagentStart (子代理開始)

SubagentStart 鉤子會在子代理被生成時觸發。

SubagentStart 輸入

除了常見欄位外，SubagentStart 鉤子還會接收：

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

SubagentStart 輸出

SubagentStart 鉤子可以將額外內容注入到子代理的對話中。

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

SubagentStop (子代理停止)

SubagentStop 鉤子會在子代理完成時觸發。

SubagentStop 輸入

除了常見欄位外，SubagentStop 鉤子還會接收：

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

SubagentStop 輸出

SubagentStop 鉤子可以防止子代理停止。

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

PreCompact (壓縮前)

PreCompact 鉤子會在對話內容被壓縮前觸發。

PreCompact 輸入

除了常見欄位外，PreCompact 鉤子還會接收：

{
  "trigger": "auto"
}

PreCompact 鉤子僅使用常見輸出格式。

透過 UI 設定鉤子

您可以透過互動式 UI 以幾種方式設定鉤子：

• 在聊天輸入框輸入 /hooks 並按下 Enter。
• 開啟命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）並執行 Chat: Configure Hooks。
• 選取聊天視圖頂部的 設定 圖示 ()，然後選取 Hooks。

在設定鉤子選單中：

1. 從清單中選取鉤子事件類型。

2. 選擇現有的鉤子進行編輯，或選取 Add new hook 建立一個。

3. 選取或建立鉤子設定檔。

該指令會在編輯器中開啟鉤子檔案，並將游標定位在指令欄位，準備進行編輯。

用 AI 產生鉤子

您可以使用 AI 來產生鉤子設定。在聊天中輸入 /create-hook 並描述您想要的自動化功能（例如：「在每次檔案編輯後執行 ESLint」）。代理會詢問澄清問題，並產生具有適當事件類型、指令和設定的鉤子設定檔。

使用情境

以下範例示範了常見的鉤子模式。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/block-dangerous.sh",
        "timeoutSec": 5
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input')

if [ "$TOOL_NAME" = "runTerminalCommand" ]; then
  COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // empty')

  if echo "$COMMAND" | grep -qE '(rm\s+-rf|DROP\s+TABLE|DELETE\s+FROM)'; then
    echo '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Destructive command blocked by security policy"}}'
    exit 0
  fi
fi

echo '{"continue":true}'

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "./scripts/format-changed-files.sh",
        "windows": "powershell -File scripts\\format-changed-files.ps1",
        "timeout": 30
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "editFiles" ] || [ "$TOOL_NAME" = "createFile" ]; then
  FILES=$(echo "$INPUT" | jq -r '.tool_input.files[]? // .tool_input.path // empty')

  for FILE in $FILES; do
    if [ -f "$FILE" ]; then
      npx prettier --write "$FILE" 2>/dev/null
    fi
  done
fi

echo '{"continue":true}'

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/log-tool-use.sh",
        "env": {
          "AUDIT_LOG": ".github/hooks/audit.log"
        }
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
SESSION_ID=$(echo "$INPUT" | jq -r '.sessionId')

echo "[$TIMESTAMP] Session: $SESSION_ID, Tool: $TOOL_NAME" >> "${AUDIT_LOG:-audit.log}"
echo '{"continue":true}'

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/require-approval.sh"
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

# Tools that should always require approval
SENSITIVE_TOOLS="runTerminalCommand|deleteFile|pushToGitHub"

if echo "$TOOL_NAME" | grep -qE "^($SENSITIVE_TOOLS)$"; then
  echo '{"hookSpecificOutput":{"permissionDecision":"ask","permissionDecisionReason":"This operation requires manual approval"}}'
else
  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
fi

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "./scripts/inject-context.sh"
      }
    ]
  }
}

#!/bin/bash
PROJECT_INFO=$(cat package.json 2>/dev/null | jq -r '.name + " v" + .version' || echo "Unknown project")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project: $PROJECT_INFO | Branch: $BRANCH | Node: $(node -v 2>/dev/null || echo 'not installed')"
  }
}
EOF

安全性

如果代理有權編輯鉤子執行的指令碼，那麼它就有能力在自己的執行過程中修改這些指令碼，並執行它所寫的程式碼。我們建議使用 chat.tools.edits.autoApprove 來禁止代理在未經手動核准的情況下編輯鉤子指令碼。

疑難排解

檢視鉤子診斷資訊

若要查看已載入哪些鉤子並檢查設定錯誤：

1. 選取 View Logs 以檢視所有記錄檔。

2. 搜尋 "Load Hooks" 以查看已載入的鉤子以及它們載入的位置。

檢視鉤子輸出

若要檢閱鉤子輸出與錯誤：

1. 開啟 Output 面板。

2. 從頻道清單中選取 GitHub Copilot Chat Hooks。

常見問題

鉤子未執行：驗證鉤子檔案是否位於 .github/hooks/ 並具有 .json 副檔名。檢查 type 屬性是否設為 "command"。

權限被拒錯誤：確保您的鉤子指令碼具有執行權限 (chmod +x script.sh)。

逾時錯誤：增加 timeout 值或最佳化您的鉤子指令碼。預設值為 30 秒。

JSON 解析錯誤：驗證您的鉤子指令碼是否輸出有效的 JSON 到 stdout。使用 jq 或 JSON 程式庫來建構輸出。

常見問題

VS Code 如何處理 Claude Code 鉤子設定？

VS Code 預設會從 .claude/settings.json、.claude/settings.local.json 和 ~/.claude/settings.json 讀取鉤子設定。VS Code 會解析 Claude Code 的鉤子設定格式，包括 Matcher 語法。目前，VS Code 會忽略 Matcher 值，因此鉤子會在所有工具呼叫時執行，而不管 Matcher 為何。

如果您要將 Claude Code 鉤子調整為 VS Code 使用，請注意下列差異：

• 工具輸入屬性名稱：Claude Code 使用 snake_case 作為工具輸入屬性（例如 tool_input.file_path），而 VS Code 工具使用 camelCase（例如 tool_input.filePath）。請更新您的鉤子指令碼以讀取正確的屬性名稱。
• 工具名稱：Claude Code 和 VS Code 使用不同的工具名稱。例如，Claude Code 對檔案操作使用 Write 和 Edit，而 VS Code 使用如 create_file 和 replace_string_in_file 等工具名稱。請檢查 tool_name 輸入欄位中的工具名稱，並據此更新您的鉤子邏輯。
• Matchers 被忽略：如 "Edit|Write" 等鉤子 Matchers 會被解析但不會被套用。所有鉤子都會在每個匹配事件上執行，而不管 Matcher 中的工具名稱為何。

VS Code 如何處理 Copilot CLI 鉤子設定？

VS Code 會解析 Copilot CLI 鉤子設定，並將 lowerCamelCase 鉤子事件名稱（如 preToolUse）轉換為 VS Code 使用的 PascalCase 格式 (PreToolUse)。bash 和 powershell 指令屬性會對應至作業系統專用指令：powershell 對應至 windows，而 bash 對應至 osx 和 linux。

安全性考量

• 審查鉤子指令碼：在啟用鉤子指令碼之前進行檢查，特別是在共用儲存庫中。

• 限制鉤子權限：使用最小權限原則。鉤子應該只能存取它們所需要的內容。

• 驗證輸入：鉤子指令碼會從代理接收輸入。請驗證並清理所有輸入，以防止注入攻擊。

• 保護憑證：切勿將秘密資訊硬編碼在鉤子指令碼中。請使用環境變數或安全憑證儲存庫。

相關資源

• 與代理一起使用工具 - 了解工具核准與執行
• 自訂代理 - 建立專業的代理設定
• 子代理 - 將任務委派給內容隔離的子代理
• 安全性考量 - VS Code 中 AI 安全性的最佳實作