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