feat(proxy): add turn-hook extension point for buffered model turns

[chopratejas]

Description

Adds a small, neutral extension point to the proxy: a "turn hook" that lets an opt-in extension observe and optionally re-drive a single buffered model turn, without touching the core request/response flow for anyone who has no extension installed.

A hook can:

• on_request(ctx) — inspect or rewrite the outbound tools/messages before they go upstream (the extensible counterpart to the built-in tool-search deferral that already lives at that point).
• on_response(ctx, response, call_model) — inspect the model's response and, if it wants, call the model again (via call_model) and return a replacement response — transparently to the client. This is the capability that can't be done from ASGI middleware: it reuses the proxy-internal re-call path (the same api_call_fn the CCR handler already drives).

The module is inert unless a hook is registered: the runners return their input unchanged and are gated on the registry, so with no extension the proxy is byte-identical to today. A failing hook is logged and skipped — it can never take the proxy down.

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• Add headroom/proxy/turn_hooks.py: TurnContext, the TurnHook protocol (on_request / on_response), a module registry (register_turn_hook / registered_turn_hooks / clear_turn_hooks), and the runners run_request_hooks / run_response_hooks. Inert when empty; never raises.
• Wire it at four seams, each gated so an empty registry is a byte-identical no-op:
  • Anthropic — pre-send (right after the existing tool-search deferral) + the CCR response seam.
  • OpenAI — the Responses tool-shaping point (right after the existing tool-search deferral, copy-on-write-safe) + the CCR response seam.
• Add tests/test_turn_hooks.py.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed (no-op regression across CCR/handler suites)

Test Output

$ ruff check headroom/proxy/turn_hooks.py tests/test_turn_hooks.py \
      headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py
All checks passed!

$ ruff format --check <same 4 files>
4 files already formatted

$ mypy headroom
Success: no issues found in 408 source files

$ pytest tests/test_turn_hooks.py -q
9 passed in 0.17s

$ pytest tests/test_turn_hooks.py tests/test_ccr_response_handler.py \
      tests/test_ccr_tool_injection.py tests/test_proxy_ccr.py \
      tests/test_openai_tool_search_deferral.py \
      tests/test_openai_responses_compression_units.py \
      tests/test_handler_outcome_tag_invariant.py -q
135 passed  (+ 1 pre-existing cross-file flake in test_proxy_ccr::test_health_endpoint,
             which passes in isolation and in its own file: `pytest tests/test_proxy_ccr.py` -> 19 passed)

Real Behavior Proof

• Environment: local macOS, project .venv (Python 3.12.6); ruff pinned to CI's 0.15.17 via uvx ruff@0.15.17; mypy from the venv.
• Exact command / steps: branched off upstream/main; added the hook module + wired the four handler seams; ran the ruff/format/mypy/pytest commands above.
• Observed result: The unit tests exercise the whole contract — registry, on_request mutating ctx.tools, on_response returning a replacement, the await call_model(...) re-drive loop, replacement-chaining across hooks, and the never-raise guarantee. The existing CCR + handler suites pass unchanged, which is the point: with no hook registered the added code is a no-op (the runners short-circuit on an empty registry).
• Not tested: the live interactive re-drive path with a registered hook against a real upstream — no hook ships in this repo, so that path is covered here only by the unit test's fake call_model. The on_request seam fires on the Anthropic pre-send and OpenAI Responses paths (where the existing tool-search deferral runs); other send paths (e.g. chat-completions, streaming) are not wired in this PR.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated the CHANGELOG.md if applicable

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Real Behavior Proof → Environment.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.

Please update the PR body, or move the PR back to draft while it is still in progress.