quest-loop 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,96 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [SemVer](https://semver.org/).
 
+## [0.3.0] — 2026-07-08
+
+### Added
+- `$quest:setup` skill plus `quest codex doctor` for native Codex validation:
+  checks Codex CLI availability, installed `quest@quest` version, hook parser
+  health, neutral-directory Quest skill roots, and native `quest-executor` /
+  `quest-reviewer` custom-agent availability.
+- `quest codex install-agents --scope project|user` installs Quest's bundled
+  agent TOML files into Codex's native `.codex/agents` or `~/.codex/agents`
+  locations. The command is idempotent, supports `--dry-run`, and requires
+  `--force` before replacing different existing agent files.
+- `quest --version` reports the package version.
+- `quest-run --codex-goal-mode auto|require|off` controls how headless Codex
+  runs treat goal tools. `auto` is the default and uses documented
+  `codex exec --json --output-schema` output as the contract; `require` blocks
+  honestly when `create_goal` is not observed; `off` avoids goal-tool prompts.
+
+### Changed
+- Codex is now the first-class plugin path in docs and skill UI metadata:
+  examples use `$quest:*`, the Codex setup flow runs `quest codex doctor`, and
+  `package.json`, `.claude-plugin/plugin.json`, and `.codex-plugin/plugin.json`
+  now share the same version.
+- `codex exec resume` invocations no longer pass unsupported `-C`; the runner
+  relies on the child process working directory and original Codex session.
+- Bundled hooks now prefer `CODEX_PLUGIN_ROOT` with a `CLAUDE_PLUGIN_ROOT`
+  fallback, include a `resume` SessionStart matcher, status messages, timeouts,
+  and Windows command variants.
+
+### Fixed
+- SubagentStop hook now recognizes Codex JSONL `command_execution` entries in
+  addition to Claude-style `tool_use.input.command` blocks, while preserving the
+  mutating-verb-only detection rule.
+
+## [0.2.0] — 2026-07-08
+
+### Added
+- `quest reopen <id> --reason <why>` — the audited exit from `complete`. Flips a
+  completed quest back to `in_progress` on both backends, recording the reason in
+  a real checkpoint via the new optional `reopen_reason` field; the GitHub backend
+  reopens the mirrored issue and swaps `quest:complete → quest:in-progress`.
+  `TRANSITIONS.complete` stays empty — a checkpoint can never resurrect a complete
+  quest; only the explicit verb can, and `cancelled` remains fully terminal.
+  Reopening a child of a complete parent epic warns on stderr that the epic's
+  verdict may be falsified. Reopened quests do not re-enter `quest list --ready`;
+  they are dispatched directly by id. `quest edit` on a complete or cancelled
+  quest now errors with a reopen-first / file-a-new-quest hint, and `quest-run`
+  on an already-complete quest suggests the verb instead of silently no-opping.
+
+### Changed
+- Wave composition now treats epics (parent quests) as orchestrator-closed, not
+  worker-dispatched. `quest list --ready` excludes any quest with a non-terminal
+  child (a child in complete or cancelled is terminal, so a cancelled child no
+  longer wedges its epic), in both the local and GitHub backends. `quest-run
+  --ready` additionally refuses to auto-dispatch a quest that has children even
+  once they are all terminal, logging an actionable "is an epic — close it inline
+  per $quest:orchestrate" line; a direct `quest-run <id>` on an epic stays
+  allowed. The orchestrate skill gains a "Closing an epic" procedure and the plan
+  skill documents that epic contracts are integration-level only.
+
+### Fixed
+- SubagentStop hook now keys quest-executor detection to real *mutating*
+  invocations — `quest start <id>` or `quest checkpoint <id>` (under any binary
+  prefix: `quest`, `./bin/quest`, `node bin/quest`) — instead of the read-only
+  `quest show <id> --json` orientation call. Reviewers and orchestrators that run
+  only read verbs (show / list / protocol / runs) never owned a quest, so they are
+  allowed silently; this removes a false positive where a read-only quest-reviewer
+  was blocked at stop for merely inspecting a terminal quest. A `quest checkpoint`
+  invocation counts too, so an executor resuming an already-in_progress quest
+  (which skips `quest start`) is still detected. The first mutating invocation wins
+  (deterministic); the executor block, per-entry parsing that keeps skill-text
+  examples from keying detection, and conservative allow-on-ambiguity are all
+  preserved.
+- SubagentStop hook now derives the quest-executor id by parsing the transcript
+  JSONL per-entry and matching its marker only inside real tool_use command
+  invocations — never prose, examples, or echoed file contents. This removes a
+  false positive where skill-text examples keyed the detection ahead of the
+  executor's real call. The first real invocation wins (deterministic);
+  conservative allow-on-ambiguity is preserved.
+
+## [0.1.1] — 2026-07-07
+
+### Fixed
+- Codex plugin hook config now uses the strict top-level `hooks` schema that
+  Codex accepts, removing the startup parse warning caused by an extra
+  `description` field.
+
+### Changed
+- Manifest validation now checks `hooks/hooks.json` for Codex-compatible
+  top-level fields before packaging or release.
+
 ## [0.1.0] — 2026-07-07
 
 First public release. The build of this release was itself executed as quests

package/README.md

@@ -12,17 +12,17 @@ actually read.
 - `quest` — the quest store: contracts, checkpoints, wave scheduling. Local
   markdown files by default; GitHub Issues opt-in.
 - `quest-run` — the headless runner: drives `claude -p` or `codex exec` workers
-  in native goal mode with deterministic budgets and notifications.
-- Five skills — `/quest:plan`, `/quest:work`, `/quest:orchestrate`,
-  `/quest:retro`, `/quest:protocol`.
-- Two agents — `quest-executor`, `quest-reviewer`.
+  with deterministic budgets, notifications, and checkpoint-based stop checks.
+- Six skills — `$quest:plan`, `$quest:work`, `$quest:orchestrate`,
+  `$quest:retro`, `$quest:protocol`, `$quest:setup`.
+- Two native-agent templates — `quest-executor`, `quest-reviewer`.
 
 ## The idea in 30 seconds
 
 ```
-you:    /quest:plan add dark mode to the settings page
+you:    $quest:plan add dark mode to the settings page
 agent:  creates quest 12 — Objective, Done-when, Validation loop… (quest create)
-you:    /quest:orchestrate
+you:    $quest:orchestrate
 agent:  dispatches a worker on quest 12; it iterates: milestone → validate →
         commit → checkpoint. You review evidence, not vibes.
 ```
@@ -39,7 +39,7 @@ npm install -g quest-loop
 ```
 
 Puts `quest` and `quest-run` on your PATH everywhere — no harness required.
-The plugin installs below add the skills, agents, and hooks on top.
+The plugin installs below add the skills, hooks, and native-agent setup on top.
 
 ### Claude Code
 
@@ -62,14 +62,46 @@ claude --plugin-dir .
 
 ### Codex
 
-The plugin ships a `.codex-plugin/` manifest and discovers its skills from the
-repo checkout (`skills/`, surfaced under `.agents/` for Codex). Until a public
-Codex marketplace listing is approved upstream, wire it up from a clone or
-submodule:
+The plugin ships a `.codex-plugin/` manifest plus the same Git marketplace
+metadata used by Claude Code. Install the marketplace once, then install the
+plugin from that marketplace:
 
 ```bash
-git clone https://github.com/robertsreberski/quest
-# add the checkout to your Codex plugin/skill discovery path (clone or submodule)
+codex plugin marketplace add robertsreberski/quest
+codex plugin add quest@quest
+```
+
+Start a new Codex thread after installing so the skills and hooks are loaded.
+Verify the install with:
+
+```bash
+codex plugin list --marketplace quest
+quest codex install-agents --scope project
+quest codex doctor
+codex debug prompt-input "noop"
+```
+
+`quest codex doctor` checks the installed plugin version, hook parser, neutral
+skill roots, and native Codex custom agents. `codex debug prompt-input "noop"`
+should not print any hook parse warnings.
+
+#### Updating the Codex plugin
+
+Codex installs plugins from a marketplace snapshot. Pulling this Git repo or
+publishing a new tag is not enough to update the already-installed plugin cache.
+Refresh the marketplace snapshot, then reinstall the plugin from it:
+
+```bash
+codex plugin marketplace upgrade quest
+codex plugin add quest@quest
+codex plugin list --marketplace quest
+quest codex doctor
+```
+
+Then start a new Codex thread. If the update contains hook changes, re-run:
+
+```bash
+codex debug prompt-input "noop"
 ```
 
 The CLI (`quest`, `quest-run`) is harness-agnostic — it works the same whether
@@ -100,9 +132,12 @@ quest list --ready
 Work the quest **in-session** with the skill:
 
 ```
-/quest:work 12
+$quest:work 12
 ```
 
+In Claude Code, use the same bundled skills through the `/quest:*` slash-command
+form.
+
 …or **headless** with the runner:
 
 ```bash
@@ -144,19 +179,21 @@ full base protocol lives in
 | `quest start` | Mark a quest in_progress (todo → in_progress) |
 | `quest checkpoint` | Record iteration evidence and drive the quest's status |
 | `quest cancel` | Cancel a quest (terminal; reason is recorded) |
+| `quest reopen` | Reopen a complete quest back into the loop (complete → in_progress; reason recorded) |
 | `quest edit` | Compatibly expand a quest (additions only; anchors are immutable) |
 | `quest lint` | Check records against the contract spec |
 | `quest amend` | Append a numbered protocol amendment (retro output) |
 | `quest protocol` | Print the loop protocol + this store's local amendments |
 | `quest runs` | Show headless runner activity (from `.quests/runs.ndjson`) |
+| `quest codex` | Validate Codex-native setup and install native agent templates |
 
 ## quest-run (headless runner)
 
 `quest-run <id>` drives a worker through the same loop without you in the chair:
 
 - **Workers** — `claude` (`claude -p`) or `codex` (`codex exec`), selected per
-  quest. Both run in **native goal mode** with a machine-verifiable completion
-  condition.
+  quest. Both use a machine-verifiable Quest checkpoint completion condition;
+  Codex goal tools are optional by default and can be required explicitly.
 - **Budgets** — deterministic iteration, cost, token, and per-session
   wall-clock (`--session-timeout`, default 1800s) caps; two sessions without a
   new checkpoint (a killed hung session counts as one) auto-writes a `blocked`
@@ -165,6 +202,12 @@ full base protocol lives in
   goes through the `quest` CLI, and the runs journal stays local.
 - **`--parallel N`** — with `--ready`, promotes and works newly-ready quests
   across dependency waves, up to N at a time.
+- **Epics are never auto-dispatched** — a quest with children stays out of
+  `--ready` until every child is terminal, and `quest-run --ready` refuses it
+  even then (it logs an "is an epic" skip line). Epics are closed by the
+  orchestrator inline per `$quest:orchestrate`, not by burning a worker run on
+  pure verification. A direct `quest-run <id>` on an epic still runs, if you
+  really mean to.
 - **`--notify '<cmd>'`** — runs a templated command on run start/stop so you get
   pinged; notify failures are isolated from the run.
 - **`--codex-sandbox <mode>`** — selects the `codex exec` sandbox
@@ -175,12 +218,19 @@ full base protocol lives in
   must commit has to opt into **`danger-full-access`** — which also grants full
   disk and network access. The runner never escalates the sandbox silently; the
   safe `workspace-write` stays the default. (Claude workers ignore this flag.)
+- **`--codex-goal-mode <mode>`** — selects how `quest-run` treats Codex goal
+  tools (`auto` | `require` | `off`; resolved as flag → config
+  `defaults.codex.goal_mode` → default `auto`). `auto` uses the documented
+  `codex exec --json --output-schema` stream as the contract and lets Codex use
+  goal tools if they are available. `require` blocks honestly if the exec
+  surface does not expose or invoke `create_goal`. `off` never asks for goal
+  tools.
 
 Inspect activity with `quest runs --active`.
 
 > **Note:** `quest-run` ships with this build's runner milestone (tracked as
 > quest 5). On a pre-0.1.0 checkout where `bin/quest-run` isn't present yet, use
-> `/quest:work` in-session instead.
+> `$quest:work` in-session instead.
 
 ## Store backends
 

package/agents/quest-executor.md

@@ -1,6 +1,6 @@
 ---
 name: quest-executor
-description: Works exactly one quest record iteratively per the quest protocol until complete or blocked, recording checkpoint evidence via the quest CLI. Dispatch with the quest id; pass the record's model/effort as the dispatch override. <example>Orchestrator sees quest 12 ready with worker claude → dispatches quest-executor with "Work quest 12 per /quest:work"; it iterates milestone-by-milestone and ends with a recorded checkpoint.</example> <example>A quest sits blocked after a human ruling → redispatch quest-executor with the ruling; it resumes from the checkpoint trail alone.</example>
+description: Works exactly one quest record iteratively per the quest protocol until complete or blocked, recording checkpoint evidence via the quest CLI. Dispatch with the quest id; pass the record's model/effort as the dispatch override. <example>Orchestrator sees quest 12 ready with worker claude → dispatches quest-executor with "Work quest 12 per $quest:work"; it iterates milestone-by-milestone and ends with a recorded checkpoint.</example> <example>A quest sits blocked after a human ruling → redispatch quest-executor with the ruling; it resumes from the checkpoint trail alone.</example>
 model: opus
 effort: xhigh
 tools: Bash, Read, Edit, Write, Glob, Grep, WebFetch, WebSearch, NotebookEdit
@@ -18,7 +18,7 @@ quest protocol            # the loop rules + this store's amendments
 git log --oneline -5
 ```
 
-Then follow the work skill (`/quest:work`) exactly: smallest unfinished
+Then follow the work skill (`$quest:work`) exactly: smallest unfinished
 milestone → the quest's STATED validation loop → commit green → `quest
 checkpoint`. The record is your entire spec; if you need context it doesn't
 give you, read the code it points at — and if it's genuinely insufficient,

package/hooks/hooks.json

@@ -1,30 +1,65 @@
 {
-  "description": "Quest goal-loop hooks: inject in-flight quest context at session start, and block quest-executor subagents that try to stop without recording a checkpoint.",
   "hooks": {
     "SessionStart": [
       {
         "matcher": "startup",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/session-start.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\session-start.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\session-start.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Loading quest state"
+          }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/session-start.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\session-start.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\session-start.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Loading quest state"
+          }
         ]
       },
       {
         "matcher": "clear",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/session-start.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\session-start.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\session-start.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Loading quest state"
+          }
         ]
       },
       {
         "matcher": "compact",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/session-start.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\session-start.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\session-start.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Loading quest state"
+          }
         ]
       }
     ],
     "SubagentStop": [
       {
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.mjs\"" }
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/subagent-stop.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\subagent-stop.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\subagent-stop.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Checking quest checkpoint"
+          }
         ]
       }
     ]

package/hooks/subagent-stop.mjs

@@ -3,12 +3,24 @@
 // recording a checkpoint — the protocol's "no stop without a checkpoint" rule,
 // enforced deterministically.
 //
-// A subagent counts as a quest-executor iff its transcript contains a
-// `quest show <id> --json` invocation (the mandatory orientation marker). We take
-// the FIRST id. No marker → not our concern, allow silently. We then compare the
-// quest's latest checkpoint against the subagent's start time (the transcript's
-// first timestamp): a checkpoint newer than start clears the stop; so does a
-// terminal store status (complete/blocked/cancelled) reached during the run.
+// A subagent counts as a quest-executor iff one of its transcript entries records
+// an actual *mutating* quest invocation — `quest start <id>` or `quest checkpoint
+// <id>` (under any binary prefix: `quest`, `./bin/quest`, `node bin/quest`) — as a
+// tool_use block whose shell command carries the marker. Read-only verbs
+// (`quest show <id> --json`, `list`, `protocol`, `runs`) are how reviewers and
+// orchestrators inspect a quest without owning it, so they must NEVER key
+// detection: an agent whose transcript holds only read verbs is allowed silently.
+// The executor id comes from that first mutating invocation (deterministic,
+// transcript order) — including `quest checkpoint <id>`, because an executor
+// resuming an already-in_progress quest skips `quest start` and its first mutating
+// verb is the checkpoint. We parse the JSONL per-entry and inspect only tool_use
+// command inputs; prose, quoted skill text, examples, and echoed file contents live
+// in text blocks and tool_result content (never in a tool_use command), so
+// `quest start 12` / `quest checkpoint 12` examples in the skills can no longer key
+// detection. No mutating invocation → not our concern, allow silently. We then
+// compare the quest's latest checkpoint against the subagent's start time (the
+// transcript's first timestamp): a checkpoint newer than start clears the stop; so
+// does a terminal store status (complete/blocked/cancelled) reached during the run.
 //
 // Conservative by construction: any missing/unreadable input or parse failure →
 // allow (exit 0), with a one-line stderr diagnostic. We never false-positive-block
@@ -22,7 +34,73 @@ import { readFileSync, writeSync } from "node:fs";
 import { findStoreDir } from "../lib/config.mjs";
 import { loadQuest } from "../lib/store-local.mjs";
 
-const MARKER = /quest\s+show\s+(\d+)\s+--json/;
+// Mutating quest verbs only. Group 1 is the verb, group 2 the id. The marker is
+// anchored to a COMMAND position — an optional `node ` launcher and/or path prefix
+// then `quest <verb> <id>` at the head of a command — so `quest checkpoint 1`
+// merely quoted inside another program's argument (e.g. `grep 'quest checkpoint 1'`,
+// `git commit -m "quest checkpoint 1"`) does not falsely key executor detection.
+// Read verbs (show/list/protocol/runs) are deliberately absent.
+const MARKER = /^(?:node\s+)?(?:[.\w/@-]*\/)?quest\s+(start|checkpoint)\s+(\d+)/;
+
+// Split a shell command into top-level segments on `&&`, `||`, `;`, `|`, and
+// newline, IGNORING any separator that sits inside single or double quotes. This
+// keeps quoted text (grep patterns, commit messages) from forging a command head.
+// (Heredoc bodies on their own line remain a rare residual; a false "checkpoint"
+// nudge is benign, and heredoc parsing is not worth the complexity in a hook.)
+function splitTopLevel(s) {
+  const segs = [];
+  let buf = "";
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (escaped) {
+      buf += c;
+      escaped = false;
+      continue;
+    }
+    if (quote !== "'" && c === "\\") {
+      buf += c;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (c === quote) quote = null;
+      buf += c;
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; buf += c; continue; }
+    if ((c === "&" && s[i + 1] === "&") || (c === "|" && s[i + 1] === "|")) { segs.push(buf); buf = ""; i++; continue; }
+    if (c === ";" || c === "|" || c === "\n") { segs.push(buf); buf = ""; continue; }
+    buf += c;
+  }
+  segs.push(buf);
+  return segs;
+}
+
+// Strip a leading shell wrapper (`bash -lc '…'`, `sh -c "…"`) and split the command
+// chain, then look for a quest invocation at the head of any segment. Returns the
+// marker id or null.
+function markerIdInCommand(cmd) {
+  if (typeof cmd !== "string") return null;
+  let s = cmd.trim();
+  const wrap = s.match(/^(?:sudo\s+)?(?:ba)?sh\s+-l?c\s+(['"])([\s\S]*)\1\s*$/);
+  if (wrap) s = wrap[2].trim();
+  for (const seg of splitTopLevel(s)) {
+    const m = MARKER.exec(seg.trim());
+    if (m) return Number(m[2]); // m[1] = verb, m[2] = id
+  }
+  return null;
+}
+
+// A Codex `command_execution` item's shell command, across the JSONL envelope
+// shapes we know: top-level `item`, legacy `msg` (the item sits directly at
+// `entry.msg`), and `msg.item`. Returns the command string or null.
+function commandExecutionCommand(node) {
+  if (!node || typeof node !== "object") return null;
+  if (node.type === "command_execution" && typeof node.command === "string") return node.command;
+  return null;
+}
 const TERMINAL = ["complete", "blocked", "cancelled"];
 
 async function readStdin() {
@@ -57,6 +135,59 @@ function firstTimestamp(text) {
   return null;
 }
 
+// A tool_use block's shell command, or null. Bash invocations carry the command
+// under `input.command`; only that field is a real command invocation. We never
+// scan other input fields (e.g. an Edit's new_string or a Read's file_path), which
+// could echo skill text and re-introduce the false positive.
+function commandOf(input) {
+  return input && typeof input === "object" && typeof input.command === "string" ? input.command : null;
+}
+
+// The mutating-verb marker id from one transcript entry, considering only tool_use
+// command invocations. Assistant messages carry an array of content blocks; string
+// content (plain prose) and tool_result blocks (echoed output/file contents) are
+// ignored. Matches `quest start <id>` or `quest checkpoint <id>` and returns the id.
+function markerIdInEntry(entry) {
+  if (!entry || typeof entry !== "object") return null;
+
+  // Codex JSONL: a `command_execution` item under `item`, the legacy `msg`, or
+  // `msg.item`. Handling all three keeps executor detection robust across shapes.
+  for (const cand of [entry.item, entry.msg, entry.msg?.item]) {
+    const cmd = commandExecutionCommand(cand);
+    if (cmd != null) {
+      const id = markerIdInCommand(cmd);
+      if (id != null) return id;
+    }
+  }
+
+  // Claude assistant messages: tool_use blocks carrying a shell command. String
+  // content (plain prose) and tool_result blocks are ignored.
+  const msg = entry.message;
+  const content = msg && typeof msg === "object" ? msg.content : null;
+  if (!Array.isArray(content)) return null; // string content is prose, never an invocation
+  for (const block of content) {
+    if (!block || typeof block !== "object" || block.type !== "tool_use") continue;
+    const id = markerIdInCommand(commandOf(block.input));
+    if (id != null) return id;
+  }
+  return null;
+}
+
+// The executor's quest id = the FIRST mutating invocation (`quest start <id>` or
+// `quest checkpoint <id>`) that appears as a real command invocation, scanning
+// entries in transcript order. Returns id or null. Per-entry parsing is what keeps
+// skill-text examples from keying detection; read verbs never match at all.
+function executorQuestId(text) {
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const id = markerIdInEntry(entry);
+    if (id != null) return id;
+  }
+  return null;
+}
+
 try {
   const raw = await readStdin();
   let payload = {};
@@ -69,9 +200,8 @@ try {
   try { transcript = readFileSync(transcriptPath, "utf8"); }
   catch (err) { diag(`cannot read transcript (${err.code || err.message}); allowing`); allow(); }
 
-  const m = MARKER.exec(transcript);
-  if (!m) allow(); // not a quest-executor subagent — leave it entirely alone, silently
-  const id = Number(m[1]);
+  const id = executorQuestId(transcript);
+  if (id == null) allow(); // no mutating quest invocation (read-only agent) — leave it alone, silently
 
   // Prefer an explicit start field if a future payload carries one; else the
   // transcript's first timestamp.

package/lib/cli.mjs

@@ -11,6 +11,7 @@ import * as local from "./store-local.mjs";
 import * as github from "./store-github.mjs";
 import { openStore } from "./store.mjs";
 import { COMMANDS, renderCommandHelp, renderGeneralHelp, renderInitNextSteps, renderNoStore, renderStatusOverview } from "./help.mjs";
+import { doctor as codexDoctor, installAgents as installCodexAgents, versionInfo } from "./codex-native.mjs";
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -77,6 +78,12 @@ async function dispatch(argv, ctx) {
   const [command, ...rest] = argv;
   const { out, errOut, cwd, env } = ctx;
 
+  if (command === "--version" || command === "-V" || command === "version") {
+    const versions = versionInfo();
+    out(versions.package);
+    return 0;
+  }
+
   if (!command) {
     const storeDir = findStoreDir(cwd, env);
     if (!storeDir) {
@@ -127,7 +134,7 @@ const HANDLERS = {
     const config = {
       backend,
       ...(p.values.repo ? { github: { repo: p.values.repo } } : {}),
-      defaults: { worker: "claude", claude: { model: "opus", effort: "xhigh" }, codex: { model: "gpt-5.5", reasoning_effort: "medium" }, max_iterations: 8, priority: "p2" },
+      defaults: { worker: "claude", claude: { model: "opus", effort: "xhigh" }, codex: { model: "gpt-5.5", reasoning_effort: "medium", goal_mode: "auto" }, max_iterations: 8, priority: "p2" },
       notify: { command: "" },
     };
     writeFileSync(join(storeDir, "config.json"), JSON.stringify(config, null, 2) + "\n");
@@ -309,6 +316,38 @@ const HANDLERS = {
     return 0;
   },
 
+  async reopen(args, { out, errOut, cwd, env }) {
+    const p = parse("reopen", args, { reason: { type: "string" } }, { positionals: 1 });
+    if (p.help) return void out(renderCommandHelp("reopen")) ?? 0;
+    const id = requireId(p, "reopen");
+    // --reason is validated in the store (a contract requirement, exit 5), not
+    // as a usage error — mirrors `cancel`. reopenQuest throws if it is missing.
+    const config = getStore(cwd, env);
+    const store = openStore(config, { env });
+    const q = store.reopenQuest(id, p.values.reason);
+    // Reopening a child of a *complete* parent epic is allowed, never blocked —
+    // but the epic's completion verdict may now be falsified, so warn the
+    // orchestrator on stderr (the epic-falsification cue). Best-effort: a
+    // missing/unloadable parent (or any lookup failure) must never fail an
+    // already-successful reopen. Runs for both backends via this one handler.
+    if (q.front.parent !== undefined) {
+      try {
+        const parent = store.loadQuest(q.front.parent);
+        if (parent.front.status === "complete") {
+          errOut(`quest: warning — quest ${id}'s parent epic ${q.front.parent} is complete; reopening this child may falsify the epic's completion verdict. Rule on it, and \`quest reopen ${q.front.parent} --reason "…"\` too if the integration gate no longer holds.`);
+        }
+      } catch {
+        /* best-effort: never fail the reopen on a parent-lookup problem */
+      }
+    }
+    if (p.values.json) out(JSON.stringify({ ok: true, id, status: q.front.status }));
+    else {
+      out(`Quest ${id} reopened — now in_progress (reason recorded in an audited checkpoint).`);
+      out(`Reopened quests are dispatched directly by id (\`quest-run ${id}\` or $quest:work ${id}); they do not re-enter \`quest list --ready\`.`);
+    }
+    return 0;
+  },
+
   async edit(args, { out, cwd, env }) {
     const p = parse("edit", args, {
       "add-done-when": { type: "string", multiple: true },
@@ -398,4 +437,62 @@ const HANDLERS = {
     else for (const r of runs) out(`${r.run_id}  quest ${r.quest}  ${r.worker}  ${r.ended ? `ended ${r.final_status}` : "ACTIVE"}  iters:${r.iterations}  $${r.cost_usd.toFixed(2)}`);
     return 0;
   },
+
+  async codex(args, { out, cwd, env }) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+      out(renderCommandHelp("codex"));
+      return 0;
+    }
+    if (subcommand === "doctor") {
+      const p = parse("codex", rest, {}, { positionals: 0 });
+      if (p.help) {
+        out(renderCommandHelp("codex"));
+        return 0;
+      }
+      const result = codexDoctor({ cwd, env });
+      if (p.values.json) out(JSON.stringify(result));
+      else {
+        for (const c of result.checks) out(`${c.ok ? "OK " : "ERR"} ${c.name}: ${c.detail}`);
+        out(result.ok ? "codex doctor: OK" : "codex doctor: problems found");
+      }
+      // 1 (generic diagnostic failure), not 5 — exit 5 is reserved for
+      // ContractError (a quest contract violation), which a doctor finding is not.
+      return result.ok ? 0 : 1;
+    }
+    if (subcommand === "install-agents") {
+      const p = parse("codex", rest, {
+        scope: { type: "string", default: "project" },
+        "dry-run": { type: "boolean" },
+        force: { type: "boolean" },
+      }, { positionals: 0 });
+      if (p.help) {
+        out(renderCommandHelp("codex"));
+        return 0;
+      }
+      if (!["project", "user"].includes(p.values.scope)) throw new UsageError(`--scope must be project or user (got "${p.values.scope}")`, { command: "codex" });
+      const isDry = Boolean(p.values["dry-run"]);
+      const result = installCodexAgents({
+        scope: p.values.scope,
+        dryRun: isDry,
+        force: Boolean(p.values.force),
+        cwd,
+        env,
+      });
+      // A real run refuses to overwrite; a --dry-run PREVIEWS the conflict
+      // (its whole purpose) rather than erroring before showing the plan.
+      if (!result.ok && !isDry) {
+        const conflicts = result.conflicts.map((c) => c.path).join(", ");
+        throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command: "codex" });
+      }
+      if (p.values.json) out(JSON.stringify(result));
+      else {
+        out(`${isDry ? "Would install" : "Installed"} Codex agents to ${result.target}`);
+        for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
+        if (!result.ok) out(`  conflicts present — pass --force to replace: ${result.conflicts.map((c) => c.path).join(", ")}`);
+      }
+      return 0;
+    }
+    throw new UsageError(`unknown codex subcommand "${subcommand}"`, { command: "codex" });
+  },
 };