生命周期钩子

钩子让你在 Agent 活动发生时进行观测和把控。你针对某个生命周期事件注册一个具名回调，运行时会在该节点调用它，回调返回一个决策，例如 { action: "continue" }。钩子可用于审计、脱敏、日志记录，或在不修改 Agent 提示词的前提下实施策略。

其生命周期是对称的：registerHook 按名称添加回调，hookCount 告诉你当前有多少个钩子处于活动状态，unregisterHook 则按名称移除某个钩子。

Rust

Node.js

Python

Rust

use std::sync::Arc;

use a3s_code_core::{
    hooks::{
        Hook, HookConfig, HookEvent, HookEventType, HookHandler, HookMatcher, HookResponse,
    },
    Agent,
};

struct ContinueHandler;

impl HookHandler for ContinueHandler {
    fn handle(&self, event: &HookEvent) -> HookResponse {
        println!("observed {}", event.event_type());
        HookResponse::continue_()
    }
}

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent.session_builder(".").build().await?;

    let hook = Hook::new("observe-env-read", HookEventType::PreToolUse)
        .with_matcher(HookMatcher::path("**/.env*"))
        .with_config(HookConfig {
            priority: 100,
            ..HookConfig::default()
        });
    session.register_hook(hook)?;
    session.register_hook_handler("observe-env-read", Arc::new(ContinueHandler))?;

    println!("active hooks: {}", session.hook_count());
    session.send("读取项目 README 并总结。", None).await?;

    session.unregister_hook_handler("observe-env-read")?;
    session.unregister_hook("observe-env-read")?;
    println!("active hooks: {}", session.hook_count());

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = await agent.sessionAsync(process.cwd());

// 为生命周期事件注册命名钩子。返回形如 { action: 'continue' } 的决策；
// 返回 null 或 undefined 也会继续。
session.registerHook(
  'observe-env-read',
  'pre_tool_use',
  { pathPattern: '**/.env*' },
  { priority: 100 },
  () => ({ action: 'continue' }),
);

console.log('active hooks:', session.hookCount()); // 1

await session.run('Read the project README and summarize it.');

// 不再需要时按名称移除钩子。
session.unregisterHook('observe-env-read');
console.log('active hooks:', session.hookCount()); // 0

await session.closeAsync();
await agent.close();

Python

from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.acl")
session = agent.session('.', SessionOptions())

# 为生命周期事件注册命名钩子，回调会返回决策。
session.register_hook(
    'observe-env-read',
    'pre_tool_use',
    {'path_pattern': '**/.env*'},
    {'priority': 100},
    lambda event: {'action': 'continue'},
)

print("active hooks:", session.hook_count())  # 1

session.run("Read the project README and summarize it.")

# 不再需要时按名称移除钩子。
session.unregister_hook('observe-env-read')
print("active hooks:", session.hook_count())  # 0

session.close()
agent.close()

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v9"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(ctx)

	session, err := agent.Session(ctx, ".", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(ctx)

	priority := 100
	err = session.RegisterHookWithHandler(ctx, code.Hook{
		ID:        "observe-env-read",
		EventType: "pre_tool_use",
		Matcher:   &code.HookMatcher{PathPattern: "**/.env*"},
		Config:    &code.HookConfig{Priority: &priority},
	}, func(_ context.Context, event json.RawMessage) (*code.HookResponse, error) {
		fmt.Println("hook event:", string(event))
		return &code.HookResponse{Action: "continue"}, nil
	})
	if err != nil {
		log.Fatal(err)
	}
	count, err := session.HookCount(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("active hooks:", count)

	if _, err = session.Run(ctx, "读取项目 README 并总结。"); err != nil {
		log.Fatal(err)
	}

	if _, err = session.UnregisterHook(ctx, "observe-env-read"); err != nil {
		log.Fatal(err)
	}
}

注意事项：

钩子回调返回一个决策。返回 { action: "continue" }（Node）/ {"action": "continue"}（Python）/ &code.HookResponse{Action: "continue"}（Go）即可让 Agent 继续执行。
永久拒绝返回带原因的 block。临时拒绝返回带原因的 retry，并附上 delayMs（Node）、 delay_ms（Python）或 DelayMS（Go）。在 send 或 stream 回合中，被拒绝的工具调用会发出 permission_denied 事件，模型收到的是 Hook denied <tool>: <reason>，而不是工具输出。对于宿主直接调用（session.tool(...) 和类型化辅助方法），被拒绝的结果还会带有 error_kind.type = "hook_denied" 以及 retryable 和 retry_after_ms，宿主无需解析输出文本。
路径匹配器读取工具的 file_path 参数，没有时回退到 path。
匹配器（Node 为 { pathPattern: '**/.env*' }，Python 为 {'path_pattern': ...}， Go 为 HookMatcher{PathPattern: ...}）将钩子限定到路径匹配该模式的事件，而 { priority: 100 } 用于对同一事件上的多个钩子排序（数值越小越先执行）。
回调只接收一个参数，即事件本身。
Node 回调若抛出异常、返回无效值或超过超时时间（配置中的 timeoutMs，默认 30,000 毫秒），该钩子即视为失败。在关卡事件（pre_tool_use、permission_request、 pre_compact、pre_prompt、pre_planning、pre_run_control）上，该动作会被阻止，原因为 Required hook '<name>' failed: ...；在其他事件上，智能体会继续执行。
hookCount / hook_count / HookCount 反映当前已注册钩子的数量，在测试中可方便地断言注册与清理是否生效。
unregisterHook / unregister_hook / UnregisterHook 接收你注册时使用的名称。请始终拆除不再需要的钩子，以免它们在多次运行之间泄漏。
把钩子当作生产关卡前，请先验证你所依赖的具体 event path。

#生命周期钩子

生命周期钩子