feat(llm): run keyless on Claude Code login — claude-code provider + chat floor

[pgsharma]

What

You asked to use Claude Code as metalworks' model — no API key, as the default. This adds a claude-code provider (ClaudeCodeChatModel over the Claude Agent SDK) that runs completions through the bundled claude CLI using your existing Claude Code login, and makes it the keyless chat floor: when no key / ref / METALWORKS_MODEL is configured and the SDK + CLI are present, resolve_chat() falls back to it instead of raising MissingKeyError — the chat analogue of how embeddings already fall back to the local model. Any explicit key/ref still wins.

Verified live (keyless, no API key): complete_text → "Tokyo.", complete_structured → {city, country} (native), and the floor via resolve_chat() → ClaudeCodeChatModel → "Paris."

Why not MCP sampling

The cleaner "host does the inference" path (MCP sampling) is not supported by Claude Code — tracked in #1785 and closed "not planned" in #31893. The Agent SDK (subprocess) is the only viable keyless path.

Changes

• llm/adapters/claude_code.py (new) — non-agentic completion (allowed_tools=[], max_turns=1, permission_mode="bypassPermissions"); native structured via the SDK's output_format json_schema → ResultMessage.structured_output, with the schema-in-prompt ladder as fallback; an async→sync bridge (one shared daemon event loop + run_coroutine_threadsafe) so the sync, thread-pooled ChatModel protocol drives the async-only SDK; SDK errors mapped to actionable MetalworksError.
• config.py — claude-code in _NATIVE_PROVIDERS; resolve_chat dispatch; _claude_code_available() (find_spec + shutil.which, no subprocess, no env read) gates the floor right before the final MissingKeyError, which now also names the metalworks[claude-code] option.
• pyproject.toml — claude-code = ["claude-agent-sdk>=0.2.110"] (+ in all).
• tests (test_claude_code_adapter.py, new) — fully offline via a fake SDK module: text, native structured, prompt fallback, is_error, non-agentic options, alias strip, MissingExtraError, and the concurrent bridge (12 calls through a thread pool); plus floor resolution (engages / key-wins / unavailable-raises / claude-code/opus ref).
• docs + CHANGELOG — with the honest trade-offs (spawns the CLI ~5–7s/call; uses your individual subscription; ToS note on distributed use).

Honest trade-offs (in the docs)

• Spawns the bundled claude CLI per call (~5–7s/call) — the keyless convenience path, not the fast one. A key is faster for a many-call research run.
• Uses your individual Claude Code subscription. Anthropic restricts offering claude.ai login in distributed products, so this is for local/individual use, not shipping a multi-user service on one subscription.

Gate

ruff check · ruff format --check · pyright (0 errors) · gen_ts_types.py --check PASSED · import metalworks stays free (SDK lazy-imported). Full suite 1188 passed clean-room (the 1 local failure is the pre-existing wedged-~/.metalworks/store.db disk I/O error from stale MCP servers — unrelated; touches nothing in llm//config). No version bump — tagging left to you.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
metalworks	🟢 Ready	View Preview	Jun 26, 2026, 12:46 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.