docs: point agents at the shared MCP session and end-user retry helpers
What
Two lines in CLAUDE.md (and AGENTS.md, its symlink) catch up with #261 and #274, both now on main:
- "Modifying Tool Behaviour" names
_run_mcp_session()(transport, deadline and failure mapping for every list and call) andretry_for_end_user()(the one retry after an end-user refusal), the two helpers #261 introduced. - The dependency-tier note says the MCP transport runs on
httpx2under mcp 2 and why it is not declared: mcp 2 requires it itself. A reviewer flagged the undeclared import as a breach of this note during #274; this records the decision so the next agent does not "fix" it.
Why
A second review pass over #261, now shipped inside #274's squash, found no code issue. The only stale material was this guidance file.
How verified
Each claim checked against stackone_ai/tools.py on main: both helpers exist and every listing and call goes through them. GET /accounts uses the httpx client, and the MCP transport uses _mcp_http. The examples and README needed no change: none uses the changed internals, and MIGRATION.md's end-user section still matches the code.
Gates (head dd51301)
| Gate | Result |
|---|---|
| Forge | not run: docs only, no code |
| Security scan / Codex security / /security-review | not run: docs only |
| /code-review | not run: docs only; claims checked by hand above |
| Demo | no runtime change, no demo |
Post-merge validation
None needed: no release (docs does not trigger release-please).
Requested by guillaume@stackone.com in Slack (repo audit thread).
🤖 Generated with Claude Code
Summary by cubic
Updates the agent-facing guidance in CLAUDE.md to match the shared MCP session and end-user retry helpers now on main.
- "Modifying Tool Behaviour" now names
_run_mcp_session()for MCP session setup andretry_for_end_user()for end-user retries as the single places for each concern. - The dependency note records that the MCP transport runs on
httpx2under mcp 2, which requires it itself, so it is not declared as a core dependency.
Docs only, no code change and no release.