#Lifecycle Hooks

Hooks let you observe and gate agent activity as it happens. You register a named callback against a lifecycle event, the runtime invokes it at that point, and the callback returns a decision such as { action: "continue" }. Use hooks for auditing, redaction, logging, or enforcing policy without changing the agent's prompt.

The lifecycle is symmetric: registerHook adds a callback by name, hookCount tells you how many are active, and unregisterHook removes one by its name.

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("Read the project README and summarize it.", 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(())
}

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

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

// Register a named hook on a lifecycle event. Return a decision such as
// { action: 'continue' }; null or undefined also continues.
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.');

// Remove the hook by name when you no longer need it.
session.unregisterHook('observe-env-read');
console.log('active hooks:', session.hookCount()); // 0

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

from a3s_code import Agent, SessionOptions

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

# Register a named hook on a lifecycle event. The callback returns a decision.
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.")

# Remove the hook by name when you no longer need 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, "Read the project README and summarize it."); err != nil {
		log.Fatal(err)
	}

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

Notes:

• A hook callback returns a decision. Return { action: "continue" } (Node) / {"action": "continue"} (Python) / &code.HookResponse{Action: "continue"} (Go) to let the agent proceed.
• Permanent denials return block with a reason. Temporary denials return retry with a reason and delayMs (Node), delay_ms (Python), or DelayMS (Go). In a send or stream turn, a denied tool call emits a permission_denied event and the model receives Hook denied <tool>: <reason> instead of the tool output. For host-direct calls (session.tool(...) and the typed helpers), the denied result also carries error_kind.type = "hook_denied" with retryable and retry_after_ms, so hosts do not need to parse output text.
• The path matcher reads the tool's file_path argument, falling back to path.
• The matcher ({ pathPattern: '**/.env*' } in Node, {'path_pattern': ...} in Python, HookMatcher{PathPattern: ...} in Go) scopes the hook to events whose path matches the pattern, and { priority: 100 } orders hooks on the same event (lower values run first).
• Callbacks receive the event as their only argument.
• A Node callback that throws, returns an invalid value, or runs past its timeout (timeoutMs in the config, default 30,000 ms) counts as a failed hook. On gating events (pre_tool_use, permission_request, pre_compact, pre_prompt, pre_planning, pre_run_control) the action is blocked with Required hook '<name>' failed: ...; on other events the agent continues.
• hookCount / hook_count / HookCount reflects the number of currently registered hooks, which is handy in tests to assert that registration and cleanup happened.
• unregisterHook / unregister_hook / UnregisterHook takes the name you registered with. Always tear down hooks you no longer need so they do not leak across runs.
• Validate the event path you depend on before using a hook as a production gate.