Skip to main content
Agent skill

Agent Runtime Hooks

Use for agent lifecycle hooks, tool mocks, intervention, sub-agent calls and context compression.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/agent-runtime-hooks && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/agent-runtime-hooks/SKILL.md' -o ~/.claude/skills/agent-runtime-hooks/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Agent Runtime Hooks when an AI agent needs a reusable SKILL.md workflow for this job: Use for agent lifecycle hooks, tool mocks, intervention, sub-agent calls and context compression.

When not to use it

Skip Agent Runtime Hooks when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/agent-runtime-hooks && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/agent-runtime-hooks/SKILL.md' -o ~/.claude/skills/agent-runtime-hooks/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/agent-runtime-hooks/SKILL.md. For a shared project, commit the folder at .claude/skills/agent-runtime-hooks/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Agent Runtime Hooks skill for this task: Use Agent Runtime Hooks when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
69/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Agent Runtime Hooks

Register lifecycle hooks through `execAgent({ hooks })`. `HookDispatcher` stores them per operation and dispatches them in registration order.

## Hook Types

16 hook types across 5 categories:

``` execAgent({ hooks }) │ ├─ beforeStep ──────────── Before each step executes │ │ │ ├─ [call_llm] LLM inference │ │ │ ├─ [call_tool] │ │ ├─ beforeToolCall ── Before tool executes (supports mocking) │ │ ├─ (tool execution) │ │ ├─ afterToolCall ─── After tool completes (optional result control) │ │ └─ onToolCallError ─ Tool threw an exception │ │ │ ├─ [request_human_approve] │ │ ├─ beforeHumanIntervention ── Before agent pauses │ │ ├─ afterHumanIntervention ─── After approve/reject + resume │ │ └─ onStopByHumanIntervention ── User rejected, agent halted │ │ │ ├─ [compress_context] │ │ ├─ beforeCompact ──── Before compression starts │ │ ├─ afterCompact ───── After compression completes │ │ └─ onCompactError ─── Compression failed │ │ │ ├─ [callAgent] (via execSubAgentTask) │ │ ├─ beforeCallAgent ── Before sub-agent starts │ │ ├─ afterCallAgent ─── After creation/start returns │ │ └─ onCallAgentError ── Sub-agent failed │ │ │ └─ afterStep ──────────── After step completes │ ├─ (next step...) │ ├─ onComplete ───────────── Operation reaches terminal state └─ onError ──────────────── Error during execution ```

## Key Files

| File | Role | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | `packages/agent-runtime/src/types/hooks.ts` | Event types and required/optional fields | | `apps/server/src/services/agentRuntime/hooks/types.ts` | Registration and webhook types | | `apps/server/src/services/agentRuntime/hooks/HookDispatcher.ts` | Registration, dispatch, local mocks, HTTP/QStash delivery | | `apps/server/src/services/agentRuntime/hooks/webhookPayload.ts` | Event projection and email enrichment | | `apps/server/src/modules/AgentRuntime/adapters/toolCallHookContext.ts` | Shared tool-event context builder | | `apps/server/src/modules/AgentRuntime/adapters/ServerToolTransport.ts` | Tool notifications and execution results | | `apps/server/src/modules/AgentRuntime/RuntimeExecutors.ts` | Tool, compression and human-intervention execution | | `apps/server/src/services/agentRuntime/AgentRuntimeService/` (`executeStep/`, `intervention.ts`) | Step events and human-intervention continuation | | `apps/server/src/services/agentRuntime/CompletionLifecycle/index.ts` | Terminal events | | `apps/server/src/services/aiAgent/subAgentRuns.ts` | Sub-agent events |

## Registration

```ts const hooks: AgentHook[] = [ { id: 'observe-step', type: 'afterStep', handler: async (event) => { console.log(event.operationId, event.stepIndex); }, }, ]; await aiAgentService.execAgent({ agentId, prompt, hooks }); ```

Completion cleans up registrations through `hookDispatcher.unregister(operationId)`.

### Webhook Hooks

Webhook-only hooks deliver in both local and queue modes. For hooks with both `handler` and `webhook`, local dispatch calls the handler; queue dispatch uses the serialized webhook. Only webhook configuration is persisted, so functions are unavailable after a process restart.

```ts const hook: AgentHook = { id: 'tool-notification', type: 'afterToolCall', matcher: '^fs/readFile$', webhook: { url: 'https://example.com/hooks', delivery: 'fetch', timeout: 5, // seconds; default 30 headers: { Authorization: 'Bearer ${HOOK_TOKEN}' }, allowedEnvVars: ['HOOK_TOKEN'], }, }; ```

- `matcher` is a regex against `${identifier}/${apiName}`, supported only on tool events. Omitted, empty, or `*` matches all tools. - Header environment templates resolve only at send time from `allowedEnvVars`; persist templates, never resolved secrets. - Notifications ignore response content and may return HTTP 204. - `beforeToolCall` with `responseHandling: 'toolCall'` awaits an optional HTTP decision before tool execution. Return HTTP 2xx JSON with `{ "decision": "allow" }` or `{ "decision": "deny", "reason": "禁止执行该操作" }` to intervene. The type is `{ decision: 'allow' } | { decision: 'deny'; reason?: string }`; a deny with an omitted or empty reason uses `Blocked by beforeToolCall hook.`. Denials preserve the reason in the tool result/card with classification `hook_denied`. - `afterToolCall` also accepts `responseHandling: 'toolCall'`. It synchronously checks the full request/result before archival and model consumption; deny replaces the original result with the receiver's optional reason in both content and blocked state. A deny with an omitted or empty reason uses `Blocked by afterToolCall hook.`, following the same `Blocked by ${type} hook.` rule as `beforeToolCall`. The reason enters model context and the tool card, as with `beforeToolCall`. It does not undo tool side effects, retries, or charges. See [the result-control contract](../../../docs/development/agent-tool-result-hooks.md) for deferred completions and runtime boundaries. - Environment response modes are `ignore` (default notifications) and `toolCall` (optional decisions for both before and after). Only subscribed events are enabled. Replace removed `toolResult`/`toolCallAndResult` values with `toolCall`; use the events list to select after-only checking. Existing after responses with a valid decision now control results. - HTTP 204, empty successful bodies, invalid JSON, and JSON without a top-level decision (including arrays, scalars, null, or only the old nested `hookSpecificOutput`) are notification responses, even with `onError: 'block'`. Continue checking subsequent hooks; do not treat a notification as permission to skip later policies. Explicit invalid decisions, non-2xx status, oversized bodies, invalid UTF-8, network failures, and timeouts follow `onError: 'continue' | 'block'` (default `continue`); blocking uses `hook_control_error` as the tool-result content and reason for both before and after hooks. Cancellation never grants permission. - Extra response fields are allowed and discarded. Only `decision` and a deny's optional string `reason` are consumed; `updatedInput`/`additionalContext` do not change tool arguments or conversation context. - Configuration: `packages/types/src/agentHook.ts`; response parsing: `packages/types/src/agentHookResponse.ts`; HTTP delivery: `apps/server/src/services/agentRuntime/hooks/httpWebhook.ts`.

### Hook configuration lifetime

- Environment hooks (`AGENT_HOOK_WEBHOOK_*`) always come from the executing worker's **current environment**, including after human approval and deferred completion. Never persist their configuration or restore a previous environment's hooks. - Code-supplied webhook hooks (`execAgent({ hooks })`) retain the existing per-operation serialization and persistence. Recover these caller hooks from the runtime snapshot or durable operation record; preserve environment-variable templates without expanding secrets into storage. - Evaluate each operation's recovered caller hooks in order, then evaluate current environment hooks once in the final round. Do not deduplicate caller hook IDs across operations. Environment-only hooks do not require durable operation storage. Removing an environment hook stops it from controlling subsequent results; when no matching result control remains, allow the result. Do not freeze a previous environment policy across an approval or restart. - Deferred completion publishes into its empty placeholder once; duplicate callbacks retain that first final result, including a denial. Propagate caller-policy storage errors rather than treating failed reads as an empty hook list. Do not extend default allow to configured-hook delivery failures: those follow `onError`. - Cover environment removal/addition across approval and snapshot expiry, publication without review markers, and continued enforcement of persisted caller hooks in regression tests.

### Publish after the result hook

- Await result control before archival, message content/state writes, streaming, and model consumption. Persist the allowed result or the sanitized denial directly; do not add `toolResultControl` pending/allowed/blocked metadata or hide raw output through history projections. - Human approval sources claim the decision and retain the answer in their private resolution/outbox. `MessageModel.resolveHumanApproval` defaults to claim-only; only the runtime calls it with `publishResult: true` after result control. Stop/rejection receipts can publish directly because they contain no executed tool output. - Recover original caller hooks through the existing intervention operation identity or deferred callback's parent operation. Keep the in-memory hook verdict separate from tool-owned state; a tool returning `type: 'blocked'` is not a hook verdict. - Every deferred backfill, including a member that fails to start, follows the same hook-before-write order. Use the existing empty placeholder to arbitrate duplicate final writes; do not introduce a replacement review state machine. - When a thread has a sub-agent or group-member completion bridge, that bridge exclusively publishes its tool result. Thread lifecycle hooks update thread metadata only; never prefill the tool message with an ungated summary, including after approval recovery. - Cover an answer held while a hook runs, atomic publication and rollback, duplicate callbacks after policy removal, and partial member startup failure. History readers should need no result-review logic.

## Events

| Event | Timing and payload | | --------------------------- | ------------------------------------------------------------------------------------------ | | `beforeStep` | Before a step; `AgentHookEvent` | | `afterStep` | After a step; content, tool calls/results and usage totals | | `onComplete` | Terminal state; reason such as `done`, `error`, `interrupted`, `max_steps` or `cost_limit` | | `onError` | Operation error; `errorMessage`, `errorDetail` and available error metadata | | `beforeToolCall` | Before tool execution; shared tool context and local `mock()` callback | | `afterToolCall` | After tool execution; structured `result` and `mocked` | | `onToolCallError` | Tool execution throws; shared tool context and `error` | | `beforeHumanIntervention` | Before approval; `pendingTools`, `operationId`, `stepIndex` | | `afterHumanIntervention` | Approval decision and continuation; `action`, optional `toolCallId` and `rejectionReason` | | `onStopByHumanIntervention` | Human rejection stops the run; optional `toolCallId` and `rejectionReason` | | `beforeCompact` | Before compression; `messageCount`, `tokenCount`, `stepIndex` | | `afterCompact` | After compression; `groupId`, `messagesBefore`, `messagesAfter`, `summary` | | `onCompactError` | Compression error; `error`, `tokenCount`, `stepIndex` | | `beforeCallAgent` | Before sub-agent creation; `agentId`, `instruction` | | `afterCallAgent` | Creation/start returns; `agentId`, `subOperationId`, `success`, optional `threadId` | | `onCallAgentError` | Sub-agent call fails; `agentId`, `error` |

CallAgent events dispatch on the parent operation identified by `parentOperationId`. An isolated child supplies `threadId`; shared group members use the shared conversation. Child completion is reported by the child's `onComplete` event.

## Tool Context

Use `buildToolCallHookContext()` for the three tool events.

- Required fields: native `toolCallId`, `assistantMessageId`, `identifier`, `apiName`, effective `args`, `callIndex`, `stepIndex`, `operationId` and `executor`. - Optional associations come from the run context: agent, topic, session, thread, group, task, workspace, document, source/tool message and parent operation IDs. - `userId` uses `runtime.userId ?? origin.userId`. - `toolSource` identifies the tool's origin; `executor` identifies the server/client dispatch route. `executionTarget` and `activeDeviceId` describe the run's execution plan and device selection. - `afterToolCall.result` carries `content`, `success`, optional `executionTime` and error/state data such as `state.type: 'blocked'`. `mocked` marks results supplied by a local hook.

Sandbox and MCP tools use the same event path. Filter with `identifier`, `apiName` or `toolSource`.

### Local Mocking

`dispatchBeforeToolCall()` exposes `event.mock(result)`. The first accepted mock wins and short-circuits the remaining mock handlers. The method returns `{ isMocked: true, result }` for a mock, or `null` to continue execution.

```ts event.mock({ content: '{"items":[]}', success: true }); ```

Tool observation payloads use `BeforeToolCallObservationEvent`; the callback belongs to the in-memory handler event. `dispatchBeforeToolCall()` does not deliver webhooks.

## Webhook Payloads

`createWebhookPayloadBuilder()` selects `eventFields`, adds `hookId`/`hookType`, then merges `webhook.body`. The body determines the final value of overlapping fields. Tool-result notification payloads use `redactResultForEvents()` to trim raw skill Work data; controls receive the full result. Work registration retains the full in-process result. `finalState` is available to local handlers; serialized payloads carry the event's data fields.

When email is selected, the builder resolves `userEmail` from the final effective `userId`, replacing supplied email values. Email-only projections use the event ID. An explicit invalid ID, missing email or lookup error leaves email omitted.

Email queries share a per-dispatcher cache of up to 1,000 users for five minutes. Query timeouts belong to the database layer. The builder's optional fourth `{ signal }` argument lets a waiter cancel independently; cancellation returns `undefined` so the caller can stop delivery. Fetch and QStash use the enriched payload.

## Delivery Errors

Dispatch awaits each handler or webhook. Ordinary errors are logged and dispatch continues. Webhooks with `fallback: 'none'` accumulate a `CriticalHookDeliveryError`, which is thrown after sibling hooks have run. QStash delivery defaults to a fetch fallback; use `fallback: 'none'` for QStash-signed endpoints.

Intended uses

  • Use Agent Runtime Hooks when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.