claudeloop + claude-agent-sdk integration

Codex skill mirror of .claude/skills/claudeloop-agent-sdk/SKILL.md. When this guidance changes, update Claude skill, Cursor rule, and .agents/skills/ in the same PR.

infrastructure/agent/ is the only place claude_agent_sdk
may be imported — see the claudeloop-architecture skill for the enforced
onion rule. This skill covers the SDK integration specifics; consult
claudeloop-domain-model for how the resulting signals get classified.

ClaudeSDKClient over query() — this is not optional

query() (single-shot) raises a plain Exception after yielding an
error ResultMessage, and the underlying process exits non-zero. A
streaming-input ClaudeSDKClient stays alive across error results — you
can keep sending messages on one live process with no resume/respawn. The
AgentGateway adapter (infrastructure/agent/gateway.py::ClaudeAgentGateway) MUST use ClaudeSDKClient, not query(), or
the whole point of collapsing the legacy respawn loop is lost. See ADR 0002
for the full reasoning.

Key ClaudeAgentOptions fields for this project

• permission_mode="bypassPermissions" — required for autonomy. Note:
  the Python SDK has no dangerously_skip_permissions field; this is
  its equivalent. Do not go looking for a field that doesn't exist.
• can_use_tool — a defensive callback that must NEVER await input.
  Intercepts AskUserQuestion specifically and denies with guidance
  (not auto-answers) — see the "Never blocking" section below.
• output_format — a JSON schema
  ({complete: bool, remaining_work: [str], blocked_on: str|null, summary: str}) so each turn returns a ResultMessage.structured_output the
  domain layer's completion.py can evaluate directly, rather than
  substring-matching output text. Property descriptions (and the autonomy
  system-prompt fragment) insist blocked_on is only for true
  external/human blockers — waitable self-started work goes in
  remaining_work with blocked_on: null, because any non-null value
  terminates the run as Blocked.
• resume / continue_conversation / fork_session / session_id —
  session_id cannot combine with resume/continue_conversation unless
  fork_session=True is also set. Get this wrong and session resumption
  breaks in a way that's easy to miss in a quick test. When building
  options, drop session_id whenever resume or continue_conversation
  is set (see build_turn_options).
• setting_sources=None for the throwaway capacity probe specifically
  — no CLAUDE.md should load for a one-token "are we still limited"
  check.
• hooks — PermissionRequest auto-allows; Notification logs only,
  never blocks.

Never blocking on a human — every mitigation, concretely

Stall path	Mitigation
Permission prompts	permission_mode="bypassPermissions"
Unexpected permission path	Defensive can_use_tool returning PermissionResultAllow without ever awaiting input
AskUserQuestion	Intercepted, denied with guidance — e.g. "running autonomously, no user available — choose the option you would recommend, note the assumption, and proceed." NEVER fabricate an answer; that silently invents a decision nobody made.
ExitPlanMode	Auto-approved
Notification hooks	Logged, never awaited
Model asks "Shall I proceed?" in plain text	No tool call to intercept — mitigated via an appended system-prompt fragment establishing autonomous operation
TTY-dependent stdin	Never inherit a TTY — must be safe under nohup/systemd
MCP OAuth	Genuinely cannot complete unattended — the doctor command checks configured MCP servers up front and fails fast, naming them, rather than discovering the problem mid-run

If you're adding a new tool-interception path, apply the same test every
time: can this ever wait on stdin or a human response? If yes, it needs
an explicit mitigation in this table before it ships.

Rate-limit signals — read three, trust none alone

RateLimitEvent.rate_limit_info: status (allowed/allowed_warning/
rejected), resets_at, rate_limit_type
(five_hour/seven_day/seven_day_opus/seven_day_sonnet/overage),
utilization, overage_status, overage_resets_at,
overage_disabled_reason. The Claude Code binary contains the string
[sdkMessageAdapter] Ignoring rate_limit_event message — treat this event
as possibly absent and always corroborate with ResultMessage .api_error_status and AssistantMessage.error (see the
claudeloop-domain-model skill's TurnSignals section for exactly how
these three combine).

Session discovery — use the supported API

list_sessions() / get_session_info() return SDKSessionInfo (session_id,
summary, last_modified, custom_title, first_prompt, git_branch, cwd, tag,
created_at) via cheap stat + head/tail reads. Never hand-parse
~/.claude/projects/<encoded-cwd>/*.jsonl directly — the docs explicitly
warn the transcript format changes between Claude Code releases, and this
API exists specifically to replace that fragile approach from the legacy
script.

The capacity probe — deliberately minimal

The throwaway turn used while WAITING (see claudeloop-domain-model):
one-token prompt, max_turns=1, no tools, setting_sources=None, and
extra_args={"no-session-persistence": None} so it leaves no transcript
and doesn't pollute the working session's history with "OK" turns. A
rejected probe isn't billed by the API.

Backend profiles — the env overlay reaches the turn AND the probe

A [profiles.<name>] table (--profile / CLAUDELOOP_PROFILE) picks the
endpoint Claude Code talks to. The decisions live in domain/backend.py
(BackendProfile, BackendRuntime, BackendIdentity); infrastructure/backend.py
reads the TOML and the environment; bootstrap.py hands the resolved
BackendRuntime to both ClaudeAgentGateway and ClaudeCapacityProbe.

• The SDK merges options.env over os.environ, so the overlay wins. That
  is the only way to remove an inherited value: a local profile sets
  ANTHROPIC_API_KEY="" so a paid key never reaches a local server. Never
  "just not set" a key you mean to scrub.
• build_turn_options and build_probe_options both take env= and
  cli_path=. A probe built without the overlay re-checks capacity on
  Anthropic while the run talks to Ollama — the defect this fixed.
• Local (base_url set) implies: every tier named and no claude-* id;
  Claude Code's haiku/sonnet/opus aliases mapped onto the tiers; --effort
  not forwarded (pass_effort); --max-budget-usd not forwarded and
  TurnAccumulator(cost_mode="zero") records $0 — Claude Code prices an
  unrecognised model at its default model's rate (observed: $0.0008365 for one
  free qwen2.5-coder:1.5b turn) — while ResultMessage.usage token counts are
  kept; CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1; web search / deep research
  refused.
• Errors a local backend produces (captured from the bundled CLI against
  Ollama 0.34.2) — AssistantMessage.error / ResultMessage.api_error_status:
  model not pulled → "model_not_found" / 404; server down → "server_error" /
  None with "Connection refused … (ConnectionRefused)"; model failed to load →
  "server_error" / 500; queue full → "server_error" / 503; conversation over
  context_window → "invalid_request" / None, "Prompt is too long" (Claude
  Code reserves max_output_tokens out of the window). TurnAccumulator
  passes local_backend=True into TurnSignals so classify can read them
  (see claudeloop-domain-model). Claude Code retries a refused connection up
  to CLAUDE_CODE_MAX_RETRIES times first — about three minutes at the
  default before claudeloop sees it; extra_env can lower it.
• A model that writes tool calls as text does nothing — and can fake Done.
  Observed live: qwen2.5-coder:14b on Ollama answers even a one-tool request
  with {"name": ..., "arguments": ...} as a text block; inside Claude Code it
  wrote its Write call and its StructuredOutput call as text, appended the done
  marker, and the run reported Done for a file it never created. Hence a local
  profile's done_marker_fallback = false (only a structured verdict completes
  a run; AutonomousRunner(done_marker_fallback=...) →
  evaluate(marker_fallback=...)) and doctor's backend-tools check, which
  POSTs one trivial tool to /v1/messages per tier and wants a tool_use block.
• AssistantMessageError in the SDK types does not list model_not_found;
  the CLI sends it anyway. Compare strings, not the Literal.
• Resume never crosses backends: run meta records backend
  (anthropic | gateway:<url> | local:<url>) and profile;
  bootstrap.check_resume_backend refuses a mismatch.

CLAUDE_CODE_RETRY_WATCHDOG — deliberately off by default

Do not set this env var in the default agent gateway configuration. It
retries 429/529 in-process indefinitely with no progress reporting, no
credits-vs-window discrimination, and no --max-wait. It's exposed as an
explicit opt-in flag (--retry-watchdog), never the default. See ADR 0005
for the full reasoning if you're tempted to "simplify" by using it instead
of the probe-based waiting policy.

Full reference

docs/architecture/decisions/0002-agent-sdk-over-subprocess.md,
docs/architecture/decisions/0005-retry-watchdog-off-by-default.md,
docs/architecture/decisions/0007-ask-user-question-denied-with-guidance.md,
docs/guides/never-blocking.md, docs/guides/rate-limits-and-credits.md,
docs/guides/local-backend.md.