hooks: align the hook contract with Claude Code (plain-text stdout, stop_hook_active, timeout unit, matchers, common input)

Summary

qwen-code's hooks engine is structurally on par with Claude Code's: event dispatch, multi-hook aggregation, HTTP hook hardening, the Stop-hook block cap and process-tree cancellation are all in place, and a few pieces (sequential chains, parent-exit-surviving hooks, two-phase Todo hooks) go further. But a hook script written against Claude Code's documented contract silently misbehaves on qwen-code in a handful of places. This issue tracks closing those gaps, together with the small consistency items found in the same audit (upstream/main compared with Claude Code 2.1.267).

Compatibility breaks

1. Plain-text stdout on exit 0 never reaches the model. The command runner turns it into systemMessage, while the SessionStart and UserPromptSubmit consumers only read hookSpecificOutput.additionalContext, and systemMessage is not shown anywhere outside the Stop path. An echo "context" SessionStart hook is therefore a silent no-op. Claude Code hands that text to the model as additional context.
2. stop_hook_active is hard-coded to true on every Stop event, both in the core client and in ACP sessions. A Stop hook that follows the usual guidance ("return success while stop_hook_active is true, so you do not loop forever") never blocks at all.
3. The timeout unit is inconsistent. Command hooks treat it as milliseconds with a 60000 default, http and prompt hooks treat it as seconds, the settings schema says seconds, and the user docs say both. Claude Code uses seconds everywhere with a 600 s default. A Claude Code config with "timeout": 10 times out after 10 ms here.
4. Matcher semantics differ per event. Notification, PreCompact, PostCompact and StopFailure only accept one exact string, so "permission_prompt|idle_prompt" never matches; session-scoped hooks anchor their regex while settings hooks do not. Claude Code applies one rule to every event.
5. The common hook input lacks permission_mode, agent_id, agent_type and prompt_id, and PostToolUse lacks duration_ms, so scripts that branch on these cannot be ported.
6. Exit code 2 ignores JSON on stdout. Not a gap after all: checked against the current Claude Code release, exit code 2 always blocks with the stderr reason there too, which is what qwen-code does.

Consistency items

• The settings schema lists 17 of the 22 hook events; PostCompact, PermissionDenied, TodoCreated, TodoCompleted and InstructionsLoaded are missing although the runtime accepts them.
• The MessageBus hook dispatch handles 14 of the 22 events and logs "Unknown hook event" for the rest.
• Dead code: TrustedHooksManager is never instantiated, HttpHookConfig.if is never read, and unregisterSkillHooks is a no-op.
• The hooks user guide omits InstructionsLoaded, UserPromptExpansion, PostToolBatch, StopFailure and PostCompact, still says "when Claude prepares to conclude response", and describes async hook output delivery that is not wired up.

Decision: timeout migration

timeout becomes seconds for every hook type, with a default of 600 s for command and http hooks (prompt hooks keep 30 s). To keep existing configs working, a command hook timeout of 1000 or more is interpreted as legacy milliseconds and a one-time warning is logged. SDK-registered function hooks keep milliseconds, since they are not configured through settings. Update: #11615 keeps the command-hook default at 60 s, because a longer default needs cancellable hook requests on the message bus; raising it to 600 s is tracked in #11688.

Plan

Each item is an independent PR and they can land in any order; the docs rewrite lands last.

• Plain-text stdout becomes additionalContext for SessionStart / UserPromptSubmit / UserPromptExpansion: #11612. Exit code 2 is left unchanged (see item 6 above).
• Report the real stop_hook_active: #11613
• Read command hook timeout in seconds, keeping the 60 s default (600 s tracked in #11688): #11615. The legacy-millisecond reading applies to command hooks only, because HTTP and prompt hooks already used seconds.
• Add permission_mode / agent_id / prompt_id to the common input and duration_ms to PostToolUse and PostToolUseFailure: #11618. agent_type stays on SessionStart, SubagentStart and SubagentStop for now, because the agent context only tracks the id.
• Apply one matcher rule to every event: #11619. Existing unanchored-regex matchers keep their meaning instead of switching to Claude Code's exact-name rule for plain words, which would silently narrow them.
• Cover every hook event in the settings schema and hook bus: #11620. The five events it adds to the schema now concatenate across scopes in the merged settings like the other events. Hook registration already reads user and workspace hooks per scope, so the change only shows where a scope without any hooks object falls back to the merged value.
• Remove the unused trusted hooks manager and implement unregisterSkillHooks: #11621. HttpHookConfig.if stays because it is part of the daemon status and SDK types; evaluating it is follow-up work.
• Rewrite the event catalog in the hooks user guide: opens after the PRs above merge, since they edit the same guide. It also states that plain-text promotion applies to command hook stdout only, so HTTP hooks must return JSON additionalContext.

Observability (a running-hook indicator, surfacing hook errors and timeouts in the UI, delivering async hook output) and further feature parity (new events, if / once on every hook type, agent and mcp_tool hooks) will be tracked separately.

Acceptance

The three canonical Claude Code hook examples work unchanged on qwen-code: a SessionStart hook that echoes context, a Stop hook that checks stop_hook_active before blocking, and a PreToolUse hook with "timeout": 10.