feat(coinbase-mcp): add agent controls guidance for orders and payments

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.0.2 — Unreleased
 
+- Add guidance for `coinbase_agent_controls_get` in `coinbase-mcp`: read the user's spend limits and pause status before previewing an order or paying for research, treat an `unknown` pause as possibly paused, and never work around a spend-limit or paused refusal. The guidance applies only where the server exposes the tool.
 - Ship only the shared router and `coinbase-mcp` in the ChatGPT distribution. Omit `coinbase-mcp/references/x402.md`, because `/mcp/chatgpt` does not expose x402 tools, and give ChatGPT its own package README.
 - Let a distribution omit selected skill files and drop source lines marked `<!-- omit: <distribution> -->`. Other distributions still copy skills unchanged, and links to unselected skills or omitted files fail the build.
 - Remove x402 from the ChatGPT listing copy and keywords, and replace its starter prompt with three prompts for portfolio review, rebalancing, and scaling in with limit orders.

skills/coinbase-mcp/SKILL.md

@@ -34,6 +34,7 @@ Client registration, Coinbase client approval, user consent, OAuth scopes, and p
 - Follow response pagination; use only fields supported by that tool, not those of a similarly named CLI command.
 - These skills target the core remote tool contract. A client-specific adapter may replace tools with confirmation-card flows. If discovery/server instructions require a signed confirmation token or widget action, use that client flow; do not synthesize tokens or call widget-only financial tools directly.
 - Write gates, feature flags, OAuth grants, and product eligibility can reject a discoverable tool. Preserve the denial; it is not a reason to switch credentials or bypass the selected client.
+- The user can set spend limits and an automatic stop that pauses the app. Where exposed, `coinbase_agent_controls_get` reads them before an order or payment (see [Trading](references/trading.md)). A spend-limit or paused refusal is the user's control: report it and do not split or reroute the action to get around it; a smaller order needs the user's fresh approval.
 - For 401, use native refresh/reconnect; for missing scopes, request consent. Do not silently use CLI credentials.
 - For 429, honor `Retry-After` and use bounded backoff. For unknown write outcomes, use authorized state reads and the original supported idempotency identifier; stop if unresolved.
 - Remote MCP can chain multiple calls but does not expose the CLI's WebSocket watch/stream flags. Do not invent a subscription or replace one with tight polling.

skills/coinbase-mcp/references/trading.md

@@ -5,6 +5,7 @@ First follow [Coinbase MCP setup and safety](../SKILL.md). Use only Coinbase MCP
 ## Plan, preview, authorize, submit, verify
 
 1. Discover the exact product, intended portfolio, available funds/positions, current size/price limits, and supported order fields. Honor the requested quote currency; never substitute BTC-USD for BTC-USDC. Ask if the currency or portfolio is ambiguous.
+   If the server exposes `coinbase_agent_controls_get`, read the user's agent controls before previewing. If `pause_status` is `yes`, stop and tell the user to resume the app; do not try other order types or products. Treat `unknown` as possibly paused, not as `no`. Compare the planned order with each `order` limit: `max` for `per_order`, and `remaining` for `rolling`. A snapshot can go stale and does not authorize the order; it can still be refused when submitted. An empty `limits` list does not mean trading is allowed.
 2. Establish product, side, size and units, portfolio, order type, price/trigger, time in force, expiry, and applicable session. Resolve relative prices from current data and confirm the absolute value.
 3. Preview supported orders and disclose estimated fees, price/slippage, and relevant risk. Preview is not authorization. If a required preview is unavailable, stop; never create an order to test it. Load [equities](equities.md) or [futures](futures.md) before planning those products.
 4. Obtain approval for the complete order. Generate and retain a unique `client_order_id` before submission; never reuse it for a different logical order. Keep it available if the response is lost.
@@ -30,6 +31,7 @@ No CLI or API key is needed. Discover current schemas and the host's actual name
 | Step | Core tools |
 | --- | --- |
 | Resolve scope, funds, and product | `coinbase_portfolios_list`, `coinbase_portfolios_get`, `coinbase_balance`, `coinbase_products_list`, `coinbase_products_get` |
+| Check the user's spend limits and pause status, where exposed | `coinbase_agent_controls_get` |
 | Estimate a new order | `coinbase_orders_preview` |
 | Submit an approved order | `coinbase_orders_create` |
 | Verify order and fills | `coinbase_orders_get`, `coinbase_orders_list`, `coinbase_orders_fills` |

skills/coinbase-mcp/references/x402.md

@@ -5,7 +5,7 @@ First follow [Coinbase MCP setup and safety](../SKILL.md). Use only Coinbase MCP
 ## Discover, authorize, fetch, report
 
 1. Search the curated resource catalog without spending. Use its actual resource URL, provider, advisory price, and input schema; never invent endpoints or fields.
-2. Establish an explicit research budget and approved resources before payment. General research, connection approval, or a trading request is not unlimited research spending authority.
+2. Establish an explicit research budget and approved resources before payment. General research, connection approval, or a trading request is not unlimited research spending authority. If the server exposes `coinbase_agent_controls_get`, check its `x402_payment` limits and `pause_status` first; they can be stricter than the budget the user gave you.
 3. Generate and retain an `idempotency_key` UUID before each logical payment. Prefer the fetch operation with the discovered URL, flat resource parameters inside `input`, and a `max_amount` within the remaining budget. Do not replace the resource inputs with a hand-built HTTP request.
 4. Inspect `paid`, payment identifiers/expiry, and `data` separately. Report the resource/provider only as identified by returned information. The audited fetch response does not expose an exact debited amount or settlement receipt: report the approved cap separately, do not label it actual spend, and do not treat `paid=true` as proof of settlement. Conservatively reserve the authorized per-request cap against the remaining research budget until reliable payment evidence reconciles it; keep an unknown-outcome reservation rather than freeing it for another purchase.