aiwcli 0.15.4 → 0.15.7

package/dist/templates/cc-native/_cc-native/plan-review/lib/preflight.ts

@@ -3,18 +3,18 @@
  * Validates provider+model combos work before committing agents to them.
  * Runs minimal "ping" requests in parallel per unique provider:model combo.
  *
- * Uses shared checkProviderModel() from _shared/lib-ts/base/preflight.ts.
+ * Uses shared checkProviderModel() from _core/lib-ts/runtime/preflight.ts.
  * This module provides the batch orchestrator and provider registry specific
  * to the plan review pipeline.
  */
 
-import { preflightCommandConfig } from "../../../_shared/lib-ts/base/cli-args.js";
-import { logInfo, logWarn } from "../../../_shared/lib-ts/base/logger.js";
-import { checkProviderModel, type PreflightCommandConfig } from "../../../_shared/lib-ts/base/preflight.js";
+import { preflightCommandConfig } from "../../../_core/lib-ts/runtime/cli-args.js";
+import { logInfo, logWarn } from "../../../_core/lib-ts/runtime/logger.js";
+import { checkProviderModel, type PreflightCommandConfig } from "../../../_core/lib-ts/runtime/preflight.js";
 import type { ModelsConfig, PreflightCheckResult, PreflightReport } from "../../lib-ts/types.js";
 
 const HOOK = "preflight";
-const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_TIMEOUT_MS = 15_000;
 
 // ---------------------------------------------------------------------------
 // Provider Registry (built from centralized cli-args)
@@ -25,25 +25,25 @@ const PREFLIGHT_COMMANDS: Record<string, PreflightCommandConfig> = {
   codex:  preflightCommandConfig("codex"),
 };
 
+export const KNOWN_PROVIDERS = new Set(Object.keys(PREFLIGHT_COMMANDS));
+
 // ---------------------------------------------------------------------------
-// Run All Checks
+// Pure Functions (extracted for direct testing)
 // ---------------------------------------------------------------------------
 
-export async function runPreflight(
+/** @internal */
+export function collectPreflightChecks(
   modelsConfig: ModelsConfig,
-  timeoutMs?: number,
-): Promise<PreflightReport> {
-  const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const start = Date.now();
-
-  // Collect unique provider:model combos from enabled providers
+  knownProviders: Set<string>,
+): { checks: Array<{ provider: string; model: string }>; skippedProviders: string[] } {
   const checks: Array<{ provider: string; model: string }> = [];
   const seen = new Set<string>();
+  const skippedProviders: string[] = [];
 
   for (const [provider, config] of Object.entries(modelsConfig.providers)) {
     if (!config.enabled || config.models.length === 0) continue;
-    if (!PREFLIGHT_COMMANDS[provider]) {
-      logWarn(HOOK, `No preflight command for provider '${provider}', skipping`);
+    if (!knownProviders.has(provider)) {
+      skippedProviders.push(provider);
       continue;
     }
     for (const model of config.models) {
@@ -55,6 +55,45 @@ export async function runPreflight(
     }
   }
 
+  return { checks, skippedProviders };
+}
+
+/** @internal */
+export function buildPreflightReport(
+  results: Array<{ provider: string; model: string; available: boolean; error?: string; latencyMs?: number }>,
+  totalMs: number,
+): PreflightReport {
+  const available = new Map<string, Set<string>>();
+  for (const r of results) {
+    if (r.available) {
+      if (!available.has(r.provider)) available.set(r.provider, new Set());
+      available.get(r.provider)!.add(r.model);
+    }
+  }
+
+  const allFailed = available.size === 0;
+
+  return { checks: results as PreflightCheckResult[], available, allFailed, totalMs };
+}
+
+// ---------------------------------------------------------------------------
+// Run All Checks
+// ---------------------------------------------------------------------------
+
+export async function runPreflight(
+  modelsConfig: ModelsConfig,
+  timeoutMs?: number,
+): Promise<PreflightReport> {
+  const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const start = Date.now();
+
+  // Collect unique provider:model combos from enabled providers
+  const { checks, skippedProviders } = collectPreflightChecks(modelsConfig, KNOWN_PROVIDERS);
+
+  for (const provider of skippedProviders) {
+    logWarn(HOOK, `No preflight command for provider '${provider}', skipping`);
+  }
+
   if (checks.length === 0) {
     logWarn(HOOK, "No provider:model combos to check");
     return { checks: [], available: new Map(), allFailed: true, totalMs: Date.now() - start };
@@ -69,17 +108,8 @@ export async function runPreflight(
     ),
   );
 
-  // Build available map
-  const available = new Map<string, Set<string>>();
-  for (const r of results) {
-    if (r.available) {
-      if (!available.has(r.provider)) available.set(r.provider, new Set());
-      available.get(r.provider)!.add(r.model);
-    }
-  }
-
-  const allFailed = available.size === 0;
   const totalMs = Date.now() - start;
+  const report = buildPreflightReport(results, totalMs);
 
   // Log summary
   const passed = results.filter(r => r.available).length;
@@ -92,5 +122,5 @@ export async function runPreflight(
     }
   }
 
-  return { checks: results, available, allFailed, totalMs };
+  return report;
 }

package/dist/templates/cc-native/_cc-native/plan-review/lib/review-pipeline.ts

@@ -8,24 +8,24 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { resolveMandatoryAgents, assignModelsToAgents, selectAgents } from "./agent-selection.js";
-import { runPreflight } from "./preflight.js";
 import { computeCorroboratedDecision } from "./corroboration.js";
 import { computePassEligible, extractTopIssuesForTracker, advanceIterationState } from "./graduation.js";
 import { runOrchestrator } from "./orchestrator.js";
 import { truncateAgentIssues, overrideVerdictsByThreshold, buildReviewOutput } from "./output-builder.js";
 import { runPlanQuestions } from "./plan-questions.js";
+import { runPreflight } from "./preflight.js";
 import { runAgentReview } from "./reviewers/index.js";
-import { getContextReviewsDir, getContextDir, getReviewFolderPath } from "../../../_shared/lib-ts/base/constants.js";
-import { logDiagnostic } from "../../../_shared/lib-ts/base/hook-utils.js";
+import { getContextBySessionId, getAllContexts } from "../../../_core/lib-ts/context/context-store.js";
+import { logDiagnostic } from "../../../_core/lib-ts/hooks/hook-utils.js";
+import { getContextReviewsDir, getContextDir, getReviewFolderPath } from "../../../_core/lib-ts/runtime/constants.js";
 import {
   logDebug,
   logInfo,
   logWarn,
   logError,
-} from "../../../_shared/lib-ts/base/logger.js";
-import { eprint } from "../../../_shared/lib-ts/base/utils.js";
-import { getContextBySessionId, getAllContexts } from "../../../_shared/lib-ts/context/context-store.js";
-import type { ContextState } from "../../../_shared/lib-ts/types.js";
+} from "../../../_core/lib-ts/runtime/logger.js";
+import { eprint } from "../../../_core/lib-ts/runtime/utils.js";
+import type { ContextState } from "../../../_core/lib-ts/types.js";
 import { writeCombinedArtifacts, buildCorroborationReport, buildHighIssuesDocument, writeReviewTracker } from "../../artifacts/lib/index.js";
 import type { ReviewTrackerEntry } from "../../artifacts/lib/index.js";
 import {

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/agent.ts

@@ -4,15 +4,15 @@
  * See cc-native-plan-review-spec.md §4.10
  */
 
-import type { ExecutionBackend } from "../../../../_shared/lib-ts/agent-exec/execution-backend.js";
-import { logWarn } from "../../../../_shared/lib-ts/base/logger.js";
-import { debugLog, debugRaw } from "../../../lib-ts/debug.js";
-import type { AgentConfig, ReviewerResult, ReviewOptions } from "../../../lib-ts/types.js";
 import { ClaudeAgent } from "./providers/claude-agent.js";
 import { CodexAgent } from "./providers/codex-agent.js";
 import { GeminiAgent } from "./providers/gemini-agent.js";
 import type { Reviewer } from "./types.js";
 import { makeResult } from "./types.js";
+import type { ExecutionBackend } from "../../../../_core/lib-ts/agent-exec/execution-backend.js";
+import { logWarn } from "../../../../_core/lib-ts/runtime/logger.js";
+import { debugLog, debugRaw } from "../../../lib-ts/debug.js";
+import type { AgentConfig, ReviewerResult, ReviewOptions } from "../../../lib-ts/types.js";
 
 /**
  * Agent reviewer — runs a CLI instance with a custom persona.

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/base/base-agent.ts

@@ -1,7 +1,7 @@
 /**
- * Re-export shim — BaseCliAgent now lives in _shared/lib-ts/agent-exec/base-agent.ts.
+ * Re-export shim — BaseCliAgent now lives in _core/lib-ts/agent-exec/base-agent.ts.
  * This file preserves all existing import paths for provider implementations.
  */
 
-export { BaseCliAgent, type AgentExecutionConfig, type AgentDebugLogger } from "../../../../../_shared/lib-ts/agent-exec/base-agent.js";
-export type { ExecutionResult as ExecResult } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
+export { type AgentDebugLogger, type AgentExecutionConfig, BaseCliAgent } from "../../../../../_core/lib-ts/agent-exec/base-agent.js";
+export type { ExecutionResult as ExecResult } from "../../../../../_core/lib-ts/agent-exec/execution-backend.js";

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/index.ts

@@ -4,7 +4,7 @@
  */
 
 export { AgentReviewer, runAgentReview } from "./agent.js";
-export { BaseCliAgent, type AgentExecutionConfig, type AgentDebugLogger } from "./base/base-agent.js";
+export { type AgentDebugLogger, type AgentExecutionConfig, BaseCliAgent } from "./base/base-agent.js";
 export { ClaudeAgent } from "./providers/claude-agent.js";
 export { CodexAgent } from "./providers/codex-agent.js";
 export { GeminiAgent } from "./providers/gemini-agent.js";

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/providers/claude-agent.ts

@@ -3,8 +3,8 @@
  * Uses claude CLI with --json-schema and --system-prompt flags.
  */
 
-import { buildCliInvocation, reviewSpec } from "../../../../../_shared/lib-ts/base/cli-args.js";
-import type { ExecutionResult } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
+import type { ExecutionResult } from "../../../../../_core/lib-ts/agent-exec/execution-backend.js";
+import { buildCliInvocation, reviewSpec } from "../../../../../_core/lib-ts/runtime/cli-args.js";
 import { parseCliOutput } from "../../../../lib-ts/cli-output-parser.js";
 import { coerceToReview } from "../../../../lib-ts/json-parser.js";
 import type { ReviewerResult } from "../../../../lib-ts/types.js";

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/providers/codex-agent.ts

@@ -7,10 +7,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { buildCliInvocation } from "../../../../../_shared/lib-ts/base/cli-args.js";
-import type { ExecutionResult } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
-import { logDebug, logWarn } from "../../../../../_shared/lib-ts/base/logger.js";
-import { getInternalSubprocessEnv, normalizePathForCli, shellQuoteWin } from "../../../../../_shared/lib-ts/base/subprocess-utils.js";
+import type { ExecutionResult } from "../../../../../_core/lib-ts/agent-exec/execution-backend.js";
+import { buildCliInvocation } from "../../../../../_core/lib-ts/runtime/cli-args.js";
+import { logDebug, logWarn } from "../../../../../_core/lib-ts/runtime/logger.js";
+import { getInternalSubprocessEnv, normalizePathForCli, shellQuoteWin } from "../../../../../_core/lib-ts/runtime/subprocess-utils.js";
 import { debugLog, debugRaw } from "../../../../lib-ts/debug.js";
 import { parseJsonMaybe, coerceToReview } from "../../../../lib-ts/json-parser.js";
 import type { ReviewerResult } from "../../../../lib-ts/types.js";

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/providers/gemini-agent.ts

@@ -3,7 +3,7 @@
  * Placeholder for future implementation.
  */
 
-import type { ExecutionResult } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
+import type { ExecutionResult } from "../../../../../_core/lib-ts/agent-exec/execution-backend.js";
 import type { ReviewerResult } from "../../../../lib-ts/types.js";
 import { BaseCliAgent } from "../base/base-agent.js";
 import { makeResult } from "../types.js";

package/dist/templates/cc-native/_cc-native/plan-review/lib/reviewers/providers/orchestrator-claude-agent.ts

@@ -3,11 +3,10 @@
  * Analyzes plan complexity and selects reviewer agents via Claude CLI.
  */
 
-import { buildCliInvocation, reviewSpec, type CliProvider } from "../../../../../_shared/lib-ts/base/cli-args.js";
-import type { ExecutionBackend } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
-import type { ExecutionResult } from "../../../../../_shared/lib-ts/agent-exec/execution-backend.js";
-import { parseStructuredOutput } from "../../../../../_shared/lib-ts/agent-exec/structured-output.js";
-import { logDebug } from "../../../../../_shared/lib-ts/base/logger.js";
+import type { ExecutionBackend , ExecutionResult } from "../../../../../_core/lib-ts/agent-exec/execution-backend.js";
+import { parseStructuredOutput } from "../../../../../_core/lib-ts/agent-exec/structured-output.js";
+import { buildCliInvocation, reviewSpec, type CliProvider } from "../../../../../_core/lib-ts/runtime/cli-args.js";
+import { logDebug } from "../../../../../_core/lib-ts/runtime/logger.js";
 import { debugLog, debugRaw } from "../../../../lib-ts/debug.js";
 import type { AgentConfig, AgentReviewSettings, AgentSelectionConfig, OrchestratorResult, ComplexityCategory } from "../../../../lib-ts/types.js";
 import { BaseCliAgent } from "../base/base-agent.js";
@@ -78,7 +77,7 @@ export class OrchestratorClaudeAgent extends BaseCliAgent<OrchestratorResult> {
     this.settings = settings;
 
     const selection = settings.agentSelection ?? DEFAULT_AGENT_SELECTION;
-    this.fallbackCount = selection.fallbackCount ?? DEFAULT_AGENT_SELECTION.fallbackCount;
+    this.fallbackCount = selection.fallbackCount ?? 2;
     this.mandatoryCount = agentLibrary.filter((a) => mandatoryNames.has(a.name)).length;
 
     logDebug("orchestrator", `Mandatory agents (always run): ${[...mandatoryNames].sort().join(", ")}`);

package/dist/templates/core/.codex/workflows/codex.md

@@ -0,0 +1,17 @@
+# Codex Workflow
+
+Use Codex CLI handoff instructions from `.aiwcli/_core/skills/codex/SKILL.md`.
+
+## Command
+
+`bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts [flags] <mode>`
+
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
+
+## Behavior
+
+Launches Codex in a visible pane when available (tmux session first; platform window fallback when applicable).
+
+If pane launch is unavailable, it automatically falls back to non-interactive `codex exec` in the current terminal.
+
+**Common flags:** `--model <name>`, `--sandbox <mode>`, `--context <id>`, `--prompt <text>`, `--no-yolo`, `--no-watch`

package/dist/templates/core/.codex/workflows/handoff.md

@@ -0,0 +1,5 @@
+# Handoff
+
+Load and execute the handoff workflow from `.aiwcli/_core/skills/handoff-system/workflows/handoff.md`.
+
+**Triggers:** "/handoff", "write a handoff", "create a session summary", "document what we did", "end session with notes"

package/dist/templates/core/.codex/workflows/meta-plan.md

@@ -0,0 +1,7 @@
+# MetaPlan -- Prompt Amplifier
+
+Load and engage with the reasoning framework at `.aiwcli/_core/skills/meta-plan/workflows/meta-plan.md`. Apply each category as a lens for deeper analysis -- not as steps to execute.
+
+**Triggers:** "meta-plan", "chain reasoning", "dissect problem", "help me figure out the right approach"
+
+**Produces:** An amplified request document (problem decomposition, approaches, trade-offs, risks, recommendation). Does NOT produce implementation steps -- those are the next session's job.

package/dist/templates/core/.cognition/AGENTS.md

@@ -0,0 +1,5 @@
+# Cognition Notes
+
+On Windows, keep any filesystem paths that appear in `.cognition` config text or agent instructions in forward-slash form when they are meant to be read by Devin/Cognition.
+
+Reason: raw backslash paths like `C:\tmp\foo.txt` are easy for the runtime to preserve but easy for the model-side parser to misread or de-escape. Use `C:/tmp/foo.txt` in human-readable instructions; keep native Windows paths only where a shell or PowerShell command is actually executing them.

package/dist/templates/core/.cognition/config.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": ["read", "edit", "grep", "glob", "exec", "mcp__*"],
+    "deny": [],
+    "ask": []
+  },
+  "read_config_from": {
+    "cursor": true,
+    "windsurf": true,
+    "claude": true
+  }
+}

package/dist/templates/{_shared → core}/.windsurf/workflows/handoff.md

@@ -4,6 +4,6 @@ description: Create handoff document to preserve session context for future sess
 
 # Handoff
 
-Load and execute the handoff workflow from `.aiwcli/_shared/skills/handoff-system/workflows/handoff.md`.
+Load and execute the handoff workflow from `.aiwcli/_core/skills/handoff-system/workflows/handoff.md`.
 
 **Triggers:** "/handoff", "write a handoff", "create a session summary", "document what we did", "end session with notes"

package/dist/templates/{_shared → core}/.windsurf/workflows/meta-plan.md

@@ -4,7 +4,7 @@ description: Prompt amplifier for complex problems — analyzes a request throug
 
 # MetaPlan — Prompt Amplifier
 
-Load and engage with the reasoning framework at `.aiwcli/_shared/skills/meta-plan/workflows/meta-plan.md`. Apply each category as a lens for deeper analysis — not as steps to execute.
+Load and engage with the reasoning framework at `.aiwcli/_core/skills/meta-plan/workflows/meta-plan.md`. Apply each category as a lens for deeper analysis — not as steps to execute.
 
 **Triggers:** "meta-plan", "chain reasoning", "dissect problem", "help me figure out the right approach"
 

package/dist/templates/core/hooks-ts/_utils/git-state.ts

@@ -0,0 +1,2 @@
+// Re-export from shared library — canonical location is lib-ts/runtime/git-state.ts
+export { getGitState } from "../../lib-ts/runtime/git-state.js";

package/dist/templates/{_shared → core}/hooks-ts/archive_plan.ts

@@ -6,16 +6,15 @@
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
-import * as path from "node:path";
+import path from "node:path";
 
-import { getContextDir, getProjectRoot } from "../lib-ts/base/constants.js";
-import {
-  loadHookInput, logDebug, logError, logInfo, logWarn, runHookAsync,
-} from "../lib-ts/base/hook-utils.js";
-import { getContextBySessionId } from "../lib-ts/context/context-store.js";
 import {
   archivePlan, extractPlanPathFromResult, findPlanPathInTranscript,
 } from "../lib-ts/context/plan-manager.js";
+import {
+  loadHookInput, logDebug, logError, logInfo, logWarn, requireBoundSession, runHookAsync,
+} from "../lib-ts/hooks/hook-utils.js";
+import { getContextDir } from "../lib-ts/runtime/constants.js";
 
 /** Find the most recent .md file in a directory */
 function mostRecentMd(dir: string): null | string {
@@ -39,9 +38,9 @@ function mostRecentMd(dir: string): null | string {
 }
 
 /** Multi-strategy plan path discovery */
-function findPlanPath(payload: Record<string, any>, projectRoot: string): null | string {
+function findPlanPath(payload: Record<string, unknown>, projectRoot: string): null | string {
   const toolResult = payload.tool_result as string | undefined;
-  const toolInput = (payload.tool_input ?? {}) as Record<string, any>;
+  const toolInput = (payload.tool_input ?? {}) as Record<string, unknown>;
   const transcriptPath = payload.transcript_path as string | undefined;
 
   // Strategy 1: Extract from tool result
@@ -100,20 +99,17 @@ async function asyncMain(): Promise<void> {
   }
 
   // Check stop flag
-  if ((payload as any).stop_hook_active) {
+  if ((payload as unknown).stop_hook_active) {
     logDebug("archive_plan", "stop_hook_active set, skipping");
     return;
   }
 
-  const projectRoot = getProjectRoot(payload.cwd);
-  const sessionId = payload.session_id;
-  if (!sessionId) {
-    logWarn("archive_plan", "No session_id");
-    return;
-  }
+  const bound = requireBoundSession("archive_plan", payload);
+  if (!bound) return;
+  const { projectRoot, state } = bound;
 
   // Find plan path
-  let planPath = findPlanPath(payload as Record<string, any>, projectRoot);
+  let planPath = findPlanPath(payload as Record<string, unknown>, projectRoot);
   if (!planPath) {
     logWarn("archive_plan", "Could not locate plan file");
     return;
@@ -130,13 +126,6 @@ async function asyncMain(): Promise<void> {
     return;
   }
 
-  // Find bound context
-  const state = getContextBySessionId(sessionId, projectRoot);
-  if (!state) {
-    logWarn("archive_plan", `No context bound to session ${sessionId}`);
-    return;
-  }
-
   // Archive the plan (async — uses AI for slug generation)
   const [archivedPath, planHash, _planSignature] = await archivePlan(planPath, state.id, projectRoot);
 
@@ -157,3 +146,5 @@ async function asyncMain(): Promise<void> {
 }
 
 runHookAsync(asyncMain, "archive_plan");
+
+

package/dist/templates/core/hooks-ts/codex_explorer.ts

@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+/**
+ * UserPromptSubmit hook: One-shot Codex codebase exploration for first plan-mode prompt.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  emitContext, loadHookInput, logDebug, logInfo, logWarn, runHookAsync,
+} from "../lib-ts/hooks/hook-utils.js";
+import { getOutputDir, getProjectRoot } from "../lib-ts/runtime/constants.js";
+import { codexInferAsync } from "../lib-ts/runtime/inference.js";
+import { CODEX_MODELS } from "../lib-ts/runtime/models.js";
+
+const MAX_PROMPT_CHARS = 8000;
+const SPARK_TIMEOUT_SECONDS = 50;
+const FIRED_FILENAME = ".codex-explorer-fired";
+const MAX_FIRED_LINES = 200;
+const PRUNE_KEEP = 100;
+
+function getCacheFilePath(projectRoot: string): string {
+  return path.join(getOutputDir(projectRoot), FIRED_FILENAME);
+}
+
+function hasSessionFired(sessionId: string, projectRoot: string): boolean {
+  const filePath = getCacheFilePath(projectRoot);
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return content.split("\n").includes(sessionId);
+  } catch {
+    return false;
+  }
+}
+
+function markSessionFired(sessionId: string, projectRoot: string): void {
+  const filePath = getCacheFilePath(projectRoot);
+  const outputDir = getOutputDir(projectRoot);
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.appendFileSync(filePath, sessionId + "\n");
+
+  // Prune if over limit
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split("\n").filter(Boolean);
+    if (lines.length > MAX_FIRED_LINES) {
+      const pruned = lines.slice(lines.length - PRUNE_KEEP);
+      fs.writeFileSync(filePath, pruned.join("\n") + "\n");
+      logDebug("codex_explorer", `Pruned fired cache from ${lines.length} to ${pruned.length} entries`);
+    }
+  } catch (error) {
+    logWarn("codex_explorer", `Failed to prune fired cache: ${error}`);
+  }
+}
+
+/**
+ * Parse Codex JSONL output into clean agent message text.
+ * Codex --json returns streaming events; we extract only agent_message text.
+ */
+function parseCodexOutput(raw: string): string {
+  const lines = raw.split("\n").filter(Boolean);
+  const parts: string[] = [];
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      if (event.type !== "item.completed") continue;
+      const item = event.item;
+      if (item?.type === "agent_message" && item.text) {
+        parts.push(item.text);
+      }
+    } catch { /* skip non-JSON lines */ }
+  }
+  return parts.join("\n\n") || raw;
+}
+
+function buildExplorerPrompt(userPrompt: string): string {
+  const trimmed = userPrompt.trim();
+  const clipped = trimmed.length > MAX_PROMPT_CHARS
+    ? `${trimmed.slice(0, MAX_PROMPT_CHARS)}...`
+    : trimmed;
+
+  return [
+    "You are a codebase explorer.",
+    "The user is starting planning work in plan mode.",
+    "Search the current repository and identify the most relevant files, patterns, and types.",
+    "",
+    "Focus on:",
+    "- Files likely to require changes",
+    "- Existing utilities/helpers that match the request",
+    "- Key functions, classes, types, and interfaces",
+    "- Relevant tests and configuration files",
+    "",
+    "Return a concise report (maximum ~2000 characters).",
+    "Do not suggest implementation steps. Only report what exists and where.",
+    "",
+    "User prompt:",
+    "---",
+    clipped,
+    "---",
+  ].join("\n");
+}
+
+async function main(): Promise<void> {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const permissionMode = payload.permission_mode ?? "";
+  if (permissionMode !== "plan") {
+    logDebug("codex_explorer", `Skip: permission_mode=${permissionMode || "none"}`);
+    return;
+  }
+
+  const prompt = (payload as unknown as { prompt?: string }).prompt?.trim() ?? "";
+  if (!prompt) {
+    logDebug("codex_explorer", "Skip: no prompt");
+    return;
+  }
+
+  const sessionId = payload.session_id;
+  if (!sessionId) {
+    logDebug("codex_explorer", "Skip: no session_id");
+    return;
+  }
+
+  const projectRoot = getProjectRoot(payload.cwd);
+
+  if (hasSessionFired(sessionId, projectRoot)) {
+    logDebug("codex_explorer", `Skip: already fired for session ${sessionId}`);
+    return;
+  }
+
+  const startedAt = Date.now();
+  const explorerPrompt = buildExplorerPrompt(prompt);
+  const result = await codexInferAsync(
+    explorerPrompt,
+    CODEX_MODELS.spark,
+    { sandbox: "read-only", timeout: SPARK_TIMEOUT_SECONDS },
+  );
+  const elapsedMs = Date.now() - startedAt;
+
+  if (!result.success || !result.output) {
+    logWarn(
+      "codex_explorer",
+      `Explorer inference failed after ${elapsedMs}ms: ${result.error ?? "empty output"}`,
+    );
+    return;
+  }
+
+  const cleanOutput = parseCodexOutput(result.output);
+  emitContext(cleanOutput);
+  logInfo("codex_explorer", `Explorer context emitted in ${elapsedMs}ms`);
+
+  markSessionFired(sessionId, projectRoot);
+  logDebug("codex_explorer", `Marked session ${sessionId} as fired`);
+}
+
+runHookAsync(main, "codex_explorer");