Visual Studio Code 中的代理程式掛鉤 (預覽)

掛鉤讓您能夠在代理程式會話的關鍵生命週期點執行自訂 shell 命令。使用掛鉤來自動化工作流程、強制執行安全策略、驗證操作並與外部工具整合。

有關掛鉤如何融入 AI 自訂框架的背景資訊，請參閱 自訂概念。

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

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

為何要使用掛鉤？

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

• 強制執行安全性策略：在危險命令（例如 rm -rf 或 DROP TABLE）執行之前阻止它們，無論代理程式是如何被提示的。

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

• 建立稽核追蹤：記錄每次工具呼叫、命令執行或檔案變更，以符合法規並進行偵錯。

• 注入上下文：新增專案特定資訊、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
}

代理程式作用域掛鉤

您可以在 自訂代理程式 的 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.

掛鉤設定格式

建立一個 JSON 檔案，其中包含一個 hooks 物件，該物件針對每個事件類型包含掛鉤命令的陣列。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"
      }
    ]
  }
}

執行服務會根據您的作業系統選擇適當的命令。如果未定義作業系統專用命令，它會回退到 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"
}

結束代碼

掛鉤的結束代碼決定 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 的格式，請開啟 代理程式日誌 並找到已記錄的工具綱要。如果 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 掛鉤僅使用通用輸出格式。

使用使用者介面設定掛鉤

您可以透過多種方式透過互動式使用者介面設定掛鉤

• 在聊天輸入中鍵入 /hooks 並按下 Enter。
• 開啟命令選擇區 (⇧⌘P (Windows、Linux Ctrl+Shift+P)) 並執行 聊天：設定掛鉤。
• 選取聊天檢視頂部的設定圖示 ()，然後選取掛鉤。

在設定掛鉤選單中

1. 從清單中選取一個掛鉤事件類型。

2. 選擇一個現有的掛鉤進行編輯，或選取新增掛鉤來建立一個。

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. 選取 檢視日誌 以查看所有日誌。

2. 尋找「載入掛鉤」以查看已載入的掛鉤以及它們從哪些位置載入。

檢視掛鉤輸出

要審查掛鉤輸出和錯誤

1. 開啟輸出面板。

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

常見問題

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

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

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

JSON 解析錯誤：驗證您的掛鉤指令碼向 stdout 輸出有效的 JSON。使用 jq 或 JSON 函式庫來建構輸出。

常見問題

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

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

如果您正在為 VS Code 修改 Claude 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 輸入欄位中的工具名稱，並據此更新您的掛鉤邏輯。
• 匹配器被忽略："Edit|Write" 等掛鉤匹配器會被解析，但不會被套用。所有掛鉤都會在每個匹配事件上執行，無論匹配器中的工具名稱為何。

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

VS Code 會解析 Copilot CLI 掛鉤設定，並將 lowerCamelCase 的掛鉤事件名稱 (例如 preToolUse) 轉換為 VS Code 使用的 PascalCase 格式 (PreToolUse)。bash 和 powershell 命令屬性會映射到作業系統專用命令：powershell 映射到 windows，而 bash 映射到 osx 和 linux。

安全性考量

• 審查掛鉤指令碼：在啟用所有掛鉤指令碼之前仔細檢查它們，尤其是在共用儲存庫中。

• 限制掛鉤權限：使用最小權限原則。掛鉤應僅能存取其所需的內容。

• 驗證輸入：掛鉤指令碼從代理程式接收輸入。驗證並清理所有輸入以防止注入攻擊。

• 安全憑證：切勿在掛鉤指令碼中硬編碼密碼。請使用環境變數或安全憑證儲存。

相關資源

• 搭配代理程式使用工具 - 了解工具批准和執行
• 自訂代理程式 - 建立專用代理程式設定
• 子代理程式 - 將任務委派給上下文隔離的子代理程式
• 安全性考量 - VS Code 中 AI 安全的最佳實務