@opencow-ai/opencow-agent-sdk 0.4.23 → 0.4.24

package/dist/capabilities/SdkTool.d.ts

@@ -11,6 +11,11 @@ export interface SdkTool {
      * behind the permissive value type.
      */
     readonly inputSchema: ToolInputSchemaShape;
+    /**
+     * Runtime policy for object keys that are absent from `inputSchema`.
+     * Defaults to `strip`; security-sensitive host tools can opt into `reject`.
+     */
+    readonly unknownKeys?: 'strip' | 'reject';
     /**
      * Business logic. Receives validated args plus a structured invocation
      * context. Must return a `CallToolResult`. Exceptions are caught by the

package/dist/capabilities/tools/AgentTool/AgentTool.d.ts

@@ -99,6 +99,7 @@ export declare const AgentTool: {
     isLsp?: boolean;
     shouldDefer?: boolean;
     alwaysLoad?: boolean;
+    unknownKeys?: "strip" | "reject";
     outputSchema?: z.ZodType<unknown>;
     call: (args: any, context: import("../../../types/toolRuntime.js").ToolRuntimeContext, canUseTool: import("../../../types/toolRuntime.js").CanUseToolFn, parentMessage: MessageType, onProgress?: import("../../../types/toolRuntime.js").ToolCallProgress<any>) => Promise<import("../../../types/toolRuntime.js").ToolResult<any>>;
     validateInput?: (input: any, context: import("../../../types/toolRuntime.js").ToolRuntimeContext) => Promise<import("../../../types/toolRuntime.js").ValidationResult>;

package/dist/capabilities/tools/AgentTool/agentMerge.d.ts

@@ -6,3 +6,4 @@ import type { AgentDefinition } from './loadAgentsDir.js';
  * host-provided `Options.agents` (`override`).
  */
 export declare function mergeAgentsByType(base: AgentDefinition[], override: AgentDefinition[]): AgentDefinition[];
+export declare function withDefaultAgentForInvocation(activeAgents: AgentDefinition[], requestedType: string | undefined, defaultAgent: AgentDefinition): AgentDefinition[];

package/dist/capabilities/tools/AgentTool/runAgent.d.ts

@@ -71,11 +71,11 @@ export declare function runAgent({ agentDefinition, promptMessages, toolUseConte
      * during long single-block streams (e.g. thinking) where no assistant
      * message is yielded for >60s. */
     onQueryProgress?: () => void;
-    /** Optional callback fired with a GROWING single-block assistant message as
-     * the sub-agent's text streams token-by-token (content_block_delta /
+    /** Optional callback fired at most once every 50ms with a GROWING single-block
+     * assistant message as the sub-agent's text streams (content_block_delta /
      * text_delta accumulated per content-block index, keyed to the message_start
      * id). The consumer (AgentTool) forwards it via the existing agent_progress
-     * onProgress channel so the host renders the sub-conversation token-by-token
+     * onProgress channel so the host renders the sub-conversation progressively
      * instead of block-at-once. Side-channel only: these partials are NOT yielded
      * and NOT recorded to the sidechain transcript — the authoritative whole
      * messages still flow through the normal yield path (graceful degradation:

package/dist/cli.mjs

@@ -94818,7 +94818,7 @@ function printStartupScreen() {
   const sLen = ` ● ${sL}    Ready — type /help to begin`.length;
   out.push(boxRow(sRow, W2, sLen));
   out.push(`${rgb(...BORDER)}╚${"═".repeat(W2 - 2)}╝${RESET}`);
-  out.push(`  ${DIM}${rgb(...DIMCOL)}opencow ${RESET}${rgb(...ACCENT)}v${"0.4.23"}${RESET}`);
+  out.push(`  ${DIM}${rgb(...DIMCOL)}opencow ${RESET}${rgb(...ACCENT)}v${"0.4.24"}${RESET}`);
   out.push("");
   process.stdout.write(out.join(`
 `) + `
@@ -146571,6 +146571,12 @@ function mergeAgentsByType(base2, override) {
     byType.set(agent.agentType, agent);
   return [...byType.values()];
 }
+function withDefaultAgentForInvocation(activeAgents, requestedType, defaultAgent) {
+  if (requestedType !== undefined || activeAgents.some((agent) => agent.agentType === defaultAgent.agentType)) {
+    return activeAgents;
+  }
+  return [...activeAgents, defaultAgent];
+}
 
 // src/capabilities/tools/AgentTool/builtInAgents.ts
 var exports_builtInAgents = {};
@@ -240340,10 +240346,23 @@ function deepOmitNullProps(value) {
   }
   return value;
 }
-function safeParseToolInputWithNullCoercion(schema, input) {
+function containsUnrecognizedKeysIssue(value) {
+  if (Array.isArray(value))
+    return value.some(containsUnrecognizedKeysIssue);
+  if (value === null || typeof value !== "object")
+    return false;
+  const issue2 = value;
+  if (issue2.code === "unrecognized_keys")
+    return true;
+  return containsUnrecognizedKeysIssue(issue2.errors);
+}
+function safeParseToolInputWithNullCoercion(schema, input, unknownKeys = "strip") {
   const first = schema.safeParse(input);
   if (first.success)
     return first;
+  if (unknownKeys === "reject" && containsUnrecognizedKeysIssue(first.error.issues)) {
+    return first;
+  }
   if (input === null || typeof input !== "object") {
     return first;
   }
@@ -240829,6 +240848,54 @@ function getRuleBehaviorDescription(permissionResult) {
   }
 }
 
+// src/controller/dispatch/permissionPreDecision.ts
+function startPermissionPreDecisions(blocks, assistantMessages, canUseTool, toolUseContext) {
+  const existing = toolUseContext.permissionPreDecisions;
+  if (existing && existing.size > 0) {
+    return;
+  }
+  const preDecisions = new Map;
+  toolUseContext.permissionPreDecisions = preDecisions;
+  for (const block2 of blocks) {
+    const tool = findToolRuntimeByName(toolUseContext.options.tools, block2.name);
+    if (!tool) {
+      continue;
+    }
+    const parsedInput = safeParseToolInputWithNullCoercion(tool.inputSchema, block2.input, tool.unknownKeys);
+    if (!parsedInput.success) {
+      continue;
+    }
+    const assistantMessage = assistantMessages.find((message) => message.message.content.some((content) => content.type === "tool_use" && content.id === block2.id));
+    if (!assistantMessage) {
+      continue;
+    }
+    let input = parsedInput.data;
+    if (tool.backfillObservableInput && typeof input === "object" && input !== null) {
+      input = { ...input };
+      tool.backfillObservableInput(input);
+    }
+    const promise3 = canUseTool(tool, input, toolUseContext, assistantMessage, block2.id);
+    promise3.catch(() => {});
+    preDecisions.set(block2.id, { input, promise: promise3 });
+  }
+}
+function consumePermissionPreDecision(toolUseContext, toolUseID, input, fallback) {
+  const cache2 = toolUseContext.permissionPreDecisions;
+  const entry = cache2?.get(toolUseID);
+  if (!cache2 || !entry) {
+    return fallback();
+  }
+  cache2.delete(toolUseID);
+  if (jsonStringify(entry.input) !== jsonStringify(input)) {
+    return fallback();
+  }
+  return entry.promise;
+}
+var init_permissionPreDecision = __esm(() => {
+  init_toolRuntime();
+  init_slowOperations();
+});
+
 // src/controller/dispatch/toolHooks.ts
 async function* runPostToolUseHooks(toolUseContext, tool, toolUseID, messageId, toolInput, toolResponse, requestId, mcpServerType, mcpServerBaseUrl) {
   const postToolStartTime = Date.now();
@@ -241016,7 +241083,7 @@ async function resolveHookPermissionDecision(hookPermissionResult, tool, input,
     if (requiresInteraction && !interactionSatisfied || requireCanUseTool) {
       logForDebugging2(`Hook approved tool use for ${tool.name}, but canUseTool is required`);
       return {
-        decision: await canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID),
+        decision: await consumePermissionPreDecision(toolUseContext, toolUseID, hookInput, () => canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID)),
         input: hookInput
       };
     }
@@ -241031,7 +241098,7 @@ async function resolveHookPermissionDecision(hookPermissionResult, tool, input,
     }
     logForDebugging2(`Hook approved tool use for ${tool.name}, but ask rule requires prompt`);
     return {
-      decision: await canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID),
+      decision: await consumePermissionPreDecision(toolUseContext, toolUseID, hookInput, () => canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID)),
       input: hookInput
     };
   }
@@ -241041,8 +241108,9 @@ async function resolveHookPermissionDecision(hookPermissionResult, tool, input,
   }
   const forceDecision = hookPermissionResult?.behavior === "ask" ? hookPermissionResult : undefined;
   const askInput = hookPermissionResult?.behavior === "ask" && hookPermissionResult.updatedInput ? hookPermissionResult.updatedInput : input;
+  const decision = forceDecision ? await canUseTool(tool, askInput, toolUseContext, assistantMessage, toolUseID, forceDecision) : await consumePermissionPreDecision(toolUseContext, toolUseID, askInput, () => canUseTool(tool, askInput, toolUseContext, assistantMessage, toolUseID));
   return {
-    decision: await canUseTool(tool, askInput, toolUseContext, assistantMessage, toolUseID, forceDecision),
+    decision,
     input: askInput
   };
 }
@@ -241203,6 +241271,7 @@ var init_toolHooks = __esm(() => {
   init_permissions2();
   init_toolErrors();
   init_utils5();
+  init_permissionPreDecision();
 });
 
 // src/controller/dispatch/toolExecution.ts
@@ -241458,9 +241527,8 @@ function streamedCheckPermissionsAndCallTool(tool, toolUseID, input, toolUseCont
   return stream4;
 }
 async function checkPermissionsAndCallTool(tool, toolUseID, input, toolUseContext, canUseTool, assistantMessage, messageId, requestId, mcpServerType, mcpServerBaseUrl, onToolProgress) {
-  const parsedInput = safeParseToolInputWithNullCoercion(tool.inputSchema, input);
-  if (!parsedInput.success) {
-    let errorContent = formatZodValidationError(tool.name, parsedInput.error);
+  const inputValidationFailure = (error41) => {
+    let errorContent = formatZodValidationError(tool.name, error41);
     const schemaHint = buildSchemaNotSentHint(tool, toolUseContext.messages, toolUseContext.options.tools);
     if (schemaHint) {
       logEvent("tengu_deferred_tool_schema_not_sent", {
@@ -241500,11 +241568,15 @@ async function checkPermissionsAndCallTool(tool, toolUseID, input, toolUseContex
               tool_use_id: toolUseID
             }
           ],
-          toolUseResult: `InputValidationError: ${parsedInput.error.message}`,
+          toolUseResult: `InputValidationError: ${error41.message}`,
           sourceToolAssistantUUID: assistantMessage.uuid
         })
       }
     ];
+  };
+  const parsedInput = safeParseToolInputWithNullCoercion(tool.inputSchema, input, tool.unknownKeys);
+  if (!parsedInput.success) {
+    return inputValidationFailure(parsedInput.error);
   }
   const isValidCall = await tool.validateInput?.(parsedInput.data, toolUseContext);
   if (isValidCall?.result === false) {
@@ -241740,6 +241812,16 @@ async function checkPermissionsAndCallTool(tool, toolUseID, input, toolUseContex
   if (permissionDecision.updatedInput !== undefined) {
     processedInput = permissionDecision.updatedInput;
   }
+  if (tool.unknownKeys === "reject") {
+    const finalInput = safeParseToolInputWithNullCoercion(tool.inputSchema, processedInput, tool.unknownKeys);
+    if (!finalInput.success) {
+      endToolBlockedOnUserSpan("reject", "input-validation");
+      endToolSpan();
+      resultingMessages.push(...inputValidationFailure(finalInput.error));
+      return resultingMessages;
+    }
+    processedInput = finalInput.data;
+  }
   const telemetryToolInput = extractToolInputForTelemetry(processedInput);
   let toolParameters = {};
   if (isToolDetailsLoggingEnabled()) {
@@ -242702,6 +242784,9 @@ function getMaxToolUseConcurrency() {
   return parseInt(resolveEnvVar("MAX_TOOL_USE_CONCURRENCY") || "", 10) || 10;
 }
 async function* runTools(toolUseMessages, assistantMessages, canUseTool, toolUseContext) {
+  if (toolUseContext.options.preDecidePermissions) {
+    startPermissionPreDecisions(toolUseMessages, assistantMessages, canUseTool, toolUseContext);
+  }
   let currentContext = toolUseContext;
   for (const { isConcurrencySafe, blocks } of partitionToolCalls(toolUseMessages, currentContext)) {
     if (isConcurrencySafe) {
@@ -242795,6 +242880,7 @@ var init_toolOrchestration = __esm(() => {
   init_toolRuntime();
   init_generators();
   init_toolExecution();
+  init_permissionPreDecision();
   init_state();
 });
 
@@ -244891,7 +244977,7 @@ function getAnthropicEnvMetadata() {
 function getBuildAgeMinutes() {
   if (false)
     ;
-  const buildTime = new Date("2026-08-28T10:03:59.640Z").getTime();
+  const buildTime = new Date("2026-09-03T09:12:13.936Z").getTime();
   if (isNaN(buildTime))
     return;
   return Math.floor((Date.now() - buildTime) / 60000);
@@ -245421,6 +245507,7 @@ function createSubagentContext(parentContext, overrides) {
     dynamicSkillDirTriggers: new Set,
     discoveredSkillNames: new Set,
     toolDecisions: undefined,
+    permissionPreDecisions: undefined,
     contentReplacementState: overrides?.contentReplacementState ?? (parentContext.contentReplacementState ? cloneContentReplacementState(parentContext.contentReplacementState) : undefined),
     abortController,
     getAppState,
@@ -248675,6 +248762,31 @@ async function* runAgent({
       level: "warn"
     });
   });
+  let partialBaseMessage = null;
+  const partialTextByIndex = new Map;
+  const PARTIAL_PROGRESS_INTERVAL_MS = 50;
+  let lastPartialAssistantAt = 0;
+  let lastPartialProgressHookAt = 0;
+  let foregroundSkipped = 0;
+  let backgroundSkipped = 0;
+  const logPartialProgress = (reason, chars, foregroundEmitted, backgroundEmitted) => {
+    logForDebugging2(`[StreamThrottle:SubAgent] ${JSON.stringify({
+      reason,
+      agentId,
+      agentType: agentDefinition.agentType,
+      messageId: partialBaseMessage?.id ?? null,
+      intervalMs: PARTIAL_PROGRESS_INTERVAL_MS,
+      chars,
+      foregroundEmitted,
+      foregroundSkipped,
+      backgroundEmitted,
+      backgroundSkipped
+    })}`);
+    if (foregroundEmitted)
+      foregroundSkipped = 0;
+    if (backgroundEmitted)
+      backgroundSkipped = 0;
+  };
   try {
     const additionalContexts = [];
     for await (const hookResult of executeSubagentStartHooks(agentId, agentDefinition.agentType, agentAbortController.signal, undefined, toolUseContext.toolUseId, isAsync2)) {
@@ -248782,10 +248894,6 @@ async function* runAgent({
       ...description && { description }
     }).catch((_err) => logForDebugging2(`Failed to write agent metadata: ${_err}`));
     let lastRecordedUuid = initialMessages.at(-1)?.uuid ?? null;
-    let partialBaseMessage = null;
-    const partialTextByIndex = new Map;
-    const PARTIAL_PROGRESS_HOOK_INTERVAL_MS = 100;
-    let lastPartialProgressHookAt = 0;
     const agentExtraBody = agentDefinition.extraBody;
     const agentQuery = query({
       messages: initialMessages,
@@ -248810,6 +248918,11 @@ async function* runAgent({
       if (message.type === "stream_event") {
         const ev = message.event;
         if (ev.type === "message_start") {
+          if (foregroundSkipped > 0 || backgroundSkipped > 0) {
+            logPartialProgress("message-start", 0, false, false);
+            foregroundSkipped = 0;
+            backgroundSkipped = 0;
+          }
           if (message.ttftMs != null) {
             toolUseContext.pushApiMetricsEntry?.(message.ttftMs);
           }
@@ -248821,22 +248934,36 @@ async function* runAgent({
           const idx = ev.index ?? 0;
           const acc = (partialTextByIndex.get(idx) ?? "") + ev.delta.text;
           partialTextByIndex.set(idx, acc);
-          onPartialAssistant?.({
-            type: "assistant",
-            message: {
-              ...partialBaseMessage,
-              content: [{ type: "text", text: acc, citations: null }]
-            },
-            uuid: randomUUID10(),
-            timestamp: new Date().toISOString()
-          });
+          const now = Date.now();
+          let foregroundEmitted = false;
+          let backgroundEmitted = false;
+          if (onPartialAssistant && now - lastPartialAssistantAt >= PARTIAL_PROGRESS_INTERVAL_MS) {
+            lastPartialAssistantAt = now;
+            foregroundEmitted = true;
+            onPartialAssistant({
+              type: "assistant",
+              message: {
+                ...partialBaseMessage,
+                content: [{ type: "text", text: acc, citations: null }]
+              },
+              uuid: randomUUID10(),
+              timestamp: new Date().toISOString()
+            });
+          } else if (onPartialAssistant) {
+            foregroundSkipped += 1;
+          }
           if (isAsync2) {
-            const now = Date.now();
-            if (now - lastPartialProgressHookAt >= PARTIAL_PROGRESS_HOOK_INTERVAL_MS) {
+            if (now - lastPartialProgressHookAt >= PARTIAL_PROGRESS_INTERVAL_MS) {
               lastPartialProgressHookAt = now;
+              backgroundEmitted = true;
               executeSubagentProgressHooks(agentId, agentDefinition.agentType, partialBaseMessage.id, toolUseContext.toolUseId, [{ type: "text", text: acc }]).catch(() => {});
+            } else {
+              backgroundSkipped += 1;
             }
           }
+          if (foregroundEmitted || backgroundEmitted) {
+            logPartialProgress("emit", acc.length, foregroundEmitted, backgroundEmitted);
+          }
         }
         continue;
       }
@@ -248885,6 +249012,9 @@ async function* runAgent({
     agentRunError = err2;
     throw err2;
   } finally {
+    if (foregroundSkipped > 0 || backgroundSkipped > 0) {
+      logPartialProgress("finalize", 0, false, false);
+    }
     await finalizeLifecycle([
       async () => {
         const naturalStopAlreadyFired = isAsync2 && hasSubagentStopFired(agentId);
@@ -265595,7 +265725,7 @@ var init_AgentTool = __esm(() => {
         }
         selectedAgent = FORK_AGENT;
       } else {
-        const allAgents = toolUseContext.options.agentDefinitions.activeAgents;
+        const allAgents = withDefaultAgentForInvocation(toolUseContext.options.agentDefinitions.activeAgents, subagent_type, GENERAL_PURPOSE_AGENT);
         const {
           allowedAgentTypes
         } = toolUseContext.options.agentDefinitions;
@@ -492398,7 +492528,7 @@ function buildPrimarySection() {
   }, undefined, false, undefined, this);
   return [{
     label: "Version",
-    value: "0.4.23"
+    value: "0.4.24"
   }, {
     label: "Session name",
     value: nameValue
@@ -540540,7 +540670,7 @@ var init_bridge_kick = __esm(() => {
 var call58 = async () => {
   return {
     type: "text",
-    value: `${"99.0.0"} (built ${"2026-08-28T10:03:59.640Z"})`
+    value: `${"99.0.0"} (built ${"2026-09-03T09:12:13.936Z"})`
   };
 }, version2, version_default;
 var init_version = __esm(() => {
@@ -558307,7 +558437,7 @@ function WelcomeV2() {
             dimColor: true,
             children: [
               "v",
-              "0.4.23",
+              "0.4.24",
               " "
             ]
           }, undefined, true, undefined, this)
@@ -558507,7 +558637,7 @@ function WelcomeV2() {
           dimColor: true,
           children: [
             "v",
-            "0.4.23",
+            "0.4.24",
             " "
           ]
         }, undefined, true, undefined, this)
@@ -558733,7 +558863,7 @@ function AppleTerminalWelcomeV2(t0) {
         dimColor: true,
         children: [
           "v",
-          "0.4.23",
+          "0.4.24",
           " "
         ]
       }, undefined, true, undefined, this);
@@ -558987,7 +559117,7 @@ function AppleTerminalWelcomeV2(t0) {
       dimColor: true,
       children: [
         "v",
-        "0.4.23",
+        "0.4.24",
         " "
       ]
     }, undefined, true, undefined, this);
@@ -569747,6 +569877,7 @@ class QueryEngine {
       includePartialMessages = false,
       agents: agents2 = [],
       setSDKStatus,
+      preDecidePermissions,
       onToolInvoke,
       uploadMedia,
       orphanedPermission
@@ -569824,7 +569955,8 @@ class QueryEngine {
         maxOutputTokensLimit,
         contextWindow,
         modelProviders: this.config.modelProviders,
-        subagentDisallowedTools: this.config.subagentDisallowedTools
+        subagentDisallowedTools: this.config.subagentDisallowedTools,
+        preDecidePermissions
       },
       getAppState,
       setAppState,
@@ -569922,7 +570054,8 @@ class QueryEngine {
         maxOutputTokensLimit,
         contextWindow,
         modelProviders: this.config.modelProviders,
-        subagentDisallowedTools: this.config.subagentDisallowedTools
+        subagentDisallowedTools: this.config.subagentDisallowedTools,
+        preDecidePermissions
       },
       getAppState,
       setAppState,
@@ -570439,6 +570572,7 @@ async function* ask({
   handleElicitation,
   agents: agents2 = [],
   setSDKStatus,
+  preDecidePermissions,
   onToolInvoke,
   uploadMedia,
   orphanedPermission
@@ -570473,6 +570607,7 @@ async function* ask({
     replayUserMessages,
     includePartialMessages,
     setSDKStatus,
+    preDecidePermissions,
     onToolInvoke,
     uploadMedia,
     abortController,
@@ -579972,7 +580107,7 @@ Usage: claude --remote "your task description"`, () => gracefulShutdown(1));
         pendingHookMessages
       }, renderAndRun);
     }
-  }).version("0.4.23 (OpenCow)", "-v, --version", "Output the version number");
+  }).version("0.4.24 (OpenCow)", "-v, --version", "Output the version number");
   program2.option("-w, --worktree [name]", "Create a new git worktree for this session (optionally specify a name)");
   program2.option("--tmux", "Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use --tmux=classic for traditional tmux.");
   if (canUserConfigureAdvisor()) {
@@ -580617,7 +580752,7 @@ if (false) {}
 async function main2() {
   const args = process.argv.slice(2);
   if (args.length === 1 && (args[0] === "--version" || args[0] === "-v" || args[0] === "-V")) {
-    console.log(`${"0.4.23"} (OpenCow)`);
+    console.log(`${"0.4.24"} (OpenCow)`);
     return;
   }
   if (args.includes("--provider")) {
@@ -580735,4 +580870,4 @@ async function main2() {
 }
 main2();
 
-//# debugId=76BE00AA5948715464756E2164756E21
+//# debugId=686B073019ED8C6564756E2164756E21