docs: point agents at the shared MCP session and end-user retry helpers

GL
3d ago
+5-1

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) and retry_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 httpx2 under 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)

GateResult
Forgenot run: docs only, no code
Security scan / Codex security / /security-reviewnot run: docs only
/code-reviewnot run: docs only; claims checked by hand above
Demono 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 and retry_for_end_user() for end-user retries as the single places for each concern.
  • The dependency note records that the MCP transport runs on httpx2 under mcp 2, which requires it itself, so it is not declared as a core dependency.

Docs only, no code change and no release.