commandmate 0.24.0 → 0.25.0

package/README.md

@@ -12,12 +12,12 @@
 **[commandmate website →](https://kewton.github.io/CommandMate/)**
 
 <p align="center">
-  <img src="./docs/images/demo-desktop.gif" width="600" alt="CommandMate Desktop Demo" />
+  <img src="./docs/images/demo-desktop.gif" width="600" alt="A task contract is sent, the verification gates run, and the exit code returns RESULT passed" />
 </p>
 
-> **Orchestrate your agent CLIs, not your terminal tabs.**
+> **From vibe coding to Vibe Engineering.**
 
-CommandMate is a local control plane for agent CLIs.
+Vibe Engineering — the AI does the building; the system, not your expertise, guarantees the engineering.
 
 ```bash
 npx commandmate@latest
@@ -27,11 +27,11 @@ npx commandmate@latest
 
 ---
 
-CommandMate adds orchestration and visibility on top of your existing agent CLIs.
-It does not replace tmux, Git worktrees, or your terminal. It makes them easier to manage at scale.
+CommandMate adds the machinery — a contract before the work, verification gates after it, Skills that carry the method — on top of the agent CLIs you already use.
+It does not replace tmux, Git worktrees, your terminal, or your agent CLI. It puts a frame around them, so the work arrives verified instead of merely finished.
 
 <p align="center">
-  <img src="./docs/images/demo-mobile.gif" width="300" alt="CommandMate Mobile Demo" />
+  <img src="./docs/images/demo-mobile.gif" width="300" alt="A waiting agent reaches you, and the prompt is answered from a phone" />
 </p>
 
 Works on desktop and mobile — monitor and steer sessions from any browser, including your phone.
@@ -44,8 +44,13 @@ If this is the kind of AI development workflow you want, [give the repo a star](
 
 | Feature | What it does | Why it matters |
 |---------|-------------|----------------|
+| **Task Contract** | Declare the goal, the changeable scope and the gates before the work starts, then `send --contract` hands them to the agent | The agent works to a written definition of done instead of guessing at one |
+| **Verification Gates** | Gates declared in `.commandmate/verify.yaml` run through `verify` / `wait --verify` and return exit `0` / `20` / `21` | "Done" is what a verification run returned, not what the agent said |
+| **Evidence & Metrics** | The built-in work-evidence and scope gates, plus `verify history`, `task show` and `report metrics` | Commits, gate logs and numbers are left behind for the next decision |
+| **Skills Catalog** | Install and update official Skills per worktree, from the web UI or `commandmate skill` | The method is installed for the agent to read, not kept in someone's head |
+| **Never miss a waiting agent** | A waiting agent shows up as a badge, a toast, the tab title, the PWA app badge and a push notification | You find out the moment an agent needs you, even away from the desk |
 | **Git Worktree Sessions** | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |
-| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini, or local models per issue | Pick the right agent for each task |
+| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity or local models per worktree | Pick the right agent for each task |
 | **Auto Yes Mode** | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling |
 | **Web UI (Desktop & Mobile)** | Full session control from any browser | Monitor and steer from your desk or your phone |
 | **File Viewer & Markdown Editor** | Browse and edit worktree files in the browser | Review changes and update AI instructions without opening an IDE |
@@ -111,12 +116,16 @@ development machine or phone will already have.
 flowchart LR
     A["Browser / Phone"] -->|HTTP| B["CommandMate Server"]
     B --> C["Session Manager"]
+    G["Task Contract\n.commandmate/tasks/*.yaml"] --> C
     C -->|"spawn / attach"| D["tmux sessions\n(per worktree)"]
-    D --> E["Claude Code CLI"]
+    D --> E["Agent CLI"]
     C <-->|"read / write"| F[("Local DB\n& State")]
+    E --> H["Verification Gates\n.commandmate/verify.yaml"]
+    H -->|"exit 0 / 20 / 21"| B
 ```
 
 Each Git worktree gets its own tmux session, so multiple tasks run in parallel without interference.
+The contract goes in before the session starts; the gates run after it stops, and their exit code is the verdict.
 
 ---
 
@@ -405,55 +414,92 @@ npm start
 ---
 
 <details>
-<summary><strong>Comparison</strong></summary>
-
-| Feature | CommandMate | Remote Control (Official) | Happy Coder | claude-squad | Omnara |
-|---------|:-----------:|:------------------------:|:-----------:|:------------:|:------:|
-| Auto Yes Mode | Yes | No | No | Yes (TUI only) | No |
-| Git Worktree Management | Yes | No | No | Yes (TUI only) | No |
-| Parallel Sessions | Yes | **No (1 only)** | Yes | Yes | No |
-| Mobile Web UI | Yes | Yes (claude.ai) | Yes | **No** | Yes |
-| File Viewer | Yes | No | No | No | No |
-| Markdown Editor | Yes | No | No | No | No |
-| Screenshot Instructions | Yes | No | No | Not possible | No |
-| Scheduled Execution | Yes | No | No | No | No |
-| Survives Laptop Close | Yes (daemon) | **No (terminal must stay open)** | Yes | Yes | Yes |
-| Token Authentication | Yes | N/A (Anthropic account) | N/A (app) | No | N/A (cloud) |
-| Free / OSS | Yes | Requires Pro/Max | Free + Paid | Yes | $20/mo |
-| Runs 100% Locally | Yes | Via Anthropic API | Server-routed | Yes | Cloud fallback |
+<summary><strong>With / Without CommandMate</strong></summary>
+
+The comparison that matters is not against other products; it is against the way of working.
+
+| Dimension | Vibe coding | Vibe Engineering with CommandMate |
+|---|---|---|
+| What "done" means | The agent says it's done | A verification run says so — exit 0 / 20 / 21 |
+| Scope of change | Whatever the agent touched | Declared in the contract, enforced by the scope gate |
+| Method | In someone's head | Installed as Skills from the Catalog (`cmate-task-contract`, `cmate-verify`, …) |
+| Evidence | A chat transcript | Commits, gate logs, `verify history`, `report metrics` |
+| Parallel work | Terminal tabs | One worktree and one contract per task |
+| When it stops | You notice, eventually | Waiting is surfaced: badge, toast, tab title, push |
+| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, local models |
 
 </details>
 
 ---
 
-## Optional Workflow Layer
+## Vibe Engineering workflow
 
 <a id="issue-driven-development"></a>
 
-If your team wants more structure, CommandMate can also help you standardize
-issue refinement, design review, planning, implementation, and acceptance checks.
-These workflows build on top of the same CLI sessions and worktrees. They are optional, not required.
+We do not make the AI smarter. We make the software-engineering ability its user needed into a system.
+That system is three things you can hand to any agent: the method, as installed Skills; the contract,
+declared before the work; the gates, which decide afterwards whether the work is done.
+
+```
+Requirement → Contract → Agent runs (any CLI, per worktree) → Verified result
+```
+
+### 1. Install the method as Skills
 
-CommandMate is built for developers who spend less time editing files and more time defining issues, reviewing direction, and accepting outcomes from coding agents. The commands below turn that workflow into a repeatable process.
+Skills come from the official Catalog
+([Kewton/commandmate-skills](https://github.com/Kewton/commandmate-skills)) and install into the
+worktree you choose — from the web UI (`/skills`, or the Skills pane of a worktree) or from the CLI.
 
+```bash
+commandmate skill list
+commandmate skill install cmate-task-contract --worktree <worktree-id> --version <version> --yes
 ```
-Define Issue → Refine with AI → Review Direction → Generate Plan → Agent Executes
+
+| Skill | What it covers |
+|-------|----------------|
+| `cmate-issue-authoring` | Turns a feature description into a set of implementable issues |
+| `cmate-issue-refinement` | Refines a vague issue into an implementable specification, read-only |
+| `cmate-task-contract` | Drafts `.commandmate/tasks/<name>.yaml` from an issue: goal, scope, gates |
+| `cmate-verify` | Declares the gates in `.commandmate/verify.yaml` and runs them for a real exit code |
+| `cmate-verify-advisor` | Proposes gate improvements from the verification history |
+| `cmate-worker-development` | The six steps a worker follows: read, investigate, plan, implement, verify, evidence |
+| `cmate-acceptance-test` | Checks the issue's acceptance criteria and returns Go / Conditional Go / No-Go |
+| `cmate-orchestrate` | Plans several issues in parallel, dispatches them with contracts, judges by exit code |
+
+The Catalog also publishes `cmate-repository-analysis`, `cmate-orchestrate-monitor`,
+`cmate-worktree-setup` and `cmate-worktree-cleanup`. See the
+[Skills guide](./docs/user-guide/skills.md) for the support matrix, the install roots, and the
+rollback story.
+
+### 2. Declare the contract, then let the gates judge
+
+```bash
+# .commandmate/tasks/issue-123.yaml declares goal, scope.allow / scope.deny and the gates to run
+commandmate send <worktree-id> --contract .commandmate/tasks/issue-123.yaml
+commandmate wait <worktree-id> --verify
 ```
 
-| Step | Command | What happens |
-|------|---------|-------------|
-| Refine the issue | `/issue-enhance` | AI asks clarifying questions and fills in missing details |
-| Review the issue | `/multi-stage-issue-review` | Multi-stage review (consistency, impact scope) with automated fixes |
-| Review the design | `/multi-stage-design-review` | 4-stage review (general → consistency → impact → security) |
-| Plan the work | `/work-plan` | Generates a task breakdown with dependencies |
-| Implement via TDD | `/tdd-impl` | Red-Green-Refactor cycle, automated |
-| Verify acceptance | `/acceptance-test` | Validates all acceptance criteria from the issue |
-| Create the PR | `/create-pr` | Auto-generates title, description, and labels |
-| Dev (full) | `/pm-auto-dev` | TDD implementation → acceptance test → refactoring → progress report |
-| Issue → Dev (full) | `/pm-auto-issue2dev` | Issue review → design review → work plan → TDD → acceptance test → refactoring → progress report |
-| Design → Dev (full) | `/pm-auto-design2dev` | Design review → work plan → TDD → acceptance test → refactoring → progress report |
-
-For details, see the [issues](https://github.com/Kewton/CommandMate/issues), [dev reports](./dev-reports/issue/), and [workflow examples](./docs/en/user-guide/workflow-examples.md) in the CommandMate repository.
+`--contract` supplies the message, so you do not pass one yourself. `wait --verify` runs the gates
+once the agent stops and returns the verdict as its exit code: **0** everything passed, **20** a gate
+failed, **21** the work-evidence gate found neither a commit nor an uncommitted change.
+
+The contract format is specified in [Task Contract](./docs/design/task-contract.md), the gate format
+in [Verification gates](./docs/design/verification-config.md) — both specifications are written in
+Japanese, but the YAML they specify is the same on either side.
+
+### Read next
+
+| Document | What it gives you |
+|----------|-------------------|
+| [Concept](./docs/en/concept.md) | The Vision, the Mission, and how each implementation item maps to a feature |
+| [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and run one task through contract and verification in about fifteen minutes |
+| [Product Highlights](./docs/en/features/product-highlights.md) | A feature-by-feature tour of the product |
+| [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Every agent-facing command, in depth |
+
+> **Developing CommandMate itself?** The `/work-plan`, `/pm-auto-dev` and other slash commands under
+> `.claude/commands` belong to **this repository only** — they are not installed into yours, and the
+> portable equivalents are the Catalog Skills above. See the
+> [Commands guide](./docs/en/user-guide/commands-guide.md).
 
 ---
 
@@ -462,9 +508,14 @@ For details, see the [issues](https://github.com/Kewton/CommandMate/issues), [de
 | Document | Description |
 |----------|-------------|
 | [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation and initial setup |
+| [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and go from contract to verified result in about fifteen minutes |
 | [Web App Guide](./docs/en/user-guide/webapp-guide.md) | Basic web app operations |
 | [Quick Start](./docs/en/user-guide/quick-start.md) | Using Claude Code commands |
-| [Concept](./docs/en/concept.md) | Vision and problems solved |
+| [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Driving sessions from the CLI: execution contracts, verification gates, Skills, agent instances |
+| [Concept](./docs/en/concept.md) | The canonical Vision, Mission and core principle, and how each implementation item maps to a feature |
+| [Product Highlights](./docs/en/features/product-highlights.md) | A feature-by-feature tour of the product |
+| [Skills Guide](./docs/en/user-guide/skills.md) | Installing official Catalog Skills into a worktree |
+| [Agent Event Hooks](./docs/en/user-guide/agent-event-hooks.md) | Structured agent events instead of terminal scraping |
 | [Architecture](./docs/en/architecture.md) | System design |
 | [Deployment Guide](./docs/en/DEPLOYMENT.md) | Production environment setup |
 | [UI/UX Guide](./docs/en/UI_UX_GUIDE.md) | UI implementation details |

package/dist/server/src/config/activity-bar-config.js

@@ -9,7 +9,7 @@
  *   - `src/components/worktree/ActivityPane.tsx`
  *   - `src/components/worktree/WorktreeDetailRefactored.tsx`
  *
- * The Activity Bar is a 48px-wide vertical bar that hosts 7 activities.
+ * The Activity Bar is a 48px-wide vertical bar that hosts the activities below.
  * Re-clicking the active icon toggles the ActivityPane closed (null).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -33,6 +33,10 @@ exports.ACTIVITIES = [
     { id: 'todo', labelKey: 'activityBar.todo', icon: lucide_react_1.ListTodo },
     // Issue #1441: worktree-scoped Skill install/uninstall management.
     { id: 'skills', labelKey: 'activityBar.skills', icon: lucide_react_1.Sparkles },
+    // Issue #1816: the execution contract and the verification gates. Appended
+    // rather than inserted so the existing ArrowUp/ArrowDown order — which users
+    // and tests both index by position — is unchanged.
+    { id: 'verification', labelKey: 'activityBar.verification', icon: lucide_react_1.ShieldCheck },
 ];
 /**
  * Set of valid ActivityId values for runtime validation.

package/dist/server/src/lib/auto-yes-poller.js

@@ -296,7 +296,43 @@ async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, clea
         if (isDuplicatePrompt(pollerState, promptKey)) {
             return 'duplicate';
         }
-        // 3. Resolve auto answer under the execution contract's policy (Issue #1547).
+        // 3. Issue #1829: codex's own launch dialogs are CodexTool.waitForReady()'s
+        // to answer, not the poller's. Every one of them defaults to option 1, and
+        // the base rules answer the default:
+        //
+        //   "Hooks need review"  -> 1. Review hooks   (undoes Issue #1760; the pane
+        //                           then sits two screens deep in a review UI that
+        //                           only `t`/`esc` leave, reported as `running`)
+        //   "Update available"   -> 1. Update now     (undoes Issue #890; runs
+        //                           `npm install -g @openai/codex`, killing codex)
+        //   "Do you trust …"     -> 1. Yes, continue
+        //
+        // waitForReady answers the same screens deliberately and differently ('3',
+        // '2', '1' — each without a trailing Enter), but only during startSession,
+        // while this poller runs on its own 2s phase for the life of the session.
+        // Whichever sees the dialog first decides, so the fix is to leave them all
+        // to the tool. Auto-answer layer only: detectPrompt above still reports the
+        // prompt, so the human keeps seeing the screen and the response poller
+        // still notifies them about it.
+        const launchDialog = cliToolId === 'codex' ? (0, cli_patterns_1.getCodexLifecycleDialog)(cleanOutput) : null;
+        if (launchDialog) {
+            // Recorded through the #1684 channel so `capture --json` and `cmate wait`
+            // can name the reason instead of showing a worker that went quiet.
+            (0, auto_yes_suppression_state_1.recordPolicySuppression)(worktreeId, cliToolId, instanceId, {
+                reason: 'agent-launch-dialog',
+                mode: null,
+                promptType: promptDetection.promptData.type,
+            });
+            logger.warn('poller:auto-yes-skipped-launch-dialog', {
+                worktreeId,
+                cliToolId,
+                instanceId,
+                dialog: launchDialog,
+                promptType: promptDetection.promptData.type,
+            });
+            return 'no_answer';
+        }
+        // 4. Resolve auto answer under the execution contract's policy (Issue #1547).
         // Auto-Yes calls detectPrompt directly instead of going through
         // status-detector, so this is the only place the policy can gate an
         // auto-answer: a prompt the policy withholds is left for a human, and the
@@ -328,7 +364,7 @@ async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, clea
         if (answer === null) {
             return 'no_answer';
         }
-        // 4. Send answer to tmux (Issue #896: resolve the instance-specific session)
+        // 5. Send answer to tmux (Issue #896: resolve the instance-specific session)
         const manager = manager_1.CLIToolManager.getInstance();
         const cliTool = manager.getTool(cliToolId);
         const sessionName = cliTool.getSessionName(worktreeId, instanceId);
@@ -343,10 +379,10 @@ async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, clea
         finally {
             (0, tmux_capture_cache_1.invalidateCache)(sessionName);
         }
-        // 5. Update timestamp and reset error count
+        // 6. Update timestamp and reset error count
         updateLastServerResponseTimestamp(compositeKey, Date.now());
         resetErrorCount(compositeKey);
-        // 6. Record answered prompt key and timestamp
+        // 7. Record answered prompt key and timestamp
         pollerState.lastAnsweredPromptKey = promptKey;
         pollerState.lastAnsweredAt = Date.now();
         logger.info('poller:response-sent', { worktreeId, cliToolId, instanceId });

package/dist/server/src/lib/cli-tools/codex.js

@@ -31,33 +31,6 @@ const CODEX_POLL_INTERVAL_MS = 1000;
 const CODEX_INIT_MAX_ATTEMPTS = 30;
 /** Timeout for waiting for prompt before sending a message */
 const CODEX_PROMPT_WAIT_TIMEOUT_MS = 15000;
-/**
- * Anchors of codex's "Hooks need review" dialog (Issue #1760, measured on
- * codex-cli 0.147.0):
- *
- * ```
- *  Hooks need review
- *  5 hooks are new or changed.
- *  Hooks can run outside the sandbox after you trust them.
- *
- * > 1. Review hooks
- *   2. Trust all and continue
- *   3. Continue without trusting (hooks won't run)
- * ```
- *
- * It has to be handled here rather than in `getCodexActiveDialog`, which
- * classifies it as `null`: its wording matches none of that function's three
- * anchors (`Skip until next version` / `Do you trust` / `Press enter to
- * continue`). Measured consequence of leaving it alone, on a pane with the
- * generated `hooks.json` present: `isCodexPromptReady` stays false for the full
- * 30-attempt window and the session is then handed to `sendMessage` still
- * sitting on the dialog. Every launch, because "continue without trusting" is
- * not remembered — verified by relaunching and getting the same screen.
- *
- * Both strings are required so a "hooks" mention elsewhere cannot select an
- * option on a live prompt.
- */
-const CODEX_HOOKS_REVIEW_ANCHORS = ['Hooks need review', 'Continue without trusting'];
 /**
  * Option 3, "Continue without trusting (hooks won't run)".
  *
@@ -72,21 +45,57 @@ const CODEX_HOOKS_REVIEW_ANCHORS = ['Hooks need review', 'Continue without trust
  * Sent alone, like the other numbered dialogs (Issue #890): codex confirms a
  * numbered selection instantly, and a trailing Enter would land on the next
  * screen. Verified live — the prompt was ready on the following poll.
+ *
+ * Re-verified on codex-cli 0.148.0 for Issue #1829, against the objection that
+ * the dialog's own footer says `Press enter to confirm`. With the trust hashes
+ * invalidated and Auto-Yes off, a session launched onto this dialog reached
+ * `› Ask Codex to do anything` and then ran the message it was sent — on the
+ * `'3'` alone. The footer and the number key are not exclusive: the number
+ * selects AND confirms, Enter confirms the highlighted option. That is also why
+ * a trailing Enter is so costly here — the number having already advanced the
+ * screen, the Enter lands on the NEXT one, which is precisely how a pane ends up
+ * two screens deep in the hooks review UI.
  */
 const CODEX_HOOKS_REVIEW_DECLINE_KEY = '3';
+/**
+ * How many times `waitForReady` may press `esc` to climb out of codex's hooks
+ * review screens (Issue #1829).
+ *
+ * Two is the depth of the UI — detail -> list -> closed — and the cap exists
+ * because the alternative is one press per poll: 30 keystrokes into whatever is
+ * really on screen if the classifier is ever wrong about a frame. Two spare
+ * presses cover a redraw landing between capture and send.
+ */
+const CODEX_HOOKS_SCREEN_MAX_ESCAPES = 4;
 /**
  * Whether the pane is sitting on the hooks review dialog.
  *
  * Position-independent on purpose, unlike `getCodexActiveDialog`: the only
  * caller checks `isCodexPromptReady` first and returns when a genuine prompt
  * exists, so residual dialog text above a live prompt is never reached, and a
- * one-shot guard stops the key being sent twice.
+ * one-shot guard stops the key being sent twice. Callers OUTSIDE this launch
+ * sequence must use `getCodexLifecycleDialog` instead, which is position-based.
+ *
+ * The dialog has to be handled here rather than in `getCodexActiveDialog`, which
+ * classifies it as `null`: its wording matches none of that function's three
+ * anchors (`Skip until next version` / `Do you trust` / `Press enter to
+ * continue`). Measured consequence of leaving it alone, on a pane with the
+ * generated `hooks.json` present: `isCodexPromptReady` stays false for the full
+ * 30-attempt window and the session is then handed to `sendMessage` still
+ * sitting on the dialog. Every launch, because "continue without trusting" is
+ * not remembered — verified by relaunching and getting the same screen.
+ *
+ * The anchors themselves live in `detection/cli-patterns` (Issue #1829): the
+ * Auto-Yes poller has to recognise the same screen in order to keep its hands
+ * off it, and two copies of the anchors would be two chances to disagree about
+ * what this dialog is.
  *
  * @param output - ANSI-stripped pane capture
  * @returns True when both anchors of the dialog are present
+ * @see CODEX_HOOKS_REVIEW_ANCHORS
  */
 function isCodexHooksReviewDialog(output) {
-    return CODEX_HOOKS_REVIEW_ANCHORS.every((anchor) => output.includes(anchor));
+    return cli_patterns_1.CODEX_HOOKS_REVIEW_ANCHORS.every((anchor) => output.includes(anchor));
 }
 /**
  * Codex CLI tool implementation
@@ -185,6 +194,7 @@ class CodexTool extends base_1.BaseCLITool {
         let updateDialogHandled = false;
         let trustDialogHandled = false;
         let hooksReviewHandled = false;
+        let hooksScreenEscapes = 0;
         for (let i = 0; i < CODEX_INIT_MAX_ATTEMPTS; i++) {
             try {
                 const rawOutput = await (0, tmux_1.capturePane)(sessionName, 50);
@@ -208,6 +218,25 @@ class CodexTool extends base_1.BaseCLITool {
                     await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.CODEX_DIALOG_SETTLE_MS));
                     continue;
                 }
+                // Issue #1829: back out of the two screens the hooks dialog leads to.
+                // Confirming its option 1 -- which the Auto-Yes poller did on two live
+                // sessions, and which a human can do too -- opens a review UI whose only
+                // exits are `t` and `esc`. `t` is out: it writes `[hooks.state…]` into
+                // the operator's own ~/.codex/config.toml, the grant Issue #1760
+                // declined on their behalf. So `esc`, once per poll until the screens
+                // are gone. Before this, nothing sent either key: the whole 30-attempt
+                // window elapsed, waitForReady returned as if ready, and the session was
+                // left parked there -- reported as `running`, because neither screen
+                // carries an option, a confirm footer or a thinking indicator.
+                const hooksScreen = (0, cli_patterns_1.getCodexLifecycleDialog)(output);
+                if ((hooksScreen === 'hooks-list' || hooksScreen === 'hooks-detail') &&
+                    hooksScreenEscapes < CODEX_HOOKS_SCREEN_MAX_ESCAPES) {
+                    await (0, tmux_1.sendSpecialKey)(sessionName, 'Escape');
+                    hooksScreenEscapes++;
+                    logger.info('codex-hooks-screen-escaped');
+                    await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.CODEX_DIALOG_SETTLE_MS));
+                    continue;
+                }
                 // Issue #892: classify the bottom-most ACTIVE dialog by position. A dialog
                 // whose text is only residual scrollback above a genuine prompt returns
                 // null here, so no stray key is sent after it has been dismissed.

package/dist/server/src/lib/detection/cli-patterns.js

@@ -4,11 +4,12 @@
  * Shared between response-poller.ts and API routes
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAUDE_SESSION_ERROR_REGEX_PATTERNS = exports.CLAUDE_SESSION_ERROR_PATTERNS = exports.extractAnsiSequences = exports.stripAnsi = exports.ANTIGRAVITY_SKIP_PATTERNS = exports.ANTIGRAVITY_SELECTION_LIST_PATTERN = exports.ANTIGRAVITY_SEPARATOR_PATTERN = exports.ANTIGRAVITY_THINKING_PATTERN = exports.ANTIGRAVITY_PROMPT_PATTERN = exports.VIBE_LOCAL_THINKING_PATTERN = exports.VIBE_LOCAL_PROMPT_PATTERN = exports.COPILOT_SKIP_PATTERNS = exports.COPILOT_SELECTION_LIST_PATTERN = exports.COPILOT_SEPARATOR_PATTERN = exports.COPILOT_THINKING_PATTERN = exports.COPILOT_PROMPT_PATTERN = exports.OPENCODE_SKIP_PATTERNS = exports.OPENCODE_SEPARATOR_PATTERN = exports.CLAUDE_SELECTION_LIST_FOOTER = exports.CLAUDE_MODEL_OVERLAY_FOOTER_PATTERN = exports.OPENCODE_SELECTION_LIST_PATTERN = exports.OPENCODE_PROCESSING_INDICATOR = exports.OPENCODE_RESPONSE_COMPLETE = exports.OPENCODE_LOADING_PATTERN = exports.OPENCODE_THINKING_PATTERN = exports.OPENCODE_PROMPT_AFTER_RESPONSE = exports.OPENCODE_PROMPT_PATTERN = exports.GEMINI_THINKING_PATTERN = exports.GEMINI_PROMPT_PATTERN = exports.MAX_PASTED_TEXT_RETRIES = exports.PASTED_TEXT_DETECT_DELAY = exports.PASTED_TEXT_PATTERN = exports.CODEX_STATUS_BAR_PATTERN = exports.CODEX_PAGER_FOOTER_PATTERN = exports.CODEX_APPROVAL_FOOTER_PATTERN = exports.CODEX_SELECTION_LIST_PATTERN = exports.CODEX_SEPARATOR_PATTERN = exports.CODEX_DIALOG_PATTERN = exports.CODEX_PROMPT_PATTERN = exports.CLAUDE_TRUST_DIALOG_PATTERN = exports.CLAUDE_SEPARATOR_PATTERN = exports.CLAUDE_PROMPT_PATTERN = exports.CODEX_INTERRUPT_HINT_PATTERN = exports.CODEX_THINKING_PATTERN = exports.CLAUDE_INTERRUPT_HINT_PATTERN = exports.CLAUDE_THINKING_PATTERN = exports.CLAUDE_SPINNER_CHARS = void 0;
+exports.CLAUDE_SESSION_ERROR_REGEX_PATTERNS = exports.CLAUDE_SESSION_ERROR_PATTERNS = exports.extractAnsiSequences = exports.stripAnsi = exports.ANTIGRAVITY_SKIP_PATTERNS = exports.ANTIGRAVITY_SELECTION_LIST_PATTERN = exports.ANTIGRAVITY_SEPARATOR_PATTERN = exports.ANTIGRAVITY_THINKING_PATTERN = exports.ANTIGRAVITY_PROMPT_PATTERN = exports.VIBE_LOCAL_THINKING_PATTERN = exports.VIBE_LOCAL_PROMPT_PATTERN = exports.COPILOT_SKIP_PATTERNS = exports.COPILOT_SELECTION_LIST_PATTERN = exports.COPILOT_SEPARATOR_PATTERN = exports.COPILOT_THINKING_PATTERN = exports.COPILOT_PROMPT_PATTERN = exports.OPENCODE_SKIP_PATTERNS = exports.OPENCODE_SEPARATOR_PATTERN = exports.CLAUDE_SELECTION_LIST_FOOTER = exports.CLAUDE_MODEL_OVERLAY_FOOTER_PATTERN = exports.OPENCODE_SELECTION_LIST_PATTERN = exports.OPENCODE_PROCESSING_INDICATOR = exports.OPENCODE_RESPONSE_COMPLETE = exports.OPENCODE_LOADING_PATTERN = exports.OPENCODE_THINKING_PATTERN = exports.OPENCODE_PROMPT_AFTER_RESPONSE = exports.OPENCODE_PROMPT_PATTERN = exports.GEMINI_THINKING_PATTERN = exports.GEMINI_PROMPT_PATTERN = exports.MAX_PASTED_TEXT_RETRIES = exports.PASTED_TEXT_DETECT_DELAY = exports.PASTED_TEXT_PATTERN = exports.CODEX_STATUS_BAR_PATTERN = exports.CODEX_PAGER_FOOTER_PATTERN = exports.CODEX_APPROVAL_FOOTER_PATTERN = exports.CODEX_SELECTION_LIST_PATTERN = exports.CODEX_SEPARATOR_PATTERN = exports.CODEX_HOOKS_REVIEW_ANCHORS = exports.CODEX_DIALOG_PATTERN = exports.CODEX_PROMPT_PATTERN = exports.CLAUDE_TRUST_DIALOG_PATTERN = exports.CLAUDE_SEPARATOR_PATTERN = exports.CLAUDE_PROMPT_PATTERN = exports.CODEX_INTERRUPT_HINT_PATTERN = exports.CODEX_THINKING_PATTERN = exports.CLAUDE_INTERRUPT_HINT_PATTERN = exports.CLAUDE_THINKING_PATTERN = exports.CLAUDE_SPINNER_CHARS = void 0;
 exports.isCodexTurnActive = isCodexTurnActive;
 exports.findClaudeChromeStart = findClaudeChromeStart;
 exports.isCodexPromptReady = isCodexPromptReady;
 exports.getCodexActiveDialog = getCodexActiveDialog;
+exports.getCodexLifecycleDialog = getCodexLifecycleDialog;
 exports.detectThinking = detectThinking;
 exports.getCliToolPatterns = getCliToolPatterns;
 exports.stripBoxDrawing = stripBoxDrawing;
@@ -330,7 +331,18 @@ function isCodexPromptReady(output) {
  * update dialog wins over its own "Press enter to continue" footer, because Enter
  * on the update dialog could confirm the default "1. Update now" (npm install).
  */
-function getCodexActiveDialog(output) {
+/**
+ * The lines of Codex's ACTIVE region: everything strictly below the bottom-most
+ * genuine input-prompt line, or the whole frame when there is no prompt line
+ * (Issue #892).
+ *
+ * This is the one rule that keeps every Codex dialog classifier honest.
+ * capturePane returns scrollback, so a dialog that was answered minutes ago is
+ * still in the frame; only what sits BELOW the live prompt is still awaiting a
+ * key. Shared by getCodexActiveDialog and getCodexLifecycleDialog so the two
+ * cannot drift into disagreeing about what "active" means.
+ */
+function codexActiveRegionLines(output) {
     const lines = output.split('\n');
     // Index of the bottom-most genuine input-prompt line (-1 if none).
     let promptIdx = -1;
@@ -340,10 +352,12 @@ function getCodexActiveDialog(output) {
             break;
         }
     }
-    // Active region = lines strictly below the genuine prompt (the whole frame when
-    // there is no genuine prompt). Residual dialog text above a live prompt is
-    // excluded, so a dialog lingering in scrollback is never treated as active.
-    const active = lines.slice(promptIdx + 1).join('\n');
+    return lines.slice(promptIdx + 1);
+}
+function getCodexActiveDialog(output) {
+    // Residual dialog text above a live prompt is excluded, so a dialog lingering
+    // in scrollback is never treated as active.
+    const active = codexActiveRegionLines(output).join('\n');
     if (active === '') {
         return null;
     }
@@ -359,6 +373,134 @@ function getCodexActiveDialog(output) {
     }
     return null;
 }
+/**
+ * Anchors of codex's "Hooks need review" launch dialog — screen 1 of the three
+ * it can put in front of a session (Issue #1760, re-measured on codex-cli
+ * 0.148.0 for Issue #1829):
+ *
+ * ```
+ *  Hooks need review
+ *  4 hooks are new or changed.
+ *  Hooks can run outside the sandbox after you trust them.
+ *
+ * > 1. Review hooks
+ *   2. Trust all and continue
+ *   3. Continue without trusting (hooks won't run)
+ *   Press enter to confirm or esc to go back
+ * ```
+ *
+ * The hook COUNT is data — 0.147.0 said 5, 0.148.0 said 4 — so neither anchor
+ * reads it. Both strings are required so a "hooks" mention elsewhere cannot
+ * select an option on a live prompt.
+ */
+exports.CODEX_HOOKS_REVIEW_ANCHORS = ['Hooks need review', 'Continue without trusting'];
+/**
+ * Footer of screen 2, the hooks LIST, new in codex-cli 0.148.0 (Issue #1829):
+ * `Press t to trust all; enter to review hooks; esc to close`.
+ *
+ * The semicolon is what separates it from screen 3's footer — "trust all;" and
+ * "trust;" are disjoint — and matching the footer rather than the table above it
+ * keeps the two screens distinguishable by a single line each.
+ */
+const CODEX_HOOKS_LIST_FOOTER_PATTERN = /press\s+t\s+to\s+trust\s+all\s*;/i;
+/**
+ * Footer of screen 3, the per-hook review DETAIL (Issue #1829):
+ * `Press t to trust; esc to go back`. Where both live sessions in the Issue were
+ * found parked.
+ */
+const CODEX_HOOKS_DETAIL_FOOTER_PATTERN = /press\s+t\s+to\s+trust\s*;/i;
+/**
+ * How much of the active region {@link getCodexLifecycleDialog} judges, in
+ * non-blank lines counted from the bottom (Issue #1829).
+ *
+ * `getCodexActiveDialog` searches the whole active region, which is right for
+ * its caller: `waitForReady` only ever runs during `startSession`, when nothing
+ * else can be on screen. This classifier runs on every Auto-Yes poll for the
+ * life of the session, where "active region" alone is not enough — a codex
+ * approval request renders no `› ` composer line, so an approval that comes up
+ * while a dismissed hooks screen is still inside the capture window would have
+ * the whole frame as its active region and would be mistaken for the dialog.
+ * Requiring the dialog to be in the TAIL is what separates the screen the user
+ * is looking at from the one they have already left.
+ *
+ * 12 lines fits the tallest screen this has to recognise (the review dialog's
+ * two anchors sit 6 lines apart) and none of the shorter frames below it.
+ */
+const CODEX_LIFECYCLE_TAIL_LINES = 12;
+/**
+ * The interactive update dialog, by its option-3 label or its option-1 line.
+ *
+ * Deliberately stricter than `getCodexActiveDialog`'s `Update` AND `Skip`
+ * fallback: that pair can occur in ordinary agent output, and here a false
+ * positive silently stops Auto-Yes answering a real prompt. Both anchors below
+ * are dialog chrome that agent output does not produce.
+ */
+const CODEX_UPDATE_DIALOG_ANCHORS = [
+    /skip until next version/i,
+    /^\s*[›❯]?\s*\d+\.\s*Update now/im,
+];
+/** The directory-trust dialog's question line. */
+const CODEX_TRUST_DIALOG_ANCHOR = /Do you trust/;
+/**
+ * Classify the bottom-most ACTIVE codex lifecycle screen (Issue #1829).
+ *
+ * Position-based, via {@link codexActiveRegionLines}: a dialog left in
+ * scrollback above a live prompt is not active and returns `null`. That is not
+ * a detail — the auto-answer guard in the Auto-Yes poller is built on this
+ * function, and a whole-frame version of it would switch Auto-Yes off for the
+ * rest of a codex session the moment any launch dialog scrolled past.
+ *
+ * The two hooks screens are matched FIRST and bottom-up, because a stuck pane
+ * holds screen 2 above screen 3 and the way out of each differs. The remaining
+ * three are region-level substring tests, which is all their anchors allow:
+ * the review dialog's are on two different lines.
+ *
+ * Deliberately NOT used to decide whether a prompt exists. `detectPrompt` still
+ * reports these screens, so a human still sees them; what this function gates is
+ * only whether a machine may answer on their behalf.
+ *
+ * @param output - ANSI-stripped pane capture
+ * @returns The active lifecycle screen, or null when none is
+ */
+function getCodexLifecycleDialog(output) {
+    const activeLines = codexActiveRegionLines(output);
+    const window = [];
+    for (let i = activeLines.length - 1; i >= 0 && window.length < CODEX_LIFECYCLE_TAIL_LINES; i--) {
+        if (activeLines[i].trim() === '')
+            continue;
+        window.unshift(activeLines[i]);
+    }
+    if (window.length === 0)
+        return null;
+    const text = window.join('\n');
+    // One bottom-up pass, returning on the first line that decides the question --
+    // including the lines that decide it NEGATIVELY. A stuck pane holds screen 2
+    // above screen 3, and an approval request can come up with a hooks screen
+    // still inside the capture window; in both cases the screen the user is
+    // looking at is the lower one.
+    for (let i = window.length - 1; i >= 0; i--) {
+        const line = window[i];
+        if (CODEX_HOOKS_LIST_FOOTER_PATTERN.test(line))
+            return 'hooks-list';
+        if (CODEX_HOOKS_DETAIL_FOOTER_PATTERN.test(line))
+            return 'hooks-detail';
+        // The agent asking the human for permission mid-turn (Issue #1628's
+        // "esc to cancel" footer, which no lifecycle screen wears). This is exactly
+        // the prompt Auto-Yes exists to answer, so whatever lifecycle text is still
+        // above it has been left behind and must not withhold the answer.
+        if (exports.CODEX_APPROVAL_FOOTER_PATTERN.test(line))
+            return null;
+        if (CODEX_UPDATE_DIALOG_ANCHORS.some((pattern) => pattern.test(line)))
+            return 'update';
+        if (CODEX_TRUST_DIALOG_ANCHOR.test(line))
+            return 'trust';
+        // Both anchors required, so a stray "hooks" mention cannot claim the screen.
+        if (line.includes(exports.CODEX_HOOKS_REVIEW_ANCHORS[1]) && text.includes(exports.CODEX_HOOKS_REVIEW_ANCHORS[0])) {
+            return 'hooks-review';
+        }
+    }
+    return null;
+}
 /**
  * Codex separator pattern
  */