feat: add HooksManager lifecycle hook system to callModel

[mattapperson]

Summary

• Adds an extensible hook system for callModel inspired by the Claude Agent SDK hooks pattern
• Two usage modes: inline config (plain object for quick setup) and HooksManager class (custom hooks, dynamic registration, programmatic emit)
• 8 built-in hooks: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, PermissionRequest, SessionStart, SessionEnd
• Features: tool matchers (string/RegExp/function), filter predicates, mutation piping, short-circuit on block/reject, async fire-and-forget handlers, configurable error handling
• Custom hook definitions via Zod schema pairs with full TypeScript autocomplete
• Additive API — existing onTurnStart, onTurnEnd, requireApproval remain unchanged

Re-creation of OpenRouterTeam/openrouter-web#16735 on the standalone agent SDK repo.

Test plan

• 35 new unit tests across 4 test files (matchers, emit engine, manager class, resolver)
• All 186 unit tests pass
• Build (pnpm build) passes cleanly
• Lint (pnpm lint) passes cleanly
• E2E testing with real API calls (PreToolUse block, mutation piping, Stop forceResume)

---

[mattapperson]

reviewed, no issues found

[robert-j-y]

1. SessionEnd fires on exactly one code path: a completed run that had tools AND made at least one tool call AND didn't throw.

packages/agent/src/lib/model-result.ts:1985-2184 — the execute IIFE has no try/catch/finally (grepped: only two try blocks in the file, at line 1587 and 2758, both unrelated). The only SessionEnd emit is at line 2178, at the very bottom, after four unconditional early returns:

• line 1990: resuming from approval, still pending
• line 2007: !this.options.tools?.length || !hasToolCalls — a plain chat response with no tool calls never emits SessionEnd
• line 2015: paused for approval
• line 2021: no executable tool calls

Plus any throw in the loop (tool exec, hook emit, state save, followup request) rejects the promise and skips SessionEnd + hooksManager.drain(). SessionEndPayload.reason at hooks-types.ts:177 declares 'user' | 'error' | 'max_turns' | 'complete'; only 'complete' is ever emitted, and then only on the happy-tool path.

Fix: wrap the IIFE body in try { ... } finally { if (this.hooksManager) { await this.hooksManager.emit('SessionEnd', { sessionId, reason }); await this.hooksManager.drain(); } }, and pick reason based on exit path ('complete' on normal end, 'error' in the catch, 'max_turns' when the loop exits via shouldStopExecution without a Stop override).

2. Stop payload reason is hardcoded to 'end_turn' — verified as the only emit site.

model-result.ts:2043-2046:

const stopResult = await this.hooksManager.emit('Stop', {
  reason: 'end_turn' as const,
  sessionId: this.currentState?.id ?? '',
});

Grepped the whole file: one Stop emit site. StopPayload at hooks-types.ts:154 declares 'end_turn' | 'max_tokens' | 'stop_sequence' — the other two are unreachable. Also: shouldStopExecution() fires off arbitrary stopWhen conditions (default stepCountIs(DEFAULT_MAX_STEPS)), which semantically is closer to 'max_turns' than 'end_turn'. The three enum values are Anthropic-style stop reasons and don't cleanly map to this engine's stop causes.

Fix: either derive reason from the actual cause (stop-condition name vs. response finish_reason) and expand the schema to cover step-count/tool-absence cases, or drop the two unreachable variants until they're wired.

3. forceResumeCount is a lifetime counter; comment says "without new progress".

model-result.ts:2031 declares let forceResumeCount = 0; outside the while. Only mutation is forceResumeCount++ at line 2083. Never reset. So a Stop hook that force-resumes at turn 2, runs 50 clean turns, force-resumes at turn 53, runs 50 more, force-resumes at turn 104 — gets cut off on the third call despite 100 turns of real progress in between.

The console.warn at line 2079 asserts "forceResume honored 3 times without new progress", which the code does not enforce.

Fix: either reset forceResumeCount = 0 at the top of each while iteration that doesn't enter the shouldStopExecution() branch, or change the warning text and the comment at 2026-2030 to say "3 times total this session".

[mattapperson]

reviewed, no issues found

[mattapperson]

Adversarial pass surfaced seven issues across the emit engine, matcher layer, and SessionStart/End pairing.

[mattapperson]

Reviewed the hooks engine and model-result integration; 5 concerns worth a second look on abort semantics, argument normalization, parse-error handling, clone depth, and timer lifetime.

[mattapperson]

reviewed, no issues found