fix(proxy/ccr): self-heal dangling headroom_retrieve reference after …

[nangsontay]

…model switch

Switching models mid-session (/model in Claude Code) or restarting the proxy rotated the model-scoped in-memory sticky session key, so the proxy stopped injecting headroom_retrieve while the client transcript still carried a tool_reference naming it — Anthropic 400'd every subsequent turn ("Tool reference 'headroom_retrieve' not found in available tools").

Injection now self-heals from the transcript: transcript_references_ccr_tool scans about-to-forward messages for a bare headroom_retrieve in anthropic tool_reference/tool_use blocks (one level of nesting) or an openai-chat assistant.tool_calls entry, and a new transcript_requires_tool flag forces (re-)injection through should_inject_ccr_tool and apply_session_sticky_ccr_tool (decision inject_transcript_recovery), recording sticky state so subsequent turns resume normal sticky replay. Exact bare-name match only, so a client-owned mcp__headroom__headroom_retrieve never triggers proxy injection. The openai /v1/responses path never proxy-injects the tool, so recovery is N/A there.

Description

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

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

# Paste relevant command output or artifact links here

Real Behavior Proof

• Environment:
• Exact command / steps:
• Observed result:
• Not tested:

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 did not edit CHANGELOG.md — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

Screenshots (if applicable)

Add screenshots to help explain your changes.

Additional Notes

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Description with a real summary of the change.
• Replace the placeholder bullets in Changes Made with the actual changes.
• Check at least one box in Type of Change.
• Check at least one verification item in Testing.
• Paste real command output or artifact links in Testing → Test Output.
• 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.
• Check I have performed a self-review before requesting human review.
• Check This PR is ready for human review or convert the PR back to draft.

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