会话钩子

使用 hooks 可以在 Copilot 会话的各个生命周期节点插入处理。你可以在不修改核心实现的前提下，添加工具执行控制、审计日志、prompt 增强、错误处理等。这与自定义代理定义中的声明式 hooks 以及基于文件的钩子加载是不同的功能。按代理的配置请参考自定义代理。

基于文件的钩子发现

在 hookDirectories 中，可以指定用于发现基于文件的钩子的显式根目录。这仅用于发现，不会授予代理一般性的文件访问权限。即使 enableConfigDiscovery 或 enableFileHooks 被禁用，显式根目录依然可用。相对路径会以指定时生效的 workingDirectory 为基准，仅解析一次。

省略或 null：不改变其他发现来源
[]：仅清除显式指定的 SDK 根目录

钩子来源的禁用设置和 Managed Settings 仍然适用。 enableFileHooks 控制来自仓库的文件钩子（.github/hooks/ 以及受信任仓库设置中的根目录）。它不会禁用显式的 hookDirectories 或 PHP 回调的 hooks。

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

钩子流程

基本使用方式

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '总结 README 的要点');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: '请修复当前的错误，并总结变更点。',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} 在此环境中不被允许",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: '必要时也可以搜索相关文件进行比较。',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: '由于临时的模型错误将进行重试。',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

可用的钩子

Hook	触发时机	主要用途
`onSessionStart`	会话开始（`new` / `resume` / `startup`）	注入初始上下文、覆盖配置
`onUserPromptSubmitted`	用户 prompt 发送时	prompt 增强、模板展开、输入过滤
`onPreToolUse`	工具执行前	允许 / 拒绝 / 需确认、修改参数、抑制输出
`onPostToolUse`	工具执行后	修改结果、脱敏敏感信息、审计日志
`onErrorOccurred`	会话内发生错误时	重试、通知、错误分类
`onSessionEnd`	会话结束时	清理、指标、结束摘要

返回 null 时会继续默认行为。单独的会话在完成对 prompt 的响应后不会结束。onSessionEnd 不是在每个 prompt 后执行，而是在会话断开连接或被销毁时执行。

阻止 prompt

onUserPromptSubmitted 可以返回 decision: 'block' 来拒绝 prompt。被拒绝时，不会开始模型轮次，也不会记录用户消息。如果指定了 reason，其内容会包含在 warningType: "policy_blocked" 的临时 session.warning 事件中。

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: '此 prompt 不被允许。',
        );
    }

    return null;
},

典型用例

1) Permission control（执行控制）

通过 onPreToolUse 用 allow-list 方式限制允许的工具
破坏性操作用 permissionDecision: 'ask' 请求人工确认
通过 permissionDecisionReason 明确拒绝理由
toolName 的候选值请参考 Tools 的列表（例如 view、glob、bash）

2) Auditing / compliance（审计）

组合生命周期钩子收集审计事件
按 session ID 单位持久化收集的数据

3) Prompt enrichment（输入增强）

在 onSessionStart 中把项目信息（语言、框架、约定）加入 additionalContext
在 onUserPromptSubmitted 中展开快捷方式（/fix、/test）

4) Result filtering（结果整形）

在 onPostToolUse 中对 API key / token / password 等进行脱敏
对过长的结果进行摘要，仅在需要时返回详细内容

5) Error recovery（故障恢复）

在 onErrorOccurred 中仅在 model_call 且 recoverable=true 时 retry
无法恢复的错误通过 userNotification 向用户简明通知

6) Session metrics（度量）

在 onSessionStart 中记录开始时间
在 onPreToolUse / onUserPromptSubmitted 中更新计数器
在 onSessionEnd 中输出耗时、工具调用次数、结束原因

Hook input / output 类型

共通输入（`BaseHookInput`）

属性	类型	说明
`sessionId`	`string`	相关的运行时会话 ID。子工具的钩子中为子会话 ID，子代理的开始/停止钩子中为父会话 ID
`timestamp`	`int`	钩子触发时间（Unix ms）
`cwd`	`string`	当前工作目录
`agentId`	`?string`	执行钩子的子代理的参与者 ID
`agentType`	`?string`	子代理的类型
`parentAgentId`	`?string`	直接父级参与者 ID

agentId / agentType / parentAgentId 可在以子代理为参与者的钩子中使用。根代理的钩子中不包含这些字段。在旧版运行时中，如果没有相关信息，字段本身会被省略。因此，它们都有可能为 null。

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`PreToolUseHookInput`

属性	类型	说明
`toolName`	`string`	将要执行的工具名
`toolArgs`	`mixed`	将要执行的参数

`PreToolUseHookOutput`

属性	类型	说明
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	拒绝 / 确认时的理由
`modifiedArgs`	`mixed`	覆盖后的参数
`additionalContext`	`?string`	追加的上下文
`suppressOutput`	`?bool`	抑制工具输出

`PostToolUseHookInput`

属性	类型	说明
`toolName`	`string`	已执行的工具名
`toolArgs`	`mixed`	执行时参数
`toolResult`	`ToolResultObject\|array`	工具结果

`PostToolUseHookOutput`

属性	类型	说明
`modifiedResult`	`ToolResultObject\|array\|null`	修改后的结果
`additionalContext`	`?string`	追加的上下文
`suppressOutput`	`?bool`	抑制工具结果显示

`UserPromptSubmittedHookInput`

属性	类型	说明
`prompt`	`string`	用户输入的 prompt

`UserPromptSubmittedHookOutput`

属性	类型	说明
`modifiedPrompt`	`?string`	修改后的 prompt
`additionalContext`	`?string`	补充上下文
`suppressOutput`	`?bool`	抑制响应显示
`decision`	`?string`	为 `block` 时拒绝 prompt，并阻止模型轮次和用户消息的记录
`reason`	`?string`	拒绝理由。包含在 `session.warning` 事件中

`SessionStartHookInput`

属性	类型	说明
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	初始 prompt

`SessionStartHookOutput`

属性	类型	说明
`additionalContext`	`?string`	会话初始上下文
`modifiedConfig`	`?array`	会话配置的部分覆盖

`SessionEndHookInput`

属性	类型	说明
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	最终消息
`error`	`?string`	结束时的错误。运行时传递错误对象时，如果 `message` 是字符串则为该值，否则为对象的 JSON 字符串

`SessionEndHookOutput`

属性	类型	说明
`suppressOutput`	`?bool`	抑制最终输出
`cleanupActions`	`?array`	执行的清理信息
`sessionSummary`	`?string`	会话摘要

`ErrorOccurredHookInput`

属性	类型	说明
`error`	`string`	错误信息。运行时传递错误对象时，如果 `message` 是字符串则为该值，否则为对象的 JSON 字符串
`errorContext`	`string`	`model_call` / `tool_execution` / `system` / `user_input` 之一
`recoverable`	`bool`	是否可恢复

`ErrorOccurredHookOutput`

属性	类型	说明
`suppressOutput`	`?bool`	抑制错误显示
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	重试次数
`userNotification`	`?string`	对用户的通知文本

ToolResultObject

工具执行结果的标准对象。

属性	类型	说明
`textResultForLlm`	`?string`	传给 LLM 的文本结果
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	面向助手的结果数据

最佳实践

不要在钩子内直接执行过重的同步处理。如有必要请异步化。
不需要修改时返回 null，交给默认行为处理。
尽可能显式地设置 permissionDecision。
关键错误不要过度抑制，请保留日志 / 通知通道。
会话级状态请基于 session id 管理，并在 onSessionEnd 时清理。

最新信息请参考 GitHub 仓库。

GitHub Copilot

SDK

AI SDK

VOICEVOX

启动套件

Feed 与 RSS

中间件

会话钩子

会话钩子

基于文件的钩子发现

钩子流程

基本使用方式

可用的钩子

阻止 prompt

典型用例

1) Permission control（执行控制）

2) Auditing / compliance（审计）

3) Prompt enrichment（输入增强）

4) Result filtering（结果整形）

5) Error recovery（故障恢复）

6) Session metrics（度量）

Hook input / output 类型

共通输入（`BaseHookInput`）

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

最佳实践

​会话钩子

​基于文件的钩子发现

​钩子流程

​基本使用方式

​可用的钩子

​阻止 prompt

​典型用例

​1) Permission control（执行控制）

​2) Auditing / compliance（审计）

​3) Prompt enrichment（输入增强）

​4) Result filtering（结果整形）

​5) Error recovery（故障恢复）

​6) Session metrics（度量）

​Hook input / output 类型

​共通输入（BaseHookInput）

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​最佳实践

会话钩子

基于文件的钩子发现

钩子流程

基本使用方式

可用的钩子

阻止 prompt

典型用例

1) Permission control（执行控制）

2) Auditing / compliance（审计）

3) Prompt enrichment（输入增强）

4) Result filtering（结果整形）

5) Error recovery（故障恢复）

6) Session metrics（度量）

Hook input / output 类型

共通输入（`BaseHookInput`）

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

最佳实践