SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscodex-external-handoff

codex-external-handoff

General & other

View repository

Updated 10-16 08:10

About this skill

Codex External Handoff

Goal

Let external Agents hand off formal tasks to local Codex while preserving the smoothness of background execution and the supervision, recovery, and human takeover capabilities of visible Threads.

Run Entry Point

Invoke the script from the installed Skill directory:

HANDOFF="skills/codex-external-handoff/scripts/codex_external_handoff.py"
python3 "$HANDOFF" doctor

On first use, after a Codex upgrade, or when invocation fails, first run doctor. For formal tasks, first read task-package.md; when troubleshooting protocol or compatibility issues, read app-server-contract.md。

Routing

  • Cross-project retrieval, complex research, architecture design, code review, deterministic engineering, important judgments, follow-up questions, or human takeover: use this Skill to create a persistent Thread.
  • Format checks or simple extractions whose output is discarded after use, require no supervision, and need no follow-up: directly use codex exec --ephemeral。
  • Codex is already the current host and the task only involves internal multi-Agent division of labor: use Codex's native team capabilities without external handoff.

Execution

  1. Form a minimal task package that clearly specifies the goal, the scope allowed for reading, prohibited actions, evidence requirements, and acceptance criteria. When the body is long, write it to a temporary or project-registered task file.
  2. By default, create the Thread with read-only + approvalPolicy=never . Only pass --sandbox workspace-writewhen the task package explicitly authorizes writing and lists the target paths; this Skill does not provide danger-full-access。
  3. Create and immediately return job_id、thread_id and the open address:
python3 "$HANDOFF" ask \
  --title "架构设计与方案审查" \
  --task-file /absolute/path/to/task.md \
  --cwd "$PWD" \
  --model gpt-5.6-sol \
  --effort high
  1. Manage background tasks with the following commands:
python3 "$HANDOFF" status <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" result <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" continue <JOB_ID_OR_THREAD_ID> --task-file /path/to/follow-up.md
python3 "$HANDOFF" cancel <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" open <JOB_ID_OR_THREAD_ID>

ask runs in the background by default; add --waitwhen this round must wait for the result. Use maxfor complex planning, read-only sourcing across the entire repository, and important reviews; use high。

  1. Read result 's structured conclusions, evidence, risks, artifacts, and suggested status increments. The external Agent is responsible for verification and deciding whether to adopt them; the Codex Thread does not directly modify the project's authoritative state or bypass human confirmation.

Handoff Contract

  • job_id is the local background run receipt, andthread_id is the authoritative session identifier that can be continued, recovered, and opened in the Codex App.
  • The task body is only staged before startup and is deleted after the Worker reads it; the run receipt is stored in the local Codex state directory and does not enter the project Git.
  • The default thread working directory is the current project root. Cross-project retrieval still keeps the project root cwd, and declares the read-only source scope in the task package.
  • The same Thread runs only one external task at a time; when parallel judgments are needed, create multiple new Threads and do not concurrently follow up on the same Thread.
  • The external Agent or final integrator is the sole writer of canonical files and state. Codex only returns evidence, artifacts, and suggested increments, unless the task package explicitly authorizes writing and satisfies the project's safety boundaries.

Completion Criteria

The handoff is complete only when the following information is fully present:job_id、thread_id, Thread title, run status, structured result or explicit error, evidence, risks, artifact paths, suggested status increments, and the available codex://threads/<threadId> or codex resume <threadId>。

Routing use cases are located in evals/; the run implementation is verified by scripts/codex_external_handoff.py and tests/ .