@cnwenf/occ 2.1.314 → 2.1.315

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-globalThis.MACRO={"VERSION":"2.1.314","BINARY_NAME":"occ","BUILD_TIME":"2026-08-28T00:45:59.205Z","FEEDBACK_CHANNEL":"","ISSUES_EXPLAINER":"","NATIVE_PACKAGE_URL":"","PACKAGE_URL":"@cnwenf/occ","VERSION_CHANGELOG":""};
+globalThis.MACRO={"VERSION":"2.1.315","BINARY_NAME":"occ","BUILD_TIME":"2026-08-28T20:42:08.546Z","FEEDBACK_CHANNEL":"","ISSUES_EXPLAINER":"","NATIVE_PACKAGE_URL":"","PACKAGE_URL":"@cnwenf/occ","VERSION_CHANGELOG":""};
 // @bun
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
@@ -231222,6 +231222,7 @@ async function loadAgentFromFile(filePath, pluginName, namespace, sourceName, pl
     }
     const isolationRaw = frontmatter.isolation;
     const isolation = isolationRaw === "worktree" ? "worktree" : undefined;
+    const cacheTtl = extractAgentCacheTtl(frontmatter);
     const effortRaw = frontmatter.effort;
     const effort = effortRaw !== undefined ? parseEffortValue(effortRaw) : undefined;
     if (effortRaw !== undefined && effort === undefined) {
@@ -231274,7 +231275,8 @@ async function loadAgentFromFile(filePath, pluginName, namespace, sourceName, pl
       ...memory ? { memory } : {},
       ...isolation ? { isolation } : {},
       ...effort !== undefined ? { effort } : {},
-      ...maxTurns !== undefined ? { maxTurns } : {}
+      ...maxTurns !== undefined ? { maxTurns } : {},
+      ...cacheTtl !== undefined ? { cacheTtl } : {}
     };
   } catch (error52) {
     logForDebugging(`Failed to load agent from ${filePath}: ${error52}`, {
@@ -231291,6 +231293,7 @@ var init_loadPluginAgents = __esm(() => {
   init_memoize();
   init_paths();
   init_agentMemory();
+  init_loadAgentsDir();
   init_prompt3();
   init_prompt4();
   init_debug();
@@ -232235,6 +232238,7 @@ __export(exports_loadAgentsDir, {
   getAgentDefinitionsWithOverrides: () => getAgentDefinitionsWithOverrides,
   getActiveAgentsFromList: () => getActiveAgentsFromList,
   filterAgentsByMcpRequirements: () => filterAgentsByMcpRequirements,
+  extractAgentCacheTtl: () => extractAgentCacheTtl,
   clearAgentDefinitionsCache: () => clearAgentDefinitionsCache
 });
 import { basename as basename12, dirname as dirname26, resolve as resolve23, join as join51 } from "path";
@@ -232438,6 +232442,14 @@ function parseAgentsFromJson(agentsJson, source = "flagSettings") {
     return [];
   }
 }
+function extractAgentCacheTtl(frontmatter) {
+  const experimental = frontmatter.experimental;
+  if (typeof experimental !== "object" || experimental === null) {
+    return;
+  }
+  const raw = Object.entries(experimental).find(([key2]) => key2.toLowerCase() === "cachettl")?.[1];
+  return raw === "5m" || raw === "1h" ? raw : undefined;
+}
 function parseAgentFromMarkdown(filePath, baseDir, frontmatter, content, source) {
   try {
     const agentType = frontmatter["name"];
@@ -232487,6 +232499,7 @@ function parseAgentFromMarkdown(filePath, baseDir, frontmatter, content, source)
         logForDebugging(`Agent file ${filePath} has invalid isolation value '${isolationRaw}'. Valid options: ${VALID_ISOLATION_MODES.join(", ")}`);
       }
     }
+    const cacheTtl = extractAgentCacheTtl(frontmatter);
     const effortRaw = frontmatter["effort"];
     const parsedEffort = effortRaw !== undefined ? parseEffortValue(effortRaw) : undefined;
     if (effortRaw !== undefined && parsedEffort === undefined) {
@@ -232564,7 +232577,8 @@ function parseAgentFromMarkdown(filePath, baseDir, frontmatter, content, source)
       ...maxTurns !== undefined ? { maxTurns } : {},
       ...background ? { background } : {},
       ...memory ? { memory } : {},
-      ...isolation ? { isolation } : {}
+      ...isolation ? { isolation } : {},
+      ...cacheTtl !== undefined ? { cacheTtl } : {}
     };
     return agentDef;
   } catch (error52) {
@@ -472395,7 +472409,8 @@ async function* runAgent({
       userContext: resolvedUserContext,
       systemContext: resolvedSystemContext,
       toolUseContext: agentToolUseContext,
-      forkContextMessages: initialMessages
+      forkContextMessages: initialMessages,
+      ...agentDefinition.cacheTtl !== undefined ? { agentCacheTtlOverride: agentDefinition.cacheTtl } : {}
     });
   }
   recordSidechainTranscript(initialMessages, agentId).catch((_err) => logForDebugging(`Failed to record sidechain transcript: ${_err}`));
@@ -472422,7 +472437,8 @@ async function* runAgent({
       canUseTool,
       toolUseContext: agentToolUseContext,
       querySource,
-      maxTurns: maxTurns ?? agentDefinition.maxTurns
+      maxTurns: maxTurns ?? agentDefinition.maxTurns,
+      agentCacheTtlOverride: agentDefinition.cacheTtl
     })) {
       onQueryProgress?.();
       if (message.type === "stream_event" && message.event.type === "message_start" && message.ttftMs != null) {
@@ -597567,7 +597583,8 @@ async function* queryLoop(params, consumedCommandUuids) {
     fallbackModel,
     querySource,
     maxTurns,
-    skipCacheWrite
+    skipCacheWrite,
+    agentCacheTtlOverride
   } = params;
   const deps = params.deps ?? productionDeps();
   let state3 = {
@@ -597780,6 +597797,7 @@ async function* queryLoop(params, consumedCommandUuids) {
               effortValue: appState.effortValue,
               advisorModel: appState.advisorModel,
               skipCacheWrite,
+              agentCacheTtlOverride,
               agentId: toolUseContext.agentId,
               addNotification: toolUseContext.addNotification,
               ...params.taskBudget && {
@@ -599250,7 +599268,8 @@ async function runForkedAgent({
     userContext,
     systemContext,
     toolUseContext,
-    forkContextMessages
+    forkContextMessages,
+    agentCacheTtlOverride
   } = cacheSafeParams;
   const isolatedToolUseContext = createSubagentContext(toolUseContext, overrides);
   const initialMessages = [...forkContextMessages, ...promptMessages];
@@ -599271,7 +599290,8 @@ async function runForkedAgent({
       querySource,
       maxOutputTokensOverride: maxOutputTokens,
       maxTurns,
-      skipCacheWrite
+      skipCacheWrite,
+      agentCacheTtlOverride
     })) {
       if (message.type === "stream_event") {
         if ("event" in message && message.event?.type === "message_delta" && message.event.usage) {
@@ -631305,11 +631325,12 @@ function getPromptCachingEnabled(model) {
 }
 function getCacheControl({
   scope,
-  querySource
+  querySource,
+  agentCacheTtlOverride
 } = {}) {
   return {
     type: "ephemeral",
-    ...should1hCacheTTL(querySource) && { ttl: "1h" },
+    ...should1hCacheTTL(querySource, agentCacheTtlOverride) && { ttl: "1h" },
     ...scope === "global" && { scope }
   };
 }
@@ -631322,7 +631343,7 @@ function isMainThreadQuerySource(querySource) {
 function parsePromptCacheTtlEnv(value) {
   return value === "5m" || value === "1h" ? value : undefined;
 }
-function resolvePromptCacheTtlOverride(querySource) {
+function resolvePromptCacheTtlOverride(querySource, agentCacheTtlOverride, isUsingOverage = false) {
   if (isEnvTruthy(process.env.FORCE_PROMPT_CACHING_5M)) {
     return { ttl: "5m", reason: "force_5m_env" };
   }
@@ -631334,16 +631355,21 @@ function resolvePromptCacheTtlOverride(querySource) {
   const settingTtl = isMainThread ? settings.promptCacheTtl : settings.subagentPromptCacheTtl;
   if (settingTtl !== undefined)
     return { ttl: settingTtl, reason: "setting" };
+  if (agentCacheTtlOverride !== undefined && !(agentCacheTtlOverride === "1h" && isUsingOverage)) {
+    return { ttl: agentCacheTtlOverride, reason: "agent_frontmatter" };
+  }
   if (isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H) || getAPIProvider() === "bedrock" && isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)) {
     return { ttl: "1h", reason: "enable_1h_env" };
   }
   return;
 }
-function resolvePromptCacheTtl(querySource) {
-  const override = resolvePromptCacheTtlOverride(querySource);
+function resolvePromptCacheTtl(querySource, options) {
+  const isSubscriber2 = isClaudeAISubscriber();
+  const isOverage = isSubscriber2 && options?.ignoreOverage !== true && currentLimits.isUsingOverage === true;
+  const override = resolvePromptCacheTtlOverride(querySource, options?.agentCacheTtlOverride, isOverage);
   if (override !== undefined)
     return override;
-  if (!isClaudeAISubscriber() || currentLimits.isUsingOverage) {
+  if (!isSubscriber2 || isOverage) {
     return { ttl: "5m", reason: "default" };
   }
   let allowlist = getPromptCache1hAllowlist();
@@ -631356,8 +631382,8 @@ function resolvePromptCacheTtl(querySource) {
   }
   return querySourceMatchesPatterns(querySource, allowlist) ? { ttl: "1h", reason: "subscriber" } : { ttl: "5m", reason: "default" };
 }
-function should1hCacheTTL(querySource) {
-  return resolvePromptCacheTtl(querySource).ttl === "1h";
+function should1hCacheTTL(querySource, agentCacheTtlOverride) {
+  return resolvePromptCacheTtl(querySource, { agentCacheTtlOverride }).ttl === "1h";
 }
 function configureEffortParams(effortValue, outputConfig, extraBodyParams, betas, model) {
   if (!modelSupportsEffort(model) || "effort" in outputConfig) {
@@ -631448,7 +631474,7 @@ async function verifyApiKey(apiKey, isNonInteractiveSession) {
     throw error52;
   }
 }
-function userMessageToMessageParam(message, addCache = false, enablePromptCaching, querySource) {
+function userMessageToMessageParam(message, addCache = false, enablePromptCaching, querySource, agentCacheTtlOverride) {
   if (addCache) {
     if (typeof message.message.content === "string") {
       return {
@@ -631458,7 +631484,10 @@ function userMessageToMessageParam(message, addCache = false, enablePromptCachin
             type: "text",
             text: message.message.content,
             ...enablePromptCaching && {
-              cache_control: getCacheControl({ querySource })
+              cache_control: getCacheControl({
+                querySource,
+                agentCacheTtlOverride
+              })
             }
           }
         ]
@@ -631468,7 +631497,12 @@ function userMessageToMessageParam(message, addCache = false, enablePromptCachin
         role: "user",
         content: message.message.content.map((_4, i6) => ({
           ..._4,
-          ...i6 === message.message.content.length - 1 ? enablePromptCaching ? { cache_control: getCacheControl({ querySource }) } : {} : {}
+          ...i6 === message.message.content.length - 1 ? enablePromptCaching ? {
+            cache_control: getCacheControl({
+              querySource,
+              agentCacheTtlOverride
+            })
+          } : {} : {}
         }))
       };
     }
@@ -631478,7 +631512,7 @@ function userMessageToMessageParam(message, addCache = false, enablePromptCachin
     content: Array.isArray(message.message.content) ? [...message.message.content] : message.message.content
   };
 }
-function assistantMessageToMessageParam(message, addCache = false, enablePromptCaching, querySource) {
+function assistantMessageToMessageParam(message, addCache = false, enablePromptCaching, querySource, agentCacheTtlOverride) {
   if (addCache) {
     if (typeof message.message.content === "string") {
       return {
@@ -631488,7 +631522,10 @@ function assistantMessageToMessageParam(message, addCache = false, enablePromptC
             type: "text",
             text: message.message.content,
             ...enablePromptCaching && {
-              cache_control: getCacheControl({ querySource })
+              cache_control: getCacheControl({
+                querySource,
+                agentCacheTtlOverride
+              })
             }
           }
         ]
@@ -631498,7 +631535,12 @@ function assistantMessageToMessageParam(message, addCache = false, enablePromptC
         role: "assistant",
         content: message.message.content.map((_4, i6) => ({
           ..._4,
-          ...i6 === message.message.content.length - 1 && _4.type !== "thinking" && _4.type !== "redacted_thinking" && (feature("CONNECTOR_TEXT") ? !isConnectorTextBlock(_4) : true) ? enablePromptCaching ? { cache_control: getCacheControl({ querySource }) } : {} : {}
+          ...i6 === message.message.content.length - 1 && _4.type !== "thinking" && _4.type !== "redacted_thinking" && (feature("CONNECTOR_TEXT") ? !isConnectorTextBlock(_4) : true) ? enablePromptCaching ? {
+            cache_control: getCacheControl({
+              querySource,
+              agentCacheTtlOverride
+            })
+          } : {} : {}
         }))
       };
     }
@@ -631720,7 +631762,7 @@ async function* queryModel(messages, systemPrompt, thinkingConfig, tools, signal
   queryCheckpoint("query_tool_schema_build_start");
   const isAgenticQuery = options.querySource.startsWith("repl_main_thread") || options.querySource.startsWith("agent:") || options.querySource === "sdk" || options.querySource === "hook_agent" || options.querySource === "verification_agent";
   const betas = getMergedBetas(options.model, { isAgenticQuery });
-  if (should1hCacheTTL(options.querySource) && shouldSendExtendedCacheTtlBeta() && !betas.includes(EXTENDED_CACHE_TTL_BETA_HEADER)) {
+  if (should1hCacheTTL(options.querySource, options.agentCacheTtlOverride) && shouldSendExtendedCacheTtlBeta() && !betas.includes(EXTENDED_CACHE_TTL_BETA_HEADER)) {
     betas.push(EXTENDED_CACHE_TTL_BETA_HEADER);
   }
   if (isAdvisorEnabled()) {
@@ -631872,7 +631914,8 @@ ${deferredToolList}
   const enablePromptCaching = options.enablePromptCaching ?? getPromptCachingEnabled(options.model);
   const system = buildSystemPromptBlocks(systemPrompt, enablePromptCaching, {
     skipGlobalCacheForSystemPrompt: needsToolBasedCacheMarker,
-    querySource: options.querySource
+    querySource: options.querySource,
+    agentCacheTtlOverride: options.agentCacheTtlOverride
   });
   const useBetas = betas.length > 0;
   const extraToolSchemas = [...options.extraToolSchemas ?? []];
@@ -632027,7 +632070,7 @@ ${deferredToolList}
     lastRequestBetas = betasParams;
     return {
       model: normalizeModelStringForAPI(options.model),
-      messages: addCacheBreakpoints(messagesForAPI, enablePromptCaching2, options.querySource, useCachedMC, consumedCacheEdits, consumedPinnedEdits, options.skipCacheWrite),
+      messages: addCacheBreakpoints(messagesForAPI, enablePromptCaching2, options.querySource, useCachedMC, consumedCacheEdits, consumedPinnedEdits, options.skipCacheWrite, options.agentCacheTtlOverride),
       system,
       tools: allTools,
       tool_choice: options.toolChoice,
@@ -632881,7 +632924,7 @@ function accumulateUsage(totalUsage, messageUsage) {
 function isToolResultBlock2(block) {
   return block !== null && typeof block === "object" && "type" in block && block.type === "tool_result" && "tool_use_id" in block;
 }
-function addCacheBreakpoints(messages, enablePromptCaching, querySource, useCachedMC = false, newCacheEdits, pinnedEdits, skipCacheWrite = false) {
+function addCacheBreakpoints(messages, enablePromptCaching, querySource, useCachedMC = false, newCacheEdits, pinnedEdits, skipCacheWrite = false, agentCacheTtlOverride) {
   logEvent2("tengu_api_cache_breakpoints", {
     totalMessageCount: messages.length,
     cachingEnabled: enablePromptCaching,
@@ -632891,9 +632934,9 @@ function addCacheBreakpoints(messages, enablePromptCaching, querySource, useCach
   const result = messages.map((msg, index2) => {
     const addCache = index2 === markerIndex;
     if (msg.type === "user") {
-      return userMessageToMessageParam(msg, addCache, enablePromptCaching, querySource);
+      return userMessageToMessageParam(msg, addCache, enablePromptCaching, querySource, agentCacheTtlOverride);
     }
-    return assistantMessageToMessageParam(msg, addCache, enablePromptCaching, querySource);
+    return assistantMessageToMessageParam(msg, addCache, enablePromptCaching, querySource, agentCacheTtlOverride);
   });
   if (!useCachedMC) {
     return result;
@@ -632984,7 +633027,8 @@ function buildSystemPromptBlocks(systemPrompt, enablePromptCaching, options) {
       ...enablePromptCaching && block.cacheScope !== null && {
         cache_control: getCacheControl({
           scope: block.cacheScope,
-          querySource: options?.querySource
+          querySource: options?.querySource,
+          agentCacheTtlOverride: options?.agentCacheTtlOverride
         })
       }
     };
@@ -727155,21 +727199,6 @@ var init_execPromptHook = __esm(() => {
   init_hookHelpers();
 });
 
-// src/utils/hooks/hookExit2Block.ts
-function exit2BlockReason(params) {
-  const { status: status2, validationError, hasJson, stderr, command: command11 } = params;
-  if (status2 !== 2) {
-    return null;
-  }
-  if (hasJson && !validationError) {
-    return null;
-  }
-  return {
-    blockingError: `[${command11}]: ${stderr || "No stderr output"}`,
-    command: command11
-  };
-}
-
 // src/utils/hooks/execAgentHook.ts
 import { randomUUID as randomUUID40 } from "crypto";
 async function execAgentHook(hook, hookName, hookEvent, jsonInput, signal, toolUseContext, toolUseID, _messages, agentName) {
@@ -727774,10 +727803,16 @@ var init_execMcpToolHook = __esm(() => {
 // src/utils/hooks.ts
 var exports_hooks2 = {};
 __export(exports_hooks2, {
+  wrapHookErrorWithStderr: () => wrapHookErrorWithStderr,
   skipFrontmatterHooksForUntrustedOrigin: () => skipFrontmatterHooksForUntrustedOrigin,
   shouldSkipHookDueToTrust: () => shouldSkipHookDueToTrust,
   processHookJSONOutput: () => processHookJSONOutput,
+  parseHookOutput: () => parseHookOutput,
+  looksLikeMissingHookScript: () => looksLikeMissingHookScript,
   isPerHookCallbackTimeout: () => isPerHookCallbackTimeout,
+  isMultipleJsonDocuments: () => isMultipleJsonDocuments,
+  isAsyncHookAnnouncement: () => isAsyncHookAnnouncement,
+  hookOutputSchemaHint: () => hookOutputSchemaHint,
   hookCallbackTimeoutMessage: () => hookCallbackTimeoutMessage,
   hasWorktreeCreateHook: () => hasWorktreeCreateHook,
   hasInstructionsLoadedHook: () => hasInstructionsLoadedHook,
@@ -727790,6 +727825,7 @@ __export(exports_hooks2, {
   getSessionEndHookTimeoutMs: () => getSessionEndHookTimeoutMs,
   getPreToolHookBlockingMessage: () => getPreToolHookBlockingMessage,
   getMatchingHooks: () => getMatchingHooks,
+  formatHookJsonValidationError: () => formatHookJsonValidationError,
   executeWorktreeRemoveHook: () => executeWorktreeRemoveHook,
   executeWorktreeCreateHook: () => executeWorktreeCreateHook,
   executeUserPromptSubmitHooks: () => executeUserPromptSubmitHooks,
@@ -727993,6 +728029,109 @@ function getSessionCronsForHookInput() {
     prompt: capHookString(task.prompt ?? "", HOOK_STRING_CAP)
   }));
 }
+function isHookJsonPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHookJsonDiscriminatorIssue(issue2) {
+  const last3 = issue2.path.at(-1);
+  return issue2.code === "invalid_value" && typeof last3 === "string" && HOOK_JSON_DISCRIMINATOR_KEYS.has(last3);
+}
+function formatHookJsonIssue(issue2, parentPath) {
+  const path39 = [...parentPath, ...issue2.path];
+  if (issue2.code !== "invalid_union" || (issue2.errors?.length ?? 0) === 0) {
+    return { path: path39, message: issue2.message.replace(/^Invalid input: /, "") };
+  }
+  const errors8 = issue2.errors;
+  const relevant = errors8.find((branch2) => branch2.length > 0 && !branch2.some(isHookJsonDiscriminatorIssue))?.[0];
+  if (relevant) {
+    return formatHookJsonIssue(relevant, path39);
+  }
+  const discriminatorIssues = errors8.flat().filter(isHookJsonDiscriminatorIssue);
+  const first2 = discriminatorIssues[0];
+  if (first2?.code !== "invalid_value") {
+    return { path: path39, message: issue2.message };
+  }
+  const values3 = [
+    ...new Set(discriminatorIssues.flatMap((discriminator) => discriminator.code === "invalid_value" ? (discriminator.values ?? []).map((value) => jsonStringify(value)) : []))
+  ];
+  const preview = values3.slice(0, 6).join(" | ");
+  return {
+    path: [...path39, ...first2.path],
+    message: `expected one of ${preview}${values3.length > 6 ? " | \u2026" : ""}`
+  };
+}
+function formatHookJsonPath(path39) {
+  return path39.map(String).join(".") || "(root)";
+}
+function formatHookJsonValidationError(parsed, issues) {
+  const hookSpecificOutput = isHookJsonPlainObject(parsed) ? parsed.hookSpecificOutput : undefined;
+  const formatted = issues.map((issue2) => formatHookJsonIssue(issue2, []));
+  const first2 = formatted[0];
+  let primary = first2 ? `${formatHookJsonPath(first2.path)}: ${first2.message}` : "unknown error";
+  if (isHookJsonPlainObject(hookSpecificOutput) && !("hookEventName" in hookSpecificOutput)) {
+    primary = 'hookSpecificOutput is missing required field "hookEventName"';
+  } else if (isHookJsonPlainObject(hookSpecificOutput) && hookSpecificOutput.hookEventName === "PermissionRequest" && !isHookJsonPlainObject(hookSpecificOutput.decision) && first2?.path[0] === "hookSpecificOutput" && first2.path[1] === "decision") {
+    primary += ' (PermissionRequest decision must be {"behavior": "allow"} or {"behavior": "deny", "message": "..."})';
+  } else if (isHookJsonPlainObject(parsed) && first2?.path.length === 1 && first2.path[0] === "decision" && (parsed.decision === "allow" || parsed.decision === "deny" || parsed.decision === "ask")) {
+    primary += parsed.decision === "ask" ? ' (top-level decision is the legacy approve|block field; for "ask" use hookSpecificOutput.permissionDecision in a PreToolUse hook)' : ` (top-level decision is the legacy approve|block field; for "${parsed.decision}" use hookSpecificOutput.permissionDecision in a PreToolUse hook, or hookSpecificOutput.decision: {"behavior": "${parsed.decision}"} in a PermissionRequest hook)`;
+  }
+  const rest = formatted.slice(1).map((entry) => `  - ${formatHookJsonPath(entry.path)}: ${entry.message}`).join(`
+`);
+  return `${HOOK_JSON_VALIDATION_ERROR_PREFIX}${primary}${rest ? `
+${rest}` : ""}
+
+The hook's output was: ${jsonStringify(parsed, null, 2)}`;
+}
+function hookOutputSchemaHint() {
+  return jsonStringify({
+    continue: "boolean (optional)",
+    suppressOutput: "boolean (optional)",
+    stopReason: "string (optional)",
+    decision: '"approve" | "block" (optional)',
+    reason: "string (optional)",
+    systemMessage: "string (optional)",
+    terminalSequence: "string (optional)",
+    hookSpecificOutput: {
+      "for PreToolUse": {
+        hookEventName: '"PreToolUse"',
+        permissionDecision: '"allow" | "deny" | "ask" | "defer" (optional)',
+        permissionDecisionReason: "string (optional)",
+        updatedInput: "object (optional) - Modified tool input to use"
+      },
+      "for PermissionRequest": {
+        hookEventName: '"PermissionRequest"',
+        decision: {
+          "to allow": {
+            behavior: '"allow"',
+            updatedInput: "object (optional) - Modified tool input to use",
+            updatedPermissions: "array (optional) - Permission updates"
+          },
+          "to deny": {
+            behavior: '"deny"',
+            message: "string (optional)",
+            interrupt: "boolean (optional)"
+          }
+        }
+      },
+      "for UserPromptSubmit": {
+        hookEventName: '"UserPromptSubmit"',
+        additionalContext: "string (optional)"
+      },
+      "for PostToolUse": {
+        hookEventName: '"PostToolUse"',
+        additionalContext: "string (optional)"
+      },
+      "for PostToolBatch": {
+        hookEventName: '"PostToolBatch"',
+        additionalContext: "string (optional)"
+      },
+      "for Stop / SubagentStop": {
+        hookEventName: '"Stop" | "SubagentStop"',
+        additionalContext: "string (optional) - Feedback for the model; the conversation continues so the model can act on it"
+      }
+    }
+  }, null, 2);
+}
 function validateHookJson(jsonString) {
   const parsed = jsonParse(jsonString);
   const validation2 = hookJSONOutputSchema().safeParse(parsed);
@@ -728000,21 +728139,57 @@ function validateHookJson(jsonString) {
     logForDebugging("Successfully parsed and validated hook JSON output");
     return { json: validation2.data };
   }
-  const errors8 = validation2.error.issues.map((err2) => `  - ${err2.path.join(".")}: ${err2.message}`).join(`
-`);
   return {
-    validationError: `Hook JSON output validation failed:
-${errors8}
-
-The hook's output was: ${jsonStringify(parsed, null, 2)}`
+    validationError: formatHookJsonValidationError(parsed, validation2.error.issues)
   };
 }
+function isAsyncHookAnnouncement(stdout) {
+  const firstLine = firstLineOf(stdout).trim();
+  if (!firstLine.startsWith("{")) {
+    return false;
+  }
+  try {
+    const parsed = jsonParse(firstLine);
+    return typeof parsed === "object" && parsed !== null && "async" in parsed && parsed.async === true;
+  } catch {
+    return false;
+  }
+}
+function isMultipleJsonDocuments(output2) {
+  const lines2 = output2.split(`
+`).filter((line) => line.trim() !== "");
+  if (lines2.length < 2) {
+    return false;
+  }
+  return lines2.every((line) => {
+    try {
+      const validation2 = hookJSONOutputSchema().safeParse(jsonParse(line.trim()));
+      return !validation2.success || Object.keys(validation2.data).length === 0;
+    } catch {
+      return false;
+    }
+  });
+}
+function wrapHookErrorWithStderr(validationError, exitCode, stderr) {
+  const trimmedStderr = stderr.trim();
+  return exitCode !== 0 && trimmedStderr ? `${validationError}
+
+Hook exited ${exitCode} with stderr:
+${trimmedStderr}` : validationError;
+}
+function looksLikeMissingHookScript(params) {
+  const { hookEvent, stdout, stderr, pluginId } = params;
+  return (MISSING_SCRIPT_HOOK_EVENTS.has(hookEvent) || Boolean(pluginId) && hookEvent === "UserPromptSubmit") && !stdout.trim() && /no such file|can't open/i.test(stderr);
+}
 function parseHookOutput(stdout) {
   const trimmed = stdout.trim();
   if (!trimmed.startsWith("{")) {
     logForDebugging("Hook output does not start with {, treating as plain text");
     return { plainText: stdout };
   }
+  if (isAsyncHookAnnouncement(stdout)) {
+    return { json: { async: true } };
+  }
   try {
     const result = validateHookJson(trimmed);
     if ("json" in result) {
@@ -728023,37 +728198,22 @@ function parseHookOutput(stdout) {
     const errorMessage3 = `${result.validationError}
 
 Expected schema:
-${jsonStringify({
-      continue: "boolean (optional)",
-      suppressOutput: "boolean (optional)",
-      stopReason: "string (optional)",
-      decision: '"approve" | "block" (optional)',
-      reason: "string (optional)",
-      systemMessage: "string (optional)",
-      permissionDecision: '"allow" | "deny" | "ask" (optional)',
-      hookSpecificOutput: {
-        "for PreToolUse": {
-          hookEventName: '"PreToolUse"',
-          permissionDecision: '"allow" | "deny" | "ask" (optional)',
-          permissionDecisionReason: "string (optional)",
-          updatedInput: "object (optional) - Modified tool input to use"
-        },
-        "for UserPromptSubmit": {
-          hookEventName: '"UserPromptSubmit"',
-          additionalContext: "string (required)",
-          sessionTitle: "string (optional) - Set the session title (same effect as /rename)"
-        },
-        "for PostToolUse": {
-          hookEventName: '"PostToolUse"',
-          additionalContext: "string (optional)"
-        }
-      }
-    }, null, 2)}`;
+${hookOutputSchemaHint()}`;
     logForDebugging(errorMessage3);
     return { plainText: stdout, validationError: errorMessage3 };
   } catch (e4) {
-    logForDebugging(`Failed to parse hook output as JSON: ${e4}`);
-    return { plainText: stdout };
+    const parseError = e4 instanceof Error ? e4.message : String(e4);
+    if (!trimmed.endsWith("}")) {
+      logForDebugging(`Hook output starts with { but is not a JSON object, treating as plain text: ${parseError}`);
+      return { plainText: stdout };
+    }
+    if (isMultipleJsonDocuments(trimmed)) {
+      logForDebugging("Hook output is several JSON documents, treating as plain text");
+      return { plainText: stdout };
+    }
+    const errorMessage3 = `Hook output looks like a JSON object but is not valid JSON \u2014 ${parseError}. Emit the payload with a JSON encoder (jq, ConvertTo-Json, json.dumps) rather than string concatenation so backslashes and quotes inside strings are escaped.`;
+    logForDebugging(errorMessage3);
+    return { plainText: stdout, validationError: errorMessage3 };
   }
 }
 function parseHttpHookOutput(body) {
@@ -729212,7 +729372,7 @@ async function* executeHooks({
             hookEvent,
             output: httpResult.body,
             stdout: httpResult.body,
-            stderr: `JSON validation failed: ${httpValidationError}`,
+            stderr: httpValidationError,
             exitCode: httpResult.statusCode,
             outcome: "error"
           });
@@ -729222,7 +729382,7 @@ async function* executeHooks({
               hookName,
               toolUseID,
               hookEvent,
-              stderr: `JSON validation failed: ${httpValidationError}`,
+              stderr: httpValidationError,
               stdout: httpResult.body,
               exitCode: httpResult.statusCode ?? 0,
               command: hook.url,
@@ -729353,43 +729513,16 @@ async function* executeHooks({
         return;
       }
       const { json: json2, plainText, validationError } = parseHookOutput(result.stdout);
-      if (validationError) {
-        const exit2Block = exit2BlockReason({
-          status: result.status,
-          validationError,
-          hasJson: !!json2,
-          stderr: result.stderr,
-          command: hookCommand
-        });
-        if (exit2Block) {
-          emitHookResponse({
-            hookId,
-            hookName,
-            hookEvent,
-            output: result.output,
-            stdout: result.stdout,
-            stderr: result.stderr,
-            exitCode: result.status,
-            outcome: "error"
-          });
-          yield {
-            blockingError: {
-              blockingError: exit2Block.blockingError,
-              command: exit2Block.command
-            },
-            outcome: "blocking",
-            hook
-          };
-          return;
-        }
+      if (validationError && result.status !== 2) {
+        const stderr = wrapHookErrorWithStderr(validationError, result.status, result.stderr);
         emitHookResponse({
           hookId,
           hookName,
           hookEvent,
           output: result.output,
           stdout: result.stdout,
-          stderr: `JSON validation failed: ${validationError}`,
-          exitCode: 1,
+          stderr,
+          exitCode: result.status,
           outcome: "error"
         });
         yield {
@@ -729398,9 +729531,9 @@ async function* executeHooks({
             hookName,
             toolUseID,
             hookEvent,
-            stderr: `JSON validation failed: ${validationError}`,
+            stderr,
             stdout: result.stdout,
-            exitCode: 1,
+            exitCode: result.status,
             command: hookCommand,
             durationMs
           }),
@@ -729411,6 +729544,55 @@ async function* executeHooks({
       }
       if (json2) {
         if (isAsyncHookJSONOutput(json2)) {
+          if (result.status === 2) {
+            emitHookResponse({
+              hookId,
+              hookName,
+              hookEvent,
+              output: result.output,
+              stdout: result.stdout,
+              stderr: result.stderr,
+              exitCode: result.status,
+              outcome: "error"
+            });
+            yield {
+              blockingError: {
+                blockingError: `[${hook.command}]: ${result.stderr || "No stderr output"}`,
+                command: hook.command
+              },
+              outcome: "blocking",
+              hook
+            };
+            return;
+          }
+          if (result.status !== 0) {
+            emitHookResponse({
+              hookId,
+              hookName,
+              hookEvent,
+              output: result.output,
+              stdout: result.stdout,
+              stderr: result.stderr,
+              exitCode: result.status,
+              outcome: "error"
+            });
+            yield {
+              message: createAttachmentMessage({
+                type: "hook_non_blocking_error",
+                hookName,
+                toolUseID,
+                hookEvent,
+                stderr: `Announced async, then failed with status code ${result.status}: ${result.stderr.trim() || "No stderr output"}`,
+                stdout: result.stdout,
+                exitCode: result.status,
+                command: hookCommand,
+                durationMs
+              }),
+              outcome: "non_blocking_error",
+              hook
+            };
+            return;
+          }
           yield {
             outcome: "success",
             hook
@@ -729513,6 +729695,39 @@ async function* executeHooks({
         };
         return;
       }
+      if (result.status === 2 && looksLikeMissingHookScript({
+        hookEvent,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        pluginId
+      })) {
+        emitHookResponse({
+          hookId,
+          hookName,
+          hookEvent,
+          output: result.output,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: result.status,
+          outcome: "error"
+        });
+        yield {
+          message: createAttachmentMessage({
+            type: "hook_non_blocking_error",
+            hookName,
+            toolUseID,
+            hookEvent,
+            stderr: `Hook script appears to be missing \u2014 "${hookCommand}" exited 2 with: ${result.stderr.trim()}. Treating as non-blocking. ${pluginId ? `Run \`/plugin\` to reinstall '${pluginId}' or remove it from settings.` : "If this is a plugin hook, check the plugin install (run /plugin)."}`,
+            stdout: result.stdout,
+            exitCode: result.status,
+            command: hookCommand,
+            durationMs
+          }),
+          outcome: "non_blocking_error",
+          hook
+        };
+        return;
+      }
       if (result.status === 2) {
         emitHookResponse({
           hookId,
@@ -729960,25 +730175,8 @@ async function executeHooksOutsideREPL({
       }
       logForDebugging(`${hookName} [${hook.command}] completed with status ${result.status}`);
       const { json: json2, validationError } = parseHookOutput(result.stdout);
-      if (validationError) {
-        const exit2Block = exit2BlockReason({
-          status: result.status,
-          validationError,
-          hasJson: !!json2,
-          stderr: result.stderr,
-          command: hook.command
-        });
-        if (exit2Block) {
-          return {
-            command: hook.command,
-            succeeded: false,
-            output: result.stderr || "",
-            blocked: true,
-            watchPaths: undefined,
-            systemMessage: undefined
-          };
-        }
-        throw new Error(validationError);
+      if (validationError && result.status !== 2) {
+        throw new Error(wrapHookErrorWithStderr(validationError, result.status, result.stderr));
       }
       if (json2 && !isAsyncHookJSONOutput(json2)) {
         logForDebugging(`Parsed JSON output from hook: ${jsonStringify(json2)}`, { level: "verbose" });
@@ -731008,7 +731206,7 @@ async function* executeMessageDisplayHooks(display, getAppState, agentId, signal
     timeoutMs
   });
 }
-var TOOL_HOOK_EXECUTION_TIMEOUT_MS, PRE_TOOL_USE_HOOK_TIMEOUT_MESSAGE = "PreToolUse hook did not respond before its timeout (host client may be unreachable). The tool call was not executed; other configured hooks may not have completed.", SESSION_END_HOOK_TIMEOUT_MS_DEFAULT = 1500, BACKGROUND_TASK_TYPE_LABELS, HOOK_STRING_CAP = 1000, MATCHER_COMMA_HYPHEN_EVENTS;
+var TOOL_HOOK_EXECUTION_TIMEOUT_MS, PRE_TOOL_USE_HOOK_TIMEOUT_MESSAGE = "PreToolUse hook did not respond before its timeout (host client may be unreachable). The tool call was not executed; other configured hooks may not have completed.", SESSION_END_HOOK_TIMEOUT_MS_DEFAULT = 1500, BACKGROUND_TASK_TYPE_LABELS, HOOK_STRING_CAP = 1000, HOOK_JSON_VALIDATION_ERROR_PREFIX = "Hook JSON output validation failed \u2014 ", HOOK_JSON_DISCRIMINATOR_KEYS, MISSING_SCRIPT_HOOK_EVENTS, MATCHER_COMMA_HYPHEN_EVENTS;
 var init_hooks5 = __esm(() => {
   init_file();
   init_envValidation();
@@ -731071,6 +731269,13 @@ var init_hooks5 = __esm(() => {
     dream: "dream",
     remote_agent: "cloud session"
   };
+  HOOK_JSON_DISCRIMINATOR_KEYS = new Set(["async", "hookEventName", "behavior"]);
+  MISSING_SCRIPT_HOOK_EVENTS = new Set([
+    "Stop",
+    "SubagentStop",
+    "TaskCompleted",
+    "TeammateIdle"
+  ]);
   MATCHER_COMMA_HYPHEN_EVENTS = new Set([
     "PreToolUse",
     "PostToolUse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnwenf/occ",
-  "version": "2.1.314",
+  "version": "2.1.315",
   "license": "MIT",
   "type": "module",
   "bin": {