handoff

Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.

Save a compact, task-owned checkpoint that lets Codex recover the current work with its authorization and worker ownership intact. Checkpointing and replacing the task are separate actions. Continue in the same task through automatic compaction unless the user requests a transfer.

Resolve the checkpoint

Read checkpoint recovery. Resolve the bundled helper from this installed skill's directory. Pass the current project directory and actual task ID, available as CODEX_THREAD_ID when the harness exposes it:

python3 "<installed-plugin>/runtime/checkpoint.py" --project "$PWD" --task "$CODEX_THREAD_ID"

Replace <installed-plugin> with the real plugin root, three levels above this SKILL.md. The helper prints JSON with the canonical project root, task ID, and checkpoint path. It creates no files. Use the returned path; only its owning task writes it. A worker returns its own evidence to its parent. If the task ID is not exposed, obtain it from the current task's app metadata or ask for a dedicated location. Never guess another task's ID or overwrite a coordinator's checkpoint.

Existing project handoffs, including .claude/handoff.md, may provide background on startup. Leave them unchanged. Loading one never authorizes stale NEXT work.

When and what to save

Save at meaningful milestones, before an explicit transfer, when the user asks, and when the harness reports impending compaction. Use active context usage rather than cumulative usage. Finish the current atomic step, save and verify, then continue. Do not wait for a manual restart after compaction.

Use the template. Keep a pointer to the recorded agreement and current state rather than a transcript. Preserve:

• The current objective, accepted decisions, authorization, and hard stop points.
• Branch/worktree and any uncommitted work; respect no-commit instructions.
• Worker/task IDs and owned process IDs, with status and the check that proves it.
• Completed work and verification evidence for its current revision.
• Pending questions, blockers, and the immediate next step on the current task.
• The tracker query for discovering new work, only when new work is authorized.
• Expensive lessons and pointers to durable decisions.

Before saving, inspect the composed checkpoint for credentials, tokens, cookies, private keys, passwords, and sensitive values copied from logs or configuration. Replace any such value with a safe location pointer describing where an authorized user can retrieve it, without embedding the value in the pointer. Keep legitimate task and ownership IDs. Do not echo suspected secrets in the report. A pattern scanner may supplement inspection, but does not prove every secret is absent.

Overwrite only this task's checkpoint with the sanitized text. Keep the ownership and authorization fields even when trimming; omit conversation transcripts.

Recover and verify

Re-read the saved file, inspect it again for secret values, and verify the safe pointers and preserved ownership fields. If a value remains, replace it and re-read the corrected file before reporting completion. Confirm paths and evidence resolve. Check live git, worker, tracker, and process state before continuing; a saved status is not a current liveness check. A fork's inherited checkpoint is background until the new task's authority and ownership are established.

Report the saved path and what was verified. Do not promise lossless recovery: an unresolved worker, stale evidence, or missing record remains explicitly unverified. No checkpoint alone permits creating a successor task or archiving the current one.

Done when (checkable)

• The resolved task-owned file exists and was re-read after writing.
• Objective, authorization, stop points, ownership, state, next step, verification, and pending questions are preserved, with explicit none values where applicable.
• Evidence and paths were checked; stale or unavailable state is labeled.
• Pre-save secret inspection, safe-pointer replacement where needed, and post-save verification are complete; secret values and transcripts are absent. Claude handoffs were not overwritten.
• The user received the path and verification result; current authorized work continues unless they requested a stop or transfer.