Shared from "Claude-Code" on Inkdown
What happens after the AI finishes a response.
query/stopHooks.ts runs after every AI turn completes. It's the post-turn pipeline that triggers background tasks, checks for hook conditions, and decides whether to continue.
Run when the model stops (no more tool_use blocks):
// Check if a stop hook should fire
const hookResult = await executeStopHook(messages, systemPrompt, toolUseContext)
// If hook returns "retry", the query loop continues
if (hookResult.retry) {
state.transition = { reason: 'stop_hook_retry' }
continue
}Stop hooks are used for:
Fire when a task completes:
// Notify about completed task
onTaskCompleted(task)Fire when a teammate agent has been idle:
// Check if teammate has been idle too long
checkTeammateIdle(teammate)After hooks, several background tasks are triggered (non-blocking):
// Suggest next prompts based on conversation state
triggerPromptSuggestion(messages, toolUseContext)// Extract memories from the conversation (EXTRACT_MEMORIES feature)
triggerMemoryExtraction(messages, toolUseContext)// Auto-dream: process conversation in background
triggerAutoDream(messages, toolUseContext)// Classify the job type (TEMPLATES feature)
triggerJobClassification(messages, toolUseContext)// Clean up computer use state (CHICAGO_MCP feature)
if (feature('CHICAGO_MCP') && !toolUseContext.agentId) {
await cleanupComputerUseAfterTurn(toolUseContext)
}Model finishes response (no more tool_use)
│
▼
executeStopHooks()
│
├─ Check Stop hook conditions
│ └─ If matched → execute hook → maybe retry
│
├─ Fire TaskCompleted hooks
│
├─ Fire TeammateIdle hooks
│
▼
Background tasks (non-blocking, fire-and-forget)
├─ Prompt suggestions
├─ Memory extraction
├─ Auto-dream
├─ Job classification
└─ Computer use cleanup
│
▼
Return to query loop
├─ If stop hook requested retry → continue
└─ Otherwise → return { reason: 'done' }When a stop hook requests a retry:
// In query.ts
if (stopHookRetried) {
state.transition = { reason: 'stop_hook_retry' }
continue // Back to the top of the query loop
}This allows the hook to inject additional messages or context and re-query the model.
Hooks are configured via Zod schemas (schemas/hooks.ts):
{
"event": "Stop",
"type": "bash",
"command": "npm test",
"matcher": { "pattern": "tests?\\s*passed" }
}{
"event": "Stop",
"type": "prompt",
"prompt": "Summarize what was accomplished in this session",
"matcher": { "pattern": "done|complete" }
}{
"event": "Stop",
"type": "http",
"url": "https://hooks.example.com/notify",
"method": "POST",
"headers": { "Authorization": "Bearer ${API_KEY}" },
"body": { "message": "${tool_result}" }
}{
"event": "Stop",
"type": "agent",
"prompt": "Review the changes made in this session",
"tools": ["Bash", "FileRead", "Grep"]
}Patterns for triggering hooks:
{
"matcher": {
"pattern": "regex pattern",
"caseSensitive": false,
"source": "assistant" | "user" | "tool_result"
}
}schemas/hooks.ts)Extracted Zod schemas to break import cycles:
const BashCommandHookSchema = z.object({ ... })
const PromptHookSchema = z.object({ ... })
const HttpHookSchema = z.object({ ... })
const AgentHookSchema = z.object({ ... })
const HookMatcherSchema = z.object({ ... })
const HooksSchema = z.record(HookEventSchema, z.array(
z.discriminatedUnion('type', [
BashCommandHookSchema,
PromptHookSchema,
HttpHookSchema,
AgentHookSchema,
])
))| File | Purpose |
|---|---|
src/query/stopHooks.ts | Post-turn hook execution |
src/query/config.ts | Query config snapshot |
src/query/deps.ts | Dependency injection |
src/query/tokenBudget.ts | Token budget tracking |
src/schemas/hooks.ts | Zod hook schemas |