Hook 扩展¶

本文你会学到：

• 🪝 Hook 是什么，解决什么问题
• ⏱️ 生命周期事件及其阻塞/非阻塞行为
• 🛠️ 如何编写和配置 Hook
• 📋 Payload 格式与决策控制机制
• 🏢 组织级安全策略的完整教程
• ⚖️ Hook 与 Git Hook 的区别
• ⚙️ 高级特性（Prompt Hook、HTTP Hook）与已知限制

打个比方：Hook 就像是你给 Copilot 安装的自动感应器——在特定时刻（会话开始、工具调用前后、出错时）自动触发你预设的操作。比如，每次 Copilot 修改文件后自动运行格式化工具，每次会话结束时自动记录日志。

❓ 为什么需要 Hook？¶

没有 Hook 的情况下，Copilot 的行为只能通过 prompt 和指令来间接影响。但有些操作需要强制执行——比如"每次写完代码必须格式化"或"出错时必须通知我"。这些需求超出了 prompt 控制的范围，Hook 正是为此而生。

⏱️ 生命周期事件¶

🛠️ 创建 Hook¶

在仓库的 .github/hooks/ 文件夹中创建 JSON 文件（文件名可自由选择，建议用功能命名如 format.json、notify.json）：

除了仓库级 Hook，还有其他几种存放位置（1.0.8 / 1.0.11 新增）：

多个来源的 Hook 会合并而非覆盖（1.0.11 改进），sessionStart Hook 的 additionalContext 字段内容会注入到对话上下文中。

如需在某个项目中临时禁用所有 Hook，在配置中设置 disableAllHooks: true（1.0.4 新增）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

[
  {
    "event": "sessionStart",
    "steps": [
      {
        "command": "echo \"Session started at $(date)\" >> /tmp/copilot-sessions.log"
      }
    ]
  },
  {
    "event": "sessionEnd",
    "steps": [
      {
        "command": "echo \"Session ended at $(date)\" >> /tmp/copilot-sessions.log"
      }
    ]
  }
]

📋 Hook 配置字段¶

每个 Hook 是一个 JSON 数组，数组中的每个对象代表一条规则。当对应的 event 被触发时，steps 中的命令会按顺序依次执行。

💡 1.0.24 改进：preToolUse Hook 的 stdout 输出现在支持 modifiedArgs/updatedInput（修改工具调用参数）和 additionalContext（注入额外上下文）字段，Hook 可以动态调整工具行为而无需用户介入。

⚠️ 注意：command 中的命令会在当前项目根目录下执行。如果命令执行失败（非零退出码），后续步骤仍会继续执行——Hook 不会因为某一步失败而中断整个流程。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[
  {
    "event": "postToolUse",
    "matcher": {
      "tool_name": "edit_file"
    },
    "hooks": [
      {
        "steps": [{ "command": "npm run lint --fix $FILEPATH" }]
      }
    ]
  }
]

💡 实战示例¶

工具调用后运行脚本¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
  {
    "event": "postToolUse",
    "steps": [
      {
        "command": "bash .github/hooks/scripts/post-tool.sh"
      }
    ]
  }
]

自动格式化代码¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
  {
    "event": "postToolUse",
    "steps": [
      {
        "command": "npx prettier --write '**/*.{ts,tsx,js,jsx}' 2>/dev/null || true"
      }
    ]
  }
]

错误时发送通知¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
  {
    "event": "errorOccurred",
    "steps": [
      {
        "command": "echo '[Copilot Error]' | mail -s 'Copilot Error Alert' dev@example.com"
      }
    ]
  }
]

1

chmod +x .github/hooks/your-script.sh

⚖️ Hook vs Git Hook¶

你可能已经熟悉 Git Hook（如 pre-commit），Copilot Hook 和它类似但作用于不同层面：

两者可以互补：Git Hook 确保提交质量，Copilot Hook 增强 AI 辅助体验。

📋 Payload 格式与决策控制¶

两种 Payload 格式¶

每个 Hook 事件都会向 Hook 处理程序传递 JSON payload。通过配置中使用的**事件名格式**来选择 payload 格式：

两种格式可以共存于同一配置文件中，不同事件可以使用不同格式。

preToolUse 决策控制¶

preToolUse Hook 可以通过 stdout 输出 JSON 来控制工具的执行行为：

1
2
3
4

{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Privilege escalation requires manual approval."
}

1
2
3
4

{
  "permissionDecision": "allow",
  "modifiedArgs": { "command": "git status" }
}

如果配置了多个 preToolUse Hook，它们按顺序执行。任意一个 Hook 返回 "deny" 即会阻止工具执行。

permissionRequest 决策控制¶

permissionRequest 在权限服务运行之前触发——早于规则检查、会话审批、自动允许/拒绝和用户提示。如果 Hook 返回 behavior: "allow" 或 "deny"，将**短路整个权限流程**，后续步骤不再执行。返回空输出则回退到正常的权限处理流程。

支持可选的 matcher 正则表达式，仅对匹配 toolName 的请求触发 Hook（锚定为 ^(?:pattern)$）。

对于 command hooks，退出码 2 等同于 deny——stdout JSON（如有）会与 {"behavior":"deny"} 合并，stderr 被忽略。

read 和 hook 权限类型会在 Hook 之前短路，不会触发 permissionRequest。

agentStop / subagentStop 决策控制¶

这两个事件可以阻止 Agent 结束，强制其继续执行：

1
2
3
4

{
  "decision": "block",
  "reason": "Please verify all test cases pass before finishing."
}

notification Hook¶

notification Hook 是异步 fire-and-forget 的，永远不会阻塞会话。通过可选的 matcher 正则表达式匹配 notification_type（锚定为 ^(?:pattern)$）。

通知类型：

输出控制： 可通过 additionalContext 字段向会话注入文本（作为前置用户消息），如果会话处于空闲状态则触发 Agent 继续处理。

🏢 组织级策略教程¶

以下内容面向 DevOps 工程师、平台团队和工程负责人，展示如何通过 Hook 为团队建立安全合规的 Copilot CLI 使用策略。

策略定义流程¶

在编写任何 Hook 脚本之前，先明确哪些操作应自动放行、哪些需要人工审查。

识别高风险命令：

决定日志策略：

• 全量日志：记录所有 prompt 和工具调用，适合合规要求严格的组织
• 仅高风险日志：只记录被拒绝的操作和敏感工具调用，减少存储开销
• 日志中**禁止**包含明文密钥或凭证，必须脱敏后再写入

与利益相关者对齐：

• 安全/合规团队：确认风险边界
• 平台/基础设施团队：确认是否需要更宽泛的权限
• 开发团队：让开发者理解什么会被阻止以及为什么

策略横幅示例¶

通过 sessionStart Hook 在每次会话启动时显示策略提醒。

Bash 脚本（.github/hooks/scripts/session-banner.sh）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#!/bin/bash
set -euo pipefail

cat << 'EOF'
COPILOT CLI POLICY ACTIVE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Prompts and tool use may be logged for auditing
• High-risk commands may be blocked automatically
• If something is blocked, follow the guidance shown
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EOF
exit 0

PowerShell 脚本（.github/hooks/scripts/session-banner.ps1）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ErrorActionPreference = "Stop"

Write-Host @"
COPILOT CLI POLICY ACTIVE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Prompts and tool use may be logged for auditing
• High-risk commands may be blocked automatically
• If something is blocked, follow the guidance shown
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"@
exit 0

Hook 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "./scripts/session-banner.sh",
        "powershell": "./scripts/session-banner.ps1",
        "cwd": ".github/hooks",
        "timeoutSec": 10
      }
    ]
  }
}

提示词日志记录¶

通过 userPromptSubmitted Hook 记录用户提交的 prompt，用于审计和合规。

Bash 脚本（.github/hooks/scripts/log-prompt.sh）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#!/bin/bash
set -euo pipefail

INPUT="$(cat)"

TIMESTAMP_MS="$(echo "$INPUT" | jq -r '.timestamp // empty')"
CWD="$(echo "$INPUT" | jq -r '.cwd // empty')"

LOG_DIR=".github/hooks/logs"
mkdir -p "$LOG_DIR"
chmod 700 "$LOG_DIR"

# 仅记录元数据，避免存储敏感数据
jq -n \
  --arg ts "$TIMESTAMP_MS" \
  --arg cwd "$CWD" \
  '{event:"userPromptSubmitted", timestampMs:$ts, cwd:$cwd}' \
  >> "$LOG_DIR/audit.jsonl"

exit 0

PowerShell 脚本（.github/hooks/scripts/log-prompt.ps1）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

$ErrorActionPreference = "Stop"

$inputObj = [Console]::In.ReadToEnd() | ConvertFrom-Json

$timestampMs = $inputObj.timestamp
$cwd = $inputObj.cwd
$prompt = $inputObj.prompt

# 脱敏：将敏感 token 替换为占位符
$redactedPrompt = $prompt -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]'
$redactedPrompt = $redactedPrompt -replace 'Bearer [A-Za-z0-9_\-\.]+', 'Bearer [REDACTED]'

$logDir = ".github/hooks/logs"
if (-not (Test-Path $logDir)) {
  New-Item -ItemType Directory -Path $logDir -Force | Out-Null
}

$logEntry = @{
  event       = "userPromptSubmitted"
  timestampMs = $timestampMs
  cwd         = $cwd
  prompt      = $redactedPrompt
} | ConvertTo-Json -Compress

Add-Content -Path "$logDir/audit.jsonl" -Value $logEntry
exit 0

Prompt 可能包含敏感信息。记录前必须进行脱敏处理，并遵循组织的数据处理和保留策略。

工具使用策略¶

通过 preToolUse Hook 在工具执行前评估策略，阻止高风险操作。

完整 Bash 策略脚本（.github/hooks/scripts/pre-tool-policy.sh）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

#!/bin/bash
set -euo pipefail

INPUT="$(cat)"

TOOL_NAME="$(echo "$INPUT" | jq -r '.toolName // empty')"
TOOL_ARGS_RAW="$(echo "$INPUT" | jq -r '.toolArgs // empty')"

LOG_DIR=".github/hooks/logs"
mkdir -p "$LOG_DIR"

# 脱敏：替换敏感模式
REDACTED_TOOL_ARGS="$(echo "$TOOL_ARGS_RAW" | \
  sed -E 's/ghp_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \
  sed -E 's/gho_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \
  sed -E 's/ghu_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \
  sed -E 's/ghs_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \
  sed -E 's/Bearer [A-Za-z0-9_\-\.]+/Bearer [REDACTED]/g' | \
  sed -E 's/--password[= ][^ ]+/--password=[REDACTED]/g' | \
  sed -E 's/--token[= ][^ ]+/--token=[REDACTED]/g')"

# 记录工具使用日志
jq -n \
  --arg tool "$TOOL_NAME" \
  --arg toolArgs "$REDACTED_TOOL_ARGS" \
  '{event:"preToolUse", toolName:$tool, toolArgs:$toolArgs}' \
  >> "$LOG_DIR/audit.jsonl"

# 仅对 bash 工具执行策略规则
if [ "$TOOL_NAME" != "bash" ]; then
  exit 0
fi

if ! echo "$TOOL_ARGS_RAW" | jq -e . >/dev/null 2>&1; then
  exit 0
fi

COMMAND="$(echo "$TOOL_ARGS_RAW" | jq -r '.command // empty')"

deny() {
  local reason="$1"
  local redacted_cmd="$(echo "$COMMAND" | \
    sed -E 's/ghp_[A-Za-z0-9]{20,}/[REDACTED_TOKEN]/g' | \
    sed -E 's/Bearer [A-Za-z0-9_\-\.]+/Bearer [REDACTED]/g' | \
    sed -E 's/--password[= ][^ ]+/--password=[REDACTED]/g' | \
    sed -E 's/--token[= ][^ ]+/--token=[REDACTED]/g')"

  jq -n \
    --arg cmd "$redacted_cmd" \
    --arg r "$reason" \
    '{event:"policyDeny", toolName:"bash", command:$cmd, reason:$r}' \
    >> "$LOG_DIR/audit.jsonl"

  jq -n \
    --arg r "$reason" \
    '{permissionDecision:"deny", permissionDecisionReason:$r}'
  exit 0
}

# 提权操作
if echo "$COMMAND" | grep -qE '\b(sudo|su|runas)\b'; then
  deny "Privilege escalation requires manual approval."
fi

# 针对根目录的破坏性操作
if echo "$COMMAND" | grep -qE 'rm\s+-rf\s*/($|\s)|rm\s+.*-rf\s*/($|\s)'; then
  deny "Destructive operations targeting the filesystem root require manual approval."
fi

# 系统级破坏性操作
if echo "$COMMAND" | grep -qE '\b(mkfs|dd|format)\b'; then
  deny "System-level destructive operations are not allowed via automated execution."
fi

# 下载执行模式
if echo "$COMMAND" | grep -qE 'curl.*\|\s*(bash|sh)|wget.*\|\s*(bash|sh)'; then
  deny "Download-and-execute patterns require manual approval."
fi

# 默认允许
exit 0

完整 PowerShell 策略脚本（.github/hooks/scripts/pre-tool-policy.ps1）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

$ErrorActionPreference = "Stop"

$inputObj = [Console]::In.ReadToEnd() | ConvertFrom-Json
$toolName = $inputObj.toolName
$toolArgsRaw = $inputObj.toolArgs

$logDir = ".github/hooks/logs"
if (-not (Test-Path $logDir)) { New-Item -ItemType Directory -Path $logDir -Force | Out-Null }

# 脱敏
$redactedToolArgs = $toolArgsRaw `
  -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `
  -replace 'gho_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `
  -replace 'ghu_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `
  -replace 'ghs_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `
  -replace 'Bearer [A-Za-z0-9_\-\.]+', 'Bearer [REDACTED]' `
  -replace '--password[= ][^ ]+', '--password=[REDACTED]' `
  -replace '--token[= ][^ ]+', '--token=[REDACTED]'

(@{
  event    = "preToolUse"
  toolName = $toolName
  toolArgs = $redactedToolArgs
} | ConvertTo-Json -Compress) | Add-Content -Path "$logDir/audit.jsonl"

if ($toolName -ne "bash") { exit 0 }

$toolArgs = $null
try { $toolArgs = $toolArgsRaw | ConvertFrom-Json } catch { exit 0 }

$command = $toolArgs.command

function Deny([string]$reason) {
  $redactedCommand = $command `
    -replace 'ghp_[A-Za-z0-9]{20,}', '[REDACTED_TOKEN]' `
    -replace 'Bearer [A-Za-z0-9_\-\.]+', 'Bearer [REDACTED]' `
    -replace '--password[= ][^ ]+', '--password=[REDACTED]' `
    -replace '--token[= ][^ ]+', '--token=[REDACTED]'

  (@{
    event    = "policyDeny"
    toolName = "bash"
    command  = $redactedCommand
    reason   = $reason
  } | ConvertTo-Json -Compress) | Add-Content -Path "$logDir/audit.jsonl"

  (@{
    permissionDecision = "deny"
    permissionDecisionReason = $reason
  } | ConvertTo-Json -Compress)

  exit 0
}

if ($command -match '\b(sudo|su|runas)\b') { Deny "Privilege escalation requires manual approval." }
if ($command -match 'rm\s+-rf\s*/(\s|$)|rm\s+.*-rf\s*/(\s|$)') { Deny "Destructive operations targeting the filesystem root require manual approval." }
if ($command -match '\b(mkfs|dd|format)\b') { Deny "System-level destructive operations are not allowed via automated execution." }
if ($command -match 'curl.*\|\s*(bash|sh)|wget.*\|\s*(bash|sh)') { Deny "Download-and-execute patterns require manual approval." }

exit 0

端到端测试¶

完成配置后，在仓库中验证 Hook 行为：

验证配置文件有效性：

1

jq '.' < .github/hooks/copilot-cli-policy.json

Unix 系统设置脚本执行权限：

1

chmod +x .github/hooks/scripts/*.sh

运行基本会话测试：

1

copilot -p "Show me the status of this repository"

预期结果：显示策略横幅，audit.jsonl 中出现 userPromptSubmitted 记录。

测试工具调用日志：

1

copilot -p "Show me the last 5 git commits"

预期结果：audit.jsonl 中出现 preToolUse 记录。

查看审计日志：

1
2
3
4
5

# 查看最近 50 条
tail -n 50 .github/hooks/logs/audit.jsonl

# 筛选被拒绝的操作
jq 'select(.event=="policyDeny")' .github/hooks/logs/audit.jsonl

推出策略¶

验证通过后，按以下策略逐步推广：

日志先行（推荐）： 先只记录日志不拒绝执行，观察一段时间了解常见使用模式后再引入拒绝规则。

逐团队推广： 先在一个团队或仓库部署，收集反馈后再扩展到其他团队。

基于风险推广： 从处理敏感系统或生产基础设施的仓库开始，再扩展到低风险仓库。

沟通期望： 确保开发者知道 Hook 已激活、哪些命令可能被阻止、被拒绝后如何处理。

持续维护： 将 Hook 配置和脚本纳入版本控制，定期审查审计日志，增量更新拒绝规则，为每条规则记录存在原因。

⚙️ 高级特性与限制¶

Prompt Hook¶

type: "prompt" 类型的 Hook 可以自动提交文本，就像用户输入一样。仅在 sessionStart 事件上支持，且仅对新交互式会话触发——不会在恢复会话或非交互模式（-p）下触发。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

prompt 字段支持自然语言消息或斜杠命令。

HTTP Hooks¶

在 Hook 配置中使用 url 字段（1.0.35 新增），Hook 会将 JSON payload POST 到指定的远程端点，无需编写本地脚本中转。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "url": "https://your-webhook.example.com/copilot-hook",
        "timeoutSec": 30
      }
    ]
  }
}

这种方式特别适合：无服务器架构、集中管理 Hook 响应、转发事件到 Slack 通知或自定义 API。

已知限制¶