docs: add Agent Hooks page and recast Human-in-the-Loop as a before_tool hook

[julian-risch]

Related Issues

• Resolves the final two subtasks of deepset-ai/haystack-private#381: feat: Add Agent Hooks #11747 (Agent Hooks) and feat!: Recast HITL as before tool hook #11831 (HITL recast as a before_tool hook)
• Follow-up to docs: document AsyncPipeline task cancellation and sync streaming callbacks #11870, docs: document Pipeline.stream(), ChatPromptBuilder insert tag, and Toolset run-scoped copies #11871, docs: document Agent run metadata, runtime exit_conditions, SearchableToolset notes, and MockChatGenerator #11873, docs: add MockTextEmbedder and MockDocumentEmbedder pages #11876, and docs: document async tools, deserialization allowlist, and SkillToolset #11877 — together these six PRs cover all 16 subtasks of the tracking issue

Proposed Changes:

• feat: Add Agent Hooks #11747 Agent Hooks — new "Hooks" page under Agents: the hooks dict on Agent, the three hook points (before_llm, before_tool with its re-read-last-message semantics, on_exit with the continue_run flag and the max-steps exception), hook-point validation incl. allowed_hook_points, the reserved state keys hooks interact with (continue_run, tools, hook_context), the @hook decorator with the three-hook-points example, and class-based hooks with warm_up/close lifecycle and to_dict/from_dict serialization (LLM-judge on_exit example). Added to the sidebar between Agent and Human in the Loop.
• feat!: Recast HITL as before tool hook #11831 HITL as before_tool hook — the Human in the Loop page now frames HITL as one application of the hooks mechanism: ConfirmationHook (with its tuple-key and "*"-wildcard strategy mapping) replaces the removed confirmation_strategies Agent parameter in all examples, the Hayhooks/Open WebUI section points to the generic hook_context run argument instead of the removed confirmation_strategy_context, and a new admonition covers the behavior change that strategies see only the model-requested tool arguments (state injection happens at execution time). The Agent page's parameter list swaps confirmation_strategies for hooks and adds hook_context to the runtime arguments.

How did you test it?

• Executed against the v3 code (hatch run python), including a full offline Agent run using MockChatGenerator with one hook per hook point: verified firing counts (before_llm twice for a two-step run, before_tool and on_exit once), hook_context and tools readable from state, ValueError on unknown hook points, ConfirmationHook.allowed_hook_points failing fast under before_llm, tuple/wildcard strategy keys, and that confirmation_strategies / confirmation_strategy_context are gone from the Agent API.
• npm run build in docs-website/ passes (also catches broken links, anchors, and sidebar IDs).

Notes for the reviewer

Draft PR targeting v3. Overlap note: the State page's "Reserved keys" admonition (added in #11873) already names the hook-facing keys continue_run / tools / hook_context without linking anywhere; this PR documents them in depth on the new Hooks page. Optional follow-up once both are merged: add a link from that State admonition to the Hooks page.

With this PR, all 16 subtasks of the tracking issue have draft PRs.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have run pre-commit hooks and fixed any issue.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	Jul 5, 2026 8:27pm