ccgx-workflow 2.4.1 → 2.5.0

package/templates/scripts/ccgx-call-plugin.mjs

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 // =============================================================================
-//  ccgx-call-plugin.mjs                                          1.0.5
+//  ccgx-call-plugin.mjs                                          1.1.0
+// -----------------------------------------------------------------------------
+//  1.1.0: gemini-ccgx fork version gate (>=1.3.0) + gemini --prompt-file path,
+//         --timeout-ms passthrough + win32 tree-kill, upstream gemini-companion
+//         fallback (positional prompt + warnings), try/finally tmp cleanup.
 // -----------------------------------------------------------------------------
 //  Pure-Node helper for invoking codex/gemini plugin companions WITHOUT any
 //  shell-escape risk. Replaces the 1.0.4 heredoc-via-Bash pattern.
@@ -27,25 +31,44 @@
 //              --prompt-file /tmp/ccg-codex-1234.txt
 //    3. Parse the JSON output emitted to stdout
 //
-//  Output schema (always JSON, even on error):
+//  Output schema (always JSON, even on error) — THREE layers, flattened:
+//
+//    Layer 1 (this helper, the OUTER envelope):
 //    {
 //      "status": "ok" | "error",
 //      "vendor": "codex" | "gemini",
 //      "version": "<plugin version>",
-//      "durationMs": <number>,
+//      "durationMs": <number>,         // helper-measured wall time
 //      "exitCode": <number | null>,
-//      "stdout": "<companion stdout>",
+//      "stdout": "<companion stdout>", // raw Layer-2 JSON string (kept for debug)
 //      "stderr": "<companion stderr>",
-//      "error": "<error message if status=error, else absent>"
+//      "error": "<message if status=error, else absent>",
+//      "warnings": ["..."],            // only when flags were dropped (upstream
+//                                      // gemini-companion fallback), else absent
+//
+//      // ---- flattened from Layer 2 (companion envelope) when --json & parseable:
+//      "text": "<model textual output>",   // codex/gemini final answer (rawOutput)
+//      "threadId": "<session id | null>",  // for resume; null if absent
+//      "stats": { ... } | null             // tokens / latency etc, vendor-verbatim
 //    }
 //
+//    Layer 2 = the companion's own JSON envelope, emitted on its stdout. For
+//      gemini-batch it is {status, threadId, rawOutput, stats, ...}; for
+//      codex-companion `task --json` it is the job-result envelope. The helper
+//      JSON.parse(stdout)s it and lifts rawOutput→text, session→threadId,
+//      stats→stats so the LLM never has to reach into a nested string.
+//    Layer 3 = the model's textual answer itself, already surfaced as `.text`.
+//
 //  CLI args:
-//    <vendor>                Required. 'codex' or 'gemini'.
-//    --prompt-file <path>    Required. Path to file containing prompt body.
-//    --json                  Pass --json to companion (default: true).
-//    --no-json               Disable --json (text output).
-//    --timeout-ms <N>        Kill companion if total wall-time exceeds N ms (default: 7200000, 2h; pass 0 to disable).
-//    --max-budget-usd <N>    Forwarded to companion (default: 50).
+//    <vendor>                  Required. 'codex' or 'gemini'.
+//    --prompt-file <path>      Required. Path to file containing prompt body.
+//    --json                    Pass --json to companion (default: true).
+//    --no-json                 Disable --json (text output).
+//    --timeout-ms <N>          Kill companion if total wall-time exceeds N ms (default: 7200000, 2h; pass 0 to disable).
+//    --resume-last             Resume the most recent thread instead of a fresh one (codex live; gemini requires fork gemini-ccgx >=1.3.0).
+//    --include-directories <l> Extra read dirs for gemini (comma list); requires fork gemini-ccgx >=1.3.0; ignored by codex.
+//    --mcp-allow <names>       Selectively re-enable named MCP servers (comma list); requires fork gemini-ccgx >=1.3.0; empty = vendor default (codex keeps, gemini suppresses all).
+//    --max-budget-usd <N>      NO-OP soft hint (no plugin reads it today; see C10).
 //
 //  Cross-cutting:
 //    - Pure stdlib (fs, child_process, path, os). No deps.
@@ -54,9 +77,10 @@
 //    - spawn uses array args + windowsHide:true → zero shell escape surface.
 // =============================================================================
 
-import { spawn } from 'node:child_process'
-import { existsSync, readFileSync, realpathSync, unlinkSync } from 'node:fs'
-import { homedir, platform } from 'node:os'
+import { randomUUID } from 'node:crypto'
+import { spawn, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
 import { basename, join, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -94,6 +118,49 @@ const VENDOR_ENTRY_SCRIPTS = {
   gemini: ['gemini-batch.mjs', 'gemini-companion.mjs'],
 }
 
+// ---------------------------------------------------------------------------
+// gemini-ccgx fork capability gate.
+//
+// The fork's flag surface is version-dependent:
+//   >=1.3.0 : --prompt-file / --resume-last / --mcp-allow / --include-directories
+//             / --timeout-ms / --idle-timeout-ms are all live
+//   <1.3.0  : --resume-last is a SILENT NO-OP, --mcp-allow and
+//             --include-directories THROW unknown-flag, prompt must inline
+//             via -p (subject to the Windows ~32K argv ceiling)
+// ---------------------------------------------------------------------------
+
+const MIN_GEMINI_FORK_VERSION = '1.3.0'
+
+// Hard ceiling for prompts inlined into a single argv element. Windows'
+// CreateProcess command line tops out at 32767 chars and Node spawn throws
+// ENAMETOOLONG synchronously past it; 30000 leaves headroom for the
+// companion path + remaining flags.
+const INLINE_PROMPT_MAX_CHARS = 30000
+
+// Dependency-free semver compare → -1 / 0 / 1. Numeric triplets only;
+// non-numeric segments (and 'unknown') count as 0, so an unparseable
+// version conservatively sorts below every real release.
+function compareSemver(a, b) {
+  const pa = String(a).split('.')
+  const pb = String(b).split('.')
+  for (let i = 0; i < 3; i++) {
+    const x = Number.parseInt(pa[i], 10)
+    const y = Number.parseInt(pb[i], 10)
+    const xv = Number.isFinite(x) ? x : 0
+    const yv = Number.isFinite(y) ? y : 0
+    if (xv !== yv) return xv < yv ? -1 : 1
+  }
+  return 0
+}
+
+function isGeminiBatchFork(disc) {
+  return disc.entryName === 'gemini-batch.mjs'
+}
+
+function geminiForkReady(disc) {
+  return isGeminiBatchFork(disc) && compareSemver(disc.version, MIN_GEMINI_FORK_VERSION) >= 0
+}
+
 // ---------------------------------------------------------------------------
 // Argument parsing — minimal, KISS, no external CLI lib.
 // ---------------------------------------------------------------------------
@@ -123,6 +190,9 @@ function parseArgs(argv) {
     // task class is supposed to stream (e.g. future protocol additions)
     // can pass --idle-timeout-ms <N> explicitly.
     idleTimeoutMs: 0,
+    // C10: NO-OP soft hint. Audited 2026-06: neither codex-companion 1.0.x nor
+    // gemini-batch 1.2.x has a single read point for CODEX/GEMINI_MAX_BUDGET_USD.
+    // Kept only so callers/templates don't break; real cost lives in stats.tokens.
     maxBudgetUsd: 50,
     // 1.0.5 regression fix: pre-1.0.5 callers always passed --write directly
     // to codex-companion. Default true preserves BC; --no-write opt-out for
@@ -131,6 +201,19 @@ function parseArgs(argv) {
     model: null,
     effort: null,
     cwd: null,
+    // C5: resume the most recent thread (codex --resume-last is live; gemini
+    // forwards `gemini -r latest` with fork gemini-ccgx >=1.3.0 — older forks
+    // are hard-blocked by checkGeminiPreflight instead of silently no-op'ing).
+    resumeLast: false,
+    // C9: extra read dirs forwarded to gemini-cli --include-directories (comma
+    // list, fork gemini-ccgx >=1.3.0); codex ignores (its sandbox is
+    // single-cwd, no --add-dir surface in companion).
+    includeDirectories: null,
+    // C8: selective MCP allowlist (comma list of server names, fork
+    // gemini-ccgx >=1.3.0). Empty/null = vendor default (codex keeps its
+    // config, gemini-batch suppresses ALL via its __ccgx_no_mcp__ sentinel).
+    // Set to re-enable only retrieval servers.
+    mcpAllow: null,
   }
 
   const positional = []
@@ -153,6 +236,9 @@ function parseArgs(argv) {
       case '--model':          opts.model = next(); break
       case '--effort':         opts.effort = next(); break
       case '--cwd':            opts.cwd = next(); break
+      case '--resume-last':    opts.resumeLast = true; break
+      case '--include-directories': opts.includeDirectories = next(); break
+      case '--mcp-allow':      opts.mcpAllow = next(); break
       case '--help':
       case '-h':
         printHelp()
@@ -188,14 +274,20 @@ Optional:
   --no-json               Disable --json (text output)
   --timeout-ms <N>        Kill companion if total wall-time exceeds N ms (default: 7200000, 2h; pass 0 to disable)
   --idle-timeout-ms <N>   Kill companion if no stdout/stderr output for N ms (default: 0 = disabled). NOTE: codex-companion and gemini-batch both emit NOTHING to stdout/stderr during execution (progress lives in internal state files); idle defaults to disabled to avoid false-positive kills of healthy long tasks. Set to a positive value only if your task class is known to stream.
-  --max-budget-usd <N>    Per-call cost cap (default: 50)
+  --max-budget-usd <N>    NO-OP soft hint (default: 50). No plugin reads it today; kept for BC. Real cost surfaces in output .stats.tokens.
   --write                 Enable workspace-write sandbox (default: true; codex needs this to spawn read commands too under default approval policy)
   --no-write              Force read-only sandbox (companion approval-policy will decline most commands)
-  --model <name>          Override model (codex only; gemini ignores)
-  --effort <level>        Reasoning effort: none|minimal|low|medium|high|xhigh (codex only)
+  --model <name>          Override model. codex: forwarded as --model. gemini: forwarded as -m to gemini-cli (NOT ignored). flash/fast aliases route to the lighter tier.
+  --effort <level>        Reasoning effort: none|minimal|low|medium|high|xhigh (codex only; gemini ignores)
   --cwd <path>            Override working directory for the companion call. codex sandbox is cwd-bound; set this when auditing a repo other than the caller's cwd.
-
-Outputs JSON to stdout: {status, vendor, version, durationMs, exitCode, stdout, stderr, error?}
+  --resume-last           Resume the most recent thread instead of starting fresh. codex: live (--resume-last). gemini: requires fork gemini-ccgx >=1.3.0 (older installs hard-error with an upgrade hint). Prefer explicit threadId in parallel runs (latest can pick the wrong thread).
+  --include-directories <list>  Extra read-only dirs for gemini-cli (comma list). Requires fork gemini-ccgx >=1.3.0. codex ignores (no --add-dir in companion).
+  --mcp-allow <names>     Selectively re-enable named MCP servers (comma list). Requires fork gemini-ccgx >=1.3.0. Empty = vendor default (codex keeps config; gemini suppresses ALL). Pass only retrieval servers to keep gemini batch startup fast.
+
+Outputs JSON to stdout (flattened 3-layer envelope):
+  {status, vendor, version, durationMs, exitCode, stdout, stderr, text, threadId, stats, warnings?, error?}
+  .text = model output (codex/gemini rawOutput), .threadId = resume handle, .stats = tokens/latency.
+  .warnings only appears when flags were dropped (upstream gemini-companion fallback).
 `)
 }
 
@@ -243,10 +335,12 @@ function discoverCompanion(vendor, homeDir = homedir()) {
   // BC: vendors with only the legacy companion still resolve correctly.
   const entryCandidates = VENDOR_ENTRY_SCRIPTS[vendor] ?? [`${vendor}-companion.mjs`]
   let companionPath = null
+  let entryName = null
   for (const name of entryCandidates) {
     const candidate = join(installPath, 'scripts', name)
     if (existsSync(candidate)) {
       companionPath = candidate
+      entryName = name
       break
     }
   }
@@ -256,6 +350,9 @@ function discoverCompanion(vendor, homeDir = homedir()) {
 
   return {
     companionPath,
+    // entryName drives the version gate + arg-building branches downstream
+    // (gemini-batch fork vs upstream gemini-companion fallback).
+    entryName,
     version: typeof inst?.version === 'string' ? inst.version : 'unknown',
   }
 }
@@ -282,6 +379,178 @@ function emitError(vendor, version, error, extra = {}) {
   })
 }
 
+// ---------------------------------------------------------------------------
+// C7: flatten the Layer-2 companion envelope into stable top-level fields.
+//
+// Both vendors emit a JSON envelope on stdout when --json is set:
+//   gemini-batch: { status, threadId, rawOutput, stats, ... }
+//   codex-companion task --json: a job-result envelope (rawOutput/text + stats)
+// The LLM should never have to reach into a nested JSON string, so we lift the
+// model output → .text, session id → .threadId, stats → .stats. Best-effort:
+// if stdout isn't parseable JSON (e.g. --no-json), we leave .text null and the
+// raw stdout string remains available on .stdout.
+// ---------------------------------------------------------------------------
+
+function flattenCompanionEnvelope(stdout) {
+  const flat = { text: null, threadId: null, stats: null }
+  if (typeof stdout !== 'string' || stdout.trim() === '') return flat
+  let env
+  try {
+    env = JSON.parse(stdout)
+  }
+  catch {
+    return flat // not JSON (text mode / partial output) — leave nulls
+  }
+  if (!env || typeof env !== 'object') return flat
+  // Model output: gemini → rawOutput; codex → text or rawOutput.
+  if (typeof env.text === 'string') flat.text = env.text
+  else if (typeof env.rawOutput === 'string') flat.text = env.rawOutput
+  // Session/thread id for resume.
+  if (typeof env.threadId === 'string') flat.threadId = env.threadId
+  else if (typeof env.sessionId === 'string') flat.threadId = env.sessionId
+  // Stats (tokens/latency) verbatim.
+  if (env.stats !== undefined) flat.stats = env.stats
+  return flat
+}
+
+// ---------------------------------------------------------------------------
+// Gemini preflight gate — fail fast BEFORE writing tmp files or spawning.
+//
+// Two classes of rejection (both better than the runtime alternative):
+//   1. <1.3.0 fork + fork-only flag requested: --resume-last would be a
+//      SILENT no-op and --mcp-allow / --include-directories would make
+//      gemini-batch throw unknown-flag. Hard-error with an upgrade hint.
+//   2. Inline-prompt path (fork <1.3.0 `-p`, or upstream companion
+//      positional) + prompt >30000 chars: Windows spawn would die with a
+//      bare ENAMETOOLONG at the ~32K argv ceiling. Reject with context.
+// Returns an error string (caller emits + exits 78 EX_CONFIG) or null.
+// ---------------------------------------------------------------------------
+
+function checkGeminiPreflight(opts, disc, promptBody) {
+  if (opts.vendor !== 'gemini') return null
+  if (isGeminiBatchFork(disc) && !geminiForkReady(disc)) {
+    const requested = []
+    if (opts.resumeLast) requested.push('--resume-last')
+    if (opts.mcpAllow) requested.push('--mcp-allow')
+    if (opts.includeDirectories) requested.push('--include-directories')
+    if (requested.length > 0) {
+      return `installed gemini-ccgx ${disc.version} does not support ${requested.join(', ')}`
+        + ` (--resume-last is a silent no-op, the others throw unknown-flag);`
+        + ` update the plugin to >=${MIN_GEMINI_FORK_VERSION}`
+    }
+    if (promptBody.length > INLINE_PROMPT_MAX_CHARS) {
+      return `prompt is ${promptBody.length} chars but gemini-ccgx ${disc.version} only accepts it`
+        + ` inlined via -p (Windows spawn throws ENAMETOOLONG past the ~32K argv ceiling);`
+        + ` update the plugin to >=${MIN_GEMINI_FORK_VERSION} for --prompt-file support`
+    }
+  }
+  if (disc.entryName === 'gemini-companion.mjs' && promptBody.length > INLINE_PROMPT_MAX_CHARS) {
+    return `prompt is ${promptBody.length} chars but upstream gemini-companion only accepts it`
+      + ` as a positional argv element (Windows spawn throws ENAMETOOLONG past the ~32K argv ceiling);`
+      + ` install the gemini-ccgx fork >=${MIN_GEMINI_FORK_VERSION} for --prompt-file support`
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// C1/C5/C8/C9: build the companion argv array. Pure function (no I/O) so unit
+// tests can assert the exact vendor-specific flag surface. Returns
+// { args, warnings } — warnings records flags dropped on the upstream
+// gemini-companion fallback so the caller can surface them in the envelope.
+//
+//   codex                          → task --prompt-file <tmp> [--json] [--write]
+//       [--model m] [--effort e] [--resume-last] [--cwd p]
+//       (NEVER -p, NEVER inlined prompt)
+//   gemini gemini-batch >=1.3.0    → task --prompt-file <tmp> [--json] [--write]
+//       [--model m] [--resume-last] [--include-directories l] [--mcp-allow n]
+//       [--timeout-ms n] [--idle-timeout-ms n] [--cwd p]
+//   gemini gemini-batch <1.3.0     → task -p <promptBody> [--json] [--write]
+//       [--model m] [--cwd p]
+//       (fork-only flags + oversized prompts hard-blocked by checkGeminiPreflight)
+//   gemini gemini-companion (upstream fallback) → task <promptBody> [--model m]
+//       [--cwd p]   (fork-only flags dropped + recorded in warnings)
+// ---------------------------------------------------------------------------
+
+function buildCompanionArgs(opts, disc, tmpPromptPath, promptBody) {
+  const warnings = []
+  const args = [disc.companionPath, 'task']
+  const companionFallback = opts.vendor === 'gemini' && disc.entryName === 'gemini-companion.mjs'
+  const forkReady = opts.vendor === 'gemini' && geminiForkReady(disc)
+
+  if (companionFallback) {
+    // Upstream ACP companion: positional prompt (it has no -p / --prompt-file)
+    // and a minimal flag surface — forward only --model/--cwd, drop the
+    // fork-only flags and record each drop for the result envelope.
+    args.push(promptBody)
+    if (opts.model) args.push('--model', opts.model)
+    if (opts.cwd) args.push('--cwd', opts.cwd)
+    const dropped = []
+    if (opts.resumeLast) dropped.push('--resume-last')
+    if (opts.includeDirectories) dropped.push('--include-directories')
+    if (opts.mcpAllow) dropped.push('--mcp-allow')
+    for (const flag of dropped) {
+      warnings.push(`${flag} dropped: upstream gemini-companion does not support it (install gemini-ccgx >=${MIN_GEMINI_FORK_VERSION})`)
+    }
+    return { args, warnings }
+  }
+
+  if (opts.vendor === 'codex') {
+    // --prompt-file is a first-class codex valueOption (companion:614). This
+    // removes both the `-p`→positional pollution and the Windows 32K argv risk.
+    args.push('--prompt-file', tmpPromptPath)
+  }
+  else if (forkReady) {
+    // fork gemini-ccgx >=1.3.0 ships the same --prompt-file valueOption, so
+    // gemini joins codex off the argv path (no 32K ceiling, no -p).
+    args.push('--prompt-file', tmpPromptPath)
+  }
+  else {
+    // gemini-batch <1.3.0 has no --prompt-file (throws on unknown flags) and
+    // requires -p (body piped over stdin internally). Size is pre-checked by
+    // checkGeminiPreflight, so this never exceeds INLINE_PROMPT_MAX_CHARS.
+    args.push('-p', promptBody)
+  }
+  if (opts.json) args.push('--json')
+  if (opts.write) args.push('--write')
+  // --model: codex forwards as --model; gemini-batch forwards as -m internally.
+  if (opts.model) args.push('--model', opts.model)
+  // --effort is codex-only (gemini-batch consumes-and-ignores it; keep it off
+  // the gemini path to avoid relying on that no-op).
+  if (opts.effort && opts.vendor === 'codex') args.push('--effort', opts.effort)
+  // C5: resume the most recent thread. codex --resume-last is live; gemini
+  // forwards `gemini -r latest` with fork gemini-ccgx >=1.3.0. Older forks are
+  // hard-blocked by checkGeminiPreflight — never emitted here defensively.
+  if (opts.resumeLast && (opts.vendor === 'codex' || forkReady)) args.push('--resume-last')
+  // C9: gemini-only extra read dirs (codex companion has no --add-dir surface),
+  // fork gemini-ccgx >=1.3.0 only (older forks throw unknown-flag).
+  if (opts.includeDirectories && forkReady) {
+    args.push('--include-directories', opts.includeDirectories)
+  }
+  // C8: selective MCP allowlist (gemini fork >=1.3.0 only). Forward real
+  // server names so retrieval MCPs (fast-context/context7) survive instead of
+  // being blanket-suppressed by gemini-batch's __ccgx_no_mcp__ sentinel.
+  // codex-companion 1.0.4 has no MCP-selection flag (its task valueOptions are
+  // model/effort/cwd/prompt-file), so MCP scoping is not forwardable to codex
+  // — emitting a flag there is a silent no-op, so we don't.
+  if (opts.mcpAllow && forkReady) {
+    args.push('--mcp-allow', opts.mcpAllow)
+  }
+  // Timeout passthrough (fork >=1.3.0): hand gemini-batch a slightly SHORTER
+  // deadline than the helper's own so its internal taskkill /T /F tree-kill
+  // fires first — a helper-side SIGTERM on win32 cannot reach gemini-cli's
+  // grandchildren (MCP servers), the fork's in-process tree-kill can.
+  if (forkReady && opts.timeoutMs > 0) {
+    args.push('--timeout-ms', String(Math.max(60000, opts.timeoutMs - 10000)))
+  }
+  if (forkReady && opts.idleTimeoutMs > 0) {
+    args.push('--idle-timeout-ms', String(Math.max(60000, opts.idleTimeoutMs - 10000)))
+  }
+  // --cwd pass-through: codex sandbox is cwd-bound. For cross-repo audits the
+  // caller must set this to the repo being audited.
+  if (opts.cwd) args.push('--cwd', opts.cwd)
+  return { args, warnings }
+}
+
 // ---------------------------------------------------------------------------
 // Main: spawn companion with array args (no shell)
 // ---------------------------------------------------------------------------
@@ -306,35 +575,6 @@ async function main(argv) {
     process.exit(66) // EX_NOINPUT
   }
 
-  // 2.1.1: auto-delete the prompt file after a successful read iff the
-  // PHYSICAL path sits inside the caller's `<cwd>/.context/tmp/` AND the
-  // filename starts with `ccg-`. This is the workflow-managed throwaway-
-  // prompt directory (see templates/commands/review.md — Step 1 writes
-  // prompts here).
-  //
-  // CRITICAL — codex audit 2026-05-12 raised: lexical `resolve()` is
-  // insufficient. If `.context` or `.context/tmp` is a symlink/junction
-  // pointing outside the workspace, OR the caller passes a path whose
-  // lexical form is `<cwd>/.context/tmp/ccg-x.txt` but its physical
-  // target is `/etc/passwd` (or worse, `C:\Windows\System32\...`), the
-  // lexical-only check would still authorize the unlink. realpathSync
-  // canonicalizes ALL symlinks/junctions/`..` segments before the
-  // whitelist compare — both for the candidate file AND the safeRoot.
-  // Two ANDed gates: physical prefix + filename prefix.
-  try {
-    const resolvedFile = realpathSync(opts.promptFile)
-    const safeRoot = realpathSync(resolve(process.cwd(), '.context', 'tmp')) + sep
-    if (resolvedFile.startsWith(safeRoot) && basename(resolvedFile).startsWith('ccg-')) {
-      unlinkSync(resolvedFile)
-    }
-  }
-  catch {
-    // Best-effort. ENOENT (.context/tmp absent, file already gone, etc.)
-    // is the dominant non-error case here; we deliberately don't surface
-    // it. Real failures (permission etc.) will leave a file behind that
-    // .gitignore catches and the user's next run overwrites.
-  }
-
   // Discover companion via SSoT (no glob, no head -1)
   const disc = discoverCompanion(opts.vendor)
   if (disc.error) {
@@ -342,106 +582,212 @@ async function main(argv) {
     process.exit(69) // EX_UNAVAILABLE
   }
 
-  // Build companion argv as ARRAY — no shell layer ever
-  const companionArgs = [
-    disc.companionPath,
-    'task',
-    '-p',
-    promptBody,
-  ]
-  if (opts.json) companionArgs.push('--json')
-  // codex-companion flag pass-through (1.0.5 regression fix). gemini-companion
-  // ignores unknown flags safely; both vendors accept this surface.
-  if (opts.write) companionArgs.push('--write')
-  if (opts.model) companionArgs.push('--model', opts.model)
-  if (opts.effort) companionArgs.push('--effort', opts.effort)
-  // --cwd pass-through: codex sandbox is cwd-bound. For cross-repo audits
-  // the caller must set this to the repo being audited (codex-companion
-  // does not expose --add-dir; multi-workspace requires deeper changes).
-  if (opts.cwd) companionArgs.push('--cwd', opts.cwd)
+  // Version/flag/size gate — fail fast before tmp files or spawn.
+  const gateError = checkGeminiPreflight(opts, disc, promptBody)
+  if (gateError) {
+    emitError(opts.vendor, disc.version, gateError)
+    process.exit(78) // EX_CONFIG
+  }
 
-  const startedAt = Date.now()
+  // C1: write promptBody to a helper-owned temp file so the companion receives
+  // it via `--prompt-file <tmp>` (NOT inlined into argv). This kills two bugs:
+  //   (a) Windows' 32767-char command-line ceiling — a big review/spec diff
+  //       inlined as a single argv element used to blow the spawn outright.
+  //   (b) codex-companion treats a bare `-p` as an UNKNOWN short flag → it
+  //       falls into positionals and gets join(' ')'d into the prompt, so every
+  //       codex prompt was silently prefixed with "-p ". --prompt-file is a
+  //       first-class valueOption (codex-companion.mjs:614, resolved vs cwd).
+  // gemini joins this path with fork gemini-ccgx >=1.3.0 (same --prompt-file
+  // flag). Older gemini-batch (<1.3.0) and the upstream gemini-companion
+  // fallback still inline the prompt into argv — for those the 32K risk is
+  // bounded by checkGeminiPreflight's explicit >30000-char rejection above.
+  let tmpPromptPath = null
+  try {
+    tmpPromptPath = join(tmpdir(), `ccgx-prompt-${randomUUID()}.txt`)
+    writeFileSync(tmpPromptPath, promptBody, 'utf-8')
+  }
+  catch (err) {
+    emitError(opts.vendor, disc.version, `temp prompt write failed: ${err.message}`)
+    process.exit(73) // EX_CANTCREAT
+  }
 
-  // spawn 'node' with array args. Node will look up its own executable;
-  // companionPath is passed as a literal arg, no shell interpretation.
-  const child = spawn(process.execPath, companionArgs, {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    windowsHide: true,
-    env: {
-      ...process.env,
-      // Forward budget cap if companion respects it (codex does)
-      CODEX_MAX_BUDGET_USD: String(opts.maxBudgetUsd),
-      GEMINI_MAX_BUDGET_USD: String(opts.maxBudgetUsd),
-    },
-  })
+  const result = await executeCompanion(opts, disc, tmpPromptPath, promptBody)
+  emitJson(result)
+  process.exit(result.status === 'ok' ? 0 : 1)
+}
 
-  let stdoutBuf = ''
-  let stderrBuf = ''
-  let lastActivityAt = Date.now()
-  child.stdout.on('data', (chunk) => {
-    stdoutBuf += chunk.toString('utf-8')
-    lastActivityAt = Date.now()
-  })
-  child.stderr.on('data', (chunk) => {
-    stderrBuf += chunk.toString('utf-8')
-    lastActivityAt = Date.now()
-  })
+// ---------------------------------------------------------------------------
+// executeCompanion: spawn → timers → wait → flatten → result envelope.
+//
+// The try/finally makes temp-prompt cleanup unconditional: a SYNCHRONOUS spawn
+// throw (e.g. Windows ENAMETOOLONG on an oversized argv) must not leak
+// tmpPromptPath, not just the normal exit path. `deps` is a test seam
+// (spawn/spawnSync injection); production callers pass nothing.
+// ---------------------------------------------------------------------------
+
+async function executeCompanion(opts, disc, tmpPromptPath, promptBody, deps = {}) {
+  const spawnImpl = deps.spawn ?? spawn
+  const spawnSyncImpl = deps.spawnSync ?? spawnSync
+
+  // Build companion argv as ARRAY — no shell layer ever (pure + testable).
+  const { args: companionArgs, warnings } = buildCompanionArgs(opts, disc, tmpPromptPath, promptBody)
 
-  // 2.1.1: two-layer timeout. wall-time is the safety ceiling; idle is the
-  // primary "stuck" detector — a healthy long task keeps producing tool-call
-  // / progress chunks, a truly hung companion produces nothing. SIGTERM is
-  // best-effort on Windows where the kernel doesn't propagate to the
-  // grandchild tree; companion processes on this code path are expected to
-  // do their own subtree cleanup (taskkill /T) when they receive SIGTERM.
-  let timedOut = false
-  let timeoutReason = null
-  const killChild = (reason) => {
-    timedOut = true
-    timeoutReason = reason
-    try { child.kill('SIGTERM') } catch { /* ignore */ }
-    setTimeout(() => {
-      try { child.kill('SIGKILL') } catch { /* ignore */ }
-    }, 5000).unref?.()
-  }
-  const wallTimer = opts.timeoutMs > 0
-    ? setTimeout(() => killChild(`wall-time ${opts.timeoutMs}ms`), opts.timeoutMs)
-    : null
-  // Check idle every 30s. A 30s sampling granularity adds at most 30s slop
-  // to the configured idle threshold, which is negligible at 600s default.
-  const idleChecker = opts.idleTimeoutMs > 0
-    ? setInterval(() => {
-        const silent = Date.now() - lastActivityAt
-        if (silent >= opts.idleTimeoutMs) {
-          killChild(`idle ${silent}ms exceeds ${opts.idleTimeoutMs}ms`)
+  const startedAt = Date.now()
+  try {
+    // spawn 'node' with array args. Node will look up its own executable;
+    // companionPath is passed as a literal arg, no shell interpretation.
+    // NOTE (C10): we no longer inject CODEX/GEMINI_MAX_BUDGET_USD — audited
+    // 2026-06, zero read points in either plugin. --max-budget-usd is a no-op
+    // soft hint; real cost lives in the flattened .stats.tokens.
+    const child = spawnImpl(process.execPath, companionArgs, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      env: process.env,
+    })
+
+    let stdoutBuf = ''
+    let stderrBuf = ''
+    let lastActivityAt = Date.now()
+    child.stdout.on('data', (chunk) => {
+      stdoutBuf += chunk.toString('utf-8')
+      lastActivityAt = Date.now()
+    })
+    child.stderr.on('data', (chunk) => {
+      stderrBuf += chunk.toString('utf-8')
+      lastActivityAt = Date.now()
+    })
+
+    // 2.1.1: two-layer timeout. wall-time is the safety ceiling; idle is the
+    // primary "stuck" detector — a healthy long task keeps producing tool-call
+    // / progress chunks, a truly hung companion produces nothing.
+    //
+    // C6: a bare child.kill() is INSUFFICIENT for codex. The codex turn runs in
+    // a DETACHED broker process (codex.mjs spawns it), so killing the foreground
+    // companion leaves the turn burning tokens, the job stuck "running", and the
+    // next --resume-last blocked by "Task X is still running". The proper
+    // teardown is codex-companion's own `cancel` subcommand, which does
+    // turn/interrupt + taskkill /T /F on the broker tree (codex-companion.mjs
+    // handleCancel:920-979). So on timeout we run `cancel` FIRST, then fall back
+    // to SIGTERM/SIGKILL.
+    //
+    // gemini has no detached broker and no `cancel` subcommand, but gemini-cli
+    // spawns its own children (MCP servers, ripgrep): on win32 a bare SIGTERM
+    // kills only the foreground node and orphans that tree, so we tree-kill via
+    // taskkill /pid <pid> /T /F. Non-win32 keeps the signal path (process
+    // groups reap children there). With fork >=1.3.0 the forwarded --timeout-ms
+    // (10s shorter) normally fires gemini-batch's own tree-kill before this.
+    let timedOut = false
+    let timeoutReason = null
+    const killChild = (reason) => {
+      timedOut = true
+      timeoutReason = reason
+      if (opts.vendor === 'codex') {
+        try {
+          const cancelArgs = [disc.companionPath, 'cancel', '--json']
+          if (opts.cwd) cancelArgs.push('--cwd', opts.cwd)
+          const canceller = spawnImpl(process.execPath, cancelArgs, {
+            stdio: 'ignore',
+            windowsHide: true,
+            env: process.env,
+          })
+          canceller.unref?.()
+        }
+        catch { /* fall through to signal kill */ }
+      }
+      else if (process.platform === 'win32') {
+        try {
+          spawnSyncImpl('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+          })
+          return
         }
-      }, 30000)
-    : null
-  if (idleChecker?.unref) idleChecker.unref()
+        catch { /* fall through to signal kill */ }
+      }
+      try { child.kill('SIGTERM') } catch { /* ignore */ }
+      setTimeout(() => {
+        try { child.kill('SIGKILL') } catch { /* ignore */ }
+      }, 5000).unref?.()
+    }
+    const wallTimer = opts.timeoutMs > 0
+      ? setTimeout(() => killChild(`wall-time ${opts.timeoutMs}ms`), opts.timeoutMs)
+      : null
+    // Check idle every 30s. A 30s sampling granularity adds at most 30s slop
+    // to the configured idle threshold, which is negligible at 600s default.
+    const idleChecker = opts.idleTimeoutMs > 0
+      ? setInterval(() => {
+          const silent = Date.now() - lastActivityAt
+          if (silent >= opts.idleTimeoutMs) {
+            killChild(`idle ${silent}ms exceeds ${opts.idleTimeoutMs}ms`)
+          }
+        }, 30000)
+      : null
+    if (idleChecker?.unref) idleChecker.unref()
+
+    const exit = await new Promise((resolve) => {
+      child.once('exit', (code, signal) => resolve({ code, signal }))
+      child.once('error', (err) => resolve({ code: 70, signal: null, errorMsg: err.message }))
+    })
+    if (wallTimer) clearTimeout(wallTimer)
+    if (idleChecker) clearInterval(idleChecker)
+
+    const durationMs = Date.now() - startedAt
+    const status = (!timedOut && exit.code === 0) ? 'ok' : 'error'
+    const flat = flattenCompanionEnvelope(stdoutBuf)
+    const result = {
+      status,
+      vendor: opts.vendor,
+      version: disc.version,
+      durationMs,
+      exitCode: exit.code,
+      stdout: stdoutBuf,
+      stderr: stderrBuf,
+      // C7: flattened Layer-2 fields so the LLM parses once.
+      text: flat.text,
+      threadId: flat.threadId,
+      stats: flat.stats,
+    }
+    if (warnings.length > 0) result.warnings = warnings
+    if (timedOut) result.error = `companion killed: ${timeoutReason}`
+    else if (exit.errorMsg) result.error = `spawn error: ${exit.errorMsg}`
+    else if (exit.code !== 0) result.error = `companion exited with code ${exit.code}`
+    return result
+  }
+  finally {
+    // C1 cleanup, in finally so it runs on BOTH the normal post-exit path and
+    // the synchronous-throw path (spawn ENAMETOOLONG/EPERM). Deferring past
+    // child exit is mandatory on the normal path — codex reads --prompt-file
+    // lazily, so an early unlink would race the child's open(). realpathSync
+    // canonicalizes symlinks/junctions/`..` before the whitelist compare on
+    // BOTH the candidate and safeRoot (codex audit 2026-05-12: lexical
+    // resolve() is insufficient).
+    cleanupTempFiles(tmpPromptPath, opts.promptFile)
+  }
+}
 
-  const exit = await new Promise((resolve) => {
-    child.once('exit', (code, signal) => resolve({ code, signal }))
-    child.once('error', (err) => resolve({ code: 70, signal: null, errorMsg: err.message }))
-  })
-  if (wallTimer) clearTimeout(wallTimer)
-  if (idleChecker) clearInterval(idleChecker)
-
-  const durationMs = Date.now() - startedAt
-  const status = (!timedOut && exit.code === 0) ? 'ok' : 'error'
-  const result = {
-    status,
-    vendor: opts.vendor,
-    version: disc.version,
-    durationMs,
-    exitCode: exit.code,
-    stdout: stdoutBuf,
-    stderr: stderrBuf,
-  }
-  if (timedOut) result.error = `companion killed: ${timeoutReason}`
-  else if (exit.errorMsg) result.error = `spawn error: ${exit.errorMsg}`
-  else if (exit.code !== 0) result.error = `companion exited with code ${exit.code}`
+// ---------------------------------------------------------------------------
+// Temp-file cleanup — best-effort, never throws.
+//   - tmpPromptPath: helper-owned throwaway (always safe to unlink).
+//   - sourcePromptFile: caller's file; only unlink when its PHYSICAL path is
+//     inside <cwd>/.context/tmp/ AND basename starts with ccg- (workflow-
+//     managed throwaway, see templates/commands/review.md Step 1).
+// ---------------------------------------------------------------------------
 
-  emitJson(result)
-  process.exit(status === 'ok' ? 0 : 1)
+function cleanupTempFiles(tmpPromptPath, sourcePromptFile) {
+  if (tmpPromptPath) {
+    try { unlinkSync(tmpPromptPath) } catch { /* best-effort */ }
+  }
+  try {
+    const resolvedFile = realpathSync(sourcePromptFile)
+    const safeRoot = realpathSync(resolve(process.cwd(), '.context', 'tmp')) + sep
+    if (resolvedFile.startsWith(safeRoot) && basename(resolvedFile).startsWith('ccg-')) {
+      unlinkSync(resolvedFile)
+    }
+  }
+  catch {
+    // ENOENT (.context/tmp absent / file already gone) is the dominant
+    // non-error case; real failures leave a file the .gitignore catches.
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -470,5 +816,12 @@ if (isMainModule()) {
 export const ccgxCallPluginExports = {
   parseArgs,
   discoverCompanion,
+  buildCompanionArgs,
+  flattenCompanionEnvelope,
+  checkGeminiPreflight,
+  compareSemver,
+  executeCompanion,
+  INLINE_PROMPT_MAX_CHARS,
+  MIN_GEMINI_FORK_VERSION,
   VENDOR_KEYS,
 }