Skip to content

docs(codex): use multi-agent v2 - #299

Open
oppegard wants to merge 4 commits into
ericlitman:mainfrom
oppegard:docs/codex-multi-agent-v2
Open

oppegard wants to merge 4 commits into
ericlitman:mainfrom
oppegard:docs/codex-multi-agent-v2

Conversation

@oppegard

@oppegard oppegard commented Nov 16, 2026 •

Copy link
Copy Markdown

Summary

Using multi_agent in Codex now issues warnings (see screenshot below). Migrate to multi_agent_v2.

  • Show the current Codex V2 setting and optional task plan tool in the README. Update the installed help skill and reference page.
  • Explain the optional V2 thread cap in the Codex tool reference.
  • Use optional Codex tools only when exposed, and remove the close_agent row because V2 does not expose it.

OpenAI Codex stabilized V2 with opt-in enablement, defined its session cap, and made update_plan opt-in. Its V2 tool registration omits close_agent.

Closes #298.

Approved plan and current checklist.

Checks

  • bun run test: 509 passed with the inherited CODEX_SANDBOX_NETWORK_DISABLED hint removed from the test process.
  • bun run typecheck: passed.
  • bun run static: passed, including 219 verifier tests.
  • claude plugin validate plugins/pstack: passed.
  • claude plugin validate .claude-plugin/marketplace.json: passed.

Exact-head live verification

  • Installed commit c33d5c7 in an isolated Codex home using the README's exact TOML block. Installed skill and reference hashes match the candidate.
  • A fresh poteto-mode session read the installed tool reference. Codex accepted the README block under strict config parsing, called update_plan, and completed both task steps. The installed V2 tool list and tool reference had no close_agent.
  • The prior head's A/B test showed the default checklist fallback and the enabled update_plan path. Its native V2 child probe dispatched codex:gpt-6.1-sol@high, read a private marker, and returned the matching value.
  • verify-open-pstack stopped before its cases with Require an open same-repository PR. This fork PR has no live-gate status.

This PR stays draft. Its repository gate needs a same-repository branch or a verifier change before merge. Merge also needs user approval.

Screenshot of multi_agent warning

CleanShot 2026-11-16 at 2 49 57 PM@2x

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 ericlitman#298.
@oppegard

oppegard commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

Codex multi-agent v2 guidance

Evidence

  • This machine runs Codex CLI 0.169.0. Its installed pstack 1.21.0 plugin and verifier doctor pass. A read-only Codex session loaded the local poteto-help skill from the installed plugin cache.
  • OpenAI Codex PR #34383 marks multi_agent_v2 stable and off by default. PR #19792 defines its max_concurrent_threads_per_session setting, which includes the root thread.
  • OpenAI Codex PR #41744 makes update_plan opt-in. This session has spawn_agent and wait_agent, but no close_agent or update_plan tool.

Proposed changes

  1. Show the stable V2 setting in the README, docs/reference.md, the Codex tool mapping, and poteto-help. Show optional update_plan in the README. Tell users to start a new Codex session after changing it. Document the optional V2 session cap without requiring a particular value.
  2. Make the Codex tool mapping conditional where a tool is optional or absent. Remove the unavailable close_agent row. Keep the native spawn and wait route clear for pstack's Codex model roles.
  3. Add a focused check for the current Codex install setting if existing repository checks offer a suitable place. Do not add dependencies.
  4. Open a draft PR linked to a repository issue. Keep the PR draft until the user approves merging.

Verification

  • Run Bun tests, strict typecheck, static invariants, and plugin validation before opening the PR, as the repository requires.
  • Install the exact PR head in the repository verifier's run-owned Codex home. Run the relevant Codex skill invocation cases and retain the machine-checked evidence.
  • Run a small read-only Codex V2 delegation probe using the candidate and check the child result and selected runtime. This proves native subagent dispatch rather than just config parsing.
  • Publish the verifier's exact-head live-gate evidence to the PR. Recheck after any head change.

Checklist

  • Confirm the current Codex V2 config and optional tool semantics.
  • Update install and runtime guidance.
  • Run repository checks: 509 Bun tests, strict typecheck, static invariants (219 verifier tests), and Claude plugin and marketplace validation pass.
  • Create draft PR docs(codex): use multi-agent v2 #299 and repository issue docs(codex): use stable multi-agent v2 #298.
  • Publish the approved plan as a separate PR comment and link it from the PR description.
  • Run exact-head live Codex checks and retain private evidence.
  • Report the outcome and the same-repository PR gate limit.

Outcome

  • Review feedback removed migration background from the README, docs/reference.md, and Codex tool reference.
  • Review feedback added optional update_plan to the README and removed the close_agent row from the Codex tool mapping.
  • Candidate c33d5c7ac84aedc10c75d7c3570f18680dbe4e88 was installed in a run-owned Codex home using the README's exact TOML block. Installed skill and reference hashes match the candidate.
  • A fresh Codex session loaded poteto-mode and the installed tool reference. Strict config parsing accepted the README block. The session called update_plan and completed two tasks. Its V2 tool surface had no close_agent.
  • The prior head's A/B task tracking test showed the default checklist fallback and the enabled plan tool. Its native child probe dispatched gpt-6.1-sol at high effort, read a private marker, and returned the matching value.
  • All 509 Bun tests passed on the preceding head after removing the inherited CODEX_SANDBOX_NETWORK_DISABLED hint from the test process. Strict typecheck, static invariants, and plugin validation also passed. The current head changes one README sentence and passed a fresh live Codex check.
  • GitHub Actions marked the CI and Windows hook runs on the current fork head action_required; neither run started a job. A maintainer with write access must approve the fork runs.
  • verify-open-pstack refused fork PR docs(codex): use multi-agent v2 #299 before any live case: Require an open same-repository PR. No live-gate status was published. Keep the PR draft until a same-repository branch or an approved verifier change can satisfy the gate.

@mergify

mergify Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Merge Protections

🟠 1 of 2 protections blocking · waiting on 🤖 CI

Protection Waiting on
🟠 Queue ready pull requests 🤖 CI
🟢 🚦 Auto-queue —

🟠 Queue ready pull requests

Waiting for

  • check-success=live-gate
  • check-success=verify
Waiting checks: live-gate, verify.

Automatically queue non-draft pull requests targeting main after verify and live-gate pass on the head and every review thread is resolved.

  • check-success=live-gate
  • check-success=verify
  • #review-threads-unresolved = 0
  • -draft

Show 1 satisfied protection

🟢 🚦 Auto-queue

When all merge protections are satisfied and these conditions match, this pull request will be queued automatically.

  • -files~=^\.github/
  • base = main

oppegard and others added 3 commits November 16, 2026 14:21
Keep installation and tool guidance focused on the current V2 setting. Remove migration background from the user-facing setup pages.
Add the opt-in task plan setting beside the V2 setup example. Remove the close-agent mapping because V2 does not expose that tool.
Clarify instructions for enabling Codex subagents.
@oppegard
oppegard marked this pull request as ready for review November 16, 2026 22:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(codex): use stable multi-agent v2

1 participant