Agent router

Use the repository's pinned ai-cli-mcp@2.22.0 server for external-model work. Do not launch provider CLIs directly when the MCP server can do the job: the server owns background process tracking, session IDs, result retrieval, and provider-specific argument validation.

Every run is resumable. Start it with run, retain the returned PID, use peek only for a bounded progress sample, use wait or get_result for the authoritative outcome, and resume with the returned session_id when a provider fails or the user asks for another pass. A one-off task is still started in the background; wait immediately afterward is the blocking recipe.

Setup and health check

Before using a new checkout or machine:

1. Confirm package.json pins ai-cli-mcp exactly and pnpm-lock.yaml contains the same version.
2. Confirm root .mcp.json and .codex/config.toml invoke workspace-local pnpm exec ai-cli-mcp; never substitute an unpinned npx download.
3. Run pnpm exec ai-cli models and retain the structured output as the model-routing fact for this run.
4. Run pnpm exec ai-cli doctor for binary availability. It does not prove login, terms acceptance, quota, or provider health, so check those with the provider's own status command when a run needs them.
5. Reload/restart the MCP client after adding or changing .mcp.json or .codex/config.toml. Confirm that the ai-cli MCP tools (models, run, wait, get_result) are present in the active tool registry.
6. Perform a small background smoke run through those MCP tools in an isolated temporary worktree, wait for it, and verify that a non-empty result includes a session ID. Resume that session with a second tiny prompt before declaring the router healthy.

pnpm exec ai-cli run is useful for diagnosing the pinned package and provider authentication, but it is only the CLI façade and does not validate the MCP transport. If the MCP server is not visible to the host client, inspect Codex with codex mcp get ai-cli and Claude with claude mcp get ai-cli, then reload the client. A missing server is a setup failure; do not report the CLI façade as an MCP smoke test or fall back silently to direct provider CLIs.