Cấu hình agent hook trong VS Code

Hook chạy hành động tuỳ biến tại các thời điểm cụ thể trong vòng đời của agent, dùng để tự động hoá quy trình (workflow), kiểm tra thao tác, ghi audit trail hoặc áp chính sách mà không phụ thuộc model. Bài này tóm tắt cách chọn đúng cơ chế hook, quản lý hook trong VS Code và cấu hình hook cho harness Local.

Chọn cơ chế hook theo session

Agent harness được chọn qua control Session Target quyết định hook nào chạy; harness sở hữu vòng đời và payload của hook. Agent Host là tiến trình chạy các harness Copilot, Claude và Codex; harness Local chạy trong extension host. Chat view và Agents window chỉ là client hiển thị và điều khiển session.

Một số harness cùng đọc một file hook (như .github/hooks/*.json hay .claude/settings.json), nhưng hành vi không giống nhau: sự kiện, tên sự kiện, matcher, thuộc tính lệnh, tên tool, payload và quyết định output đều có thể khác. Session Copilot trên Agent Host dùng cùng cơ chế SDK với Copilot CLI; dùng phần Copilot CLI trong tài liệu GitHub nhưng kiểm tra sự kiện có trong phiên bản VS Code của bạn không.

Chuyển hook giữa các harness

Trước khi đổi session target cho quy trình có sẵn:

• Xác nhận harness đích có tìm thấy file hook.
• So sánh sự kiện và thuộc tính lệnh được hỗ trợ.
• Kiểm tra tên tool và dạng input trước khi dùng lại bộ lọc hay logic kiểm tra.
• Kiểm tra script đọc transcript chat; định dạng transcript không phải API ổn định giữa các harness.
• Thử các quyết định output, như chặn lời gọi tool hay thêm ngữ cảnh (context).
• Xác nhận lệnh hook chạy ở đâu và truy cập được file, biến môi trường nào.

Đừng kiểm chứng việc chuyển chỉ bằng cách đổi model; hãy chọn harness đích trong Session Target và chạy session thử.

Tạo và quản lý hook

Chọn session target trước, để VS Code hiện customization của đúng harness. Sau đó mở Agent Customizations editor: trong Chat view chọn Configure Chat (bánh răng) rồi Hooks; trong Agents window chọn Hooks ở panel Customizations; hoặc gõ /hooks trong chat. Chọn một hook để mở cấu hình.

Lệnh Chat: Configure Hooks trong Command Palette quản lý file hook của Local. Để sinh hook bằng AI, gõ /create-hook <description> hoặc chạy Chat: Generate Hook; hook sinh ra nằm trong .github/hooks/, nhớ đối chiếu với tài liệu của harness đích trước khi dùng.

Hook cho harness Local

Phần còn lại chỉ áp cho harness Local; sự kiện, setting, payload và output ở đây không tự áp cho session Copilot, Claude hay Codex trên Agent Host.

Hook đầu tiên

Hook sau ghi tên mọi tool trước khi agent Local gọi. Tạo .github/hooks/audit.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "node .github/hooks/log-tool-use.cjs"
      }
    ]
  }
}

Và .github/hooks/log-tool-use.cjs:

const fs = require('node:fs');

let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
  const event = JSON.parse(input);
  fs.appendFileSync(
    '.github/hooks/tool-use.log',
    `${event.timestamp} ${event.tool_name}\n`
  );
});

Chạy một session Local có dùng tool, mỗi tên tool sẽ được ghi vào .github/hooks/tool-use.log (thêm file này vào .gitignore nếu không muốn commit). Ví dụ này cũng giúp bạn biết chính xác tên tool của Local để dùng trong hook kiểm tra, vì tên và tham số tool khác nhau giữa các harness.

Vị trí file hook

Setting chat.useHooks (mặc định bật) điều khiển việc chạy hook Local; file hook trong workspace chịu Workspace Trust. Dùng chat.hookFilesLocations để thêm hoặc tắt vị trí (giá trị mặc định rỗng vì vị trí có sẵn được đăng ký riêng):

"chat.hookFilesLocations": {
  "custom/hooks": true,              // Load all JSON hook files in this folder.
  "~/my-hooks/security.json": true,  // Load one hook file.
  ".claude/settings.json": false     // Disable a built-in location.
}

Trong monorepo, bật chat.useCustomizationsInParentRepositories để tìm hook từ gốc repo cha.

Định dạng cấu hình

Hook Local mới nên dùng JSON với tên sự kiện và thuộc tính lệnh dạng PascalCase:

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

Parser của Local còn nhận:

• Định dạng gốc VS Code: sự kiện PascalCase, không có thuộc tính số version; dùng command, windows, linux, osx, timeout.
• Định dạng Copilot: có version dạng số và sự kiện lower camel case; được ánh xạ sang định dạng Local, payload lúc chạy vẫn theo schema Local.
• Định dạng Claude: file settings.json hoặc settings.local.json trong thư mục .claude; cần chat.useClaudeHooks. Local đọc lệnh lồng nhau nhưng bỏ qua matcher, nên mọi lệnh của sự kiện đều chạy.

Lệnh override theo hệ điều hành được chọn theo nền tảng của extension host; trong cửa sổ Remote Development, nền tảng này có thể khác hệ điều hành đang hiển thị giao diện VS Code.

Sự kiện vòng đời

Khi sự kiện xảy ra, Local truyền một object JSON vào lệnh qua stdin; lệnh có thể ghi JSON ra stdout để thêm ngữ cảnh hoặc điều khiển bước tiếp theo. Sự kiện không nhất thiết trùng với lúc kết thúc toàn bộ session. Chi tiết input, output và exit code ở Local hooks reference.

Hook theo agent

Hook theo agent (Preview, chỉ Local) là map hooks trong frontmatter custom agent, chỉ chạy khi agent đó hoạt động, cộng thêm vào hook user, workspace và plugin:

---
name: Strict Formatter
description: Format code after the agent uses a tool
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

Follow the project's formatting requirements.

Khi agent chạy làm sub-agent, hook Stop của nó được coi là SubagentStop. Cần chat.useHooks và workspace được tin cậy. Với agent từ plugin định dạng Claude hoặc OpenPlugin cũ, dùng plugin-root tokens để trỏ tới script đi kèm.

Ví dụ khác trong nguồn

• Xin phê duyệt cho một tool: hook PreToolUse truyền tên tool nhạy cảm qua env (SENSITIVE_TOOL_NAME); script trả hookSpecificOutput với permissionDecision: 'ask' nếu trùng tên, ngược lại trả { continue: true }. Dùng đúng tên tool của Local, không chép từ harness khác.
• Thêm ngữ cảnh khi session bắt đầu: hook SessionStart ghi ra stdout hookSpecificOutput có additionalContext chứa tên và phiên bản từ package.json.

Xử lý sự cố

Trước hết xác nhận session target khớp với tài liệu hook bạn làm theo. Với hook Local:

• Chạy Chat: Configure Hooks để xem file nào được tìm thấy.
• Mở agent debug logs để xem tên sự kiện, schema tool, input và output của hook.
• Mở panel Output, chọn kênh GitHub Copilot Chat Hooks để xem output và lỗi của lệnh.
• Kiểm tra chat.useHooks đã bật và workspace được tin cậy; với file định dạng Claude, bật chat.useClaudeHooks và nhớ Local bỏ qua matcher.
• Chỉ tăng timeout khi đã chắc lệnh đang chạy tiến triển.

Với harness trên Agent Host, dùng tài liệu và công cụ chẩn đoán của nhà cung cấp; các setting chat.useHooks, chat.hookFilesLocations, chat.useClaudeHooks không cấu hình hook của Copilot, Claude hay Codex.

Bảo mật

• Coi cấu hình hook và script là code thực thi.
• Yêu cầu phê duyệt trước khi agent sửa script mà hook sau đó sẽ chạy.
• Kiểm tra mọi input JSON trước khi đưa giá trị vào lệnh shell.
• Chỉ cấp cho lệnh hook quyền file, tiến trình và mạng thật sự cần.
• Lưu credential ở kho bí mật được phê duyệt, không đặt trong cấu hình hook, script, output hay ngữ cảnh agent.
• Xem mô hình tin cậy và chính sách của harness được chọn; các kiểm soát này không mang sang runtime khác được.

Tài liệu liên quan

• Local hooks reference
• Choose and use an agent harness
• Security considerations for AI agents

Nguồn

• Tóm tắt từ https://raw.githubusercontent.com/microsoft/vscode-docs/main/docs/agent-customization/hooks.md, giấy phép CC-BY-3.0-US.