aiwcli 0.13.8 → 0.14.0

package/README.md

@@ -38,12 +38,22 @@ After installation, run `aiw init --method cc-native` to set up the template in
 AIW CLI provides the following commands:
 
 ### `aiw launch`
-Launch Claude Code with AIW configuration (sandbox disabled, supports parallel sessions).
+Launch Claude Code with AIW configuration (sandbox disabled, tmux-first by default when outside tmux).
 
 ```bash
 aiw launch
 aiw launch --debug  # Enable verbose logging
 aiw launch --quiet  # Suppress informational output
+aiw launch --no-tmux  # Bypass tmux auto-launch and run directly
+aiw launch --tmux-session aiw-main  # Reuse/attach a specific tmux session name
+```
+
+`aiw launch` now creates a fresh tmux session by default when auto-launching tmux.
+
+If you prefer typing `codex`, route it through AIW launch behavior with an alias:
+
+```bash
+alias codex='aiw launch --codex'
 ```
 
 ### `aiw init`

package/dist/commands/launch.d.ts

@@ -13,9 +13,17 @@ export default class LaunchCommand extends BaseCommand {
     static flags: {
         codex: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         new: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'no-tmux': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'tmux-session': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         help: import("@oclif/core/interfaces").BooleanFlag<void>;
         quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    private buildTmuxShellCommand;
+    private isTmuxAvailable;
+    private sanitizeTmuxSessionName;
+    private buildUniqueTmuxSessionName;
+    private enableTmuxMouseIfPossible;
+    private shellQuote;
 }

package/dist/commands/launch.js

@@ -1,3 +1,5 @@
+import { execSync } from 'node:child_process';
+import { basename } from 'node:path';
 import { Flags } from '@oclif/core';
 import BaseCommand from '../lib/base-command.js';
 import { ProcessSpawnError } from '../lib/errors.js';
@@ -14,22 +16,26 @@ import { EXIT_CODES } from '../types/index.js';
  * Supports multiple parallel sessions.
  */
 export default class LaunchCommand extends BaseCommand {
-    static description = 'Launch Claude Code or Codex with AIW configuration (sandbox disabled, supports parallel sessions)\n\n' +
+    static description = 'Launch Claude Code or Codex with AIW configuration (sandbox disabled, tmux-first by default)\n\n' +
         'FLAGS\n' +
         '  --codex/-c: Launch Codex instead of Claude Code (uses --yolo flag)\n' +
-        '  --new/-n: Open a new terminal in the current directory and launch there\n\n' +
+        '  --new/-n: Open a new terminal in the current directory and launch there\n' +
+        '  --no-tmux/-t: Launch directly in current shell instead of auto-launching tmux\n' +
+        '  --tmux-session/-s: tmux session name to reuse when auto-launching tmux (default is fresh session per launch)\n\n' +
         'EXIT CODES\n' +
         '  0  Success - AI assistant launched and exited successfully\n' +
         '  1  General error - unexpected runtime failure\n' +
         '  2  Invalid usage - check your arguments and flags\n' +
-        '  3  Environment error - CLI not found (install Claude Code from https://claude.ai/download or Codex from npm)';
+        '  3  Environment error - CLI/tmux not found (install Claude Code from https://claude.ai/download, Codex from npm, tmux from your package manager)';
     static examples = [
-        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %>  # Auto-launches tmux with a fresh session when not already in tmux',
         '<%= config.bin %> <%= command.id %> --codex  # Launch Codex with --yolo flag',
         '<%= config.bin %> <%= command.id %> -c  # Short form for --codex',
         '<%= config.bin %> <%= command.id %> --new  # Launch in a new terminal window',
         '<%= config.bin %> <%= command.id %> -n  # Short form for --new',
         '<%= config.bin %> <%= command.id %> --codex --new  # Launch Codex in new terminal',
+        '<%= config.bin %> <%= command.id %> --no-tmux  # Run directly in current shell',
+        '<%= config.bin %> <%= command.id %> --tmux-session aiw-main  # Reuse/attach explicit tmux session name',
         '<%= config.bin %> <%= command.id %> --debug  # Enable verbose logging',
         '# Check exit code in Bash\n<%= config.bin %> <%= command.id %>\necho $?',
         '# Check exit code in PowerShell\n<%= config.bin %> <%= command.id %>\necho $LASTEXITCODE',
@@ -46,6 +52,16 @@ export default class LaunchCommand extends BaseCommand {
             description: 'Open a new terminal in the current directory and run aiw launch there',
             default: false,
         }),
+        'no-tmux': Flags.boolean({
+            char: 't',
+            description: 'Launch directly in current shell instead of auto-launching tmux',
+            default: false,
+        }),
+        'tmux-session': Flags.string({
+            char: 's',
+            description: 'tmux session name to reuse when auto-launching tmux (default: new aiw-<current-dir>-<unique> session)',
+            required: false,
+        }),
     };
     async run() {
         const { flags } = await this.parse(LaunchCommand);
@@ -54,6 +70,10 @@ export default class LaunchCommand extends BaseCommand {
         const cliCommand = useCodex ? 'codex' : 'claude';
         const cliArgs = useCodex ? ['--yolo'] : ['--dangerously-skip-permissions'];
         const launchFlag = useCodex ? '--codex' : '';
+        const disableTmux = flags['no-tmux'];
+        const insideTmux = Boolean(process.env.TMUX);
+        const interactiveTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        const shouldAutoTmux = !flags.new && !disableTmux && !insideTmux && interactiveTty;
         // Handle --new flag: launch in a new terminal
         if (flags.new) {
             const cwd = process.cwd();
@@ -92,7 +112,36 @@ export default class LaunchCommand extends BaseCommand {
             // Spawn AI CLI with sandbox permissions disabled
             // AIW hook system provides safety guardrails
             // Continue launch regardless of version check result (graceful degradation)
-            exitCode = await spawnProcess(cliCommand, cliArgs);
+            if (shouldAutoTmux) {
+                if (!this.isTmuxAvailable()) {
+                    this.error('tmux is required for default launch mode but was not found on PATH.\n' +
+                        'Install tmux, or rerun with --no-tmux to launch directly.', { exit: EXIT_CODES.ENVIRONMENT_ERROR });
+                }
+                const shellCommand = this.buildTmuxShellCommand(cliCommand, cliArgs);
+                const sessionFromFlag = flags['tmux-session']?.trim();
+                if (sessionFromFlag && sessionFromFlag.length > 0) {
+                    const sessionName = this.sanitizeTmuxSessionName(sessionFromFlag);
+                    this.logInfo(`Launching in tmux session: ${sessionName} (reuse/attach)`);
+                    exitCode = await spawnProcess('tmux', ['new-session', '-A', '-s', sessionName, shellCommand]);
+                }
+                else {
+                    const sessionBase = `aiw-${basename(process.cwd())}`;
+                    const sessionName = this.buildUniqueTmuxSessionName(sessionBase);
+                    this.logInfo(`Launching in new tmux session: ${sessionName}`);
+                    exitCode = await spawnProcess('tmux', ['new-session', '-s', sessionName, shellCommand]);
+                }
+            }
+            else {
+                if (disableTmux)
+                    this.debug('tmux launch disabled via --no-tmux');
+                else if (insideTmux) {
+                    this.debug('Already inside tmux; launching directly in current pane');
+                    this.enableTmuxMouseIfPossible();
+                }
+                else if (!interactiveTty)
+                    this.debug('Non-interactive terminal detected; launching directly');
+                exitCode = await spawnProcess(cliCommand, cliArgs);
+            }
         }
         catch (error) {
             if (error instanceof ProcessSpawnError) {
@@ -105,4 +154,46 @@ export default class LaunchCommand extends BaseCommand {
         // Pass through Claude Code's exit code (outside try-catch to avoid catching exit)
         this.exit(exitCode);
     }
+    buildTmuxShellCommand(command, args) {
+        const launchCommand = [command, ...args].map((part) => this.shellQuote(part)).join(' ');
+        return `tmux set-option -g mouse on >/dev/null 2>&1 || true; exec ${launchCommand}`;
+    }
+    isTmuxAvailable() {
+        try {
+            const cmd = process.platform === 'win32' ? 'where tmux' : 'which tmux';
+            execSync(cmd, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    sanitizeTmuxSessionName(input) {
+        const trimmed = input.trim().toLowerCase();
+        const safe = trimmed
+            .replaceAll(/[^a-z0-9_-]/g, '-')
+            .replaceAll(/-+/g, '-')
+            .replaceAll(/^[-_]+|[-_]+$/g, '');
+        return safe || 'aiw';
+    }
+    buildUniqueTmuxSessionName(base) {
+        const safeBase = this.sanitizeTmuxSessionName(base);
+        const timestamp = Date.now().toString(36);
+        const pid = process.pid.toString(36);
+        return this.sanitizeTmuxSessionName(`${safeBase}-${timestamp}-${pid}`);
+    }
+    enableTmuxMouseIfPossible() {
+        if (!this.isTmuxAvailable())
+            return;
+        try {
+            execSync('tmux set-option -g mouse on', { stdio: 'ignore' });
+            this.debug('Enabled tmux mouse support (set-option -g mouse on)');
+        }
+        catch {
+            this.debug('Could not enable tmux mouse support automatically');
+        }
+    }
+    shellQuote(input) {
+        return `'${input.replaceAll("'", `'"'"'`)}'`;
+    }
 }

package/dist/templates/_shared/.claude/skills/codex/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: codex
+description: Launch Codex CLI in a tmux pane. USE WHEN codex OR send to codex OR codex implement OR hand off to codex OR launch codex OR codex plan OR run codex.
+user-invocable: true
+---
+
+# Codex CLI
+
+Launch Codex in a tmux split pane and optionally inject a prompt.
+
+## Command
+
+`bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [flags] <mode>`
+
+**Modes:** `plan` (inject active plan) | `--file <path>` (inject file) | `<text...>` (inject inline text)
+
+**Flags:**
+- `--model <name>` — Model aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or any full model ID.
+- `--sandbox <mode>` — `read-only`, `workspace-write`, `danger-full-access`. Default: Codex default.
+- `--context <id>` — Pass the active context ID so Codex receives project orientation (context folder, notes path). **Always pass this when an active context exists** (check the `Active Context:` system reminder for the ID).
+
+## Model Reference
+
+| Name | Resolves To |
+|------|-------------|
+| `spark` | `gpt-5.3-codex-spark` (fastest) |
+| `codex` | `gpt-5.3-codex` (default) |
+| `gpt` | `gpt-5.2` (non-Codex GPT) |
+| `fast` | `gpt-5.3-codex-spark` (tier) |
+| `standard` | `gpt-5.3-codex` (tier) |
+| `smart` | `gpt-5.3-codex` (tier) |
+
+## Examples
+
+- `/codex --model spark --context <context-id> plan` — hand off active plan to Spark with context
+- `/codex --model codex --context <context-id> Refactor auth to use JWT` — inline prompt with context
+- `/codex --file ./spec.md` — inject file contents (no context)
+
+## Requirements
+
+- Must be running inside tmux
+- `codex` CLI must be on PATH

package/dist/templates/_shared/.claude/skills/codex/prompt.md

@@ -0,0 +1,10 @@
+# /codex
+
+| Command | Description |
+|---|---|
+| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|disabled] plan` | Launch Codex REPL with active plan. |
+| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|disabled] --file <path>` | Launch Codex REPL with file contents. |
+| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|disabled] <inline text...>` | Launch Codex REPL with inline prompt. |
+
+- `--model`: model tier (`fast`/`standard`/`smart`) resolves to `gpt-5.3-codex-spark` / `gpt-5.3-codex-think`, or any explicit Codex model id.
+- `--sandbox`: `read-only` or `disabled` (default). `read-only` restricts file writes; `disabled` allows writes.

package/dist/templates/_shared/lib-ts/agent-exec/backends/headless.ts

@@ -0,0 +1,33 @@
+/**
+ * Headless execution backend — wraps execFileAsync() for subprocess execution.
+ * Default backend for all CLI agents. If outputFilePath is specified and exists
+ * after execution, reads output from file instead of stdout (Codex pattern).
+ */
+
+import * as fs from "node:fs";
+
+import { execFileAsync } from "../../base/subprocess-utils.js";
+import type { ExecutionBackend, ExecutionRequest, ExecutionResult } from "../execution-backend.js";
+
+export class HeadlessBackend implements ExecutionBackend {
+  async execute(request: ExecutionRequest): Promise<ExecutionResult> {
+    const result = await execFileAsync(request.cliPath, request.args, {
+      input: request.input,
+      timeout: request.timeoutMs,
+      env: request.env,
+      maxBuffer: request.maxBuffer ?? 10 * 1024 * 1024,
+      shell: request.shell ?? (process.platform === "win32"),
+    });
+
+    // If outputFilePath specified and exists, read from file instead of stdout
+    if (request.outputFilePath && fs.existsSync(request.outputFilePath)) {
+      const fileContent = fs.readFileSync(request.outputFilePath, "utf-8");
+      return {
+        ...result,
+        stdout: fileContent,
+      };
+    }
+
+    return result;
+  }
+}

package/dist/templates/_shared/lib-ts/agent-exec/backends/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Barrel re-export for execution backends.
+ */
+
+export { HeadlessBackend } from "./headless.js";
+export { TmuxBackend, type TmuxBackendOptions } from "./tmux.js";

package/dist/templates/_shared/lib-ts/agent-exec/backends/tmux.ts

@@ -0,0 +1,145 @@
+/**
+ * Tmux execution backend — runs CLI agents in visible tmux panes
+ * with sentinel-file-based output capture.
+ *
+ * Delegates pane management to tmux-driver.ts primitives. Does NOT use
+ * launchDriverInTmuxOrFallback() because fallback is the caller's concern,
+ * not the backend's.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { execFileAsync } from "../../base/subprocess-utils.js";
+import { getTmuxAvailability, quoteForSh, normalizeSplitFlag } from "../../base/tmux-driver.js";
+import type { ExecutionBackend, ExecutionRequest, ExecutionResult } from "../execution-backend.js";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface TmuxBackendOptions {
+  splitFlag?: string;
+  splitTarget?: string;
+}
+
+export class TmuxBackend implements ExecutionBackend {
+  private options: TmuxBackendOptions;
+
+  constructor(options?: TmuxBackendOptions) {
+    this.options = options ?? {};
+  }
+
+  async execute(request: ExecutionRequest): Promise<ExecutionResult> {
+    const tmux = getTmuxAvailability();
+    if (!tmux.available || !tmux.tmuxPath) {
+      return {
+        stdout: "",
+        stderr: `tmux pane launch failed: ${tmux.reason ?? "tmux unavailable"}`,
+        exitCode: 1,
+        killed: false,
+        signal: null,
+      };
+    }
+
+    // Create temp directory for IPC files
+    const agentName = path.basename(request.cliPath).replace(/\.[^.]+$/, "");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `aiwcli-agent-${agentName}-`));
+
+    const promptPath = path.join(tmpDir, "prompt.txt");
+    const stdoutPath = path.join(tmpDir, "stdout.txt");
+    const stderrPath = path.join(tmpDir, "stderr.txt");
+    const sentinelPath = path.join(tmpDir, "sentinel.txt");
+
+    try {
+      // Write prompt to file for stdin redirection
+      fs.writeFileSync(promptPath, request.input, "utf-8");
+
+      // Build env prefix
+      const envEntries = Object.entries(request.env).filter(
+        ([, v]) => v !== undefined,
+      ) as Array<[string, string]>;
+      const envPrefix = envEntries
+        .map(([k, v]) => `${k}=${quoteForSh(v)}`)
+        .join(" ");
+
+      // Build command
+      const quotedArgs = request.args.map((a) => quoteForSh(a)).join(" ");
+      const script = [
+        `${envPrefix} ${quoteForSh(request.cliPath)} ${quotedArgs}`,
+        `< ${quoteForSh(promptPath)}`,
+        `> ${quoteForSh(stdoutPath)}`,
+        `2> ${quoteForSh(stderrPath)}`,
+        `; echo $? > ${quoteForSh(sentinelPath)}`,
+      ].join(" ");
+
+      // Launch tmux pane
+      const splitFlag = normalizeSplitFlag(this.options.splitFlag);
+      const tmuxArgs = ["split-window", splitFlag, "-P", "-F", "#{pane_id}"];
+      if (this.options.splitTarget) {
+        tmuxArgs.push("-t", this.options.splitTarget);
+      }
+      tmuxArgs.push(`bash -lc ${quoteForSh(script)}`);
+
+      const split = await execFileAsync(tmux.tmuxPath, tmuxArgs, { timeout: 5000 });
+      if (split.exitCode !== 0) {
+        return {
+          stdout: "",
+          stderr: `tmux pane launch failed: ${split.stderr.trim()}`,
+          exitCode: 1,
+          killed: false,
+          signal: null,
+        };
+      }
+
+      const paneId = split.stdout.trim().split(/\r?\n/).pop() ?? "";
+
+      // Poll for sentinel file
+      const deadline = Date.now() + request.timeoutMs;
+      while (Date.now() < deadline) {
+        if (fs.existsSync(sentinelPath)) break;
+        await sleep(250);
+      }
+
+      if (!fs.existsSync(sentinelPath)) {
+        // Timeout: kill pane
+        if (paneId) {
+          await execFileAsync(tmux.tmuxPath, ["kill-pane", "-t", paneId], { timeout: 3000 });
+        }
+        return {
+          stdout: "",
+          stderr: "",
+          exitCode: -1,
+          killed: true,
+          signal: "SIGTERM",
+        };
+      }
+
+      // Read results
+      const exitCode = parseInt(fs.readFileSync(sentinelPath, "utf-8").trim(), 10) || 1;
+      const stdout = fs.existsSync(stdoutPath) ? fs.readFileSync(stdoutPath, "utf-8") : "";
+      const stderr = fs.existsSync(stderrPath) ? fs.readFileSync(stderrPath, "utf-8") : "";
+
+      // If outputFilePath specified and exists, read from it instead
+      if (request.outputFilePath && fs.existsSync(request.outputFilePath)) {
+        return {
+          stdout: fs.readFileSync(request.outputFilePath, "utf-8"),
+          stderr,
+          exitCode,
+          killed: false,
+          signal: null,
+        };
+      }
+
+      return { stdout, stderr, exitCode, killed: false, signal: null };
+    } finally {
+      // Clean up temp dir
+      try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+  }
+}

package/dist/templates/_shared/lib-ts/agent-exec/base-agent.ts

@@ -0,0 +1,229 @@
+/**
+ * Abstract base class for CLI-based agent subprocess invocations.
+ * Lives in _shared so all templates can use it. Provider-specific
+ * implementations (Claude, Codex, Gemini) extend this class.
+ *
+ * Execution strategy is injected via ExecutionBackend (default: HeadlessBackend).
+ * Debug logging is injectable via AgentDebugLogger (default: no-op).
+ */
+
+import { logDebug, logInfo, logWarn, logError } from "../base/logger.js";
+import { getInternalSubprocessEnv, findExecutable, normalizePathForCli } from "../base/subprocess-utils.js";
+import { HeadlessBackend } from "./backends/headless.js";
+import type { ExecutionBackend, ExecutionResult, AgentDebugLogger } from "./execution-backend.js";
+import type { AgentConfig } from "../types.js";
+
+// Re-export for consumers
+export type { ExecutionResult, AgentDebugLogger };
+
+/** Configuration object for BaseCliAgent construction. */
+export interface AgentExecutionConfig {
+  agent: AgentConfig;
+  schema: Record<string, unknown>;
+  timeout: number;
+  contextPath?: string;
+  sessionName?: string;
+  debugLogger?: AgentDebugLogger;
+}
+
+/**
+ * Abstract base class for all CLI agent subprocess invocations.
+ * Parameterized over return type T — ReviewerResult for reviewers,
+ * OrchestratorResult for the orchestrator.
+ * Subclasses implement provider-specific details.
+ */
+export abstract class BaseCliAgent<T> {
+  protected agent: AgentConfig;
+  protected backend: ExecutionBackend;
+  protected contextPath?: string;
+  protected debugLogger?: AgentDebugLogger;
+  protected schema: Record<string, unknown>;
+  protected sessionName: string;
+  protected timeout: number;
+
+  constructor(
+    config: AgentExecutionConfig,
+    backend?: ExecutionBackend,
+  ) {
+    this.agent = config.agent;
+    this.schema = config.schema;
+    this.timeout = config.timeout;
+    this.contextPath = config.contextPath;
+    this.sessionName = config.sessionName ?? "unknown";
+    this.debugLogger = config.debugLogger;
+    this.backend = backend ?? new HeadlessBackend();
+  }
+
+  /** Build the command-line arguments for the CLI */
+  protected abstract buildCliArgs(): string[];
+
+  // ─── Abstract Methods (Subclass Implements) ────────────────────────────
+
+  /** Build the stdin prompt for the CLI */
+  protected abstract buildPrompt(plan: string): string;
+
+  /** Optional cleanup after subprocess execution */
+  protected async cleanup(): Promise<void> {
+    // Default: no-op. Subclasses override if needed (e.g., Codex temp files).
+  }
+
+  /** Coerce parsed JSON into the result type T */
+  protected abstract coerceResult(obj: Record<string, unknown> | null, raw: string, err: string): T;
+
+  /** Extract stdout/stderr from subprocess result. Override for file-based output (Codex). */
+  protected extractOutput(result: ExecutionResult): { raw: string; err: string } {
+    return {
+      raw: result.stdout.trim(),
+      err: result.stderr.trim(),
+    };
+  }
+
+  /** Find the CLI executable. Override for custom search logic. */
+  protected findCli(): string | null {
+    return findExecutable(this.getCliName());
+  }
+
+  // ─── Template Methods (Subclass Can Override) ──────────────────────────
+
+  /** Get the CLI executable name (e.g., "claude", "codex") */
+  protected abstract getCliName(): string;
+
+  /** Get default error message for coerceToReview */
+  protected getDefaultErrorMessage(): string {
+    return `Retry or check ${this.getCliName()} configuration.`;
+  }
+
+  /** Handle non-zero exit with no output */
+  protected handleExitError(result: ExecutionResult): T {
+    const msg = `${this.agent.name} failed to run (exit ${result.exitCode})`;
+    logError(this.agent.name, `Process exited with code ${result.exitCode} and no output`);
+    return this.makeErrorResult("error", msg);
+  }
+
+  /** Handle timeout scenario */
+  protected handleTimeout(): T {
+    const msg = `${this.getCliName()} TIMEOUT after ${this.timeout}s`;
+    logWarn(this.agent.name, msg);
+    return this.makeErrorResult("error", `${this.agent.name} timed out after ${this.timeout}s`);
+  }
+
+  // ─── Shared Infrastructure ──────────────────────────────────────────────
+
+  /** Log parsed JSON result */
+  protected logParsedResult(obj: Record<string, unknown> | null): void {
+    if (this.contextPath && obj) {
+      this.debugLogger?.log(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "parsed_result", {
+        parsed_keys: Object.keys(obj),
+        verdict: obj.verdict ?? null,
+        has_summary: Boolean(obj.summary),
+        issues_count: Array.isArray(obj.issues) ? (obj.issues as unknown[]).length : 0,
+      });
+    }
+
+    if (obj) {
+      logInfo(this.agent.name, `Parsed JSON successfully, verdict: ${obj.verdict ?? "N/A"}`);
+    } else {
+      logWarn(this.agent.name, "Failed to parse JSON from output");
+    }
+  }
+
+  /** Log subprocess execution results */
+  protected logSubprocessResult(result: ExecutionResult, raw: string, err: string): void {
+    logDebug(this.agent.name, `Exit code: ${result.exitCode}`);
+    logDebug(this.agent.name, `stdout length: ${raw.length} chars`);
+    if (err) logDebug(this.agent.name, `stderr: ${err.slice(0, 500)}`);
+
+    // Debug logging
+    if (this.contextPath) {
+      this.debugLogger?.raw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stdout", raw);
+      if (err) {
+        this.debugLogger?.raw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stderr", err);
+      }
+      this.debugLogger?.log(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "subprocess_info", {
+        exit_code: result.exitCode,
+        stdout_len: raw.length,
+        stderr_len: err.length,
+        model: this.agent.model,
+        provider: this.agent.provider,
+        timeout: this.timeout,
+      });
+    }
+
+    if (raw) logDebug(this.agent.name, `stdout preview: ${raw.slice(0, 500)}`);
+  }
+
+  /** Construct a T for error/skip/timeout scenarios. Subclasses define shape. */
+  protected abstract makeErrorResult(type: "skip" | "error", message: string): T;
+
+  /** Create skip result when CLI not found */
+  protected makeSkipResult(reason: string): T {
+    logWarn(this.agent.name, reason);
+    return this.makeErrorResult("skip", reason);
+  }
+
+  /** Parse JSON from CLI output */
+  protected abstract parseOutput(raw: string, result: ExecutionResult): Record<string, unknown> | null;
+
+  /**
+   * Template method - orchestrates the review flow.
+   * Subclasses override abstract methods to customize behavior.
+   */
+  async review(plan: string): Promise<T> {
+    // 1. Find CLI executable
+    const cliPath = this.findCli();
+    if (!cliPath) {
+      return this.makeSkipResult(`${this.getCliName()} CLI not found on PATH`);
+    }
+
+    logDebug(this.agent.name, `Found ${this.getCliName()} CLI at: ${cliPath}`);
+
+    // 2. Build prompt and args (provider-specific)
+    const prompt = this.buildPrompt(plan);
+    const args = this.buildCliArgs();
+
+    logInfo(this.agent.name, `Running ${this.getCliName()} with model: ${this.agent.model}, timeout: ${this.timeout}s`);
+
+    // 3. Execute via backend
+    const env = getInternalSubprocessEnv();
+    const normalizedCliPath = normalizePathForCli(cliPath);
+    const result = await this.backend.execute({
+      cliPath: normalizedCliPath,
+      args,
+      input: prompt,
+      env: env as Record<string, string>,
+      timeoutMs: this.timeout * 1000,
+      maxBuffer: 10 * 1024 * 1024,
+      shell: process.platform === "win32",
+    });
+
+    // 4. Handle timeout
+    if (result.killed || result.signal === "SIGTERM") {
+      return this.handleTimeout();
+    }
+
+    // 5. Extract output (provider-specific)
+    const { raw, err } = this.extractOutput(result);
+
+    // 6. Handle exit errors
+    if (!raw && !err && result.exitCode !== 0) {
+      return this.handleExitError(result);
+    }
+
+    // 7. Log subprocess results
+    this.logSubprocessResult(result, raw, err);
+
+    // 8. Parse JSON output (provider-specific)
+    const obj = this.parseOutput(raw, result);
+
+    // 9. Log parsed result
+    this.logParsedResult(obj);
+
+    // 10. Coerce to result type T (provider-specific)
+    const coerced = this.coerceResult(obj, raw, err);
+
+    // 11. Cleanup (optional override)
+    await this.cleanup();
+
+    return coerced;
+  }
+}