@cognipeer/agent-sdk 0.10.1 → 0.10.2

package/dist/index.d.cts

@@ -451,6 +451,13 @@ interface HookMap {
             error?: Error;
             durationMs: number;
             executionId: string;
+            /**
+             * Where `output` came from. `tool` is a real execution (or its error);
+             * `hook` is a `preToolUse.result` short-circuit; `cache` is a hit on the
+             * tool's own result cache — that value already passed this hook once,
+             * when it was stored, so a redactor sees it twice.
+             */
+            source?: "tool" | "hook" | "cache";
         };
         output: {
             /** Rewritten output — redaction, normalization, schema coercion. */

package/dist/index.d.ts

@@ -451,6 +451,13 @@ interface HookMap {
             error?: Error;
             durationMs: number;
             executionId: string;
+            /**
+             * Where `output` came from. `tool` is a real execution (or its error);
+             * `hook` is a `preToolUse.result` short-circuit; `cache` is a hit on the
+             * tool's own result cache — that value already passed this hook once,
+             * when it was stored, so a redactor sees it twice.
+             */
+            source?: "tool" | "hook" | "cache";
         };
         output: {
             /** Rewritten output — redaction, normalization, schema coercion. */

package/dist/index.mjs

@@ -4591,18 +4591,60 @@ function createToolsNode(initialTools, opts) {
         toolStateRef.__currentToolCallId = toolCallId;
         delete toolStateRef.__awaitingApproval;
       }
-      let hookAskedForApproval = false;
-      let hookApprovalPrompt;
-      let hookResult;
-      if (host?.has("preToolUse")) {
+      const stableJson = (value) => {
+        try {
+          if (value === null || typeof value !== "object") return JSON.stringify(value);
+          if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+          const keys = Object.keys(value).sort();
+          return `{${keys.map((k) => JSON.stringify(k) + ":" + stableJson(value[k])).join(",")}}`;
+        } catch {
+          return String(value);
+        }
+      };
+      const rejectByPolicy = (gateReason, gatedArgs) => {
+        const reason = gateReason || `Tool call blocked by policy: ${toolName}`;
+        push({ role: "tool", content: reason, tool_call_id: toolCallId, name: tc.name });
+        toolHistory.push({
+          executionId: nanoid(),
+          toolName,
+          args: gatedArgs,
+          output: reason,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          tool_call_id: toolCallId,
+          status: "rejected"
+        });
+        onEvent?.({ type: "tool_call", phase: "skipped", name: toolName, id: tc.id, args: gatedArgs, error: { message: reason } });
+        recordTraceEvent(traceSession, {
+          type: "tool_call",
+          label: `Tool Denied - ${toolName}`,
+          actor: { scope: "tool", name: toolName, role: "tool" },
+          status: "skipped",
+          toolDetails,
+          toolExecutionId: toolCallId,
+          sections: buildToolTraceSections({
+            args: gatedArgs,
+            executionId: toolCallId,
+            output: reason,
+            status: "skipped",
+            summary: reason,
+            toolDetails,
+            toolName
+          })
+        });
+        toolCount += 1;
+        return { status: "error" };
+      };
+      const applyPreToolUseGate = async (candidate) => {
+        if (!host?.has("preToolUse")) return { ok: true, args: candidate, ask: false };
         const gate = await host.runGate("preToolUse", {
           toolName,
           toolCallId,
-          args,
+          args: candidate,
           tool,
           executionCount: countSuccessfulToolExecutions(toolHistory, toolName)
         });
-        if (gate.input.args !== args) {
+        let next = candidate;
+        if (gate.input.args !== candidate) {
           const revalidated = validateToolArgs(tool, gate.input.args);
           if (!revalidated.ok && resolved.toolResponses.schemaValidation === "strict") {
             const message = `Tool argument validation failed after a plugin rewrite for ${toolName}: ${revalidated.message}`;
@@ -4610,48 +4652,31 @@ function createToolsNode(initialTools, opts) {
             markToolFailure(message, toolName, toolCallId);
             onEvent?.({ type: "tool_call", phase: "error", name: toolName, id: tc.id, args: gate.input.args, error: { message } });
             toolCount += 1;
-            return { status: "error" };
+            return { ok: false, outcome: { status: "error" } };
           }
-          args = revalidated.ok ? revalidated.value : gate.input.args;
+          next = revalidated.ok ? revalidated.value : gate.input.args;
         }
         if (gate.decision === "deny") {
-          const reason = gate.reason || `Tool call blocked by policy: ${toolName}`;
-          push({ role: "tool", content: reason, tool_call_id: toolCallId, name: tc.name });
-          toolHistory.push({
-            executionId: nanoid(),
-            toolName,
-            args,
-            output: reason,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-            tool_call_id: toolCallId,
-            status: "rejected"
-          });
-          onEvent?.({ type: "tool_call", phase: "skipped", name: toolName, id: tc.id, args, error: { message: reason } });
-          recordTraceEvent(traceSession, {
-            type: "tool_call",
-            label: `Tool Denied - ${toolName}`,
-            actor: { scope: "tool", name: toolName, role: "tool" },
-            status: "skipped",
-            toolDetails,
-            toolExecutionId: toolCallId,
-            sections: buildToolTraceSections({
-              args,
-              executionId: toolCallId,
-              output: reason,
-              status: "skipped",
-              summary: reason,
-              toolDetails,
-              toolName
-            })
-          });
-          toolCount += 1;
-          return { status: "error" };
-        }
-        if (gate.decision === "ask") {
-          hookAskedForApproval = true;
-          hookApprovalPrompt = gate.approvalPrompt;
+          return { ok: false, outcome: rejectByPolicy(gate.reason, next) };
         }
-        if (gate.shortCircuit !== void 0) hookResult = gate.shortCircuit;
+        return {
+          ok: true,
+          args: next,
+          ask: gate.decision === "ask",
+          approvalPrompt: gate.approvalPrompt,
+          result: gate.shortCircuit
+        };
+      };
+      let hookAskedForApproval = false;
+      let hookApprovalPrompt;
+      let hookResult;
+      {
+        const gated = await applyPreToolUseGate(args);
+        if (!gated.ok) return gated.outcome;
+        args = gated.args;
+        hookAskedForApproval = gated.ask;
+        hookApprovalPrompt = gated.approvalPrompt;
+        if (gated.result !== void 0) hookResult = gated.result;
       }
       const maxExecutionsPerRun = normalizeMaxExecutionsPerRun(tool.maxExecutionsPerRun);
       if (maxExecutionsPerRun !== null) {
@@ -4736,7 +4761,34 @@ function createToolsNode(initialTools, opts) {
           return { status: "rejected", approval: approvalEntry };
         }
         if (approvalEntry.status === "approved" && approvalEntry.approvedArgs !== void 0) {
-          args = approvalEntry.approvedArgs;
+          const approvedArgs = approvalEntry.approvedArgs;
+          if (stableJson(approvedArgs) !== stableJson(args)) {
+            const settleRefused = (resolution) => {
+              approvalEntry.metadata = { ...approvalEntry.metadata || {}, resolution };
+              approvalEntry.status = "executed";
+              approvalEntry.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+              pendingByCallId.set(toolCallId, approvalEntry);
+            };
+            const revalidated = validateToolArgs(tool, approvedArgs);
+            if (!revalidated.ok && resolved.toolResponses.schemaValidation === "strict") {
+              const message = `Tool argument validation failed for reviewer-edited arguments of ${toolName}: ${revalidated.message}`;
+              push({ role: "tool", content: message, tool_call_id: toolCallId, name: tc.name });
+              markToolFailure(message, toolName, toolCallId);
+              settleRefused("invalid_args");
+              onEvent?.({ type: "tool_call", phase: "error", name: toolName, id: tc.id, args: approvedArgs, error: { message } });
+              toolCount += 1;
+              return { status: "error", approval: approvalEntry };
+            }
+            const gated = await applyPreToolUseGate(revalidated.ok ? revalidated.value : approvedArgs);
+            if (!gated.ok) {
+              settleRefused("policy_denied");
+              return { ...gated.outcome, approval: approvalEntry };
+            }
+            args = gated.args;
+            if (gated.result !== void 0 && hookResult === void 0) hookResult = gated.result;
+          } else {
+            args = approvedArgs;
+          }
           onEvent?.({ type: "tool_approval", status: "approved", id: approvalEntry.id, toolName: approvalEntry.toolName, toolCallId: approvalEntry.toolCallId, decidedBy: approvalEntry.decidedBy, comment: approvalEntry.comment });
         }
       }
@@ -4746,16 +4798,6 @@ function createToolsNode(initialTools, opts) {
       const cacheCfg = tool.cache;
       const cacheEnabled = cacheCfg === true || cacheCfg && typeof cacheCfg === "object";
       const cacheKeyFn = cacheEnabled && typeof cacheCfg === "object" ? cacheCfg.keyFn : void 0;
-      const stableJson = (value) => {
-        try {
-          if (value === null || typeof value !== "object") return JSON.stringify(value);
-          if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-          const keys = Object.keys(value).sort();
-          return `{${keys.map((k) => JSON.stringify(k) + ":" + stableJson(value[k])).join(",")}}`;
-        } catch {
-          return String(value);
-        }
-      };
       const cacheKey = cacheEnabled ? `${toolName}|${cacheKeyFn ? cacheKeyFn(args) : stableJson(args)}` : void 0;
       const toolCache = state.toolCache = state.toolCache || {};
       let cachedHit = void 0;
@@ -4803,6 +4845,22 @@ function createToolsNode(initialTools, opts) {
       try {
         if (cachedHit !== void 0) {
           const executionId2 = nanoid();
+          if (host?.has("postToolUse")) {
+            const shortGate = await host.runGate("postToolUse", {
+              toolName,
+              toolCallId,
+              args,
+              output: cachedHit,
+              durationMs: 0,
+              executionId: executionId2,
+              source: shortCircuitSource === "plugin" ? "hook" : "cache"
+            });
+            if (shortGate.decision === "deny") {
+              cachedHit = shortGate.reason || `Tool output withheld by policy: ${toolName}`;
+            } else if (shortGate.input.output !== cachedHit) {
+              cachedHit = shortGate.input.output;
+            }
+          }
           const { output: compressedCachedHit, stats: cachedContextPilotStats } = maybeCompressToolOutput(toolName, cachedHit, executionId2);
           const responsePolicy2 = applyToolResponseHardCap(toolName, compressedCachedHit, executionId2, resolved);
           toolHistory.push({
@@ -4969,7 +5027,8 @@ function createToolsNode(initialTools, opts) {
             args,
             output,
             durationMs,
-            executionId
+            executionId,
+            source: "tool"
           });
           if (postGate.decision === "deny") {
             output = postGate.reason || `Tool output withheld by policy: ${toolName}`;
@@ -5064,7 +5123,8 @@ function createToolsNode(initialTools, opts) {
               output: message,
               error: error instanceof Error ? error : new Error(message),
               durationMs,
-              executionId
+              executionId,
+              source: "tool"
             });
             if (errorGate.decision === "deny") {
               message = errorGate.reason || `Tool error withheld by policy: ${toolName}`;
@@ -5740,7 +5800,14 @@ var DISALLOWED_CTX_KEYS = /* @__PURE__ */ new Set([
   // Session bookkeeping: a resumed run must open its OWN session, so these
   // must not travel in a snapshot.
   "__pluginRunStarted",
-  "__pluginRunEnded"
+  "__pluginRunEnded",
+  // Set by restoreSnapshot on the way OUT, consumed by the next invoke. Never
+  // persisted: a snapshot of a restored run would otherwise mark every later
+  // restore as "resumed" forever.
+  "__restoredFromSnapshot",
+  // A per-turn verdict. It describes the run that produced the snapshot, not
+  // the run that will resume from it.
+  "__guardrailBlocked"
 ]);
 var clone = (value) => {
   if (typeof globalThis.structuredClone === "function") {
@@ -6364,6 +6431,7 @@ var SLOT_NAMES = [
   "contextBuilder"
 ];
 var DECISION_RANK = { allow: 0, ask: 1, deny: 2 };
+var isHookDecision = (value) => typeof value === "string" && Object.prototype.hasOwnProperty.call(DECISION_RANK, value);
 function escalate(current, next) {
   return DECISION_RANK[next] > DECISION_RANK[current] ? next : current;
 }
@@ -6373,6 +6441,15 @@ var HookTimeoutError = class extends Error {
     this.name = "HookTimeoutError";
   }
 };
+var InvalidHookDecisionError = class extends Error {
+  constructor(plugin, hook, value) {
+    const shown = typeof value === "string" ? JSON.stringify(value) : String(value);
+    super(
+      `plugin "${plugin}" hook "${hook}" returned an unknown decision ${shown}; expected "allow", "ask" or "deny"`
+    );
+    this.name = "InvalidHookDecisionError";
+  }
+};
 function withTimeout(value, ms, label) {
   if (!ms || !Number.isFinite(ms) || ms <= 0) return Promise.resolve(value);
   return new Promise((resolve, reject) => {
@@ -6662,10 +6739,18 @@ function createPluginHost(plugins = [], options = {}) {
                 `plugin "${entry.plugin}" hook "${hook}"`
               );
               output = raw ?? void 0;
+              if (output && typeof output === "object" && output.decision !== void 0 && !isHookDecision(output.decision)) {
+                throw new InvalidHookDecisionError(entry.plugin, hook, output.decision);
+              }
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err);
               const timedOut = err instanceof HookTimeoutError;
-              logger.warn(`plugin "${entry.plugin}" hook "${hook}" failed:`, message);
+              const badDecision = err instanceof InvalidHookDecisionError;
+              if (badDecision) {
+                logger.error(`plugin "${entry.plugin}" hook "${hook}" returned an invalid decision:`, message);
+              } else {
+                logger.warn(`plugin "${entry.plugin}" hook "${hook}" failed:`, message);
+              }
               emitPluginEvent(entry, hook, {
                 phase: timedOut ? "timeout" : "error",
                 error: { message },
@@ -6677,8 +6762,9 @@ function createPluginHost(plugins = [], options = {}) {
                 durationMs: performanceNow() - startedAt
               });
               if (entry.failureMode === "closed") {
+                const cause = timedOut ? "timed out" : badDecision ? "invalid decision" : "hook error";
                 result.decision = "deny";
-                result.reason = `${entry.plugin}: ${timedOut ? "timed out" : "hook error"} (fail-closed) \u2014 ${message}`;
+                result.reason = `${entry.plugin}: ${cause} (fail-closed) \u2014 ${message}`;
                 result.deniedBy = entry.plugin;
                 result.input = current;
                 return result;
@@ -6736,11 +6822,19 @@ function createPluginHost(plugins = [], options = {}) {
             if (output.metadata && typeof output.metadata === "object") {
               result.metadata = { ...result.metadata ?? {}, ...output.metadata };
             }
-            const decision = output.decision;
+            let decision = output.decision;
+            if (decision === "ask" && hook !== "preToolUse") {
+              logger.warn(
+                `plugin "${entry.plugin}" returned "ask" from "${hook}", which cannot pause for approval; treating it as "deny".`
+              );
+              decision = "deny";
+            }
             const escalated = decision ? escalate(result.decision, decision) : result.decision;
             const escalatesHere = escalated !== result.decision;
             result.decision = escalated;
-            if (typeof output.reason === "string" && (escalatesHere || !result.reason)) {
+            if (escalatesHere) {
+              result.reason = typeof output.reason === "string" ? `${entry.plugin}: ${output.reason}` : void 0;
+            } else if (typeof output.reason === "string" && !result.reason) {
               result.reason = `${entry.plugin}: ${output.reason}`;
             }
             if (mutatedHere) {
@@ -6834,7 +6928,7 @@ async function openPluginSession(runHost, params) {
   const appended = startGate.collected.systemPromptAppend ?? [];
   const systemPromptAppend = appended.length > 0 ? appended.join("\n\n") : void 0;
   const last = messages[messages.length - 1];
-  if (params.resumed || last?.role !== "user" || !runHost.has("userPromptSubmit")) {
+  if (params.pausedMidRun || last?.role !== "user" || !runHost.has("userPromptSubmit")) {
     return { messages, systemPromptAppend };
   }
   const content = last.content;
@@ -7079,6 +7173,11 @@ function createAgent(opts) {
       delete nextCtx.__paused;
       state = { ...state, ctx: Object.keys(nextCtx).length > 0 ? nextCtx : void 0 };
     }
+    if (state.ctx?.__restoredFromSnapshot) {
+      const nextCtx = { ...state.ctx };
+      delete nextCtx.__restoredFromSnapshot;
+      state = { ...state, ctx: Object.keys(nextCtx).length > 0 ? nextCtx : void 0 };
+    }
     let resumeStage = null;
     if (state.ctx?.__resumeStage) {
       const nextCtx = { ...state.ctx };
@@ -7353,7 +7452,7 @@ function createAgent(opts) {
         continue;
       }
       if (toolCalls.length === 0) {
-        if (soManager && !state.ctx?.__finalizedDueToStructuredOutput && !state.ctx?.__structuredOutputForceFinalize) {
+        if (soManager && !state.ctx?.__finalizedDueToStructuredOutput && !state.ctx?.__structuredOutputForceFinalize && !state.ctx?.__guardrailBlocked) {
           if (soManager.strategy.kind === "native") {
             const assistantText = extractMessageText2(lastMsg);
             if (assistantText) {
@@ -7522,6 +7621,7 @@ function createAgent(opts) {
     delete ctx.__plugins;
     delete ctx.__applySystemPromptContribution;
     delete ctx.__pluginState;
+    delete ctx.__guardrailBlocked;
     const inheritedSession = config?.__pluginSession;
     ctx.__runId = inheritedSession?.runId ?? traceSession?.sessionId ?? `run_${nanoid(10)}`;
     const stateHolder = inheritedSession?.stateHolder ?? { value: void 0 };
@@ -7571,9 +7671,11 @@ function createAgent(opts) {
       usage: input.usage || { perRequest: [], totals: {} }
     };
     stateHolder.value = initial;
-    const resumed = Boolean(
-      input.ctx?.__restoredFromSnapshot || input.ctx?.__paused || input.ctx?.__resumeStage || input.ctx?.__awaitingApproval || input.ctx?.__awaitingUserQuestion
+    const pausedMidRun = Boolean(
+      input.ctx?.__paused || input.ctx?.__resumeStage || input.ctx?.__awaitingApproval || input.ctx?.__awaitingUserQuestion
     );
+    const resumed = Boolean(input.ctx?.__restoredFromSnapshot || pausedMidRun);
+    delete ctx.__restoredFromSnapshot;
     const startedAt = Date.now();
     let sessionEnded = false;
     const endSession = async (status, payload) => {
@@ -7599,6 +7701,7 @@ function createAgent(opts) {
       const opened = await openPluginSession(runHost, {
         messages: initial.messages,
         resumed,
+        pausedMidRun,
         config
       });
       if (opened.messages !== initial.messages) {
@@ -10255,6 +10358,11 @@ ${pluginAppend}`;
   const instance = {
     invoke: async (input, config) => {
       await ensurePluginSetup();
+      if (input?.ctx?.__guardrailBlocked !== void 0) {
+        const clearedCtx = { ...input.ctx };
+        delete clearedCtx.__guardrailBlocked;
+        input = { ...input, ctx: clearedCtx };
+      }
       const sessionHolder = { value: input };
       const emitSessionEvent = (event) => {
         try {
@@ -10305,12 +10413,20 @@ ${pluginAppend}`;
             stateHolder: sessionHolder
           }
         };
-        const resumed = Boolean(
-          input.ctx?.__restoredFromSnapshot || input.ctx?.__paused || input.ctx?.__resumeStage || input.ctx?.__awaitingApproval || input.ctx?.__awaitingUserQuestion
+        const pausedMidRun = Boolean(
+          input.ctx?.__paused || input.ctx?.__resumeStage || input.ctx?.__awaitingApproval || input.ctx?.__awaitingUserQuestion
         );
+        const resumed = Boolean(input.ctx?.__restoredFromSnapshot || pausedMidRun);
+        if (input.ctx?.__restoredFromSnapshot) {
+          const consumedCtx = { ...input.ctx };
+          delete consumedCtx.__restoredFromSnapshot;
+          input = { ...input, ctx: consumedCtx };
+          sessionHolder.value = input;
+        }
         const opened = await openPluginSession(runHost, {
           messages: input.messages || [],
           resumed,
+          pausedMidRun,
           config
         });
         if (opened.denied) {
@@ -11100,7 +11216,7 @@ var HOOKS = {
   sessionStart: { implemented: true },
   userPromptSubmit: {
     implemented: true,
-    notes: "Fires once per run for a new user turn. Skipped on resume, where the transcript tail is a tool result rather than a user message."
+    notes: "Fires once per run whenever the transcript tail is a NEW user turn \u2014 including a turn appended to a state that was restored from a snapshot. Skipped on a genuine resume, where the tail is a tool result rather than a user message."
   },
   preModelCall: {
     implemented: true,
@@ -11113,7 +11229,7 @@ var HOOKS = {
   },
   postToolUse: {
     implemented: true,
-    notes: "Raw output, before compression and the hard cap. Also fires on a tool ERROR. Does NOT fire for a call that parks the run."
+    notes: "Raw output, before compression and the hard cap. Also fires on a tool ERROR, on a preToolUse `result` short-circuit and on a tool-cache hit (`input.source` says which). Does NOT fire for a call that parks the run."
   },
   preCompact: { implemented: true },
   postCompact: { implemented: true },
@@ -12097,6 +12213,12 @@ function auditLog(config = {}) {
       return "[unserializable]";
     }
   };
+  const renderDetail = (detail) => {
+    if (!detail || typeof detail !== "object" || Array.isArray(detail) || !("args" in detail)) return detail;
+    const { args, ...rest } = detail;
+    const rendered = renderArgs(args);
+    return rendered === void 0 ? rest : { ...rest, args: rendered };
+  };
   return {
     name: config.name ?? "audit-log",
     // Lowest number: runs first, so denials by later plugins are still recorded
@@ -12125,7 +12247,7 @@ function auditLog(config = {}) {
           at: (/* @__PURE__ */ new Date()).toISOString(),
           kind: "notification",
           status: kind,
-          detail
+          detail: renderDetail(detail)
         });
       },
       sessionEnd: async ({ status }, ctx) => {