Skip to the content.

Hooks Guide

A hook is the host's policy at the boundaries of a turn. core/agent defines the three points; core/agent-host runs them; core/deploy lets a deployment declare its own.

The three points are the ones a host owns, rather than the ones an engine owns: a session arrives, a turn arrives, a turn ends. They exist because a host has no other place to reach a turn it did not start — a delegated child, a message that came in over A2A — and because "what this agent is" belongs to the agent, not to the substrate that happens to run it.

type Hooks struct {
    // Runs after a session is opened or restored, before its turn.
    OnSession func(ctx context.Context, session SessionInfo) error
    // Runs before the turn reaches the engine and may rewrite its message.
    BeforeTurn func(ctx context.Context, turn *Turn) error
    // Runs after the run ends, with the state and result it reached.
    AfterTurn func(ctx context.Context, turn Turn, result Result) error
}

What a hook cannot do

Deliberately: it cannot rewrite the system framing, cut the engine's transcript, or intercept one model call. Those are the engine's state, and a hook that reached into them would turn core/agent into a prompt framework. A host that needs per-call control owns the engine instead — see graph.md for a model node whose own code sits between the run and the provider.

The three slots

Slot Runs Receives An error means
OnSession After a session is opened or restored, before its turn SessionInfo: agent, session id, task id, state, Resumed The open fails. A host that cannot prepare its memory refuses the turn instead of running it blind.
BeforeTurn Before the turn reaches the engine *Turn: agent, session, message (mutable) The turn stops before it starts. Nothing was sent, so nothing has to be undone.
AfterTurn After the run ends Turn and the Result it reached Logged, and the turn stands.

The AfterTurn asymmetry is not an oversight. The work is already durable, and reporting an error after the terminal event would break the stream contract every consumer relies on — a client that saw Completed cannot then be told the turn failed.

SessionInfo.Resumed is what a memory hook branches on: a fresh task needs recall, a restored one needs the state it left.

Attaching hooks from Go

hooks := agent.Hooks{
    BeforeTurn: func(ctx context.Context, turn *agent.Turn) error {
        recap, err := memory.Recall(ctx, turn.Agent, turn.SessionID, turn.Message)
        if err != nil {
            return err
        }
        turn.Message = memory.Prefix(recap, turn.Message)
        return nil
    },
    AfterTurn: func(ctx context.Context, turn agent.Turn, res agent.Result) error {
        return memory.Persist(ctx, turn, res)
    },
}

Turn.Message is the input, metadata included, and BeforeTurn may replace the whole value — that is the seam a policy uses to inject a recap without touching the stored transcript. TaskID is empty there: the run mints the task, so a hook that needs one reads it in AfterTurn.

Attaching hooks from a document

A deployment names hook kinds, and each kind is registered by the host:

agents:
  - name: forge
    hooks:
      - kind: memory
        settings:
          scope: session
      - kind: audit
        settings:
          sink: stdout
kinds := builtin.Kinds().WithHooks(deploy.HookKind{
    Name: "audit",
    Decode: func(settings json.RawMessage) (any, error) {
        var cfg auditConfig
        return cfg, decode.Strict(settings, &cfg)   // a typo fails the load
    },
    Build: func(ctx context.Context, deps deploy.HookDeps) (agent.Hooks, error) {
        cfg := deps.Spec.Settings           // decode again for the typed value
        return auditHooks(deps.Agent, cfg), nil
    },
})
HookDeps field What it gives the kind
Agent The deployment name the hook is attached to — what a seat-bound policy keys itself by.
Spec The kind and its raw settings.
Runtime The agent's substrate; nil for a remote engine, because a hook that only observes turns does not need one.
Store The checkpoint store, so a hook can read the task log to assemble what it needs.
LoadOptions Placeholder resolvers, for a kind that reads its own documents.

Decode runs at load (so a typo fails before the agent is built) and again inside Build for the typed value — the same two-phase contract engine and protocol kinds use. See deploy.md.

Several hooks on one agent are chained in declaration order. The host's own Bindings.Hooks runs before them, so a host can always observe or adjust what a deployment configured. builtin.Kinds() registers no hook kinds: a host's policy is the host's.

Cost and blocking

Hooks run synchronously on the run's goroutine. A slow hook stalls the run and its protocol stream, so a hook that does I/O belongs behind a queue of its own — OnEvent in agent-host.Bindings has the same rule for the same reason.

Delegation

A delegated child is a session of its own: the hooks run for it, with Agent naming the child's deployment, not the caller's. A hook that keys on the session identity therefore answers for the child — see delegation.md.

What this replaced

The previous core/hooks package ran hooks.json entries as sh -c children on a large event vocabulary (PreToolUse, PostToolUse, PermissionRequest, TurnEnd, …). It is gone: the vocabulary grew faster than anyone could keep stable, and every command hook paid a process spawn on the turn's critical path. The three in-process slots cover what hosts actually used those events for, and a host that still wants external processes can spawn them from AfterTurn.