git:20260908.e4274e8 to git:20260908.fc96e93

52 added, 5 removed. Audit A to A.

---

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, credentials, authoritative imaging, source-data mutation, external publication, or a task that cannot safely be isolated."

---

# 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. Never put PHI, credentials, patient identifiers, source

imaging, or protected clinical text in the prompt or worker-visible paths.

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. Safety

+ 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"

+ --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.

+ 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.

- - Run the relevant verification independently. Treat Claude's report as a claim, not

- evidence.

+ - 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.