oh-my-opencode 4.16.2 → 4.17.0

package/packages/omo-codex/plugin/skills/refactor/SKILL.md

@@ -15,15 +15,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be ABSENT from the spawn schema (verified 2026-07-11: only `fork_turns`/`message`/`task_name`) — when absent, omit it and describe the role inside `message`; installed role TOMLs cannot be selected on that surface. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
 

package/packages/omo-codex/plugin/skills/remove-ai-slops/SKILL.md

@@ -15,15 +15,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be ABSENT from the spawn schema (verified 2026-07-11: only `fork_turns`/`message`/`task_name`) — when absent, omit it and describe the role inside `message`; installed role TOMLs cannot be selected on that surface. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # Remove AI Slops Skill
 
@@ -84,7 +84,7 @@ The agent looks for these nine categories. The first three are stylistic, the ne
    **Hard rule**: only apply when behavior equivalence is obvious. Do NOT change algorithms with subtle correctness implications. Do NOT micro-optimize hot paths without a benchmark. If in doubt, SKIP.
 
 ### Behavior coverage
-9. **Missing tests** — behavior present in changed files that is not locked by any regression test. The fix is not to remove code but to ADD the narrowest test that pins the behavior.
+9. **Missing tests** — behavior present in changed files that is not locked by any regression test. The fix is not to remove code but to ADD the narrowest test that pins the behavior. EXCEPTION: a PROSE file (prompt, `SKILL.md`, rule, markdown) has no behavioral seam — do NOT add a text/word-count/phrase pin for it; that guards a diff, not behavior. Cover only a machine-consumed value (parsed field, sentinel a runtime greps, a doc JSON sample through its real validator) or leave it to review.
 
 ### Structural
 10. **Oversized modules** — any source file exceeding **250 pure LOC** (non-blank, non-comment lines). This is an architectural defect, not a style preference. Measure: `awk '!/^[[:space:]]*$/ && !/^[[:space:]]*(#|\/\/)/' <file> | wc -l`.
@@ -144,7 +144,7 @@ For each in-scope source file:
 
 1. Identify the public/observable behavior the file exposes (exported functions, HTTP handlers, CLI commands, classes used elsewhere).
 2. Check whether existing tests cover that behavior. Use `git grep` / project test conventions to find related test files.
-3. **If behavior is uncovered or weakly covered, write the narrowest regression test that pins current behavior BEFORE editing the file.** Tests should pin observable outputs, not implementation details.
+3. **If behavior is uncovered or weakly covered, write the narrowest regression test that pins current behavior BEFORE editing the file.** Tests should pin observable outputs, not implementation details. A PROSE file (prompt/`SKILL.md`/rule/markdown) is exempt — its wording is not behavior; skip the test and rely on review, or assert only a machine-consumed value.
 4. Run the test suite (or at minimum the relevant tests). They must be **green** before any cleanup begins.
 
 If you cannot establish a green baseline (e.g., test runner is broken), STOP and report. Do not proceed with cleanup on unverified ground.

package/packages/omo-codex/plugin/skills/review-work/SKILL.md

@@ -14,15 +14,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be ABSENT from the spawn schema (verified 2026-07-11: only `fork_turns`/`message`/`task_name`) — when absent, omit it and describe the role inside `message`; installed role TOMLs cannot be selected on that surface. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## Codex Subagent Reliability
 
@@ -64,6 +64,12 @@ failed, investigate the underlying uncertainty with the `debugging` skill when
 runtime behavior may be wrong, fix with evidence, and rerun the affected lane
 before claiming completion, creating or handing off a PR, or merging.
 
+A rejecting lane must name its blockers inline in its final message — each
+blocker cites the violated goal criterion or requirement plus an evidence
+pointer. A bare REJECT/FAIL token without findings is not a verdict; treat it
+as an inconclusive lane (one bounded respawn, then record it inconclusive with
+that reason).
+
 When reviewing a PR or branch, collect diff, file contents, and verification
 results from a dedicated review worktree attached to that branch. Never
 checkout, test, or edit the review branch in the main worktree.

package/packages/omo-codex/plugin/skills/start-work/SKILL.md

@@ -15,20 +15,23 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be ABSENT from the spawn schema (verified 2026-07-11: only `fork_turns`/`message`/`task_name`) — when absent, omit it and describe the role inside `message`; installed role TOMLs cannot be selected on that surface. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## ABSOLUTE RULE: YOU ARE AN ORCHESTRATOR — NEVER THE IMPLEMENTER
 
 **YOU DO NOT WRITE CODE. YOU DO NOT EDIT PRODUCT FILES. YOU DO NOT RUN QA YOURSELF. EVERY unit of implementation, test, QA, and review work MUST be delegated to a spawned subagent. NO EXCEPTIONS.** Your hands touch only plan selection, `.omo/` state (Boulder, ledger, plan checkboxes), decomposition, dispatch, verdicts, and evidence records. About to edit a product file or run an implementation command yourself? **STOP. SPAWN A WORKER INSTEAD.** Orchestrate at **MAXIMUM PARALLELISM**: every independent unit runs concurrently; only named dependencies serialize.
 
+### Delegation by difficulty (Codex tier workers)
+When tier worker agents are installed (Codex), size each implementation lane by difficulty and pass the matching `agent_type` where the spawn schema exposes it: LOW (one-file fix, boilerplate, config/copy) -> `lazycodex-worker-low`; MEDIUM (standard feature, few files, known patterns) -> `lazycodex-worker-medium`; HIGH (new module, cross-module refactor, concurrency/security/migration) -> `lazycodex-worker-high`. Explorer/librarian research lanes keep their own roles. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts. On spawn surfaces without `agent_type` (deployed v2), state the tier inside `message`.
+
 ## Codex Subagent Reliability
 
 Every `multi_agent_v1.spawn_agent` message is a self-contained executable assignment: `TASK: <imperative assignment>`, then `DELIVERABLE`, `SCOPE`, and `VERIFY`, with role instructions inside `message`. Use `fork_context: false` unless full history is truly required; paste only the context the child needs.

package/packages/omo-codex/plugin/skills/teammode/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: teammode
-description: "Codex-only team orchestration: run a named team of cooperating Codex threads with durable, script-managed state. MUST USE when the user asks Codex to create, run, coordinate, inspect, archive, or delete a team of threads/sessions, or to work on something as a team in parallel. The main session is always the leader; members are defined by a concrete part, ownership area, or perspective - never a vague job role; a bundled cross-platform script writes the .omo/teams state plus an auto-generated member field manual. Use a team when the work is not perfectly isolated but parallelizing helps, or when a task still needs exploration under a clear goal; use plain subagents when scope is perfectly isolated or the goal is ambiguous. Triggers: team mode, teammode, make a team, run as a team, team of agents, coordinate threads, parallel Codex threads, archive the team, delete the team."
+description: "Codex-only team orchestration: run a named team of cooperating Codex workers with durable, script-managed state. MUST USE when the user asks Codex to create, run, coordinate, inspect, archive, or delete a team of agents/threads/sessions, or to work on something as a team in parallel. FIRST inspects the active tool surface and tells the user which transport it selected: native MultiAgentV2 agents (flat spawn_agent with task_name) when available, Codex App threads as the fallback. The main session is always the leader; members are defined by a concrete part, ownership area, or perspective - never a vague job role; a bundled cross-platform script writes the .omo/teams state plus an auto-generated member field manual. Use a team when the work is not perfectly isolated but parallelizing helps; use plain subagents when scope is perfectly isolated or the goal is ambiguous. Triggers: team mode, teammode, make a team, run as a team, team of agents, coordinate threads, parallel Codex threads, archive the team."
 ---
 
 # Teammode
 
-Run a named team of cooperating Codex threads under one leader, with durable state on disk.
-This is a Codex-only workflow. It is inspired by the lifecycle concerns in the
-Yeachan-Heo/oh-my-codex team skill, but it does not copy that runtime model and never depends
-on an external terminal runner - it coordinates through Codex's own thread tools plus a bundled
-state script.
+Run a named team of cooperating Codex workers under one leader, with durable state on disk.
+This is a Codex-only workflow. It never depends on an external terminal runner - it
+coordinates through Codex's own collaboration tools plus a bundled state script, on ONE of
+two transports chosen up front: native MultiAgentV2 agents, or Codex App threads as the
+fallback.
 
 ## When to use a team (and when to use plain subagents instead)
 
@@ -19,17 +19,43 @@ Use a TEAM when EITHER holds:
 - one task still needs exploration, yet its GOAL is already clear - parallel investigation under
   a fixed objective.
 
-Use plain subagents (`$ulw` / `multi_agent_v1.spawn_agent` / flat `spawn_agent` on `multi_agent_v2`) - NOT a team - when EITHER holds:
+Use plain fire-and-forget subagents (`$ulw` / one-off `spawn_agent` workers) - NOT a team - when
+EITHER holds:
 - the work IS perfectly isolated, so there is no coordination cost worth paying; or
 - the GOAL is still ambiguous, where one mind should resolve direction before any fan-out.
 
 A team buys cross-member coordination at a real overhead cost; only spend it when coordination
 is the thing you actually need.
 
+## Pick the transport FIRST - then tell the user
+
+Before creating any team state, decide which transport this session can run.
+Inspect your active tool list and select:
+
+1. **MultiAgentV2 (preferred)** - select when the flat V2 collaboration tools are ALL active:
+   flat `spawn_agent` whose schema requires `task_name`, plus `send_message`, `followup_task`,
+   `wait_agent`, `list_agents`, and `interrupt_agent`. Members are durable native agents
+   addressed by task name / agent path (`/root/<task_name>`). The namespaced
+   `multi_agent_v1.*` surface never qualifies as a team transport.
+2. **Codex App threads (fallback)** - select when flat V2 is not available but the
+   `codex_app.*` thread tools are (`create_thread`, `read_thread`, `send_message_to_thread`,
+   `set_thread_title`, `set_thread_archived`).
+3. **Neither complete set available** - STOP before `init`. Tell the user which tools are
+   missing; do not fake a team with partial tooling.
+
+Then, BEFORE running `init`, tell the user in one line which transport you selected and why,
+e.g. `Teammode transport: MultiAgentV2 (flat spawn_agent with task_name).` or
+`Teammode transport: Codex App threads (flat V2 tools not present in this session).`
+
+Pass that choice to `init` as `--transport multi_agent_v2` or `--transport codex_app`. The
+transport is recorded in `team.json` and is IMMUTABLE for the team's lifetime: a V2 spawn
+failure is a V2 blocker to report, never permission to mix Codex App threads into the same
+team. Never probe by trial-calling tools; read your tool list.
+
 ## You are the leader - orchestrate, do not implement
 
 The main session is ALWAYS the team leader; you orchestrate directly and never spin up a separate
-leader thread. Your job is orchestration, NOT writing product code: split the work and assign each
+leader worker. Your job is orchestration, NOT writing product code: split the work and assign each
 slice, hold live situational awareness of every member, verify and QA what they deliver, relay
 findings between members, instruct and unblock, and synthesize the result. DELEGATE every code edit
 to a member - if you catch yourself editing product files while the team runs, that work was a
@@ -39,7 +65,7 @@ merge), not the keystrokes.
 ## Compose by part, ownership, or perspective - not by job title
 
 A team is ALWAYS two or more members - never a single-member team. One worker on an isolated
-job is a spawned subagent, not a team; if you end up with a single member,
+job is a plain subagent, not a team; if you end up with a single member,
 either split off a second distinct slice or drop the team and use a subagent.
 
 Compose the team from what you actually KNOW about the work. Ground the split in real knowledge
@@ -50,8 +76,10 @@ perspective/lens. Assigning a vague role ("backend dev", "release analyst", "the
 anti-pattern - it gives the member no real boundary and invites overlap. Each member's `focus`
 names what they own concretely; the `lens` is one of `area`, `ownership`, or `perspective`.
 Give each member a short, distinct `--name` too - its role or what it watches (e.g.
-`app-server-lifecycle`, `mailbox-delivery`) - because that name titles its thread; never reuse
-one name for two members.
+`app-server-lifecycle`, `mailbox-delivery`) - it labels the member everywhere; never reuse
+one name for two members. On MultiAgentV2 teams also give each member a unique
+`--task-name` in `lowercase_digits_underscores` form - it becomes the member's permanent
+agent path `/root/<task_name>`.
 
 ## Run the script - never hand-write team state
 
@@ -60,9 +88,10 @@ the member manual by hand. Run it with `node` (or `bun`); it works on macOS, Lin
 Replace `<skill-root>` with this skill's own directory.
 
 ```
-node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<session>" [--session <leader_session_id>] [--worktree] [--base-branch dev]
-node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
-node "<skill-root>/scripts/team.mjs" bind-thread  --team <session_id> --id A --thread <thread_id> [--cwd <path>]
+node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<session>" --transport multi_agent_v2|codex_app [--session <leader_thread_id>] [--worktree] [--base-branch dev]
+node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --name "<short role>" [--task-name <v2_task_name>] --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
+node "<skill-root>/scripts/team.mjs" bind-agent   --team <session_id> --id A --agent-path /root/<task_name> [--cwd <path>]   # multi_agent_v2 teams
+node "<skill-root>/scripts/team.mjs" bind-thread  --team <session_id> --id A --thread <thread_id> [--cwd <path>]             # codex_app teams
 node "<skill-root>/scripts/team.mjs" member-prompt --team <session_id> --id A
 node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --status reported|blocked|active|archived [--note "<...>"]
 node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
@@ -74,70 +103,93 @@ node "<skill-root>/scripts/team.mjs" status       --team <session_id>
 ```
 
 `init` creates `.omo/teams/{session_id}/` containing `team.json` (the single durable state file:
-team id, the main-session leader, the member roster, status, worktree config, and a lifecycle
-log), `guide.md` (the auto-generated member field manual), and `artifacts/` (a shared exchange
-space). `{session_id}` is the leader's Codex session id when you can pass it via `--session`;
-otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
-subcommand rewrites `guide.md`, so the manual always matches the current team.
+team id, transport, the main-session leader, the member roster, status, worktree config, and a
+lifecycle log), `guide.md` (the auto-generated member field manual), and `artifacts/` (a shared
+exchange space). On codex_app teams `{session_id}` is the leader's Codex session id when you can
+pass it via `--session`; otherwise the script generates a stable handle. Re-running `init` is a
+safe no-op. Every mutating subcommand rewrites `guide.md`, so the manual always matches the
+current team.
 
 Mutating subcommands take a per-team state lock before reading and rewriting `team.json`. It is
-safe to run independent `add-member`, `bind-thread`, `set-status`, `archive`, `delete`, `guide`,
-and worktree mutation commands concurrently against the same team: they serialize and each command
-reads the latest committed state before writing. If a command reports that team state is locked,
-do not treat the intended mutation as complete; retry after the named command finishes, or inspect
-`.omo/teams/{session_id}/.team.lock/owner.json` if the previous command crashed.
-
-## Create the team and its threads
-
-1. `init` the team, then `add-member` once per member.
-2. Create a durable thread per member with `codex_app.create_thread` - ALWAYS this tool for every
-   member, never a spawned agent - titled `[team name] <member name>`, using THAT member's own
-   name (its role / what it watches), so no two threads share a title. `add-member` prints the
-   exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
-   set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
-   Use `codex_app.set_thread_title` if the title did not land at creation.
-   If Codex returns only `pendingWorktreeId`, the worktree-backed thread is not ready yet: do not
-   `bind-thread` and do not send the member bootstrap. Wait until Codex surfaces a real `threadId`
-   or the thread appears in the thread list, then set the title, bind that real id with the cwd,
-   and only then send the bootstrap.
-3. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
-   trigger (printed by `add-member` / `member-prompt`) as the thread's first message. The trigger
-   is short on purpose: it tells the new thread to READ its `guide.md` and `team.json` rather than
-   carrying the whole protocol inline.
-4. Whenever you report, audit, reopen, or hand off a member thread, include the app deep link
-   `codex://threads/<thread_id>` next to the raw id. For example:
-   `codex://threads/019ef350-ee78-72a3-bd5e-e40cebc3d814`. Worktree-backed threads are easy to
-   lose in the sidebar without this link.
-
-Every team member is a real Codex thread created with `codex_app.create_thread` - this is strict,
-not a preference. NEVER substitute a spawned in-process subagent (`multi_agent_v1.spawn_agent` or flat `spawn_agent`)
-for a team member: a spawned agent is an ephemeral helper that does not show up as a team thread,
-cannot carry the `[team name] <member name>` title, and cannot be inspected, titled, archived, or
-re-opened with the `codex_app.*` thread tools - which defeats the entire point of a durable team.
-A member only counts once you have `bind-thread`-ed it to a real `codex_app.create_thread` thread
-id. If the thread-creation tool is unavailable, STOP and say so (see Stop rules); do not quietly
-fall back to a spawned agent.
+safe to run independent `add-member`, `bind-agent`, `bind-thread`, `set-status`, `archive`,
+`delete`, `guide`, and worktree mutation commands concurrently against the same team: they
+serialize and each command reads the latest committed state before writing. If a command reports
+that team state is locked, do not treat the intended mutation as complete; retry after the named
+command finishes, or inspect `.omo/teams/{session_id}/.team.lock/owner.json` if the previous
+command crashed. `bind-agent` refuses codex_app teams and `bind-thread` refuses multi_agent_v2
+teams, and a refused command never changes `team.json`.
+
+## Create the team and its members
+
+`init` the team, then `add-member` once per member. What happens next depends on the transport.
+
+**MultiAgentV2 teams:**
+1. If a member needs an isolated worktree, run `worktree-add` BEFORE spawning it - flat
+   `spawn_agent` has no cwd argument, so the path must ride in the bootstrap message.
+2. Spawn each member with flat `spawn_agent`: `task_name` is that member's `--task-name`,
+   `message` is the bootstrap printed by `add-member` / `member-prompt`, and
+   `fork_turns: "none"` (members read `guide.md` for context; full parent history is not
+   their context model). Do not set `agent_type`, `model`, or `reasoning_effort`.
+3. `bind-agent --agent-path` with the canonical task name the spawn returned (normally
+   `/root/<task_name>`); binding confirms the runtime identity matches the roster and records
+   the member's cwd. Members are durable: they persist as subagent threads, survive idling,
+   and are re-tasked with `followup_task` - never respawned under a second name.
+4. Members appear in `list_agents` with their task paths; inspect status there instead of
+   deep links (V2 exposes no thread title or `codex://` link surface to you).
+
+**Codex App teams:**
+1. Create a durable thread per member with `codex_app.create_thread` - ALWAYS this tool for
+   every member - titled `[team name] <member name>`, using THAT member's own name, so no two
+   threads share a title. `add-member` prints the exact title to use. If the tool accepts a
+   working directory / cwd argument, set it to that member's worktree; otherwise the member's
+   manual tells it to `cd` there first. Use `codex_app.set_thread_title` if the title did not
+   land at creation. If Codex returns only `pendingWorktreeId`, the worktree-backed thread is
+   not ready yet: do not `bind-thread` and do not send the member bootstrap. Wait until Codex
+   surfaces a real `threadId`, then set the title, bind that real id with the cwd, and only
+   then send the bootstrap.
+2. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
+   trigger as the thread's first message. The trigger is short on purpose: it tells the new
+   thread to READ its `guide.md` and `team.json` rather than carrying the whole protocol inline.
+3. Whenever you report, audit, reopen, or hand off a member thread, include the app deep link
+   `codex://threads/<thread_id>` next to the raw id - worktree-backed threads are easy to lose
+   in the sidebar without it. On a codex_app team, a spawned in-process agent is never a
+   member substitute: it cannot carry the team title or be inspected, titled, archived, or
+   re-opened with the `codex_app.*` tools this team runs on.
+
+On either transport, a member only counts once it is bound (`bind-agent` / `bind-thread`). If
+the selected transport's tools stop working mid-run, STOP and say so (see Stop rules); do not
+quietly switch transports.
 
 ## Communication
 
-Members push to you and to one another with `codex_app.send_message_to_thread`; you inspect their
-state with `codex_app.read_thread`. So members can actually reach you, run `init` with
-`--session <your own thread id>` - that makes `leader.sessionId` in team.json a real, messageable
-thread; without it members cannot report to you and you are stuck polling. The generated manual binds
-members to the hard rules, so you mainly keep the channel open: expect frequent small inbound updates
-from each member - findings, `WORKING:`/`BLOCKED:` markers, peer digests - rather than one final
-dump, and act on them as they arrive. All member-to-member and member-to-leader traffic is in English;
-when the END user addresses a member, that member replies in the user's own language. Members hand off
-files and memos through the team `artifacts/` directory and reference them by path.
+Members push to you and to one another; you never poll them as a routine. The address book is
+`team.json`, and the generated manual binds members to the hard rules, so you mainly keep the
+channel open: expect frequent small inbound updates from each member - findings,
+`WORKING:`/`BLOCKED:` markers, peer digests - rather than one final dump, and act on them as
+they arrive.
+
+- **MultiAgentV2:** members reach you with `send_message` to `/root` and reach peers by their
+  `members[].agentPath`. You reach members the same way; use `followup_task` when you hand an
+  idle member NEW work (it wakes the member), `send_message` for context that should not
+  interrupt, and `wait_agent` only when you are genuinely blocked on their next update - a
+  `wait_agent` timeout only means no new mailbox update arrived, never that a member failed.
+  Your own session IS `/root` - members can always reach you; leave `--session` unset.
+- **Codex App:** members push with `codex_app.send_message_to_thread`; you inspect state with
+  `codex_app.read_thread`. So members can actually reach you, run `init` with
+  `--session <your own thread id>` - that makes `leader.sessionId` in team.json a real,
+  messageable thread; without it members cannot report to you and you are stuck polling.
+
+All member-to-member and member-to-leader traffic is in English; when the END user addresses a
+member, that member replies in the user's own language. Members hand off files and memos
+through the team `artifacts/` directory and reference them by path.
 
 ## Let members work - do not rush them
 
 Members heartbeat every few tool calls and message you on every finding, blocker, and finished
 slice (their manual binds them to this). So a member that is quiet between heartbeats is **working,
 not stalled** - a stretch of silence is the normal sound of focused work, not a problem to chase.
-Re-reading `codex_app.read_thread` to check on a calm member, or sending "any update?" / "are you
-done?" / "hurry up" pings, interrupts that member and slows the whole team. Trust the heartbeat and
-let them cook.
+Re-reading a calm member's state, or sending "any update?" / "are you done?" / "hurry up" pings,
+interrupts that member and slows the whole team. Trust the heartbeat and let them cook.
 
 Message a member only when one of these is true:
 - you have new information, context, or a correction it needs to do its slice right;
@@ -147,7 +199,9 @@ Message a member only when one of these is true:
   then send one specific question, not a barrage.
 
 Otherwise stay calm and keep the channel open: read inbound updates as they arrive and act on them.
-A long-running member is alive; a heartbeat you have not received yet is not a failure. Wait for
+A long-running member is alive; a heartbeat you have not received yet is not a failure. Fallback only when
+a member is completed without its deliverable, explicitly `BLOCKED:`, or no longer running - then
+unblock, reassign, or re-task that slice instead of waiting on it. Wait for
 every required member's final report before you declare the team done - rushing toward "done" while
 members are still mid-slice just produces half-built work you will have to redo.
 
@@ -162,10 +216,12 @@ its own worktree. To land the work, `integrate --team <id>` merges every member
 current branch with a merge commit (never a squash or rebase); resolve any conflict it reports, then
 `worktree-remove` each worktree at cleanup.
 
-After `worktree-add`, immediately send the member a follow-up that includes both its assigned
-worktree path and its `codex://threads/<thread_id>` link. Use `bind-thread --cwd <worktree>` or
-`--worktree-path <worktree>` after the thread exists so `team.json`, `guide.md`, `status`, and
-`member-prompt` all point at the same worktree-backed thread.
+Delivering the path differs by transport: on MultiAgentV2, create the worktree BEFORE spawning
+so the bootstrap carries it, or send it to an already-running member as a `followup_task`; on
+Codex App, send a follow-up message that includes both the worktree path and the member's
+`codex://threads/<thread_id>` link. Either way, run `bind-agent`/`bind-thread` with
+`--cwd <worktree>` (or `--worktree-path`) so `team.json`, `guide.md`, `status`, and
+`member-prompt` all point at the same worktree-backed member.
 
 When the member starts inside a worktree, it must verify the assigned cwd exists and contains the
 repository checkout before editing. If the directory is missing, empty, or does not look like a git
@@ -194,8 +250,11 @@ then delete the team state only after archival evidence is clean or preserved. A
 is never disbanded is a leak.
 
 - `archive` closes the team: notify each active member, copy anything useful into `artifacts/`,
-  then try to archive each member thread with `codex_app.set_thread_archived`. Treat Codex App
-  failures such as "Ambiguous Codex thread id" or a thread id that is ambiguous across hosts as an
+  then close each member on its transport. On MultiAgentV2, `interrupt_agent` any member still
+  mid-turn and record in the note that V2 exposes no runtime archive operation - the durable
+  `team.json` state IS the archive; never claim a V2 agent itself was archived. On Codex App,
+  try `codex_app.set_thread_archived` per member thread; treat failures such as
+  "Ambiguous Codex thread id" or an id that is ambiguous across hosts as an
   app-thread archival blocker, not as a team-state blocker: record the failure in the team log,
   tell the user which member thread was not proven archived, and continue the team-state archive
   with `archive --note "<blocker>"`. Never pretend a member thread was archived. Do not delete the
@@ -212,5 +271,6 @@ is never disbanded is a leak.
 - Stop and ask before deleting an unarchived team while any member is still active.
 - Member communication stays English unless the user explicitly requests otherwise; user-facing
   replies follow the user's language.
-- Stop if the requested operation needs Codex thread tools (create/read/send/title/archive) and
-  they are unavailable; say so instead of faking it.
+- Stop if the selected transport's tools (V2 spawn/message/wait/list/interrupt, or Codex App
+  create/read/send/title/archive) are unavailable or stop working; say so instead of faking it
+  or silently switching transports.