Spike: cli/claude-code provider adapter + PATH discovery

[suleimansh]

Part of #495.

Wire one provider end to end so the estimate for the rest is real.

• discover.ts: probe PATH for the claude-code CLI via the local runner, resolve to an absolute path, read --version. Candidate model like Traycer (path / custom / bundled).
• cli/claude-code ProviderAdapter in ai-sdk: spawn the CLI in headless/print mode (claude -p), map generate/stream to its stdin/stdout, register under AiRegistry as cli/claude-code.
• Prove it: an autopilot worker with model string cli/claude-code runs a subtask with no API key set.

Two things this spike answers:

• exact headless invocation per CLI (claude-code has -p; codex/gemini TBD)
• whether tool-calls round-trip through the CLI, or we keep tools on our side and use the CLI for generation only

Gated on Rom's go on #495.

[suleimansh]

De-risked the headless part locally. claude-code maps ~1:1 onto our ProviderAdapter:

• generate(): claude -p --output-format json -> parse .result
• stream(): claude -p --output-format stream-json --input-format stream-json
• instructions -> --append-system-prompt, model -> --model, structured output -> --json-schema

Smoke test proves the BYOS premise: ran with NO ANTHROPIC_API_KEY (pure subscription auth), got clean JSON back with the result, a full token-usage block (maps onto our TokenUsage), total_cost_usd, and a session_id (lines up with our conversation-continuation seam for free).

So the claude-code adapter is a thin wrapper, not a research project. Remaining unknown is only the other CLIs: codex + gemini aren't installed here, so their headless flags (equivalent of -p / --output-format json) still need a check before we widen discovery.

Waiting on the go for #495 + the config-location call, then I'll build discover.ts + the claude-code adapter.

[suleimansh]

Spike done (throwaway, findings only, nothing committed). It works, and I picked the wrong seam. Short version:

It works. agent({model:'cli/claude-code'}).prompt(...) returns the right answer in ~5s with no ANTHROPIC_API_KEY set. Discovery resolves claude on PATH to an abs path and reads --version. Usage maps cleanly onto our TokenUsage. So the BYOS premise is fine.

Wrong seam. I told you BYOS was a new ProviderAdapter plus discovery. Our adapter contract is tools-in / tool-calls-out, with the agent loop executing them. That's model-shaped. Claude Code isn't a model, it's an agent that owns its own tool loop. Verified directly: told it to read a file, and the stream shows tool_use -> tool_result -> text all executed inside the CLI. We watch the trace, we never service it.

So an adapter can only be generation-only (--tools "", proven working), which throws away the agent and pays subscription prices for text completion while autopilot's loop redoes the work. And it doesn't generalize: codex and gemini have no tools-off flag at all, only sandbox/approval modes. The one shape that fits ProviderAdapter fits exactly one provider.

These CLIs are peers of a worker, not peers of a model. Of the two plug points I named on #495, it's Runner. I named the wrong one.

Separate finding, bigger than this spike. Every --output-format stream-json run emits this for free. No /api/oauth/usage, no polling, no 429 exposure:

{"type":"rate_limit_event","rate_limit_info":{
  "status":"allowed","resetsAt":1784079000,"rateLimitType":"five_hour"}}

The 2.1.210 binary has status = allowed|allowed_warning|rejected and rateLimitType = five_hour|seven_day|seven_day_opus|seven_day_sonnet|weekly. I only observed allowed/five_hour at runtime, the rest are strings in the binary, so treat that as strong evidence and not proof.

If allowed_warning fires the way the name implies, "don't fire when low" is buildable off the free stream with no private endpoint. What it does not carry is usedPercent, which is all the private endpoint actually buys. resetsAt also removes the brittle part of fire-then-backoff (no parsing reset times out of error strings). This supersedes the caveat I posted on #298, worth re-checking before that lands as plan.

Headless flags confirmed for all three (codex exec --json, gemini -p -o stream-json), so widening discovery is cheap. codex and gemini runtime is unverified, both are unauthed here.

Now that it's concrete: BYOS at the worker/runner level, or park it? The adapter version isn't worth building.

[suleimansh]

Spike done and superseded by the real thing: the seam turned out to be the Driver, not the ai-sdk adapter, and it shipped as CodexDriver (#541) plus --agent (#543).