claude-code-worker git:20260922.608ac59A

Immutable. This exact content is served forever at /api/v1/blob/8a216daea58026fb.

---
name: claude-code-worker
description: "Delegate a bounded coding, review, or research subtask from Codex to Claude Code in an isolated Git worktree, then continue the same Claude session with follow-up turns. Use when the user explicitly asks for Claude/Claude Code delegation, asks to save Codex quota with Claude, or requests a Claude worker that can inspect and edit a repository. Do not use for PHI or credentials, authoritative imaging, source-data mutation, external publication, or a task that cannot safely be isolated; de-identified study identifiers are fine."
---

# Claude Code Worker

Use Claude as a write-capable external worker while Codex remains the supervising owner.
The worker is conversational across invocations, but it does not inherit the Codex thread or
native tool state. Give it a compact, self-contained prompt and verify its work yourself.

## Choose Claude Deliberately

Prefer Claude when the task is bounded, isolatable, large enough to repay delegation overhead,
and has objective acceptance checks. It is especially useful for multi-file implementation,
mechanical migration, and repository audit work when Claude quota is cheaper than Codex quota.

Work locally instead for a trivial edit, a task needing frequent interactive decisions, or work
whose main difficulty is supervisor judgment. Do not delegate protected or credential-bearing
content, authoritative imaging, source-data mutation, external publication, frozen execution
state, or any task that cannot be isolated safely. If repeated parent correction dominates the
work, stop delegating that task shape even when Claude quota is free.

## Before Launch

1. Read the repository's applicable `AGENTS.md` and task instructions yourself.
2. Choose one concrete, bounded task with an inspectable result.
3. Create a dedicated clean Git worktree under the repository's configured worktree root.
   Do not point Claude at a shared checkout or an execution checkout bound to a live job.
   Do not improvise a second worktree under `/tmp`; inspect a baseline with `git show` or a
   worktree created under the configured root.
4. Create the state directory outside the worktree. Use a protected directory when the
   prompt or result is private. Keep PHI, credentials and protected clinical text out of
   the prompt and out of worker-visible paths. De-identified study identifiers -- the
   accession or subject keys a de-identified cohort is organized by -- are fine, and a
   worker usually cannot do the work without them.
5. Write a self-contained prompt that includes:
   - the exact outcome and boundaries;
   - relevant user constraints and applicable repository rules;
   - current evidence and file paths needed for the task;
   - verification expected from the worker;
   - exact writable paths, an exploration boundary, and a stopping condition;
   - whether it may commit (default: no);
   - an instruction to report changed files, checks, findings, and blockers.

Bound diagnosis with a timeout, budget, or explicit retry limit when unchanged failures could
produce an open-ended loop. A synchronous worker cannot receive a live answer while Codex is
sleeping: if it needs a decision, it must send one AgentCom question, return `BLOCKED`, and let
the supervisor resume the same session with a focused answer.

## Start And Continue

## Coordinate Through AgentCom

When AgentCom is configured for the repository, use it as the default control
channel between the supervising agent and Claude. Give each worker a unique,
attributable AgentCom name and send the bounded assignment to that mailbox.
Claude must acknowledge the assignment, report questions or blockers, and send
a concise completion message through AgentCom. The supervisor reads its inbox
at natural task boundaries and sends corrections through the same thread.

Before launch, resolve AgentCom with `command -v agentcomm` and put that exact
executable path and the required commands in the bootstrap prompt. Claude's
restricted shell may not inherit the supervisor's `PATH`. Tell Claude not to
search the filesystem for AgentCom; if the supplied executable fails, it must
report that transport blocker in its bridge result instead of broadening the
search.

Do not duplicate the complete assignment in both a prompt file and AgentCom.
Use the bridge prompt only to bootstrap the named Claude worker, direct it to
read its mailbox, and state the safety boundary. Keep large reports and patches
in the isolated worktree or protected state directory; AgentCom carries a short
summary and exact artifact paths. Avoid periodic status chatter that creates
model turns without changing a decision.

For a synchronous one-shot task, prefer the bundled
`scripts/run_agentcomm_worker.py`: it registers the supervisor with explicit
`--as`, sends the task, generates the bootstrap, resolves the bridge relative
to the installed skill, and fails before launch if delivery fails. The worker
returns its compact result through the bridge as well as sending AgentCom
acknowledgement/completion. Treat the bridge result as primary and do not poll
or reread the supervisor mailbox unless the worker explicitly reports a
question or the bridge fails. Do not use interactive `agentcomm bind` in an
automated worker launch, and do not assume `$CODEX_HOME` is set.

Choose the supervision mode explicitly:

- **Quota saver (default):** keep every process wait inside one composed `functions.exec`
  call. Codex does not reason on other work during that call, but already-running agents,
  Claude, Slurm jobs, and other processes continue. Use tool-level notifications for
  heartbeats; they do not wake the model.
- **Concurrent supervisor:** allow the command to return a live process/session handle, do
  other work, and check it only at natural boundaries. This uses more Codex quota because
  every supervisory turn reloads context. Use it when concurrent judgment is worth more than
  minimum quota, not accidentally.

When the bridge runs longer than one tool yield, keep its `write_stdin` waits
inside the same composed `functions.exec` call so waiting does not repeatedly
wake the supervising model. See [references/communication.md](references/communication.md)
for the compact orchestration pattern.

AgentCom is coordination rather than authentication, persistence, or a
security boundary. It does not replace the isolated worktree, the bridge's
saved Claude session, quota handling, or parent verification. If AgentCom is
not installed or configured, use the prompt-file start/follow-up workflow
below rather than blocking the task.

Run the bundled bridge from the repository that owns the worktree:

```bash
python "<skill-dir>/scripts/run_claude_worker.py" start \
  --workdir "$WORKTREE" \
  --prompt-file "$PROMPT_FILE" \
  --state-dir "$STATE_DIR"
```

Resolve `<skill-dir>` from the loaded skill path rather than relying on
`$CODEX_HOME`; the environment variable may be unset in fresh supervisors.

The default is Sonnet at medium effort for bounded coding and review, with
autonomous tool use, unrestricted turn count, and write plus shell tools. Use
compact, file-referenced briefs and send only unfinished scope. Do small edits
locally when delegation and review would cost more than the task. Escalate model
or effort only for an identified difficulty, not by default. Prefer a stronger model only
when it is likely to reduce iteration or correction enough to offset its Claude quota use. Safety
comes from Claude restricted/safe mode and the isolated worktree, not from making the
worker read-only. The bridge does not use `--no-session-persistence`; it records the
Claude session ID and raw JSON result under the state directory.

Use `--timeout-seconds` and `--max-budget-usd` on the AgentCom helper when appropriate. It
writes `delegation_receipt.json` under the state directory with task class, model/effort,
Claude turns/usage/duration, expected supervisor wakeups, and changed-file/LOC counts. Raw
turns remain in the state directory; do not copy them into chat. After follow-ups, record the
actual counts in the receipt so future routing decisions use completed-task evidence rather than
only the initial turn; the follow-up command does this automatically.

Send a follow-up turn to the same worker conversation:

```bash
python "<skill-dir>/scripts/run_claude_worker.py" followup \
  --state-dir "$STATE_DIR" \
  --prompt-file "$FOLLOWUP_PROMPT_FILE" \
  --parent-correction
```

Use follow-ups for correction, missing tests, or a focused question. Do not hand the
worker a second unrelated task; start another isolated session instead. Include
`--parent-correction` only when the follow-up repairs or redirects worker output; omit it
for an answer to the worker's blocker or a planned next validation. When a delegation
receipt exists, the bridge updates its follow-up and correction counts automatically.

## Recover From Quota Limits

The bridge recognizes quota errors even when Claude exits successfully with
`is_error: true`. It returns exit code **75** and structured `status`, `retry_at`
and `quota_path` fields, preserving the worker session and every attempted turn.
The default cooldown ledger is `~/.cache/claude-code-worker/quota.json`, shared
across workers using the same Claude account. Use `--quota-file` consistently on
all commands if separate accounts need separate ledgers; do not switch accounts,
models or paid usage to evade a limit.

- Keep doing independent authorized work. Record the returned UTC `retry_at` in
  the existing task state and check it at natural work boundaries. Do not label
  the worker completed or abandon Claude for the rest of the goal.
- During cooldown, use native Codex subagents for bounded work when the user
  permits that fallback. They consume Codex quota; do not infer permission from
  a request to save Codex quota with Claude. Pass compact task context, not the
  full conversation, and preserve the same scope and safety boundaries. For
  bounded implementation and cross-file audits, use `gpt-5.6-terra` at
  `medium` effort with `fork_turns="none"` rather than inheriting an expensive
  manager model. Reserve smaller/lower-effort workers for mechanical tasks.
  If an existing worker cannot change model in place, stop it, inspect its
  partial work and transfer only unfinished work with a compact handoff.
- Keep one owner per task. Before transferring unfinished Claude work to Codex,
  confirm the Claude invocation has ended, inspect its partial work, and record
  the transfer in existing task state. Give Codex only the remaining scope;
  never run both workers on the same task or write set.
- `python <skill-dir>/scripts/run_claude_worker.py availability` is a local-only
  check. `waiting` means the cooldown is active; `probe_due` means the time has
  elapsed, **not** that access is restored.
- At `retry_at`, run the same command with `--probe`. This performs one tiny
  tool-free, non-persistent request using the worker model (Sonnet by default).
  It does not execute the pending task. Before the deadline it makes no request.
  A recognized new limit refreshes the cooldown; other failures need diagnosis.
- On `available`, prefer Claude again for new delegations and relevant paused
  follow-ups. Let already-assigned Codex tasks finish; do not restart them in
  Claude. For a task still owned by Claude, inspect its partial changes and
  current relevance, then resume its same session with `followup` for only the
  unfinished work. Reconcile any completed Codex work before a later Claude
  follow-up; never replay a superseded or already-completed action.
- A time-only reset with an explicit IANA timezone is interpreted as the next
  occurrence plus 60 seconds. Unknown reset formats use a 15-minute backoff.
  If quota is the only remaining wait, retain the task and use the product's
  interruptible wait mechanism, with at most 60 seconds between control returns.

The supervisor owns this loop while active; the helper does not install a daemon
or wake an ended session. Concurrent probes are locked, and worker state is locked
per session so a retry cannot overwrite the failed turn's evidence.

## Supervise And Integrate

- Inspect the worktree diff, status, and commands/tests reported by Claude.
- Have the worker run Ruff/parse checks and a small number of targeted behavioral checks.
  Codex independently owns final liveness/reference searches, semantic-diff review, provenance
  pins, and the broad acceptance check. Treat Claude's report as a claim, not evidence.
- When the repository embeds source/config digests, compute the old and new digest for every
  changed tracked file, search for every old digest, repin only edges that were valid before,
  and report edges that were already stale. The supervisor repeats this audit before integration.
- Steer with another follow-up when the same bounded task needs correction.
- Codex owns staging, integration, conflict handling, and user-facing conclusions unless
  the initial prompt explicitly assigned a worktree-local commit.
- Stop after the requested outcome or an explicit blocker. Do not use the bridge to evade
  repository safety rules or broaden authority.

Read [references/communication.md](references/communication.md) when explaining how this
bridge differs from native Codex subagents.