From 0b628fa4afae4c87b7744429df948dc0a52175d0 Mon Sep 17 00:00:00 2001 From: Martin Patino Date: Thu, 1 Oct 2026 21:10:16 -0700 Subject: [PATCH] docs: note that Codex runs the opt-in session hook Codex 0.157.1 runs the plugin's SessionStart hook and injected the old poteto-mode mandate as a developer message in 20 recorded sessions, so the opt-in gate from #19 applies to Codex too. Correct the README, reference, and changelog lines that said Codex has no hook runtime. Refs #18 --- CHANGES.md | 2 +- README.md | 2 +- docs/reference.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 6850d0b2..da7cd688 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,7 +4,7 @@ - The `SessionStart` hook no longer routes every non-trivial engineering task into `poteto-mode`. `hooks/session-start-context.md` is now an opt-in gate: Claude invokes a `pstack:*` skill only when the user types `/pstack:`, names pstack or one of its skills in the request, or keeps a standing CLAUDE.md or AGENTS.md instruction for it. A pstack skill the user started keeps routing to the skills it needs for that task, and dispatched subagents follow their dispatch prompt. - The gate also covers skills whose own descriptions ask for automatic use, such as `unslop` and `typescript-best-practices`, without changing those upstream descriptions or adding `disable-model-invocation`, which would block `poteto-mode` from invoking them. -- Why: the mandate sent ordinary tasks through the full poteto-mode pipeline (playbook and principle reads, `how`, `architect` panels, external Codex delegation, `interrogate`), which made simple work slow on Claude Code. Codex already worked this way because it has no plugin hook runtime. Users who want the old always-on routing add one standing instruction to CLAUDE.md. Tracked in [pstack-flex #18](https://github.com/thisguymartin/pstack-flex/issues/18). +- Why: the mandate sent ordinary tasks through the full poteto-mode pipeline (playbook and principle reads, `how`, `architect` panels, external Codex delegation, `interrogate`), which made simple work slow on Claude Code. Codex runs the same hook (observed on Codex 0.157.1, which injected the old mandate as a developer message), so the gate applies there too. Users who want the old always-on routing add one standing instruction to CLAUDE.md. Tracked in [pstack-flex #18](https://github.com/thisguymartin/pstack-flex/issues/18). ## Unreleased: GPT-6 Codex families become stock diff --git a/README.md b/README.md index 26666349..8c72e0e2 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,7 @@ Both apps read the same pstack skills. Only the way they start those skills and | | Claude Code | Codex | | --- | --- | --- | -| Start poteto-mode | Run `/pstack:poteto-mode` or ask for pstack by name. A small startup instruction keeps Claude from starting pstack skills on its own. | Ask for `pstack:poteto-mode` by name. Codex does not load the Claude startup instruction. | +| Start poteto-mode | Run `/pstack:poteto-mode` or ask for pstack by name. A small startup instruction keeps Claude from starting pstack skills on its own. | Ask for `pstack:poteto-mode` by name. Codex runs the same startup instruction, so pstack skills also wait for a request there. | | Runs inside the app | Claude models stay inside Claude Code. | The Codex families stay inside Codex. | | Other models | The Codex families and Grok run through their signed-in command-line tools. | Claude and Grok run through their signed-in command-line tools. | | Gateway models | DeepSeek and MiniMax always run through the external runner with an isolated config directory, never as a native agent. | Same. | diff --git a/docs/reference.md b/docs/reference.md index fd54a789..b1caada6 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -62,7 +62,7 @@ The marketplace install is the normal user path. Direct links are only for testi │ ├── skills/ # 54 skills shared by Claude Code and Codex │ │ ├── poteto-mode/references/{codex-tools,provider-dispatch}.md # tool + provider routing │ │ └── poteto-mode/scripts/ # bun/bash/node tooling: watch-pr, orch, runner, check-plan.mjs, worktree-audit.sh -│ ├── hooks/ # SessionStart opt-in gate: pstack runs only on request (Claude Code only) +│ ├── hooks/ # SessionStart opt-in gate: pstack runs only on request (Claude Code and Codex) │ └── agents/ # Claude subagents, including native Fable and Opus lanes at each selectable effort ├── tests/skill-collision-repro.sh # native-skill package invariants and Claude invocation checks ├── LICENSE # pstack upstream MIT @@ -85,7 +85,7 @@ The Codex build shares one `skills/` tree with the Claude Code build. Nothing is - **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 23 `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 can keep Sol native while invoking Claude and Grok externally. - **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; external Claude and Grok 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. -- **Opt-in.** The `hooks/` SessionStart gate 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 every non-trivial task routed into it. +- **Opt-in.** Codex runs the plugin's `hooks/` SessionStart hook and adds the opt-in gate to each session as a developer message (observed on Codex 0.157.1). Codex records trust for the hook in `~/.codex/config.toml` under `hooks.state`. Enter `pstack:poteto-mode` by name, or add a standing instruction to `~/.codex/AGENTS.md` if you want every non-trivial task routed into it. After a plugin update, run `codex plugin marketplace upgrade open-pstack` so the installed copy carries the current gate. - **Models.** `/setup-pstack` writes provider-qualified descriptors and asks one requested effort per frontier family (`low`, `medium`, `high`, `xhigh`, `max`). The first-run panel is Fable max, GPT-6 Astra high, Grok 4.6 xhigh, and Opus xhigh. Fable and Opus use Claude's rolling aliases. 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. The GPT-6 Astra, Sol, and Luna Codex families are stock: GPT-6 Sol high carries `feature, refactoring`, `bug-fix`, `perf-issue`, and `hillclimb`; Luna high carries `how explorer` and `swarm workers`; Astra high sits on every panel. GPT-5.6 Sol remains a selectable family. In Codex, every Codex family uses native `spawn_agent`; Claude and Grok use the deterministic external runner. In Claude Code, Fable and Opus use native agents; the Codex families and Grok use the runner. Children never detect the parent or reroute themselves. The solo code roles stay on a Codex model instead of upstream's Fable default because it costs less for these frequent delegated code roles. Verified in fresh installed Claude Code and Codex sessions: the user-facing skills are discovered and namespaced under `pstack`; both parents fan out the frontier quad through the documented native/external route table, retain long-running handles without a default timeout, and cross-judge only after every candidate is terminal. The `principle-*` leaves remain available for `poteto-mode` to read by path. Claude honors their `user-invocable: false` metadata; Codex 0.149.0 does not ([#8](https://github.com/ericlitman/open-pstack/issues/8)).