aiwcli 0.11.1 → 0.12.1

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

@@ -4,27 +4,27 @@
  * See SPEC.md §5
  */
 
-import * as fs from "node:fs";
+import * as fs from "node:fs";
 
 import { getProjectRoot } from "./constants.js";
-import { getContextPath as _getContextPath, hookLog, logDebug, setSessionId } from "./logger.js";
+import { logDebug,  logWarn,     hookLog, setSessionId,  getContextPath as _getContextPath } from "./logger.js";
 import { getContextBySessionId } from "../context/context-store.js";
-import type { HookInput, HookOutput } from "../types.js";
+import type { HookInput, HookOutput, PermissionRequestOutput } from "../types.js";
 
 // Re-export logger functions for convenience (matches Python hook_utils re-exports)
-
+export {          setSessionId };
 
 // Context window baseline: tokens not visible in hook data §5.9
 export const CONTEXT_BASELINE_TOKENS = 22_600;
 export const DEFAULT_CONTEXT_WINDOW_SIZE = 200_000;
 
 // Event metadata stash — populated by loadHookInput(), read by runHook()
-let _lastHookEvent: null | string = null;
-let _lastToolName: null | string = null;
-let _cachedHookName: null | string = null;
+let _lastHookEvent: string | null = null;
+let _lastToolName: string | null = null;
+let _cachedHookName: string | null = null;
 
 // Pre-fetched input stash
-let _prefetchedInput: null | Record<string, any> = null;
+let _prefetchedInput: Record<string, any> | null = null;
 
 /**
  * Load and parse JSON from stdin (or return prefetched input if set).
@@ -39,13 +39,12 @@ export function loadHookInput(): HookInput | null {
       _lastHookEvent = result.hook_event_name ?? null;
       _lastToolName = result.tool_name ?? null;
     }
-
     return result as HookInput;
   }
 
   try {
     // Read entire stdin using fd 0 (cross-platform, works on Windows)
-    const inputData = fs.readFileSync(0, "utf8").trim();
+    const inputData = fs.readFileSync(0, "utf-8").trim();
     if (!inputData) return null;
 
     const result = JSON.parse(inputData);
@@ -53,7 +52,6 @@ export function loadHookInput(): HookInput | null {
       _lastHookEvent = result.hook_event_name ?? null;
       _lastToolName = result.tool_name ?? null;
     }
-
     return result as HookInput;
   } catch {
     return null;
@@ -80,7 +78,7 @@ export function validateHookEvent(
  */
 export function getToolInput(
   payload: HookInput,
-): null | Record<string, any> {
+): Record<string, any> | null {
   const toolInput = payload.tool_input;
   return toolInput && typeof toolInput === "object" ? toolInput : null;
 }
@@ -101,7 +99,6 @@ export function checkSkipPersistence(
     logDebug(hookName, "Skipping persistence (skip_persistence flag set)");
     return true;
   }
-
   return false;
 }
 
@@ -109,10 +106,23 @@ export function checkSkipPersistence(
  * Emit hookSpecificOutput with additionalContext to stdout.
  * hookEventName is required by Claude Code's Zod validator (discriminated union).
  * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ *
+ * SubagentStop and Stop events use top-level systemMessage field instead of hookSpecificOutput.
  * See SPEC.md §5.5
  */
 export function emitContext(additionalContext: string): void {
   const eventName = _lastHookEvent ?? undefined;
+  const tool = _lastToolName;
+
+  // SubagentStop and Stop use top-level systemMessage field
+  if (eventName === "SubagentStop" || eventName === "Stop") {
+    const out = { systemMessage: additionalContext };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    _logEmit("systemMessage", additionalContext.length, { event: eventName ?? "unknown", systemMessage: additionalContext });
+    return;
+  }
+
+  // All other events use hookSpecificOutput
   const out: HookOutput = {
     hookSpecificOutput: {
       ...(eventName ? { hookEventName: eventName } : {}),
@@ -120,7 +130,8 @@ export function emitContext(additionalContext: string): void {
     },
   };
   const json = JSON.stringify(out);
-  _logEmit("context", additionalContext.length, { additionalContext });
+  const eventDesc = tool ? `${eventName}:${tool}` : eventName ?? "unknown";
+  _logEmit("context", additionalContext.length, { event: eventDesc, additionalContext });
   process.stdout.write(json + "\n");
 }
 
@@ -135,6 +146,12 @@ export function emitContextAndBlock(
   reason: string,
 ): void {
   const eventName = _lastHookEvent ?? undefined;
+  if (eventName && eventName !== "PreToolUse") {
+    logWarn(_cachedHookName ?? "unknown",
+      `emitContextAndBlock() called from ${eventName} — permissionDecision only works for PreToolUse. ` +
+      `Use emitBlock() or the event-specific function instead.`);
+  }
+  const tool = _lastToolName;
   const out: HookOutput = {
     hookSpecificOutput: {
       ...(eventName ? { hookEventName: eventName } : {}),
@@ -144,19 +161,151 @@ export function emitContextAndBlock(
     },
   };
   const json = JSON.stringify(out);
-  _logEmit("block", additionalContext.length, { additionalContext, blockReason: reason });
+  const eventDesc = tool ? `${eventName}:${tool}` : eventName ?? "unknown";
+  _logEmit("block", additionalContext.length, { event: eventDesc, additionalContext, blockReason: reason });
   process.stdout.write(json + "\n");
 }
 
-/** Log hook output (context or block) to hook-log.jsonl for visibility. */
-function _logEmit(type: "block" | "context", chars: number, payload: Record<string, any>): void {
+/** Log hook output (context, systemMessage, or block) to hook-log.jsonl for visibility. */
+function _logEmit(type: "context" | "systemMessage" | "block", chars: number, payload: Record<string, any>): void {
   const hook = _cachedHookName ?? "unknown";
+  const event = payload.event ?? "unknown";
+  const mechanism = payload.mechanism ? ` via ${payload.mechanism}` : "";
   const msg = type === "block"
-    ? `HOOK_OUTPUT [${type}] ${chars} chars, reason="${(payload.blockReason ?? "").slice(0, 80)}"`
-    : `HOOK_OUTPUT [${type}] ${chars} chars`;
+    ? `HOOK_OUTPUT [${type}] ${event} ${chars} chars${mechanism}, reason="${(payload.blockReason ?? "").slice(0, 80)}"`
+    : `HOOK_OUTPUT [${type}] ${event} ${chars} chars`;
   hookLog("info", hook, msg, { data: payload });
 }
 
+/**
+ * Block a user prompt submission with a reason.
+ * Only works for UserPromptSubmit hooks.
+ * Output: top-level { decision: "block", reason } + optional hookSpecificOutput.additionalContext
+ */
+export function emitBlockPrompt(reason: string, context?: string): void {
+  const eventName = _lastHookEvent ?? undefined;
+  if (eventName && eventName !== "UserPromptSubmit") {
+    logWarn(_cachedHookName ?? "unknown",
+      `emitBlockPrompt() called from ${eventName} — only works for UserPromptSubmit`);
+  }
+  const out: HookOutput = {
+    decision: "block",
+    reason,
+    ...(context ? {
+      hookSpecificOutput: {
+        ...(eventName ? { hookEventName: eventName } : {}),
+        additionalContext: context,
+      }
+    } : {}),
+  };
+  _logEmit("block", context?.length ?? 0, { event: eventName ?? "unknown", additionalContext: context, blockReason: reason });
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+/**
+ * Block via exit code 2 + stderr feedback.
+ * Works for PostToolUse, PostToolUseFailure.
+ * The reason becomes the stderr message (fed to Claude as system-reminder).
+ * If context is provided, it's prepended to the stderr message for richer feedback.
+ * NOTE: Exit 2 causes Claude Code to ignore all JSON stdout — only stderr matters.
+ */
+export function emitBlockViaExit(reason: string, context?: string): void {
+  const stderrMessage = context ? `${context}\n\n${reason}` : reason;
+  _logEmit("block", stderrMessage.length, {
+    event: _lastHookEvent ?? "unknown",
+    blockReason: reason,
+    mechanism: "exit2",
+  });
+  process.stderr.write(stderrMessage + "\n");
+  throw new Error("SystemExit:2");
+}
+
+/**
+ * Block via top-level { decision: "block", reason }.
+ * Works for Stop and SubagentStop events.
+ * These events do NOT support additionalContext — only reason is available.
+ */
+export function emitBlockTopLevel(reason: string): void {
+  const eventName = _lastHookEvent ?? undefined;
+  if (eventName && eventName !== "Stop" && eventName !== "SubagentStop") {
+    logWarn(_cachedHookName ?? "unknown",
+      `emitBlockTopLevel() called from ${eventName} — only works for Stop/SubagentStop`);
+  }
+  const out = { decision: "block", reason };
+  _logEmit("block", reason.length, {
+    event: eventName ?? "unknown",
+    blockReason: reason,
+    mechanism: "topLevelDecision",
+  });
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+/**
+ * Respond to a PermissionRequest with allow/deny.
+ * Only works for PermissionRequest hooks.
+ */
+export function emitPermissionDecision(
+  behavior: "allow" | "deny",
+  opts?: { message?: string; updatedInput?: Record<string, unknown>; updatedPermissions?: Record<string, unknown> },
+): void {
+  const out: PermissionRequestOutput = {
+    decision: {
+      behavior,
+      ...(opts?.message ? { message: opts.message } : {}),
+      ...(opts?.updatedInput ? { updatedInput: opts.updatedInput } : {}),
+      ...(opts?.updatedPermissions ? { updatedPermissions: opts.updatedPermissions } : {}),
+    },
+  };
+  _logEmit("block", 0, {
+    event: _lastHookEvent ?? "unknown",
+    blockReason: `permission:${behavior}`,
+    mechanism: "permissionRequest",
+  });
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+/**
+ * Unified block dispatcher — auto-detects the correct blocking mechanism
+ * based on the current hook event type.
+ *
+ * PreToolUse → permissionDecision: "deny" (via emitContextAndBlock)
+ * UserPromptSubmit → top-level decision: "block" (via emitBlockPrompt)
+ * PostToolUse/PostToolUseFailure → exit(2) + stderr (via emitBlockViaExit)
+ * Stop/SubagentStop → top-level { decision: "block", reason } (via emitBlockTopLevel)
+ * PermissionRequest → decision: { behavior: "deny" } (via emitPermissionDecision)
+ * SessionStart/Notification/SubagentStart/SessionEnd/etc. → warn and no-op
+ *
+ * This is the RECOMMENDED universal blocking API. Hook authors should use
+ * emitBlock() and let the library handle event-specific dispatch.
+ */
+export function emitBlock(reason: string, context?: string): void {
+  const event = _lastHookEvent;
+  switch (event) {
+    case "PermissionRequest":
+      emitPermissionDecision("deny", { message: reason });
+      break;
+    case "PostToolUse":
+    case "PostToolUseFailure":
+      emitBlockViaExit(reason, context);
+      break;
+    case "PreToolUse":
+      emitContextAndBlock(context ?? reason, reason);
+      break;
+    case "Stop":
+    case "SubagentStop":
+      emitBlockTopLevel(reason);
+      break;
+    case "UserPromptSubmit":
+      emitBlockPrompt(reason, context);
+      break;
+    default: {
+      logWarn(_cachedHookName ?? "unknown",
+        `emitBlock() called from ${event ?? "unknown"} — no blocking mechanism exists for this event type, ignoring`);
+      break;
+    }
+  }
+}
+
 /**
  * Auto-detect template origin from the hook script path.
  */
@@ -165,7 +314,6 @@ function detectTemplate(scriptPath = ""): string {
   if (p.includes("/_shared/hooks/") || p.startsWith("_shared/hooks/")) {
     return "shared";
   }
-
   const match = p.match(/_([a-z][a-z0-9-]*)\/hooks\//);
   if (match?.[1]) return match[1]; // e.g., "cc-native"
   return "unknown";
@@ -178,7 +326,7 @@ function detectTemplate(scriptPath = ""): string {
  */
 export function parseContextWindow(
   hookInput: HookInput,
-): [null | number, null | number] {
+): [number | null, number | null] {
   const contextWindow = hookInput.context_window;
   if (!contextWindow) return [null, null];
 
@@ -204,7 +352,7 @@ export function parseContextWindow(
  */
 export function getContextPercentRemaining(
   hookInput: HookInput,
-): [null | number, null | number, null | number] {
+): [number | null, number | null, number | null] {
   const [tokensUsed, maxTokens] = parseContextWindow(hookInput);
 
   if (tokensUsed !== null && maxTokens !== null && maxTokens > 0) {
@@ -249,13 +397,12 @@ function _earlyReadInput(prefetchedInput?: Record<string, any>): void {
     if (_prefetchedInput.session_id) {
       setSessionId(_prefetchedInput.session_id);
     }
-
     return;
   }
 
   // Read stdin now so HOOK_START can include sid
   try {
-    const inputData = fs.readFileSync(0, "utf8").trim();
+    const inputData = fs.readFileSync(0, "utf-8").trim();
     if (inputData) {
       const parsed = JSON.parse(inputData);
       if (parsed && typeof parsed === "object") {
@@ -304,7 +451,7 @@ export function runHook(
   try {
     const result = mainFunc();
     exitCode = typeof result === "number" ? result : 0;
-    status = exitCode === 0 ? "success" : "blocked";
+    status = exitCode !== 0 ? "blocked" : "success";
   } catch (error: any) {
     if (error instanceof Error && error.message.startsWith("SystemExit:")) {
       const code = parseInt(error.message.slice(11), 10);
@@ -351,7 +498,7 @@ export function runHookAsync(
   mainFunc()
     .then((result) => {
       const exitCode = typeof result === "number" ? result : 0;
-      _emitHookEnd(hookName, startTime, exitCode, exitCode === 0 ? "success" : "blocked", null, startData, event, tool, template);
+      _emitHookEnd(hookName, startTime, exitCode, exitCode !== 0 ? "blocked" : "success", null, startData, event, tool, template);
       _drainAndExit(exitCode);
     })
     .catch((error: any) => {
@@ -383,7 +530,7 @@ function _emitHookEnd(
   errorInfo: [Error, string] | null,
   startData: Record<string, any>,
   event: string,
-  tool: null | string,
+  tool: string | null,
   template: string,
 ): void {
   // Retroactive HOOK_START to per-context log (context_path resolved after main runs)
@@ -435,5 +582,5 @@ function _drainAndExit(code: number): void {
     process.exit(code);
   });
 }
-
-export {hookLog, logBlocking, logDebug, logDiagnostic, logError, logHookError, logInfo, logWarn, setContextPath, setSessionId} from "./logger.js";
+
+export {logInfo, logError, logBlocking, logHookError, logDiagnostic, setContextPath, hookLog, logDebug, logWarn} from "./logger.js";

package/dist/templates/_shared/lib-ts/base/logger.ts

@@ -235,7 +235,7 @@ export function logHookError(
   tracebackStr = "",
 ): void {
   const errStr = typeof error === "string" ? error : String(error);
-  const msg = errStr.replace(/[\n\r]/g, " ").slice(0, 200);
+  const msg = errStr.replaceAll(/[\n\r]/g, " ").slice(0, 200);
   const errType =
     typeof error === "object" && error !== null
       ? error.constructor.name

package/dist/templates/_shared/lib-ts/base/state-io.ts

@@ -5,7 +5,7 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
+import * as path from "node:path";
 
 import { atomicWrite } from "./atomic-write.js";
 import { getContextDir } from "./constants.js";
@@ -30,7 +30,7 @@ export function toDict(state: ContextState): Record<string, unknown> {
     if (value !== null && value !== undefined) {
       result[key] = value;
     }
-  }
+  }
 
   return result;
 }
@@ -112,5 +112,14 @@ export function dictToState(data: Record<string, any>): ContextState {
   if ("handoff_path" in data) state.handoff_path = data.handoff_path;
   if ("last_session" in data) state.last_session = data.last_session;
 
+  // Preserve method-specific extension data (e.g., cc_native) that isn't
+  // part of the core ContextState interface. Without this, round-trip
+  // read→write cycles silently drop extension fields.
+  for (const key of Object.keys(data)) {
+    if (!(key in state)) {
+      state[key] = data[key];
+    }
+  }
+
   return state as ContextState;
 }