From 04ca84db71b88306f16853e211643cf611b7db6e Mon Sep 17 00:00:00 2001 From: Glenn Oppegard Date: Mon, 16 Nov 2026 13:56:48 -0700 Subject: [PATCH 1/4] docs(codex): use multi-agent v2 Replace the deprecated V1 configuration in install and runtime guidance. Document the V2 session cap and account for optional Codex tools so pstack can select native lanes from the active tool surface. Closes #298. --- README.md | 8 ++++---- docs/reference.md | 10 ++++++---- plugins/pstack/skills/poteto-help/SKILL.md | 2 +- .../skills/poteto-mode/references/codex-tools.md | 16 +++++++++------- 4 files changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ac51439c..2580c1ec 100644 --- a/README.md +++ b/README.md @@ -67,14 +67,14 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Turn on Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: +Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true ``` -Start a new Codex task after installation so it can discover the new skills and setting. +Remove any explicit `multi_agent = ...` entry: Codex warns on this deprecated V1 setting. V2 allows three child threads by default, alongside the root thread. For larger fan-outs, set `max_concurrent_threads_per_session` in the same V2 table to the total number of threads you need. Start a new Codex task after installation so it can discover the new skills and setting. ## Get started diff --git a/docs/reference.md b/docs/reference.md index a6af5699..03b3fe59 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -33,13 +33,15 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Codex discovers the plugin skills under the `pstack` namespace, so they list as `pstack:poteto-mode`, `pstack:tdd`, and so on. The namespace comes from `plugins/pstack/.codex-plugin/plugin.json`. To enable the multi-model and parallel-subagent skills (`interrogate`, `arena`, `how`, `why`, `reflect`, `architect`), turn on subagents in `~/.codex/config.toml`: +Codex discovers the plugin skills under the `pstack` namespace, so they list as `pstack:poteto-mode`, `pstack:tdd`, and so on. The namespace comes from `plugins/pstack/.codex-plugin/plugin.json`. To enable native subagents for parallel skills (`interrogate`, `arena`, `how`, `why`, `reflect`, `architect`), turn on multi-agent V2 in `~/.codex/config.toml`: ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true ``` +Codex [deprecated the explicit `multi_agent` setting](https://github.com/openai/codex/pull/59479) while keeping its V1 fallback on by default. Remove that key from user and project config to clear the startup warning. [V2 is stable but off by default](https://github.com/openai/codex/pull/34383). Its default limit is four total threads, including the root. Set `max_concurrent_threads_per_session` in the V2 table when a larger fan-out needs more slots; the [V2 limit counts the root](https://github.com/openai/codex/pull/19792). Start a new task after changing the setting. + For local plugin development, you can clone the repository and link its skills directly: ```shell @@ -86,7 +88,7 @@ The Codex build shares one `skills/` tree with the Claude Code build. Nothing is - **Skill invocation.** Codex loads `SKILL.md` natively. There is no `Skill` tool. You invoke a skill by name (ask for it, or pick `pstack:poteto-mode` from the list). - **Package surface.** The native `skills/` tree is the only workflow source. The plugin ships no `commands/` layer and does not link prompts into `~/.codex/prompts/`. Codex would migrate such files into duplicate source-command skills while loading the native skill tree. The 24 `principle-*` leaves declare `user-invocable: false`. Claude keeps them out of its user picker; Codex 0.149.0 currently shows them despite that metadata ([#8](https://github.com/ericlitman/open-pstack/issues/8)). - **Tool and built-in mapping.** Claude tool names and built-in skills resolve through [`codex-tools.md`](../plugins/pstack/skills/poteto-mode/references/codex-tools.md). Model execution resolves separately through [`provider-dispatch.md`](../plugins/pstack/skills/poteto-mode/references/provider-dispatch.md), so Codex models stay native while other providers run through the external runner. -- **Subagents.** The `Agent` tool maps to Codex `spawn_agent` / `wait_agent`, enabled by `multi_agent = true`. Parallel fan-out is multiple `spawn_agent` calls in one turn. If the native Codex lane is unavailable, record that lane as a dropout; the configured external lanes still run, and no provider is silently substituted. There is no `poteto-agent` subagent type on Codex; route ad-hoc subagents by dispatching a `spawn_agent` told to read `poteto-mode` first. +- **Subagents.** The `Agent` tool maps to Codex `spawn_agent` / `wait_agent`. Enable `multi_agent_v2` as shown above and check that the current tool surface exposes `spawn_agent`. Parallel fan-out is multiple `spawn_agent` calls in one turn. If the native Codex lane is unavailable, record that lane as a dropout; the configured external lanes still run, and no provider is silently substituted. There is no `poteto-agent` subagent type on Codex; route ad-hoc subagents by dispatching a `spawn_agent` told to read `poteto-mode` first. - **Auto-fire.** The `hooks/` SessionStart injection is Claude Code-only; Codex has no plugin hook runtime. Enter `pstack:poteto-mode` by name, or add a standing instruction to `~/.codex/AGENTS.md` if you want the same always-on routing. - **Models.** `/setup-pstack` writes provider-qualified descriptors and asks one requested effort per assigned family (`low`, `medium`, `high`, `xhigh`, `max`, and `ultra` where the model's CLI lists it, today Sol and Astra). The first-run sheet is the model catalog's [role defaults](../plugins/pstack/skills/poteto-mode/references/model-catalog.md#role-defaults), with a panel of Opus, Sol, and Grok; Fable, Sonnet, Luna, Astra, Haiku 5.5 and an exact Opus pin stay selectable. Fable, Opus and Sonnet use Claude's rolling aliases; a registered exact pin keeps its own model. Runtime dispatch normalizes older versioned descriptors in memory, so an installed sheet stops pinning immediately. A setup rerun persists that migration while keeping each role's family and effort. In Codex, Codex families such as Sol use native `spawn_agent`; every other provider uses the deterministic external runner. In Claude Code, Claude families use native agents; every other provider uses the runner. In Grok, `inherit-parent` and `auto` use `spawn_subagent`; every explicit descriptor, including Grok's, uses the runner with `--parent grok`. A Codex writer that the runner launches stays in Codex's `workspace-write` sandbox unless the sheet opts in with the line `codex writer sandbox: full-access`, which setup asks about once. Full access lets the writer launch a browser and write dot-folders such as `.agents/`, and removes every sandbox limit. A provider whose writes no sandbox confines, such as OpenCode, Cursor or Muse, writes only when the sheet holds ` writer sandbox: full-access`, which setup asks about when a writer role uses that provider. Children never detect the parent or reroute themselves. The `bug-fix`, `perf-issue`, and `hillclimb` roles stay on Sol instead of upstream's Grok default. diff --git a/plugins/pstack/skills/poteto-help/SKILL.md b/plugins/pstack/skills/poteto-help/SKILL.md index d2c3d0a6..870f7ee4 100644 --- a/plugins/pstack/skills/poteto-help/SKILL.md +++ b/plugins/pstack/skills/poteto-help/SKILL.md @@ -35,7 +35,7 @@ When the model rule is missing and it matters, ask whether the user wants to pic ## Get set up -1. Install. In Claude Code, run `/plugin marketplace add ericlitman/open-pstack`, then `/plugin install pstack@open-pstack`, then `/reload-plugins`. In Codex, run `codex plugin marketplace add ericlitman/open-pstack --ref main`, then `codex plugin add pstack@open-pstack`, and turn on `multi_agent` per [`codex-tools.md`](../poteto-mode/references/codex-tools.md). +1. Install. In Claude Code, run `/plugin marketplace add ericlitman/open-pstack`, then `/plugin install pstack@open-pstack`, then `/reload-plugins`. In Codex, run `codex plugin marketplace add ericlitman/open-pstack --ref main`, then `codex plugin add pstack@open-pstack`, and turn on `multi_agent_v2` per [`codex-tools.md`](../poteto-mode/references/codex-tools.md). 2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It maps a model to each role, asks one requested effort for each model family it assigns, probes those models, and writes a model sheet. A rerun that keeps a valid sheet and names no change asks none of these questions: it keeps the sheet's roles and efforts, probes them, and writes when every probe passes. The sheet applies to new sessions. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one. On a rerun that keeps the sheet, it mentions each offer in one line instead of asking. 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail. diff --git a/plugins/pstack/skills/poteto-mode/references/codex-tools.md b/plugins/pstack/skills/poteto-mode/references/codex-tools.md index 2494d4bf..a9b73d22 100644 --- a/plugins/pstack/skills/poteto-mode/references/codex-tools.md +++ b/plugins/pstack/skills/poteto-mode/references/codex-tools.md @@ -65,18 +65,20 @@ The copy registers under its plain name beside the plugin's `pstack:`, an | Dispatch a subagent (the `Agent`/`Task` tool) | `spawn_agent` | `spawn_subagent` with `subagent_type: pstack:poteto-agent` | | Dispatch N parallel subagents in one turn | N `spawn_agent` calls in one response | N `spawn_subagent` calls in one response | | Wait for a subagent result | `wait_agent` | `get_command_or_subagent_output`, as [Waits on Grok](#waits-on-grok) says | -| Free a finished subagent slot | `close_agent` | None | -| Track tasks (the todolist / `TodoWrite`) | `update_plan` | `todo_write` | -| Ask the human a fixed-choice question (`AskUserQuestion`) | Ask in plain text and let the user answer. Codex has no structured-choice tool. | `ask_user_question` | +| Free a finished subagent slot | Use `close_agent` when exposed; otherwise skip the explicit close step. | None | +| Track tasks (the todolist / `TodoWrite`) | Use `update_plan` when exposed; otherwise keep a short checklist in the conversation. | `todo_write` | +| Ask the human a fixed-choice question (`AskUserQuestion`) | Use a structured question tool when exposed; otherwise ask in plain text. | `ask_user_question` | -Subagent dispatch needs `multi_agent` enabled. Add to `/config.toml`, using Codex's [config-home rule](#harness-config-homes): +For predictable native subagent dispatch, enable stable multi-agent V2 in `/config.toml`, using Codex's [config-home rule](#harness-config-homes): ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true ``` -Without it, the native Codex lane is a named dropout. Independent external lanes still run, and the parent records the reduced provider count. Never collapse a panel into a sequential single-model pass. +Codex [deprecated the explicit `multi_agent` setting](https://github.com/openai/codex/pull/59479); remove it from user and project config to clear the startup warning. [V2 is stable but off by default](https://github.com/openai/codex/pull/34383). Its default limit is four total threads, including the root. If a larger fan-out needs more slots, set `max_concurrent_threads_per_session` in the V2 table to the required total; this [V2 limit includes the root](https://github.com/openai/codex/pull/19792). Start a new Codex task after changing the setting. `update_plan` is [opt-in](https://github.com/openai/codex/pull/41744). + +Check that the current Codex tool surface exposes `spawn_agent` before a native lane. If it does not, the native lane is a named dropout. Independent external lanes still run, and the parent records the reduced provider count. Never collapse a panel into a sequential single-model pass. ## Subagent policy From c4726c0e3fc93283826e2fbc66a42b9e039bf57b Mon Sep 17 00:00:00 2001 From: Glenn Oppegard Date: Mon, 16 Nov 2026 14:21:29 -0700 Subject: [PATCH 2/4] docs(codex): trim V2 setup guidance Keep installation and tool guidance focused on the current V2 setting. Remove migration background from the user-facing setup pages. --- README.md | 2 +- docs/reference.md | 2 -- plugins/pstack/skills/poteto-mode/references/codex-tools.md | 2 +- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2580c1ec..9d0af98c 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare wo enabled = true ``` -Remove any explicit `multi_agent = ...` entry: Codex warns on this deprecated V1 setting. V2 allows three child threads by default, alongside the root thread. For larger fan-outs, set `max_concurrent_threads_per_session` in the same V2 table to the total number of threads you need. Start a new Codex task after installation so it can discover the new skills and setting. +Start a new Codex task after installation so it can discover the new skills and setting. ## Get started diff --git a/docs/reference.md b/docs/reference.md index 03b3fe59..9c64a106 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -40,8 +40,6 @@ Codex discovers the plugin skills under the `pstack` namespace, so they list as enabled = true ``` -Codex [deprecated the explicit `multi_agent` setting](https://github.com/openai/codex/pull/59479) while keeping its V1 fallback on by default. Remove that key from user and project config to clear the startup warning. [V2 is stable but off by default](https://github.com/openai/codex/pull/34383). Its default limit is four total threads, including the root. Set `max_concurrent_threads_per_session` in the V2 table when a larger fan-out needs more slots; the [V2 limit counts the root](https://github.com/openai/codex/pull/19792). Start a new task after changing the setting. - For local plugin development, you can clone the repository and link its skills directly: ```shell diff --git a/plugins/pstack/skills/poteto-mode/references/codex-tools.md b/plugins/pstack/skills/poteto-mode/references/codex-tools.md index a9b73d22..c0c0c2a5 100644 --- a/plugins/pstack/skills/poteto-mode/references/codex-tools.md +++ b/plugins/pstack/skills/poteto-mode/references/codex-tools.md @@ -76,7 +76,7 @@ For predictable native subagent dispatch, enable stable multi-agent V2 in ` Date: Mon, 16 Nov 2026 14:39:06 -0700 Subject: [PATCH 3/4] docs(codex): show optional plan tool Add the opt-in task plan setting beside the V2 setup example. Remove the close-agent mapping because V2 does not expose that tool. --- README.md | 6 +++++- plugins/pstack/skills/poteto-mode/references/codex-tools.md | 1 - 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9d0af98c..a1bdaa90 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,15 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: +Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel. The task plan tool is optional: ```toml [features.multi_agent_v2] enabled = true + +# Optional: enable the task plan tool +[tools.update_plan] +enabled = true ``` Start a new Codex task after installation so it can discover the new skills and setting. diff --git a/plugins/pstack/skills/poteto-mode/references/codex-tools.md b/plugins/pstack/skills/poteto-mode/references/codex-tools.md index c0c0c2a5..53282724 100644 --- a/plugins/pstack/skills/poteto-mode/references/codex-tools.md +++ b/plugins/pstack/skills/poteto-mode/references/codex-tools.md @@ -65,7 +65,6 @@ The copy registers under its plain name beside the plugin's `pstack:`, an | Dispatch a subagent (the `Agent`/`Task` tool) | `spawn_agent` | `spawn_subagent` with `subagent_type: pstack:poteto-agent` | | Dispatch N parallel subagents in one turn | N `spawn_agent` calls in one response | N `spawn_subagent` calls in one response | | Wait for a subagent result | `wait_agent` | `get_command_or_subagent_output`, as [Waits on Grok](#waits-on-grok) says | -| Free a finished subagent slot | Use `close_agent` when exposed; otherwise skip the explicit close step. | None | | Track tasks (the todolist / `TodoWrite`) | Use `update_plan` when exposed; otherwise keep a short checklist in the conversation. | `todo_write` | | Ask the human a fixed-choice question (`AskUserQuestion`) | Use a structured question tool when exposed; otherwise ask in plain text. | `ask_user_question` | From c33d5c7ac84aedc10c75d7c3570f18680dbe4e88 Mon Sep 17 00:00:00 2001 From: Glenn Oppegard Date: Mon, 16 Nov 2026 14:47:19 -0700 Subject: [PATCH 4/4] Update README for Codex subagents configuration Clarify instructions for enabling Codex subagents. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a1bdaa90..81cc626d 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel. The task plan tool is optional: +Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: ```toml [features.multi_agent_v2]