Threads

Threads

Use this skill to turn a broad request into controlled Codex-native subthreads with explicit lanes, file ownership, review gates, and verifiable closure.

Native Codex threads are short-lived parallel work lines inside the Codex workflow. They are not the same as OMX/tmux workers. If native subagent tools are not visible, discover them with tool search. If no native subagent capability is available, produce the thread prompt pack and execution plan instead of pretending threads were launched.

Quick Path

1. Classify the request: single_agent, plan_only, execute_direct, review_only, research_spec, or clarify_first.
2. If the user explicitly asked for threads, record intent_contract and thread_dispatch_gate, write a run_phase: preflight record, and pass append_run_log.py --validate-only before spawning.
3. For GitHub queues, fetch remote state in the coordinator lane, then write queue_gate, queue_ledger, issue_to_pr_map, and the validated queue_bounds.
4. Write a lane map with file ownership, verification owner, stop conditions, context budget, and output firewall.
5. Route large command output to artifacts before dispatch; the parent reads only summaries, short tails, targeted greps, and evidence paths.
6. Dispatch only bounded native lanes with disjoint writable scopes or read-only roles.
7. Collect, wait, and close spawned agents; do not count the coordinator as a spawned thread.
8. Run fresh verification tied to the current head or artifact.
9. End with a compact final report and threads_run_log; write durable JSONL for queue, multi-lane, push, comment, or merge-capable runs.

Do Not Use For

Do not use this skill for generic uses of "thread" unless the user explicitly means Codex workflow orchestration:

• operating-system threads, language concurrency, or async programming models
• chat, email, forum, Slack, GitHub discussion, or comment threads
• OpenAI Assistants API threads or other product APIs
• ordinary single-agent repo work where there are no independent lanes

Decision

Choose one mode:

• single_agent: handle a small, well-scoped task locally with the same evidence gates.
• plan_only: map issues, PRs, risks, and parallelization without edits.
• execute_direct: run one or more bounded implementation lanes after planning.
• review_only: launch independent reviewers for PRs, diffs, or risky code.
• research_spec: split exploration by angle, then synthesize docs/spec/issues.
• clarify_first: ask only when repo, target queue, permission, or done-when is missing.

Use single_agent only for one-file fixes, simple questions, or tasks where the next step depends on one immediate result. If the user explicitly asks for threads, subagents, or a GitHub issue/PR queue and native subagents are available, do not silently choose single_agent; record a concrete no_spawn_reason before implementation work begins.

For any implementation mode, start with a lane map before spawning workers. For GitHub issue/PR queues, complete the Capability Gate and Queue Gate first; do not create worker lanes until capability_gate, queue_gate, queue_ledger, and issue_to_pr_map are written.

Explicit Thread Dispatch Gate

When the user explicitly asks for threads, subagents, "开几个子 agent", or a GitHub issue/PR queue that the skill classifies as plan_only, execute_direct, review_only, or research_spec, native dispatch is required whenever native subagent tools are available.

Record this gate before implementation, review, or merge work:

thread_dispatch_gate:
- explicit_thread_request: yes | no
- native_subagents: available | unavailable
- spawn_requirement: required | optional | unavailable
- fallback_mode: single_agent | prompt_pack_only | none
- planned_native_threads:
  - id:
    role:
    target:
    write_scope: read_only | disjoint_writable | none
    spawn_status: planned | spawned | skipped
    no_spawn_reason:
- native_thread_evidence:
    user_requested_native_threads: yes | no
    spawned_agents:
      - lane_id:
        spawn_tool:
        agent_id_or_thread_id:
        wait_evidence:
        close_evidence:
        result_collected: yes | no
    fallback_reason:
- no_spawn_reason:

Rules:

• If explicit_thread_request: yes, native_subagents: available, and spawn_requirement: required, spawn at least one bounded native subagent before claiming the run is using threads.
• native_subagents: available plus fallback_mode: none is valid only when native_thread_evidence.spawned_agents contains at least one real agent/thread ID.
• Every planned_native_threads lane must have a matching native_thread_evidence.spawned_agents[].lane_id or a lane-level no_spawn_reason; spawning one native thread does not justify running the remaining planned lanes serially.
• A main-thread lane is a coordinator lane, not a native thread. Do not count the coordinator as native_thread_evidence.spawned_agents.
• If no native thread is spawned, set fallback_mode: single_agent and write no_spawn_reason before editing files, commenting on GitHub, or merging. Valid reasons are narrow: task is tiny and truly sequential, all possible writable lanes overlap, native tools are unavailable, or the user explicitly asks not to spawn.
• For GitHub PR merge work, at least one read-only reviewer or merge-reviewer native thread is required when native subagents are available. A self-review by the coordinator does not satisfy the independent review lane.
• If native tools are unavailable, produce a prompt pack or continue as single_agent only after saying that no native threads were launched.

Operating Contract

Before dispatch, record this block as intent_contract:

intent_contract:
  goal:
  non_goals:
  done_when:
  authorized_actions:
  fresh_confirmation_required:
  merge_policy: no_merge | merge_after_gate | user_confirm_before_merge
  remote_truth_required: yes | no
  truth_level: A | B | C | D
  queue_ledger: required_for_queue | optional | none
  ci_truth_source: discovered_workflow | user_supplied | language_default | none
  data_collection: final_report | local_jsonl | none
  active_skill_source: path | source_sha | unknown
  queue_bounds:
    max_items:
    max_model_calls:
    planned_items:
    planned_model_calls:
    planned_seconds:
    time_budget:
    checkpoint_every_items:
    queue_tranche:
  context_budget:
    window_tokens:
    soft_stop_ratio:
    hard_stop_ratio:
    critical_stop_ratio:
    current_usage_signal:
  output_firewall:
    raw_log_policy: file_only | summary_only | not_applicable
    max_parent_stdout_lines:
    max_subagent_final_lines:
    artifact_root:
  remote_refresh:
    cadence:
    last_fetch:
    stale_base_policy:
  thread_dispatch:
    explicit_thread_request:
    spawn_requirement:
    no_spawn_reason:

Defaults:

• merge_policy is no_merge unless the user explicitly authorizes merging in the current conversation.
• data_collection is local_jsonl for GitHub issue/PR queues, multi-lane runs, or any run that may push/comment/merge; use final_report only for tiny read-only/single-agent runs or explicit user opt-out.
• Record the active skill path and source revision when discoverable; record unknown rather than guessing.
• If merge permission is ambiguous, stop after merge review and report the exact recommendation or merge command instead of merging.
• authorized_actions is the closed mutation set for this run. Put cross-repo writes, GitHub writes, installs/upgrades/restarts, migrations/reindexing, and global config/hook changes in fresh_confirmation_required unless the current request explicitly authorizes them.
• Reaching done_when ends the run. A blocker does not expand authorized_actions; report it and request confirmation for any adjacent remediation.

Direct actions: inspect repo instructions, fetch remote state, map lanes, apply the Explicit Thread Dispatch Gate, spawn required bounded native subagents, integrate results, verify, and report closure.

Escalate before: modifying high-context files, merging without fresh CI/review-thread truth, sharing writable files across workers, or switching to shell/tmux/OMX orchestration.

Evidence-backed pushback: choose single_agent only when parallelism adds coordination risk without independent work, and record the no_spawn_reason; challenge vague worker output, stale remote state, or unverified completion claims.

Feedback loop: record notable failures in threads_run_log, classify the failure mode, tighten the lane prompt or split, then retry only after the hypothesis changes.

If the user asks for issue/PR queue handling, remote_truth_required is yes and queue_ledger is required_for_queue.

Broad queue requests such as "all issues and PRs" are bounded by default. If the user did not give an explicit long-run budget, choose one smallest mergeable tranche, record max_items / max_model_calls / time_budget / checkpoint_every_items / queue_tranche, and leave the remaining queue for the next run with exact next actions. Every preflight also records concrete planned_items, planned_model_calls, and planned_seconds; each must fit the allowance remaining after cumulative usage. Values such as unbounded, as needed, or not pre-budgeted are invalid.

Mass-Record Cost Gate

Do not use a long-lived native thread as a generic loop over hundreds or thousands of similar records.

1. Validate a run_phase: preflight record with scripts/append_run_log.py --validate-only before the first spawn.
2. Run one representative calibration tranche and collect measured usage when the worker runtime exposes it. Project total model calls and tokens from that evidence; use the token projection as approval evidence, while the enforceable contract remains the item, model-call, time, and checkpoint bounds. Record unavailable usage as a blocker rather than guessing.
3. Ask for confirmation before the full run when the concrete projection was not already authorized. After confirmation or existing authorization, validate a second preflight containing the full run's approved max_items, max_model_calls, time_budget, and checkpoint_every_items before dispatching another tranche.
4. Start a fresh bounded child for every tranche. Do not resume the same child across tranches or feed it raw prior transcripts; pass compact instructions and artifact paths only.
5. Before every child or tranche dispatch, recheck item, model-call, and elapsed-time usage, stop at any validated ceiling, and cap the next tranche to the smallest remaining allowance. At each checkpoint_every_items cadence, persist the queue ledger and compare measured token usage with the calibration projection; stop and request a revised budget on material overrun. Close completed children and update the existing queue-ledger artifact listed in output_firewall.evidence_paths; do not invent a checkpoint run phase, and append the final run log only after collection. Carry the approved queue_bounds into that final record, including for a one-child tranche.

Parent Context Budget

For long queues, multi-lane runs, CI polling, or any run likely to carry large logs, record a parent context budget before dispatch:

context_budget:
- window_tokens:
- soft_stop_ratio: 0.50
- hard_stop_ratio: 0.65
- critical_stop_ratio: 0.75
- current_usage_signal:
- override_reason:

Defaults are guidance, not universal limits. Override them when the model window, task size, or user budget requires it, but record the override.

Rules:

• At soft_stop, do not spawn new lanes, broaden queue scope, or run broad discovery. Finish the current bounded lane and use targeted reads only.
• At hard_stop, stop expanding work, collect current lane evidence, write or update the queue ledger/run log, and hand off to a fresh parent thread.
• At critical_stop, do not read large files, raw logs, broad search results, or historical transcripts. Write the minimum handoff/resume prompt and stop.
• Do not treat old parent transcripts, raw Codex session JSONL, or compaction summaries as live queue state. Use current repo/GitHub truth plus durable ledgers or artifacts.
• For long issue/PR queues, a fresh parent per bounded tranche is the default recovery path, not a failure.

Output Firewall

Large-output commands are allowed only when raw stdout/stderr are written to artifact files outside the parent transcript:

output_firewall:
- raw_log_policy: file_only
- max_parent_stdout_lines: 150
- max_subagent_final_lines: 150
- artifact_root:
- evidence_paths:

Parent-visible output should be limited to exit code, command name, short tail, targeted grep result, failure summary, and artifact path.

Rules:

• Do not paste raw gh run view --log, full workspace test output, broad rg/git grep results, long diffs, copied source files, or session JSONL into the parent.
• Redirect large commands such as full local test suites, CI logs, or wide searches to files under the run's artifact root, then read only the bounded summary needed for the next decision.
• Bound searches by path and exclude .codex, .claude, target, node_modules, session JSONL, and log files unless the user explicitly asks for forensic analysis.
• Worker and reviewer lanes must return findings and evidence paths, not raw logs.
• If raw output enters the parent and materially increases context risk, record raw_output_blocked or parent_context_hard_stop in threads_run_log and hand off if needed.

Capability Gate

Before dispatching lanes, record whether native Codex subagents are actually available:

capability_gate:
- native_subagents: available | unavailable
- tools_seen:
- explicit_thread_request: yes | no
- spawn_requirement: required | optional | unavailable
- fallback_mode: single_agent | prompt_pack_only | none
- no_spawn_reason:
- manual_orchestration_allowed: yes | no

Rules:

• If native subagents are unavailable, do not claim threads were launched.
• If native subagents are available and spawn_requirement is required, do not proceed past planning until at least one native subagent is spawned or fallback_mode and no_spawn_reason are recorded.
• Do not switch to shell, tmux, OMX, Harness, or other manual orchestration unless the user explicitly asks for that fallback.
• If fallback_mode is single_agent, explain why parallelism was rejected.
• If fallback_mode is prompt_pack_only, output exact lane prompts and stop before implementation.

Queue Gate

For GitHub issue/PR queue handling, write a queue_gate block before the lane map and before any implementation worker is launched. This is mandatory even when all open PRs look MERGEABLE or CLEAN.

The gate must use live state from the current session:

queue_gate:
- fetched_remote:
- truth_level:
- remote_refresh:
    base_ref:
    owner_lane:
    origin_main_sha:
    local_base_sha:
    stale_base:
    policy:
- current_branch:
- dirty_files:
- unpushed_commits:
- worktrees:
- open_prs:
- open_issues:
- pr_classification:
  - PR:
    head_sha:
    merge_state:
    check_rollup:
    review_threads:
    classification:
    reason:
- issue_to_pr_map:
  - issue:
    covering_pr:
    status: covered | uncovered | stale_or_superseded | needs_human_decision
    reason:
- recommended_order:
- stop_conditions:

Classify every open PR as exactly one of:

• merge_ready
• review_thread_blocked
• ci_failed
• conflict_blocked
• stale_or_superseded
• needs_human_decision

Rules:

• MERGEABLE or CLEAN is never sufficient by itself. A PR is merge_ready only when the current head SHA, check rollup, merge state, and GraphQL review-thread state are all fresh and clean.
• Query review threads with a thread-aware source such as GraphQL reviewThreads { isResolved isOutdated }; flat PR comments are not sufficient.
• Map open issues to existing PRs before opening new implementation lanes. Prefer fixing, reviewing, or merging an existing covering PR over opening a competing PR.
• If an existing covering contributor PR has maintainerCanModify: true, update that PR before opening a maintainer replacement unless the branch is unsafe, unwritable, or the user approves replacement.
• For review-gated queues, work one blocker or bounded tranche to closure unless writable file ownership is clearly disjoint and the PRs are not stacked.
• Keep remote truth separate from local stale or dirty worktree state.

Remote Truth Levels

Use the highest truth level available from the current session and record it in intent_contract, queue_gate, and threads_run_log:

• A: git fetch plus GitHub API or GraphQL can prove current PR head, check rollup, merge state, and review-thread state. Implementation, review, and merge gates may proceed if all other conditions pass.
• B: git fetch plus REST PR/review/comment data is available, but GraphQL review-thread state is unavailable. Implementation and review may proceed; merge is forbidden.
• C: only local git state is reliable. Local implementation and review may proceed; PR closure, merge readiness, and remote cleanup claims are forbidden.
• D: no reliable repo or remote state is available. Use plan_only or prompt_pack_only; do not implement, push, merge, or claim closure.

Never fabricate remote state to reach a higher level. If the tool or permission gap matters, report the lower level and the blocked operation.

Queue Ledger

For issue/PR queues, keep a live queue ledger from discovery through final closure. The ledger can be a concise table in the conversation, a local durable log, or both, but it must survive handoff and compaction when the run is long.

Use these fields:

queue_ledger:
- item:
  type: issue | pr | review_thread | local_task
  remote_state:
  owner_lane:
  dependencies:
  base_ref:
  branch:
  worktree:
  writable_files:
  pr:
  head_sha:
  ci_status:
  review_thread_state:
  acceptance_evidence:
  merge_sha:
  closed_by:
  remote_checked_at:

Rules:

• Update the ledger after initial remote discovery, after queue gate classification, after each PR open/update, before merge, after merge/close, and before the final report.
• Keep dependency edges explicit. If a lane depends on another PR or a newer origin/main, rebase or recreate the lane only after recording the dependency and checking for changed files.
• Do not claim Fixes #... or close an issue until each meaningful acceptance point is mapped to evidence: changed files, tests, commands, PR, commit, or remote state.
• If a queue item is superseded by another PR or issue, record the superseding item instead of silently dropping it.

Remote Refresh

Long queue runs must refresh remote state without mutating worker worktrees:

• Run git fetch --prune origin at queue start, before opening a new lane, before pushing, before merge review, and after long waits such as CI polling. For runs longer than one focused tranche, refresh at least every 20-30 minutes.
• Compare the current origin/main SHA with each lane's recorded base_ref. Do not automatically merge or rebase during a lane.
• If origin/main advanced, record stale_base: yes in queue_gate, queue_ledger, and threads_run_log.
• Continue without rebase only when changed upstream files are disjoint from the lane's writable files and verification remains meaningful.
• Rebase, recreate the worktree, or stop with stale_remote_state when upstream changes overlap the lane, alter CI, or invalidate the acceptance evidence.
• Remote refresh is not required for tiny single_agent tasks unless the task touches GitHub remote state.