Topics/Hook Composition

Hooks place deterministic code at stable lifecycle events. A hook can shrink context before a model call, check authority before a tool call, start the next agent after an artifact is accepted, record trace data, save a checkpoint, or release resources.

A hook is a mechanism. Its role comes from the event, the state it reads, the authority it holds, and its failure semantics.

Four roles

Composition

before_model → context_policy → prompt_trace
before_tool  → identity_check → policy_decision → approval_if_needed
after_tool   → receipt_capture → state_diff → next_stage_or_recovery

The runtime should display the effective order. When two hooks rewrite arguments, order changes behavior. When an audit hook fails, the design must state whether business execution blocks or observation degrades.

For a payroll commit, before_tool first verifies the caller, then reads policy and determines whether approval is required. After resume, before_commit rechecks employee state and the Intent digest. Following a successful call, after_tool records the receipt and after-read. A telemetry failure may degrade a low-risk read, while a production write normally blocks. Order and failure semantics belong to the composition and cannot depend on accidental plugin registration order.

HookSpec

hook_id: payroll.before_commit.policy
event: before_tool
priority: 200
reads: [principal, intent, tool_digest, resource_scope]
writes: [policy_decision]
idempotency_key: run_id + intent_digest
on_failure: deny
emits: [policy.decided]
owner: security-platform
version: 7

Relation to G5

G5 keeps its historical identifier and focuses on deterministic governance enforcement. Hook Composition spans a wider set of responsibilities, so no new collaboration pattern has been added.

Common failures

• Effective order depends on registration order and remains invisible.
• Retry repeats a notification, quota charge, or external action.
• Policy source, decision, enforcement, and logging live in one handler.
• Failure of a non-critical observation hook blocks the main task.
• Parent and child agents use different hook sets without version evidence.

Review questions

1. Which event triggers each hook, and what state does it read or write?
2. Are order and conflict rules explicit?
3. Are retry, resume, and duplicate events idempotent?
4. Does failure fail open, fail closed, or escalate?
5. Can a run show the effective hook set and versions?

Source

The Governance workshop separated policy source, decision, enforcement, and evidence. The Collaboration workshop added stage transitions, cross-agent triggers, and recovery. This topic joins both discussions while retaining G5 as the historical governance entry.