aiwcli 0.11.1 → 0.12.1

package/dist/templates/_shared/lib-ts/base/subprocess-utils.ts

@@ -1,165 +1,181 @@
-/**
- * Subprocess environment utilities.
- * See SPEC.md §5.10
- */
-
-import { execSync, execFile } from "node:child_process";
-
-/**
- * Check if this is an internal subprocess call.
- * All hooks should check this and return early to prevent recursion.
- */
-export function isInternalCall(): boolean {
-  return process.env.AIWCLI_INTERNAL_CALL === "true";
-}
-
-/**
- * Get environment for internal subprocess calls.
- * Returns a copy of process.env with AIWCLI_INTERNAL_CALL=true.
- */
-export function getInternalSubprocessEnv(): Record<string, string | undefined> {
-  return {
-    ...process.env,
-    AIWCLI_INTERNAL_CALL: "true",
-  };
-}
-
-/**
- * Find an executable on the system PATH.
- * Uses `where` on Windows, `which` on Unix.
- * On Windows, prefers .cmd/.exe over extensionless shims since
- * execFileSync cannot spawn extensionless shell scripts.
- * Returns the first match or null if not found.
- */
-export function findExecutable(name: string): string | null {
-  try {
-    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
-    const lines = execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], shell: true })
-      .trim()
-      .split(/\r?\n/)
-      .map((l) => l.trim())
-      .filter(Boolean);
-
-    if (lines.length === 0) return null;
-
-    // On Windows, `where` may return an extensionless shim first (e.g. npm creates
-    // both `claude` and `claude.cmd`). execFileSync can't spawn the extensionless
-    // one, so prefer .cmd or .exe.
-    if (process.platform === "win32") {
-      const preferred = lines.find((l) => /\.(cmd|exe)$/i.test(l));
-      return preferred ?? lines[0] ?? null;
-    }
-
-    return lines[0] ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Type guard for Node.js child_process exec errors.
- * ExecSync throws objects with these extra properties on non-zero exit or timeout.
- */
-export interface ExecSyncError {
-  killed: boolean;
-  signal: string | null;
-  stdout: Buffer | string;
-  stderr: Buffer | string;
-  status: number | null;
-  message: string;
-}
-
-/** Check if an unknown error is an ExecSync error with process info. */
-export function isExecSyncError(e: unknown): e is ExecSyncError {
-  return (
-    typeof e === "object" &&
-    e !== null &&
-    "killed" in e &&
-    "signal" in e
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Async Subprocess Execution
-// ---------------------------------------------------------------------------
-
-/**
- * Result from an async subprocess execution.
- * Never throws — callers inspect fields to determine outcome.
- */
-export interface ExecResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  killed: boolean;
-  signal: string | null;
-}
-
-/** Options for execFileAsync. */
-export interface ExecAsyncOptions {
-  /** Data piped to the child's stdin. */
-  input?: string;
-  /** Timeout in milliseconds (not seconds). */
-  timeout?: number;
-  /** Environment variables for the child process. */
-  env?: Record<string, string | undefined>;
-  /** Maximum bytes on stdout/stderr. Default: 10 MB. */
-  maxBuffer?: number;
-  /** Use shell for execution. Required on Windows for .cmd files. */
-  shell?: boolean;
-}
-
-/**
- * Async subprocess execution that does NOT block the event loop.
- * Drop-in replacement for execFileSync in Promise-based parallel patterns.
- *
- * Returns ExecResult on both success and non-zero exit.
- * On timeout: result.killed = true, result.signal = "SIGTERM".
- * On spawn failure: result.exitCode = -1, result.stderr contains error.
- */
-export function execFileAsync(
-  file: string,
-  args: string[],
-  options?: ExecAsyncOptions,
-): Promise<ExecResult> {
-  return new Promise((resolve) => {
-    const child = execFile(
-      file,
-      args,
-      {
-        encoding: "utf-8",
-        timeout: options?.timeout ?? 0,
-        env: options?.env as NodeJS.ProcessEnv,
-        maxBuffer: options?.maxBuffer ?? 10 * 1024 * 1024,
-        shell: options?.shell,
-      },
-      (error, stdout, stderr) => {
-        if (error) {
-          // execFile callback error includes process exit info
-          const errObj = error as unknown as Record<string, unknown>;
-          resolve({
-            stdout: String(stdout ?? ""),
-            stderr: String(stderr ?? ""),
-            exitCode: typeof errObj.code === "number" ? errObj.code : (error as any).status ?? 1,
-            killed: Boolean(errObj.killed),
-            signal: typeof errObj.signal === "string" ? errObj.signal : null,
-          });
-        } else {
-          resolve({
-            stdout: String(stdout ?? ""),
-            stderr: String(stderr ?? ""),
-            exitCode: 0,
-            killed: false,
-            signal: null,
-          });
-        }
-      },
-    );
-
-    // Pipe input to stdin if provided
-    if (options?.input != null && child.stdin) {
-      child.stdin.write(options.input);
-      child.stdin.end();
-    }
-  });
-}
+/**
+ * Subprocess environment utilities.
+ * See SPEC.md §5.10
+ */
+
+import { execSync, execFile } from "node:child_process";
+
+/**
+ * Check if this is an internal subprocess call.
+ * All hooks should check this and return early to prevent recursion.
+ */
+export function isInternalCall(): boolean {
+  return process.env.AIWCLI_INTERNAL_CALL === "true";
+}
+
+/**
+ * Get environment for internal subprocess calls.
+ * Returns a copy of process.env with AIWCLI_INTERNAL_CALL=true and
+ * Claude Code nesting-detection env vars removed so subprocess
+ * claude instances can run without being blocked.
+ */
+export function getInternalSubprocessEnv(): Record<string, string | undefined> {
+  const env = {
+    ...process.env,
+    AIWCLI_INTERNAL_CALL: "true",
+  };
+  // Explicitly delete vars that block subprocess calls (set to undefined does not work)
+  delete env.CLAUDECODE;
+  delete env.CLAUDE_CODE_ENTRYPOINT;
+  return env;
+}
+/**
+ * Find an executable on the system PATH.
+ * Uses `where` on Windows, `which` on Unix.
+ * On Windows, prefers .cmd/.exe over extensionless shims since
+ * execFileSync cannot spawn extensionless shell scripts.
+ * Returns the first match or null if not found.
+ */
+export function findExecutable(name: string): string | null {
+  try {
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
+    const lines = execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], shell: true })
+      .trim()
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+
+    if (lines.length === 0) return null;
+
+    // On Windows, `where` may return an extensionless shim first (e.g. npm creates
+    // both `claude` and `claude.cmd`). execFileSync can't spawn the extensionless
+    // one, so prefer .cmd or .exe.
+    if (process.platform === "win32") {
+      const preferred = lines.find((l) => /\.(cmd|exe)$/i.test(l));
+      return preferred ?? lines[0] ?? null;
+    }
+
+    return lines[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Type guard for Node.js child_process exec errors.
+ * ExecSync throws objects with these extra properties on non-zero exit or timeout.
+ */
+export interface ExecSyncError {
+  killed: boolean;
+  signal: string | null;
+  stdout: Buffer | string;
+  stderr: Buffer | string;
+  status: number | null;
+  message: string;
+}
+
+/** Check if an unknown error is an ExecSync error with process info. */
+export function isExecSyncError(e: unknown): e is ExecSyncError {
+  return (
+    typeof e === "object" &&
+    e !== null &&
+    "killed" in e &&
+    "signal" in e
+  );
+}
+
+/**
+ * Quote a string for use as a cmd.exe argument when shell: true.
+ * Wraps in double quotes and escapes inner double quotes as "".
+ * On non-Windows platforms, returns the string unchanged (execFile
+ * handles quoting automatically without shell).
+ */
+export function shellQuoteWin(arg: string): string {
+  if (process.platform !== "win32") return arg;
+  return '"' + arg.replaceAll('"', '""') + '"';
+}
+
+// ---------------------------------------------------------------------------
+// Async Subprocess Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Result from an async subprocess execution.
+ * Never throws — callers inspect fields to determine outcome.
+ */
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  killed: boolean;
+  signal: string | null;
+}
+
+/** Options for execFileAsync. */
+export interface ExecAsyncOptions {
+  /** Data piped to the child's stdin. */
+  input?: string;
+  /** Timeout in milliseconds (not seconds). */
+  timeout?: number;
+  /** Environment variables for the child process. */
+  env?: Record<string, string | undefined>;
+  /** Maximum bytes on stdout/stderr. Default: 10 MB. */
+  maxBuffer?: number;
+  /** Use shell for execution. Required on Windows for .cmd files. */
+  shell?: boolean;
+}
+
+/**
+ * Async subprocess execution that does NOT block the event loop.
+ * Drop-in replacement for execFileSync in Promise-based parallel patterns.
+ *
+ * Returns ExecResult on both success and non-zero exit.
+ * On timeout: result.killed = true, result.signal = "SIGTERM".
+ * On spawn failure: result.exitCode = -1, result.stderr contains error.
+ */
+export function execFileAsync(
+  file: string,
+  args: string[],
+  options?: ExecAsyncOptions,
+): Promise<ExecResult> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      file,
+      args,
+      {
+        encoding: "utf-8",
+        timeout: options?.timeout ?? 0,
+        env: options?.env as NodeJS.ProcessEnv,
+        maxBuffer: options?.maxBuffer ?? 10 * 1024 * 1024,
+        shell: options?.shell,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          // execFile callback error includes process exit info
+          const errObj = error as unknown as Record<string, unknown>;
+          resolve({
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+            exitCode: typeof errObj.code === "number" ? errObj.code : (error as any).status ?? 1,
+            killed: Boolean(errObj.killed),
+            signal: typeof errObj.signal === "string" ? errObj.signal : null,
+          });
+        } else {
+          resolve({
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+            exitCode: 0,
+            killed: false,
+            signal: null,
+          });
+        }
+      },
+    );
+
+    // Pipe input to stdin if provided
+    if (options?.input != null && child.stdin) {
+      child.stdin.write(options.input);
+      child.stdin.end();
+    }
+  });
+}

package/dist/templates/_shared/lib-ts/context/plan-manager.ts

@@ -8,11 +8,12 @@
  * - extractPlanPathFromResult: parse plan path from ExitPlanMode output
  */
 
-import * as fs from "node:fs";
-import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { getContextDir, getContextPlansDir, sanitizeTitle } from "../base/constants.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
 import { atomicWrite } from "../base/atomic-write.js";
+import { getContextDir, getContextPlansDir, sanitizeTitle } from "../base/constants.js";
 import { logDebug, logInfo, logWarn, logError } from "../base/logger.js";
 import { generateSlug } from "../base/utils.js";
 import type { ContextState } from "../types.js";
@@ -43,8 +44,8 @@ export function archivePlan(
   let content: string;
   try {
     content = fs.readFileSync(planPath, "utf-8");
-  } catch (e: any) {
-    logError("plan_manager", `Failed to read plan: ${e}`);
+  } catch (error_: any) {
+    logError("plan_manager", `Failed to read plan: ${error_}`);
     return [null, null, null];
   }
 
@@ -148,8 +149,8 @@ export function findLatestPlan(
     if (state?.plan_path && fs.existsSync(state.plan_path)) {
       return state.plan_path;
     }
-  } catch (e: any) {
-    logWarn("plan_manager", `Failed to check state.json plan_path: ${e}`);
+  } catch (error: any) {
+    logWarn("plan_manager", `Failed to check state.json plan_path: ${error}`);
   }
 
   // 2. Fall back to most recent .md in plans/ dir
@@ -182,7 +183,7 @@ export function findLatestPlan(
  * See SPEC.md §9.4
  */
 export function generatePlanId(): string {
-  return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+  return crypto.randomUUID().replaceAll('-', "").slice(0, 8);
 }
 
 /**
@@ -191,8 +192,8 @@ export function generatePlanId(): string {
  * See SPEC.md §9.5
  */
 export function normalizePlanContent(text: string): string {
-  let result = text.replace(/<[^>]+>/g, "");
-  result = result.replace(/\s+/g, " ").trim();
+  let result = text.replaceAll(/<[^>]+>/g, "");
+  result = result.replaceAll(/\s+/g, " ").trim();
   return result;
 }
 
@@ -249,8 +250,8 @@ export function findPlanPathInTranscript(transcriptPath: string): string | null
   let lines: string[];
   try {
     lines = fs.readFileSync(transcriptPath, "utf-8").split(/\r?\n/);
-  } catch (e: any) {
-    logWarn("plan_manager", `Failed to read transcript: ${e}`);
+  } catch (error: any) {
+    logWarn("plan_manager", `Failed to read transcript: ${error}`);
     return null;
   }
 
@@ -282,7 +283,7 @@ export function findPlanPathInTranscript(transcriptPath: string): string | null
       if (!filePath) continue;
 
       // Check if path contains .claude/plans/ as consecutive parts
-      const parts = filePath.replace(/\\/g, "/").split("/");
+      const parts = filePath.replaceAll('\\', "/").split("/");
       for (let j = 0; j < parts.length - 1; j++) {
         if (parts[j] === ".claude" && parts[j + 1] === "plans") {
           logInfo("plan_manager", `Extracted plan path from transcript: ${filePath}`);

package/dist/templates/_shared/lib-ts/handoff/handoff-reader.ts

@@ -7,7 +7,8 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
+import * as path from "node:path";
+
 import { getContextHandoffsDir } from "../base/constants.js";
 import { getContext } from "../context/context-store.js";
 import type { HandoffSections } from "../types.js";
@@ -29,7 +30,7 @@ export function findLatestHandoff(contextId: string, projectRoot?: string): stri
       .sort();
 
     if (entries.length === 0) return null;
-    return path.join(handoffsDir, entries[entries.length - 1]!);
+    return path.join(handoffsDir, entries.at(-1)!);
   } catch {
     return null;
   }

package/dist/templates/_shared/lib-ts/package.json

@@ -7,8 +7,7 @@
     "test:unit": "mocha '__tests__/base/**/*.test.ts' '__tests__/templates/**/*.test.ts'",
     "test:contract": "mocha '__tests__/context/**/*.test.ts' '__tests__/handoff/**/*.test.ts'",
     "test:integration": "mocha '__tests__/integration/**/*.test.ts'",
-    "test:parity": "mocha '__tests__/integration/python-parity.test.ts'",
-    "fixtures": "python __tests__/fixtures/generate_fixtures.py"
+    "test:parity": "mocha '__tests__/integration/python-parity.test.ts'"
   },
   "devDependencies": {
     "mocha": "^10.0.0",

package/dist/templates/_shared/lib-ts/templates/plan-context.ts

@@ -1,65 +1,58 @@
 /**
- * Plan context templates for add_plan_context hook.
- * See SPEC.md §13.6
+ * Plan evaluation guidance template.
+ * Injected as context to guide the Plan agent during plan creation.
  */
 
 export function getEvaluationContextReminder(): string {
-  return `## CRITICAL: Write This Plan for a Different Agent
+  return `## Write This Plan for a Different Agent
 
-The agent executing this plan has ZERO context from this conversation — no chat history, no memory of files you explored or research you did.
+The agent executing this plan has zero context from this conversation — no chat history, no memory of files explored or decisions made.
 
-**Write as if YOU are that agent. What would you need?**
+Write as if you are that agent. What would you need?
 
-### Required Structure
+### Structure
 
 \`\`\`
-# Plan: <descriptive title>
+# Plan: [descriptive title]
 
 ## Background
-Why this change is needed (2-3 sentences)
+Why this change is needed (2-3 sentences of motivation)
 
 ## Task
-What exactly to build/change
+What exactly to build or change
 
 ## Files
 **Modify:**
-- \`exact/path/to/file.py\` - What changes (reference line numbers or patterns)
+- \`exact/path/to/file.ext\` — What changes and why
 
 **Reference:**
-- \`exact/path/to/reference.py\` - Why relevant (e.g., "pattern to follow at lines 12-30")
+- \`exact/path/to/reference.ext\` — Why relevant (e.g., "pattern to follow at lines 12-30")
 
 ## Steps
-1. [Specific steps with function names, patterns, or code snippets]
+Numbered steps with specific details. For each step, consider whether any of the skills available in your system-reminder messages would help the implementation agent — if so, reference the skill inline at the point of use.
+
+1. [Specific action with function names, patterns, or code snippets]
 2. [Enough detail for someone who never saw this conversation]
 
 ## Constraints
-- Technical requirements, preferences, or limitations
-
-## Documentation
-Decisions not written down are lost when this session ends. Update the nearest CLAUDE.md and MEMORY.md so the next session inherits what you learned.
-
-**CLAUDE.md** (nearest to changed code — cascades to subdirectories):
-- \`exact/path/to/CLAUDE.md\` — What to document
-
-**What to write:**
-- Architectural choices and why alternatives were rejected
-- Non-obvious constraints (what breaks if this changes)
-- Workarounds with context on the underlying issue
-- Patterns that prevent future mistakes
+Technical requirements, preferences, or limitations discovered during planning
 
-**Format:** \`## Topic\` / \`**Decision:** ...\` / \`**Rationale:** ...\`
+## Verification
+Binary-testable checks the implementation agent runs to confirm success. Reference relevant skills inline where they aid verification.
 
-**MEMORY.md** (cross-session learning for the AI agent):
-- Insight that would prevent a future mistake (e.g., "hook X silently drops field Y")
+## Decisions Worth Preserving
+Decisions made during this session that would be lost without documentation. Focus on:
+- What was chosen and why the alternatives were rejected
+- Constraints that aren't obvious from the code itself
+- Patterns discovered that prevent future mistakes
 
-**Include when:** Architectural decisions, non-obvious constraints, workarounds, or patterns discovered during implementation.
-**Omit entries for:** Routine changes with no decisions (rename, formatting, dependency bump).
-When in doubt, write it — a lean entry is better than a lost decision.
+The implementation agent should document these so the next session inherits what this session learned.
 \`\`\`
 
 ### Self-Check
-- [ ] Could I execute this if I forgot our entire conversation?
-- [ ] Are file paths exact (not "the auth file")?
+- [ ] Could I execute this plan having never seen this conversation?
+- [ ] Are all file paths exact (not "the auth file")?
 - [ ] Are implementation details specific (not "use the approach we discussed")?
-- [ ] Do documentation entries capture decisions the next session would otherwise lose?`;
+- [ ] Are relevant skills referenced where they add value?
+- [ ] Are key decisions captured so they survive this session?`;
 }

package/dist/templates/_shared/lib-ts/types.ts

@@ -108,13 +108,28 @@ export interface HookInput {
   transcript_path?: string;
 }
 
-// §1.7
+// §1.7 — Three hook output patterns (see hook-utils.ts for emit functions)
 export interface HookOutput {
+  // Pattern 1: hookSpecificOutput (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
   hookSpecificOutput?: {
     additionalContext?: string;
     hookEventName?: string;
-    permissionDecision?: "allow" | "deny";
+    permissionDecision?: "allow" | "deny" | "ask";
     permissionDecisionReason?: string;
+    updatedInput?: Record<string, unknown>;
+  };
+  // Pattern 2: Top-level decision (UserPromptSubmit, Stop, SubagentStop)
+  decision?: "block";
+  reason?: string;
+}
+
+// §1.7b — PermissionRequest output (structurally different from HookOutput)
+export interface PermissionRequestOutput {
+  decision: {
+    behavior: "allow" | "deny";
+    message?: string;
+    updatedInput?: Record<string, unknown>;
+    updatedPermissions?: Record<string, unknown>;
   };
 }
 

package/dist/templates/_shared/scripts/resume_handoff.ts

@@ -15,16 +15,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import { getGitStatusShort } from "../lib-ts/base/git-state.js";
+import { eprint } from "../lib-ts/base/utils.js";
+import { findActiveContextId } from "../lib-ts/context/context-store.js";
 import {
   findLatestHandoff,
   readHandoffSections,
   getHandoffTimestamp,
   getHandoffPlanReference,
 } from "../lib-ts/handoff/handoff-reader.js";
-import { getProjectRoot } from "../lib-ts/base/constants.js";
-import { findActiveContextId } from "../lib-ts/context/context-store.js";
-import { getGitStatusShort } from "../lib-ts/base/git-state.js";
-import { eprint } from "../lib-ts/base/utils.js";
 
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/templates/_shared/scripts/save_handoff.ts

@@ -22,12 +22,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import { getContext, saveState } from "../lib-ts/context/context-store.js";
-import { getHandoffFolderPath, getProjectRoot } from "../lib-ts/base/constants.js";
 import { atomicWrite } from "../lib-ts/base/atomic-write.js";
-import { logInfo, logWarn, logError } from "../lib-ts/base/logger.js";
+import { getHandoffFolderPath, getProjectRoot } from "../lib-ts/base/constants.js";
 import { getGitStatusShort } from "../lib-ts/base/git-state.js";
+import { logInfo, logWarn, logError } from "../lib-ts/base/logger.js";
 import { eprint } from "../lib-ts/base/utils.js";
+import { getContext, saveState } from "../lib-ts/context/context-store.js";
 
 // ---------------------------------------------------------------------------
 // Parsing helpers
@@ -250,8 +250,8 @@ function main(): void {
       } else {
         logWarn("save_handoff", `Failed to copy plan: ${error}`);
       }
-    } catch (e) {
-      logWarn("save_handoff", `Failed to read plan: ${e}`);
+    } catch (error) {
+      logWarn("save_handoff", `Failed to read plan: ${error}`);
     }
   }
 
@@ -339,8 +339,8 @@ function main(): void {
     } else {
       logWarn("save_handoff", `Could not load context state for ${contextId}`);
     }
-  } catch (e) {
-    logWarn("save_handoff", `Handoff saved but auto-resume won't work (context update failed): ${e}`);
+  } catch (error) {
+    logWarn("save_handoff", `Handoff saved but auto-resume won't work (context update failed): ${error}`);
   }
 
   // Output success message