II.
Page overview
Reference · livepage:docs-agent-stack-hooks-missing-events
Hook Event Gaps — Specs for Remaining Runtime Work overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-agent-stack-hooks-missing-events.
Attributes
nodeKind
Page
sourcePath
docs/agent-stack/hooks/missing-events.md
sourceKind
repo-docs
title
Hook Event Gaps — Specs for Remaining Runtime Work
displayName
Hook Event Gaps — Specs for Remaining Runtime Work
slug
docs/agent-stack/hooks/missing-events
articlePath
wiki/docs/agent-stack/hooks/missing-events.md
article
# Hook Event Gaps — Specs for Remaining Runtime Work
These events are defined in the atlas graph and the hooks-adapter canonical contract. As of issue #636, hooks-adapter core, Claude adapter normalization/rendering, CLI invoke coverage, adapters Claude runtime hook registration, and SDK task lifecycle hooks cover the concrete surfaces that exist today.
This file now tracks remaining runtime-emission gaps, plus `TeammateIdle`, which is blocked until the stack has a concrete teammate idle lifecycle source.
## Priority 1 — Tool & Turn Lifecycle (4 events)
### PostToolUseFailure
**Canonical phase:** `tool.after_failure`
**Fires:** After a tool call fails (error, timeout, permission denied at execution)
**Input:** `{ tool_name, tool_input, error, exit_code }`
**Decisions:** Cannot block (side-effect only). Can inject `additionalContext`.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- agent-platform: Fire after tool execution error in effect resolution
- SDK: Add to runtime hook dispatch in `callRuntimeHook()`
### PostToolBatch
**Canonical phase:** `tool.after_batch`
**Fires:** After a parallel batch of tool calls resolves (all tools in one model turn)
**Input:** `{ batch_results: [{ tool_name, tool_input, success, output }] }`
**Decisions:** Can block (prevents next model invocation). Can inject `additionalContext`.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- agent-platform: Fire after all effects in one iteration resolve
- SDK: Add batch-level hook dispatch after parallel task resolution
### StopFailure
**Canonical phase:** `turn.stop_failure`
**Fires:** When a turn ends due to API error (rate limit, auth failure, server error)
**Input:** `{ error_type, error_message, retry_after }`
**Matcher:** Error type (`rate_limit`, `authentication_failed`, `billing_error`, `server_error`)
**Decisions:** Cannot block. Can inject context for recovery.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- agent-platform: Fire on API errors in orchestration loop
- agent-core: Emit error event from session.prompt() catch block
### UserPromptExpansion
**Canonical phase:** `turn.prompt_expansion`
**Fires:** Before a slash command/skill expands into its content
**Input:** `{ expansion_type, command_name, command_args, command_source, prompt }`
**Matcher:** Command name
**Decisions:** Can block (prevent expansion). Can modify prompt via `additionalContext`.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- SDK: Fire before skill invocation in CLI dispatch
## Priority 2 — Task & Team (3 events)
### TaskCreated
**Canonical phase:** `task.created`
**Fires:** When a task/effect is being created (ctx.task() in process)
**Input:** `{ task_id, task_kind, task_title, task_labels }`
**Decisions:** Can block (prevent task creation). Can modify task metadata.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- SDK: ✅ fires in `runTaskIntrinsic()` before effect dispatch
- agent-platform: Uses SDK task lifecycle paths where applicable
### TaskCompleted
**Canonical phase:** `task.completed`
**Fires:** When a task/effect is marked complete
**Input:** `{ task_id, task_kind, task_status, task_result }`
**Decisions:** Can block (prevent completion, request re-do).
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- SDK: ✅ fires in effect result commit
- agent-platform: Uses SDK task lifecycle paths where applicable
### TeammateIdle
**Canonical phase:** `team.idle`
**Fires:** When a teammate agent is about to go idle (no more work)
**Input:** `{ agent_id, agent_type, idle_reason }`
**Decisions:** Can block (assign more work before idle).
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: intentionally not registered until a native/runtime source exists
- agent-platform: Fire in subagent lifecycle management once a real idle boundary exists
- Requires multi-agent coordination infrastructure
## Priority 3 — Session & Config (3 events)
### Setup
**Canonical phase:** `session.setup`
**Fires:** One-time initialization (`--init-only`, `--init`, `--maintenance`)
**Input:** `{ trigger: "init" | "maintenance" }`
**Decisions:** Cannot block. Can inject initial context.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- SDK: Fire on first-time project initialization
- agent-platform: Fire during harness install/setup
### InstructionsLoaded
**Canonical phase:** `session.instructions_loaded`
**Fires:** When CLAUDE.md or rules files are loaded
**Input:** `{ file_path, memory_type, load_reason, globs, trigger_file_path, parent_file_path }`
**Matcher:** Load reason (`session_start`, `nested_traversal`, `path_glob_match`, `include`)
**Decisions:** Cannot block. Can inject `additionalContext`.
**Where to implement:**
- hooks-adapter: ✅ canonical phase and Claude adapter support exist
- adapters: ✅ native Claude runtime hook registration exists
- SDK: Fire when babysitterMdDiscovery loads instructions
- agent-platform: Fire when process library instructions load
### ConfigChange
**Note:** Already handled as canonical phase `session.config_changed`; do not use `session.config_change`.
**Status:** hooks-adapter and adapters support blocking decisions for native Claude `ConfigChange`.
**Where to fix:**
- S../platform: Add explicit config mutation emission only where a concrete config-write path owns the event.
## Priority 4 — Advanced (3 events)
### MessageDisplay
**Note:** Formalized as `message.received` in hooks-adapter and registered in adapters Claude runtime hooks.
**Gap:** S../platform streaming output emission remains separate from native Claude runtime hook dispatch.
**Where to fix:**
- agent-platform: Emit during streaming output
### model.before_request / model.after_response (Gemini-specific)
**Note:** These are in the atlas graph for Gemini adapter but not in the Claude Code 30-event spec.
**Status:** Low priority — only relevant for Gemini CLI integration.
### planner.before_tool_selection (Gemini-specific)
**Note:** Atlas graph only. Not in Claude Code spec.
**Status:** Low priority.
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-agent-stack-hooks·PageAgent Stack Hooks — Gap Analysis & Specs