Add {before,wrap,after,on_error}_{validate,execute}_output hooks to
AbstractCapability, enabling pre-parse normalization, error recovery,
and post-processing of model output across all output types.

Output hooks fire for text, structured text, and tool-based output.
For tool output, they fire inside the tool execution pipeline (tool
hooks are the outer layer, output hooks the inner layer).

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- Use processor.process() instead of accessing private _str_argument_name
  and _function_schema in TextFunctionOutputProcessor handler
- Add 8 new tests covering error paths: on_output_validate_error with
  retry, on_output_execute_error recovery, composed error hook chains,
  Hooks decorator API for error hooks, WrapperCapability delegation

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- Re-export OutputContext from pydantic_ai.capabilities
- Rename `input` param to `validated_output` in after_output_execute
  to avoid shadowing builtin
- Reuse _run_output_validate/execute_hooks in _tool_manager.py instead
  of duplicating orchestration logic
- Use RawOutput alias consistently across combined/wrapper/hooks
- Pass tool_call/tool_def as constructor args to OutputContext
- Add explicit isinstance check for UnionOutputProcessor with
  assert_never fallback
- Update docs links to point to public re-export

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- Remove unnecessary # pyright: ignore[reportPrivateUsage] comment
- Add tests for default error hook behavior (no override)
- Add tests for edge cases: dict transform, streaming, no-capability
  fast path, Hooks decorator wrap_output_execute

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- Add tests exercising default error hooks (bare AbstractCapability),
  WrapperCapability error hook delegation, and Hooks class error chaining
- Add pragma: no cover on ObjectOutputProcessor.process() error handling
  and OutputToolset.call_tool() which are now bypassed when capabilities
  are present (handled by run_output_with_hooks and _raw_execute_output_tool)

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- Simplify bad_function test helper to always raise (remove unreachable return)
- Replace unreachable error hook body with simpler test that verifies
  hooks fire without triggering errors

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

#5238)

…ols()` time

Wraps the function and output toolsets in `Agent._get_toolset` with `PreparedToolset`s
that dispatch the capability hook chain. The filtered/modified tool defs now flow into
`ToolManager.tools` (so hallucinated calls to filtered tools fail with unknown-tool
errors) and into the model's `ModelRequestParameters` simultaneously, instead of only
the latter as before.

Previously the dispatch happened in `_prepare_request_parameters` after `for_run_step`
had already built `tool_manager.tools`, so the hook only changed what the model saw —
it didn't affect tool execution lookup. Reported by Devin on PR #4859.

The output-side dispatch closure overrides `ctx.max_retries` to the agent's
`max_result_retries` to preserve the contract that `prepare_output_tools` sees the
output retry budget (#4745).

Adds a regression test asserting that a tool removed via `prepare_tools` is unreachable
even when the model hallucinates a call to it.

…rage gaps

`process()` was the legacy validate-then-call entry point on `BaseOutputProcessor`
and its subclasses, replaced everywhere in production by `hook_validate`/`hook_execute`
when output hooks landed. The two tests still calling it — covering only one branch each
of `wrap_validation_errors=False` with invalid data — left the wrap-True and success
branches uncovered. Remove the methods, update those tests to exercise `hook_validate`
directly (the path that's actually hit in production).

Also adds tests covering:
- `PreparedToolset` with a synchronous prepare function (the no-await branch in
  `get_tools`).
- The `@hooks.on.prepare_output_tools` decorator path (registration + dispatch).
- `prepare_output_tools` filtering with a real `ToolOutput` so the hook actually
  fires (the prior tests used `output_type=str`, which has no output tools).

…s additive

Reverts the breaking-change part of the prepare-tools split so existing capabilities
that override `prepare_tools` (released for ~2 weeks) keep getting the full tool
set — function + output — as documented and shipped. `prepare_output_tools` is now
a purely additive hook for output-tool-specific filtering with `ctx.max_retries`
reflecting the output retry budget (the original motivation, see #4745).

Implementation:
- `PrepareTools` capability is back to overriding `get_wrapper_toolset` (matches main),
  so the agent-level `prepare_tools=` arg sees function tools only — unchanged from
  release. The `prepare_tools` capability hook itself now dispatches via a
  `PreparedToolset` wrap on the **combined** toolset, so it sees both function and
  output tool defs and the result still flows into `ToolManager.tools`.
- `PrepareOutputTools` keeps its `prepare_output_tools` hook implementation; the
  hook is dispatched via a `PreparedToolset` wrap on the output toolset specifically
  (with `ctx.max_retries` overridden to the output budget). `Agent(prepare_output_tools=...)`
  injects a `PrepareOutputTools` capability mirroring `prepare_tools=`.

Order: `prepare_output_tools` runs first (innermost — only sees output tools),
then `prepare_tools` sees the merged list (outermost — fires after output prep).

Also updates the `prepare_tools` / `prepare_output_tools` docstrings and the
`docs/capabilities.md` / `docs/hooks.md` sections to reflect the additive shape, and
flips the `TestPrepareToolsHook` snapshot test to assert that the hook sees both
function and output tool kinds.

Per `tests/AGENTS.md` rule, agent/model/stream tests should snapshot the message
history alongside the final-output assertion. Adds `assert result.all_messages() ==
snapshot(...)` to the output validate/process error-recovery and retry-flow tests in
`TestOutputHookErrorPaths` and `TestDefaultOutputErrorHooks` so future regressions
in retry-prompt content, tool-call IDs, message ordering, etc. get caught instead of
being masked by tests that only check `result.output`.

…via PreparedToolset

`prepare_tools` capability hook now receives function tools only and
filters at the registry level (via `PreparedToolset`), matching what the
agent-level `prepare_tools=` kwarg has always done. Output tools route
exclusively to `prepare_output_tools`. The kwarg now flows through the
same hook path the capability uses (`PrepareTools.prepare_tools`),
unifying both entry points.

This is technically a behavior change — the released capability hook saw
all tools (function + output) and was visibility-only — but framing it
as a bug fix: the kwarg/hook split was inconsistent on two axes (which
tools, registry vs visibility), and we already split tool execute hooks
to skip output tools post-release. Closes #5241 (no v2 follow-up needed).

Also:
- Order: `prepare_tools` wraps **inside** other capability
  `get_wrapper_toolset` results (e.g. `ToolSearch`, `CodeMode`),
  preserving main's kwarg ordering — toolset transformations layer on
  top of prepared defs.
- Pass `include_context=False` to `ValidationError.errors()` for output
  retry prompts, matching tool retries — drops the duplicative `ctx`
  field from `RetryPromptPart` content.

…ests

Output retry prompts now use `include_context=False`, matching tool
retries — drop the now-stale `ctx` entries from existing provider
snapshots.

…Tools`/`PrepareOutputTools`

`PreparedToolset.get_tools` already rejects added/renamed tools and
normalizes `None` to an empty list. The capability hooks just need to
normalize sync/async `prepare_func` calls — collapse the helper to that
and let the toolset wrap handle validation.