feat(modelerrors): surface structured provider error details on non-2xx responses

[dgageot]

What

Adds the four lifecycle hook events that Claude Code, OpenCode, and pi all expose but docker-agent did not, plus a small documentation fix.

Why

While auditing how docker-agent's hook system compares to peer AI coding agents, four events stood out as universally supported by competitors but missing from us. Each one unlocks a real use case that today either has to be hacked in via pre_tool_use/on_user_input or simply isn't possible.

New hook events

Event	When it fires	Can shape behaviour?
user_prompt_submit	Once per real user message in RunStream, after session_start and before the first model call. Skipped for sub-sessions (whose kick-off message is synthesised by the runtime).	Block submission, or contribute transient additional_context for that turn.
pre_compact	Inside summarizeWithSource before context compaction. Trigger source (manual / auto / overflow / tool_overflow) is reported in Input.Source.	Cancel compaction, or append guidance to the compaction prompt.
subagent_stop	After runSubSessionForwarding and runSubSessionCollecting complete — success or failure (deferred dispatch).	Observational.
permission_request	Inside askUserForConfirmation just before the runtime would prompt the user.	Auto-allow (skip the prompt) or auto-deny (permission_decision: allow / deny), mirroring pre_tool_use. Returning nothing falls through to the interactive confirmation.

Also fixed

• post_tool_use doc / schema / example wording: it fires on both success and failure, with tool_response.is_error distinguishing them. The previous "after a tool completes successfully" claim was wrong.
• EventPermissionRequest's doc comment now spells out the asymmetry with pre_tool_use (where allow is the implicit default vs. permission_request where it's an explicit auto-approve verdict). That's why Result.PermissionAllowed exists separately from Result.Allowed.

Files touched

• pkg/config/latest/types.go — 4 new fields on HooksConfig + validation
• pkg/hooks/{types,executor,config}.go — 4 new EventType constants, Result.PermissionAllowed, Input.{Prompt, AgentName, ParentSessionID}, executor wiring
• pkg/runtime/{hooks,loop,runtime,agent_delegation,skill_runner,tool_dispatch}.go — dispatch helpers and call-site integration
• agent-schema.json, examples/hooks.yaml, docs/configuration/hooks/index.md — schema, example yaml demonstrating all events, and user-facing docs

Testing

• 7 contract tests in pkg/hooks/contract_widening_test.go pin the wire format for every new event (block-produces-deny, allow-produces-permission-allowed, fields-reach-the-hook, …).
• 2 runtime tests in pkg/runtime/user_prompt_submit_test.go pin the gating contract: fires-once for top-level submissions, never for sub-sessions (SendUserMessage=false).
• The example examples/hooks.yaml parses through config.Load and validates against agent-schema.json.
• mise run lint → 0 issues. go test -count=1 ./... → 0 failures across ~150 packages.

Commits

1. feat(hooks): add 4 new hook events to match Claude Code / OpenCode / pi — the feature
2. refactor(hooks): simplify the call sites added for the new events — small in-place readability cleanup (merge duplicated guards, switch on PermissionDecision, stop double-decoding tool args, take *agent.Agent directly instead of name + lookup)
3. fix(hooks): address review findings on the new hook events — subagent_stop now fires on the error path of both sub-session helpers (defer); EventPermissionRequest doc clarification; examples/hooks.yaml jq-dependency note; user_prompt_submit gating regression test

Backward compatibility

• The four new fields on HooksConfig are all omitempty; existing configs continue to parse unchanged.
• Summarize's public signature is unchanged; internal call-sites use a private summarizeWithSource to attribute the trigger to pre_compact hooks.
• runSubSessionForwarding's parameter list changed (string → *agent.Agent) but the function is package-private; both call-sites updated.