pi-interactive-shell 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -2,7 +2,53 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
-## [Unreleased]
+## [0.10.0] - 2026-03-13
+
+### Added
+- **Test harness** - Added vitest with 20 tests covering session queries, key encoding, notification formatting, headless monitor lifecycle, session manager, config/docs parity, and module loading.
+- **`gpt-5-4-prompting` skill** - New bundled skill with GPT-5.4 prompting best practices for Codex workflows.
+
+### Changed
+- **Architecture refactor** - Extracted shared logic into focused modules for better maintainability:
+  - `session-query.ts` - Unified output/query logic (rate limiting, incremental, drain, offset modes)
+  - `notification-utils.ts` - Message formatting for dispatch/hands-free notifications
+  - `handoff-utils.ts` - Snapshot/preview capture on session exit/transfer
+  - `runtime-coordinator.ts` - Centralized overlay/monitor/widget state management
+  - `pty-log.ts` - Raw output trimming and line slicing
+  - `pty-protocol.ts` - DSR cursor position query handling
+  - `spawn-helper.ts` - macOS node-pty permission fix
+  - `background-widget.ts` - TUI widget for background sessions
+- README, `SKILL.md`, install output, and the packaged Codex workflow examples now tell the same story about dispatch being the recommended delegated mode, the current 8s quiet threshold / 15s grace-period defaults, and the bundled prompt-skill surface.
+- The Codex workflow docs now point at the packaged `gpt-5-4-prompting`, `codex-5-3-prompting`, and `codex-cli` skills instead of describing a runtime fetch of the old 5.2 prompting guide.
+- Example prompts and skill docs are aligned around `gpt-5.4` as the default Codex model, with `gpt-5.3-codex` remaining the explicit opt-in fallback.
+- Renamed `codex-5.3-prompting` → `codex-5-3-prompting` example skill (filesystem-friendly path).
+
+### Fixed
+- **Map iteration bug** - Fixed `disposeAllMonitors()` modifying Map during iteration, which could cause unpredictable behavior.
+- **Array iteration bug** - Fixed PTY listener notifications modifying arrays during iteration if a listener unsubscribed itself.
+- **Missing runtime dependency** - Added `@sinclair/typebox` to dependencies (was imported but not declared).
+- Documented the packaged prompt/skill onboarding path more clearly so users can either rely on the exported package metadata or copy the bundled examples into their own prompt and skill directories.
+
+## [0.9.0] - 2026-02-23
+
+### Added
+- `examples/skills/codex-5.3-prompting/` skill with GPT-5.3-Codex prompting guide -- self-contained best practices for verbosity control, scope discipline, forced upfront reading, plan mode, mid-task steering, context management, and reasoning effort recommendations.
+- **`interactive-shell:update` event** — All hands-free update callbacks now emit `pi.events.emit("interactive-shell:update", update)` with the full `HandsFreeUpdate` payload. Extensions can listen for quiet, exit, kill, and user-takeover events regardless of which code path started the session (blocking, non-blocking, or reattach).
+- **`triggerTurn` on terminal events** — Non-blocking hands-free sessions now send `pi.sendMessage` with `triggerTurn: true` when the session exits, is killed, or the user takes over. Periodic "running" updates emit only on the event bus (cheap for extensions) without waking the agent.
+
+### Fixed
+- **Quiet detection broken for TUI apps** — Ink-based CLIs (Claude Code, etc.) emit periodic ANSI-only PTY data (cursor blink, frame redraws) that reset the quiet timer on every event, preventing quiet detection from ever triggering. Now filters data through `stripVTControlCharacters` and only resets the quiet timer when there's visible content. Fixed in both the overlay (`overlay-component.ts`) and headless dispatch monitor (`headless-monitor.ts`). Also seeds the quiet timer at startup when `autoExitOnQuiet` is enabled, so sessions that never produce visible output still get killed after the grace period.
+- **Lifecycle guard decoupled from callback** — The overlay used `onHandsFreeUpdate` presence as a proxy for "blocking tool call" to decide whether to unregister sessions on completion. Wiring the callback in non-blocking paths (for event emission) would cause premature session cleanup. Introduced `streamingMode` flag to separate "has update callback" from "should unregister on completion," so non-blocking sessions stay queryable after the callback fires.
+- **`autoExitOnQuiet` broken in interval update mode** — The `onData` handler only reset the quiet timer in `on-quiet` mode, so `autoExitOnQuiet` never fired with `updateMode: "interval"`. Also, the interval timer's safety-net flush unconditionally stopped the quiet timer, preventing `autoExitOnQuiet` from firing if the interval flushed before the quiet threshold. Both fixed: data handler now resets the timer whenever `autoExitOnQuiet` is enabled regardless of update mode, and the interval flush restarts (rather than stops) the quiet timer when `autoExitOnQuiet` is active.
+- **RangeError on narrow terminals** — `render()` computed `width - 2` for border strings without a lower bound, causing `String.prototype.repeat()` to throw with negative counts when terminal width < 4. Clamped in both the main overlay and reattach overlay. Fixes #2.
+- **Hardcoded `~/.pi/agent` path** — Config loading, snapshot writing, and the install script all hardcoded `~/.pi/agent`, ignoring `PI_CODING_AGENT_DIR`. Now uses `getAgentDir()` from pi's API in all runtime paths and reads the env var in the install script. Fixes #1.
+
+### Changed
+- Default `handsFreeQuietThreshold` increased from 5000ms to 8000ms and `autoExitGracePeriod` reduced from 30000ms to 15000ms. Both remain adjustable per-call via `handsFree.quietThreshold` and `handsFree.gracePeriod`, and via config file.
+- Dispatch mode is now the recommended default for delegated Codex runs. Updated `README.md`, `SKILL.md`, `tool-schema.ts`, `examples/skills/codex-cli/SKILL.md`, and all three codex prompt templates to prefer `mode: "dispatch"` over hands-free for fire-and-forget delegations.
+- Rewrote `codex-5.3-prompting` skill from a descriptive model-behavior guide into a directive prompt-construction reference. Cut behavioral comparison, mid-task steering, and context management prose sections; reframed each prompt block with a one-line "include when X" directive so the agent knows what to inject and when.
+- Added "Backwards compatibility hedging" section to `codex-5.3-prompting` skill covering the "cutover" keyword trick -- GPT-5.3-Codex inserts compatibility shims and fallback code even when told not to; using "cutover" + "no backwards compatibility" + "do not preserve legacy code" produces cleaner breaks than vague "don't worry about backwards compatibility" phrasing.
+- Example prompts (`codex-implement-plan`, `codex-review-impl`, `codex-review-plan`) updated for GPT-5.3-Codex: load `codex-5.3-prompting` and `codex-cli` skills instead of fetching the 5.2 guide URL at runtime, added scope fencing instructions to counter 5.3's aggressive refactoring, added "don't ask clarifying questions" and "brief updates" constraints, strengthened `codex-review-plan` to force reading codebase files referenced in the plan and constrain edit scope.
 
 ## [0.8.2] - 2026-02-10
 

package/README.md

@@ -49,7 +49,7 @@ Three modes control how the agent engages with a session:
 
 **Hands-free** returns immediately so the agent can do other work, but the agent must poll periodically to discover output and completion. Good for processes the agent needs to monitor and react to mid-flight, like watching build output and sending follow-up commands.
 
-**Dispatch** also returns immediately, but the agent doesn't poll at all. When the session completes — whether by natural exit, quiet detection, timeout, or user intervention — the agent gets woken up with a notification containing the tail output. This is the right mode for delegating a task to a subagent and moving on. Add `background: true` to skip the overlay entirely and run headless.
+**Dispatch** also returns immediately, but the agent doesn't poll at all. When the session completes — whether by natural exit, quiet detection, timeout, or user intervention — the agent gets woken up with a notification containing the tail output. This is the right mode for delegating a task to a subagent and moving on. For fire-and-forget delegated runs and QA checks, prefer dispatch by default. Add `background: true` to skip the overlay entirely and run headless.
 
 ## Quick Start
 
@@ -115,7 +115,7 @@ Attach to review full output: interactive_shell({ attach: "calm-reef" })
 
 The notification includes a brief tail (last 5 lines) and a reattach instruction. The PTY is preserved for 5 minutes so the agent can attach to review full scrollback.
 
-Dispatch defaults `autoExitOnQuiet: true` — the session gets a 30s startup grace period, then is killed after output goes silent (5s by default), which signals completion for task-oriented subagents. Tune the grace period with `handsFree: { gracePeriod: 60000 }` or opt out entirely with `handsFree: { autoExitOnQuiet: false }`.
+Dispatch defaults `autoExitOnQuiet: true` — the session gets a 15s startup grace period, then is killed after output goes silent (8s by default), which signals completion for task-oriented subagents. Tune the grace period with `handsFree: { gracePeriod: 60000 }` or opt out entirely with `handsFree: { autoExitOnQuiet: false }`.
 
 The overlay still shows for the user, who can Ctrl+T to transfer output, Ctrl+B to background, take over by typing, or Ctrl+Q for more options.
 
@@ -151,7 +151,7 @@ interactive_shell({
 
 ### Auto-Exit on Quiet
 
-For fire-and-forget single-task delegations, enable auto-exit to kill the session after 5s of output silence:
+For fire-and-forget single-task delegations, enable auto-exit to kill the session after 8s of output silence:
 
 ```typescript
 interactive_shell({
@@ -161,7 +161,7 @@ interactive_shell({
 })
 ```
 
-A 30s startup grace period prevents the session from being killed before the subprocess has time to produce output. Customize it per-call with `gracePeriod`:
+A 15s startup grace period prevents the session from being killed before the subprocess has time to produce output. Customize it per-call with `gracePeriod`:
 
 ```typescript
 interactive_shell({
@@ -282,8 +282,8 @@ Configuration files (project overrides global):
   "completionNotifyMaxChars": 5000,
   "handsFreeUpdateMode": "on-quiet",
   "handsFreeUpdateInterval": 60000,
-  "handsFreeQuietThreshold": 5000,
-  "autoExitGracePeriod": 30000,
+  "handsFreeQuietThreshold": 8000,
+  "autoExitGracePeriod": 15000,
   "handsFreeUpdateMaxChars": 1500,
   "handsFreeMaxTotalChars": 100000,
   "handoffPreviewEnabled": true,
@@ -306,8 +306,8 @@ Configuration files (project overrides global):
 | `completionNotifyLines` | 50 | Lines in dispatch completion notification (10-500) |
 | `completionNotifyMaxChars` | 5000 | Max chars in completion notification (1KB-50KB) |
 | `handsFreeUpdateMode` | "on-quiet" | "on-quiet" or "interval" |
-| `handsFreeQuietThreshold` | 5000 | Silence duration before update (ms) |
-| `autoExitGracePeriod` | 30000 | Startup grace before `autoExitOnQuiet` kill (ms) |
+| `handsFreeQuietThreshold` | 8000 | Silence duration before update (ms) |
+| `autoExitGracePeriod` | 15000 | Startup grace before `autoExitOnQuiet` kill (ms) |
 | `handsFreeUpdateInterval` | 60000 | Max interval between updates (ms) |
 | `handsFreeUpdateMaxChars` | 1500 | Max chars per update |
 | `handsFreeMaxTotalChars` | 100000 | Total char budget for updates |
@@ -331,7 +331,7 @@ Full PTY. The subprocess thinks it's in a real terminal.
 
 ## Example Workflow: Plan, Implement, Review
 
-The `examples/prompts/` directory includes three prompt templates that chain together into a complete development workflow using Codex CLI. Each template instructs pi to gather context, generate a tailored meta prompt based on the [Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md), and launch Codex in an interactive overlay.
+The `examples/prompts/` directory includes three prompt templates that chain together into a complete development workflow using Codex CLI. Each template now loads the bundled `gpt-5-4-prompting` skill by default, falls back to `codex-5-3-prompting` when the user explicitly asks for Codex 5.3, and launches Codex in an interactive overlay.
 
 ### The Pipeline
 
@@ -347,14 +347,22 @@ Write a plan
 
 ### Installing the Templates
 
-Copy the prompt templates and Codex CLI skill to your pi config:
+Install the package first so pi can discover the bundled prompt and skill directories via the package metadata:
+
+```bash
+pi install npm:pi-interactive-shell
+```
+
+If you want your own slash commands and local skill copies, copy the examples into your agent config:
 
 ```bash
 # Prompt templates (slash commands)
 cp ~/.pi/agent/extensions/interactive-shell/examples/prompts/*.md ~/.pi/agent/prompts/
 
-# Codex CLI skill (teaches pi how to use codex flags, sandbox caveats, etc.)
+# Skills used by the templates
 cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-cli ~/.pi/agent/skills/
+cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/gpt-5-4-prompting ~/.pi/agent/skills/
+cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-5-3-prompting ~/.pi/agent/skills/
 ```
 
 ### Usage
@@ -388,9 +396,9 @@ Say you have a plan at `docs/auth-redesign-plan.md`:
 
 These templates demonstrate a "meta-prompt generation" pattern:
 
-1. **Pi gathers context** — reads the plan, runs git diff, fetches the Codex prompting guide
-2. **Pi generates a calibrated prompt** — tailored to the specific plan/diff, following the guide's best practices
-3. **Pi launches Codex in the overlay** — with explicit flags (`-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`) and hands off control
+1. **Pi gathers context** — reads the plan, runs git diff, and loads the local `gpt-5-4-prompting` or `codex-5-3-prompting` skill
+2. **Pi generates a calibrated prompt** — tailored to the specific plan/diff, following the selected skill's best practices
+3. **Pi launches Codex in the overlay** — defaulting to `-m gpt-5.4 -a never` and switching to `-m gpt-5.3-codex -a never` only when the user explicitly asks for Codex 5.3
 
 The user watches Codex work in the overlay and can take over anytime (type to intervene, Ctrl+T to transfer output back to pi, Ctrl+Q for options).
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Cheat sheet + workflow for launching interactive coding-agent CLIs
 
 # Interactive Shell (Skill)
 
-Last verified: 2026-01-18
+Last verified: 2026-03-12
 
 ## Foreground vs Background Subagents
 
@@ -84,6 +84,8 @@ interactive_shell({
 
 Dispatch defaults `autoExitOnQuiet: true`. The agent can still query the sessionId if needed, but doesn't have to.
 
+For fire-and-forget delegated runs (including QA-style delegated checks), prefer dispatch as the default mode.
+
 #### Background Dispatch (Headless)
 No overlay opens. Multiple headless dispatches can run concurrently:
 
@@ -163,7 +165,7 @@ interactive_shell({
   reason: "Security review",
   handsFree: { autoExitOnQuiet: true }
 })
-// Session auto-kills after ~5s of quiet
+// Session auto-kills after ~8s of quiet (after the startup grace period)
 // Read results from file:
 // read("/tmp/security-review.md")
 ```

package/background-widget.ts

@@ -0,0 +1,76 @@
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { formatDuration } from "./types.js";
+import type { ShellSessionManager } from "./session-manager.js";
+
+export function setupBackgroundWidget(
+	ctx: { ui: { setWidget: Function }; hasUI?: boolean },
+	sessionManager: ShellSessionManager,
+): (() => void) | null {
+	if (!ctx.hasUI) return null;
+
+	let durationTimer: ReturnType<typeof setInterval> | null = null;
+	let tuiRef: { requestRender: () => void } | null = null;
+
+	const requestRender = () => tuiRef?.requestRender();
+	const unsubscribe = sessionManager.onChange(() => {
+		manageDurationTimer();
+		requestRender();
+	});
+
+	function manageDurationTimer() {
+		const sessions = sessionManager.list();
+		const hasRunning = sessions.some((s) => !s.session.exited);
+		if (hasRunning && !durationTimer) {
+			durationTimer = setInterval(requestRender, 10_000);
+		} else if (!hasRunning && durationTimer) {
+			clearInterval(durationTimer);
+			durationTimer = null;
+		}
+	}
+
+	ctx.ui.setWidget(
+		"bg-sessions",
+		(tui: any, theme: any) => {
+			tuiRef = tui;
+			return {
+				render: (width: number) => {
+					const sessions = sessionManager.list();
+					if (sessions.length === 0) return [];
+					const cols = width || tui.terminal?.columns || 120;
+					const lines: string[] = [];
+					for (const s of sessions) {
+						const exited = s.session.exited;
+						const dot = exited ? theme.fg("dim", "○") : theme.fg("accent", "●");
+						const id = theme.fg("dim", s.id);
+						const cmd = s.command.replace(/\s+/g, " ").trim();
+						const truncCmd = cmd.length > 60 ? cmd.slice(0, 57) + "..." : cmd;
+						const reason = s.reason ? theme.fg("dim", ` · ${s.reason}`) : "";
+						const status = exited ? theme.fg("dim", "exited") : theme.fg("success", "running");
+						const duration = theme.fg("dim", formatDuration(Date.now() - s.startedAt.getTime()));
+						const oneLine = ` ${dot} ${id}  ${truncCmd}${reason}  ${status} ${duration}`;
+						if (visibleWidth(oneLine) <= cols) {
+							lines.push(oneLine);
+						} else {
+							lines.push(truncateToWidth(` ${dot} ${id}  ${cmd}`, cols, "…"));
+							lines.push(truncateToWidth(`   ${status} ${duration}${reason}`, cols, "…"));
+						}
+					}
+					return lines;
+				},
+				invalidate: () => {},
+			};
+		},
+		{ placement: "belowEditor" },
+	);
+
+	manageDurationTimer();
+
+	return () => {
+		unsubscribe();
+		if (durationTimer) {
+			clearInterval(durationTimer);
+			durationTimer = null;
+		}
+		ctx.ui.setWidget("bg-sessions", undefined);
+	};
+}

package/config.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 export interface InteractiveShellConfig {
 	exitAutoCloseDelay: number;
@@ -52,8 +52,8 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" as const,
 	handsFreeUpdateInterval: 60000,
-	handsFreeQuietThreshold: 5000,
-	autoExitGracePeriod: 30000,
+	handsFreeQuietThreshold: 8000,
+	autoExitGracePeriod: 15000,
 	handsFreeUpdateMaxChars: 1500,
 	handsFreeMaxTotalChars: 100000,
 	// Query rate limiting (default 60 seconds between queries)
@@ -62,7 +62,7 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 
 export function loadConfig(cwd: string): InteractiveShellConfig {
 	const projectPath = join(cwd, ".pi", "interactive-shell.json");
-	const globalPath = join(homedir(), ".pi", "agent", "interactive-shell.json");
+	const globalPath = join(getAgentDir(), "interactive-shell.json");
 
 	let globalConfig: Partial<InteractiveShellConfig> = {};
 	let projectConfig: Partial<InteractiveShellConfig> = {};

package/examples/prompts/codex-implement-plan.md

@@ -1,23 +1,34 @@
 ---
 description: Launch Codex CLI in overlay to fully implement an existing plan/spec document
 ---
-Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then read the plan at `$1`.
+Determine which prompting skill to load based on model:
+- Default: Load `gpt-5-4-prompting` skill (for `gpt-5.4`)
+- If user explicitly requests Codex 5.3: Load `codex-5-3-prompting` skill (for `gpt-5.3-codex`)
+
+Also load the `codex-cli` skill. Then read the plan at `$1`.
 
 Analyze the plan to understand: how many files are created vs modified, whether there's a prescribed implementation order or prerequisites, what existing code is referenced, and roughly how large the implementation is.
 
-Based on the prompting guide's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+Based on the prompting skill's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
 
 1. Read and internalize the full plan document. Identify every file to be created, every file to be modified, and any prerequisites or ordering constraints.
 2. Before writing any code, read all existing files that will be modified — in full, not just the sections mentioned in the plan. Also read key files they import from or that import them, to absorb the surrounding patterns, naming conventions, and architecture.
 3. If the plan specifies an implementation order or prerequisites (e.g., "extract module X before building Y"), follow that order exactly. Otherwise, implement bottom-up: shared utilities and types first, then the modules that depend on them, then integration/registration code last.
 4. Implement each piece completely. No stubs, no TODOs, no placeholder comments, no "implement this later" shortcuts. Every function body, every edge case handler, every error path described in the plan must be real code.
 5. Match existing code patterns exactly — same formatting, same import style, same error handling conventions, same naming. Read the surrounding codebase to absorb these patterns before writing. If the plan references patterns from specific files (e.g., "same pattern as X"), read those files and replicate the pattern faithfully.
-6. Keep files reasonably sized. If a file grows beyond ~500 lines, split it as the plan describes or refactor into logical sub-modules.
-7. After implementing all files, do a self-review pass: re-read the plan from top to bottom and verify every requirement, every edge case, every design decision is addressed in the code. Check for: missing imports, type mismatches, unreachable code paths, inconsistent field names between modules, and any plan requirement that was overlooked.
-8. Do NOT commit or push. Write a summary listing every file created or modified, what was implemented in each, and any plan ambiguities that required judgment calls.
+6. Stay within scope. Do not refactor, rename, or restructure adjacent code that the plan does not mention. No "while I'm here" improvements. If something adjacent looks wrong, note it in the summary but do not touch it.
+7. Keep files reasonably sized. If a file grows beyond ~500 lines, split it as the plan describes or refactor into logical sub-modules.
+8. After implementing all files, do a self-review pass: re-read the plan from top to bottom and verify every requirement, every edge case, every design decision is addressed in the code. Check for: missing imports, type mismatches, unreachable code paths, inconsistent field names between modules, and any plan requirement that was overlooked.
+9. Do NOT commit or push. Write a summary listing every file created or modified, what was implemented in each, and any plan ambiguities that required judgment calls.
+
+The meta prompt should follow the prompting skill's patterns: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Instruct Codex not to ask clarifying questions about things answerable by reading the plan or codebase — read first, then act. Keep progress updates brief and concrete (no narrating routine file reads or tool calls). Emphasize that the plan has already been thoroughly reviewed — the job is faithful execution, not second-guessing the design. Emphasize scope discipline and verification requirements per the prompting skill.
+
+Determine the model flag:
+- Default: `-m gpt-5.4`
+- If user explicitly requests Codex 5.3: `-m gpt-5.3-codex`
 
-The meta prompt should follow the Codex guide's structure: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Emphasize that the plan has already been thoroughly reviewed — the job is faithful execution, not second-guessing the design.
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using the chosen model flag plus `-a never`.
 
-Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
 
 $@

package/examples/prompts/codex-review-impl.md

@@ -1,24 +1,35 @@
 ---
 description: Launch Codex CLI in overlay to review implemented code changes (optionally against a plan)
 ---
-Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then determine the review scope:
+Determine which prompting skill to load based on model:
+- Default: Load `gpt-5-4-prompting` skill (for `gpt-5.4`)
+- If user explicitly requests Codex 5.3: Load `codex-5-3-prompting` skill (for `gpt-5.3-codex`)
+
+Also load the `codex-cli` skill. Then determine the review scope:
 
 - If `$1` looks like a file path (contains `/` or ends in `.md`): read it as the plan/spec these changes were based on. The diff scope is uncommitted changes vs HEAD, or if clean, the current branch vs main.
 - Otherwise: no plan file. Diff scope is the same. Treat all of `$@` as additional review context or focus areas.
 
 Run the appropriate git diff to identify which files changed and how many lines are involved. This context helps you generate a better-calibrated meta prompt.
 
-Based on the prompting guide's best practices, the diff scope, and the optional plan, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+Based on the prompting skill's best practices, the diff scope, and the optional plan, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
 
 1. Identify all changed files via git diff, then read every changed file in full — not just the diff hunks. For each changed file, also read the files it imports from and key files that depend on it, to understand integration points and downstream effects.
 2. If a plan/spec was provided, read it and verify the implementation is complete — every requirement addressed, no steps skipped, nothing invented beyond scope, no partial stubs left behind.
 3. Review each changed file for: bugs, logic errors, race conditions, resource leaks (timers, event listeners, file handles, unclosed connections), null/undefined hazards, off-by-one errors, error handling gaps, type mismatches, dead code, unused imports/variables/parameters, unnecessary complexity, and inconsistency with surrounding code patterns and naming conventions.
 4. Trace key code paths end-to-end across function and file boundaries — verify data flows, state transitions, error propagation, and cleanup ordering. Don't evaluate functions in isolation.
 5. Check for missing or inadequate tests, stale documentation, and missing changelog entries.
-6. Fix every issue found with direct code edits. After all fixes, write a clear summary listing what was found, what was fixed, and any remaining concerns that require human judgment.
+6. Fix every issue found with direct code edits. Keep fixes scoped to the actual issues identified — do not expand into refactoring or restructuring code that wasn't flagged in the review. If adjacent code looks problematic, note it in the summary but don't touch it.
+7. After all fixes, write a clear summary listing what was found, what was fixed, and any remaining concerns that require human judgment.
+
+The meta prompt should follow the prompting skill's patterns: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Instruct Codex not to ask clarifying questions — if intent is unclear, read the surrounding code for context instead of asking. Keep progress updates brief and concrete (no narrating routine file reads or tool calls). Emphasize thoroughness — read the actual code deeply before making judgments, question every assumption, and never rubber-stamp. Emphasize scope discipline and verification requirements per the prompting skill.
+
+Determine the model flag:
+- Default: `-m gpt-5.4`
+- If user explicitly requests Codex 5.3: `-m gpt-5.3-codex`
 
-The meta prompt should follow the Codex guide's structure: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Emphasize thoroughness — read the actual code deeply before making judgments, question every assumption, and never rubber-stamp.
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using the chosen model flag plus `-a never`.
 
-Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
 
 $@

package/examples/prompts/codex-review-plan.md

@@ -1,19 +1,29 @@
 ---
 description: Launch Codex CLI in overlay to review an implementation plan against the codebase
 ---
-Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then read the plan at `$1`.
+Determine which prompting skill to load based on model:
+- Default: Load `gpt-5-4-prompting` skill (for `gpt-5.4`)
+- If user explicitly requests Codex 5.3: Load `codex-5-3-prompting` skill (for `gpt-5.3-codex`)
 
-Based on the prompting guide's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+Also load the `codex-cli` skill. Then read the plan at `$1`.
 
-1. Read and internalize the full plan
-2. Systematically review the plan against the reference docs/links/code
-3. Verify every assumption, file path, API shape, data flow, and integration point mentioned in the plan
-4. Check that the plan's approach is logically sound, complete, and accounts for edge cases
-5. Identify any gaps, contradictions, incorrect assumptions, or missing steps
-6. Make direct edits to the plan file to fix any issues found, adding inline notes where changes were made
+Based on the prompting skill's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
 
-The meta prompt should be structured according to the Codex guide's recommendations (clear system context, explicit constraints, step-by-step instructions, expected output format).
+1. Read and internalize the full plan. Then read every codebase file the plan references — in full, not just the sections mentioned. Also read key files adjacent to those (imports, dependents) to understand the real state of the code the plan targets.
+2. Systematically review the plan against what the code actually looks like, not what the plan assumes it looks like.
+3. Verify every assumption, file path, API shape, data flow, and integration point mentioned in the plan against the actual codebase.
+4. Check that the plan's approach is logically sound, complete, and accounts for edge cases.
+5. Identify any gaps, contradictions, incorrect assumptions, or missing steps.
+6. Make targeted edits to the plan file to fix issues found, adding inline notes where changes were made. Fix what's wrong — do not restructure or rewrite sections that are correct.
 
-Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+The meta prompt should follow the prompting skill's patterns (clear system context, explicit constraints, step-by-step instructions, expected output format). Instruct Codex not to ask clarifying questions — read the codebase to resolve ambiguities instead of asking. Keep progress updates brief and concrete. Emphasize scope discipline and verification requirements per the prompting skill.
+
+Determine the model flag:
+- Default: `-m gpt-5.4`
+- If user explicitly requests Codex 5.3: `-m gpt-5.3-codex`
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using the chosen model flag plus `-a never`.
+
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
 
 $@

package/examples/skills/codex-5-3-prompting/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: codex-5-3-prompting
+description: How to write system prompts and instructions for GPT-5.3-Codex. Use when constructing or tuning prompts targeting Codex 5.3.
+---
+
+# GPT-5.3-Codex Prompting Guide
+
+GPT-5.3-Codex is fast, capable, and eager. It moves quickly and will skip reading, over-refactor, and drift scope if prompts aren't tight. Explicit constraints matter more than with GPT-5.2-Codex. Include the following blocks as needed when constructing system prompts.
+
+## Output shape
+
+Always include. Controls verbosity and response structure.
+
+```
+<output_verbosity_spec>
+- Default: 3-6 sentences or <=5 bullets for typical answers.
+- Simple yes/no questions: <=2 sentences.
+- Complex multi-step or multi-file tasks:
+  - 1 short overview paragraph
+  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
+- Avoid long narrative paragraphs; prefer compact bullets and short sections.
+- Do not rephrase the user's request unless it changes semantics.
+</output_verbosity_spec>
+```
+
+## Scope constraints
+
+Always include. GPT-5.3-Codex will add features, refactor adjacent code, and invent UI elements if you don't fence it in.
+
+```
+<design_and_scope_constraints>
+- Explore any existing design systems and understand them deeply.
+- Implement EXACTLY and ONLY what the user requests.
+- No extra features, no added components, no UX embellishments.
+- Style aligned to the design system at hand.
+- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
+- If any instruction is ambiguous, choose the simplest valid interpretation.
+</design_and_scope_constraints>
+```
+
+## Context loading
+
+Always include. GPT-5.3-Codex skips reading and starts writing if you don't force it.
+
+```
+<context_loading>
+- Read ALL files that will be modified -- in full, not just the sections mentioned in the task.
+- Also read key files they import from or that depend on them.
+- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
+- Do not ask clarifying questions about things that are answerable by reading the codebase.
+</context_loading>
+```
+
+## Plan-first mode
+
+Include for multi-file work, large refactors, or any task with ordering dependencies.
+
+```
+<plan_first>
+- Before writing any code, produce a brief implementation plan:
+  - Files to create vs. modify
+  - Implementation order and prerequisites
+  - Key design decisions and edge cases
+  - Acceptance criteria for "done"
+- Get the plan right first. Then implement step by step following the plan.
+- If the plan is provided externally, follow it faithfully -- the job is execution, not second-guessing the design.
+</plan_first>
+```
+
+## Long-context handling
+
+Include when inputs exceed ~10k tokens (multi-chapter docs, long threads, multiple PDFs).
+
+```
+<long_context_handling>
+- For inputs longer than ~10k tokens:
+  - First, produce a short internal outline of the key sections relevant to the task.
+  - Re-state the constraints explicitly before answering.
+  - Anchor claims to sections ("In the 'Data Retention' section...") rather than speaking generically.
+- If the answer depends on fine details (dates, thresholds, clauses), quote or paraphrase them.
+</long_context_handling>
+```
+
+## Uncertainty and ambiguity
+
+Include when the task involves underspecified requirements or hallucination-prone domains.
+
+```
+<uncertainty_and_ambiguity>
+- If the question is ambiguous or underspecified:
+  - Ask up to 1-3 precise clarifying questions, OR
+  - Present 2-3 plausible interpretations with clearly labeled assumptions.
+- Never fabricate exact figures, line numbers, or external references when uncertain.
+- When unsure, prefer "Based on the provided context..." over absolute claims.
+</uncertainty_and_ambiguity>
+```
+
+## User updates
+
+Include for agentic / long-running tasks.
+
+```
+<user_updates_spec>
+- Send brief updates (1-2 sentences) only when:
+  - You start a new major phase of work, or
+  - You discover something that changes the plan.
+- Avoid narrating routine tool calls ("reading file...", "running tests...").
+- Each update must include at least one concrete outcome ("Found X", "Confirmed Y", "Updated Z").
+- Do not expand the task beyond what was asked; if you notice new work, call it out as optional.
+</user_updates_spec>
+```
+
+## Tool usage
+
+Include when the prompt involves tool-calling agents.
+
+```
+<tool_usage_rules>
+- Prefer tools over internal knowledge whenever:
+  - You need fresh or user-specific data (tickets, orders, configs, logs).
+  - You reference specific IDs, URLs, or document titles.
+- Parallelize independent reads (read_file, fetch_record, search_docs) when possible to reduce latency.
+- After any write/update tool call, briefly restate:
+  - What changed
+  - Where (ID or path)
+  - Any follow-up validation performed
+</tool_usage_rules>
+```
+
+## Reasoning effort
+
+Set `model_reasoning_effort` via Codex CLI: `-c model_reasoning_effort="high"`
+
+| Task type | Effort |
+|---|---|
+| Simple code generation, formatting | `low` or `medium` |
+| Standard implementation from clear specs | `high` |
+| Complex refactors, plan review, architecture | `xhigh` |
+| Code review (thorough) | `high` or `xhigh` |
+
+## Backwards compatibility hedging
+
+GPT-5.3-Codex has a strong tendency to preserve old patterns, add compatibility shims, and provide fallback code "just in case" -- even when explicitly told not to worry about backwards compatibility. Vague instructions like "don't worry about backwards compatibility" get interpreted weakly; the model may still hedge.
+
+Use **"cutover"** to signal a clean, irreversible break. It's a precise industry term that conveys finality and intentional deprecation -- no dual-support phase, no gradual migration, no preserving old behavior.
+
+Instead of:
+> "Rewrite this and don't worry about backwards compatibility"
+
+Say:
+> "This is a cutover. No backwards compatibility. Rewrite using only Python 3.12+ features and current best practices. Do not preserve legacy code, polyfills, or deprecated patterns."
+
+## Quick reference
+
+- **Force reading first.** "Read all necessary files before you ask any dumb question."
+- **Use plan mode.** Draft the full task with acceptance criteria before implementing.
+- **Steer aggressively mid-task.** GPT-5.3-Codex handles redirects without losing context. Be direct: "Stop. Fix the actual cause." / "Simplest valid implementation only."
+- **Constrain scope hard.** GPT-5.3-Codex will refactor aggressively if you don't fence it in.
+- **Watch context burn.** Faster model = faster context consumption. Start fresh at ~40%.
+- **Use domain jargon.** "Cutover," "golden-path," "no fallbacks," "domain split" get cleaner, faster responses.
+- **Download libraries locally.** Tell it to read them for better context than relying on training data.