Claude Code adapter

claude_adapter.py is a local, explicit session adapter, not an account or pricing bypass. It uses the installed Claude Code executable and the user's configured authentication. Authentication and session availability depend on the target machine. A probe does not make a model call.

• probe() reports the version and whether CLI auth reports signed in, without returning credential values. A sign-in or configured provider is not proof of a free entitlement.
• list_sessions(project_dir) uses claude agents --json --all --cwd <project> and checks the reported cwd exactly. It returns IDs and status fields, never summaries or prompts. CLI coverage is active sessions and completed background sessions, not all historical interactive sessions. Where claude_agent_sdk is installed, its supported list_sessions(directory=...) adds matching saved metadata. The SDK reads portions of local session records internally; the adapter does not copy or return transcripts. Metadata without an exact working directory is omitted.
• start_session(project_dir, prompt, authorized=True, model_use_authorized=True) starts a new session with a generated UUID only when a user has explicitly requested it and authorized model use under the account's actual budget/provider. It returns that UUID even if the result is unknown, so an uncertain attempt is not replayed. Prompt text is delivered through an ephemeral OS temporary file as stdin, not shell arguments. For real model turns, stdout and stderr are discarded so output cannot grow without bound or break when the supervisor stops waiting. A supervisor wait timeout leaves the Claude process running and returns its session ID and PID; Claude retains control of its own rate-limit behavior. The adapter does not guarantee survival across MCP, host or OS termination.
• resume_session(project_dir, session_id, prompt, authorized=True, model_use_authorized=True) requires a full UUID verified for the exact project. It requires the native listing to confirm a background session in done, failed or stopped state with no PID, live status or waiting indicator. SDK-only history or unknown state is insufficient. It also refuses duplicate IDs and project entries without a verifiable UUID. Claude's own --resume searches other projects, hence the additional local check. The check and start are not atomic against another process; do not use this adapter as an unattended retry scheduler or run concurrent starts against the same session.
• Real start/resume returns running_unobserved if the supervisor wait expires without stopping the worker, finished_unverified if the process exits, or unknown if waiting fails after launch. No exit code proves task completion; check the native session or authorized SDK summary afterward. Direct CLI output cannot be returned in this detached-safe path, even if include_outcome=True. Fake-runner tests can exercise bounded JSON result handling, but that is not a real Claude outcome. There is no automatic retry or rate-limit intervention.
• session_status(project_dir, session_id) reports a fresh sanitized snapshot for a verified project/session. stop_session(project_dir, session_id, authorized=True) requests a stop only for a verified background session with a safe native short ID and explicit human authorization. Success is only stop_requested; check status to confirm, and treat timeout/failure as unknown.
• read_session_summary(project_dir, session_id, authorized=True) uses the optional SDK for a project-verified, bounded summary, custom title, tag and last-modified timestamp. It never returns first prompts or full transcripts; SDK internals may read session records. Returned metadata may contain private project data and credential masking is best effort. No real history read was performed here.
• rename_session and tag_session require the optional Claude Agent SDK and explicit authorization for that session. The adapter checks exact project membership through get_session_info and reads the title/tag back to confirm the update; exceptions or mismatches return unknown. The SDK appends organization metadata to its session record; the wrapper does not copy or return transcripts. Neither method was exercised on a real session here.
• The adapter does not manage Claude rate limits. Claude's own behavior remains in control; no claim is made that an exited process wakes automatically. It does not bypass permissions, configure credentials, install a background scheduler, or create/open a Codex chat.

Tests are offline fake subprocess and fake SDK tests. An actual Claude model turn, the optional real SDK path, per-provider cost, and behavior under live rate limits are not verified on this signed-out machine.

Sources: https://code.claude.com/docs/en/agent-view ; https://code.claude.com/docs/en/cli-reference ; https://code.claude.com/docs/en/headless ; https://platform.claude.com/cookbook/claude-agent-sdk-05-building-a-session-browser .