@salesforce/sfdx-agent-sdk 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.61.0] - 2026-09-01
+
+### Features
+- **agent-sdk**: add policy-aware tool declines @W-24048333@ ([#776](https://github.com/forcedotcom/agentic-dx/pull/776))
+
+### Chores
+- **deps-dev**: bump typescript-eslint from 8.67.0 to 8.68.0 in the dev-dependencies group across 1 directory ([#777](https://github.com/forcedotcom/agentic-dx/pull/777))
+- **deps-dev**: bump eslint from 10.8.1 to 10.9.1 in the eslint group ([#778](https://github.com/forcedotcom/agentic-dx/pull/778))
+
+## [0.60.0] - 2026-08-28
+
+### Tests
+- **agent-sdk**: make connectivity-headers multi-step e2e deterministic via #529 held-iterator pattern @W-23930393@ ([#771](https://github.com/forcedotcom/agentic-dx/pull/771))
+
 ## [0.59.0] - 2026-08-28
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -168,7 +168,7 @@ A single conversation thread.
 | `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `declineToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `declineToolCall`   | `(toolCallId: string, options?: DeclineToolCallOptions) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. `{ reason: { kind: 'organization-policy', modelMessage? } }` delivers a terminal policy explanation to the model and error result without persisting a remembered user rule. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -377,6 +377,14 @@ With `{ remember: true }` the SDK derives the matcher from the pending `tool-app
 restart and a persistence failure surfaces as the settle's rejection. A `remember` settle for a `toolCallId` with no
 pending approval throws `TOOL_CALL_NOT_FOUND`.
 
+**Organization-policy decline.** A host enforcing policy can call
+`declineToolCall(id, { reason: { kind: 'organization-policy', modelMessage? } })`. A nonblank custom message is trimmed
+and followed by a blank line plus the invariant “This block is enforced by organization policy, not by the user. Do not
+retry this tool call or attempt the same action using another tool or command.” Blank or omitted custom text uses the
+invariant alone. The exact resolved message reaches both the model and the single terminal `tool-result(isError=true)`.
+It is never written to telemetry/log fields and never creates a remembered deny rule; untyped JavaScript that also
+supplies `remember: true` still follows those safety rules.
+
 #### `MCPConfiguration`
 
 ```typescript
@@ -565,6 +573,14 @@ type ToolResultInfo = {
   /** Present when isError is true. Best-effort: error.stack is not guaranteed to point at the tool's throw site. */
   error?: Error;
 };
+
+type ToolDeclineReason = {
+  kind: 'organization-policy';
+  modelMessage?: string;
+};
+
+type DeclineToolCallOptions =
+  { remember?: boolean; reason?: undefined } | { remember?: false; reason: ToolDeclineReason };
 ```
 
 ### Message Types

package/dist/chat-session.d.ts

@@ -6,7 +6,7 @@ import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
 import type { SessionContext } from './types/session-context.js';
 import { type TelemetryBus, type TelemetryEventCallback } from './types/telemetry-events.js';
-import type { ToolPolicyRule, ToolResultInfo } from './types/tools.js';
+import type { DeclineToolCallOptions, ToolPolicyRule, ToolResultInfo } from './types/tools.js';
 import type { ContextUsage } from './types/usage.js';
 /**
  * Options for a single chat interaction.
@@ -160,10 +160,10 @@ export interface ChatSession {
      *   `updateAgentConfig` **before** settling the decline. Symmetric with
      *   {@link approveToolCall}'s `remember`. Throws `TOOL_CALL_NOT_FOUND` if
      *   `toolCallId` does not match a pending `tool-approval-request`.
+     * @param options.reason - Optional organization-policy reason delivered to the model and
+     *   terminal error result. Policy reasons require `remember: false` and are never persisted.
      */
-    declineToolCall(toolCallId: string, options?: {
-        remember?: boolean;
-    }): Promise<void>;
+    declineToolCall(toolCallId: string, options?: DeclineToolCallOptions): Promise<void>;
     /**
      * Retrieve message history for this session.
      *
@@ -274,16 +274,18 @@ export declare class DefaultChatSession implements ChatSession {
     private readonly clock;
     private readonly idGenerator;
     /**
-     * Tracks the start timestamp of every in-flight `tool-call` keyed by `toolCallId`,
-     * used by `deriveToolTelemetry` to compute `tool-execution-completed.durationMs`.
+     * Tracks observability state for every in-flight `tool-call` keyed by `toolCallId`.
+     * The start timestamp drives `tool-execution-completed.durationMs`; an optional
+     * exact policy-message set lets the same derivation omit only that text from telemetry.
      *
      * Lifetime is per-session (not per-stream) so a `tool-call` on the initial chat stream
      * pairs with a `tool-result` on the approval-continuation / submit-tool-result
      * continuation stream — those are continuations of the same logical chat turn. Cleared
      * on every terminal `finish` ChatEvent (the turn closed cleanly; any unmatched entries
-     * are stale and should not bleed into the next turn).
+     * are stale and should not bleed into the next turn). Attempted policy messages remain
+     * until result/turn cleanup because another concurrent settle for the same id may succeed.
      */
-    private readonly toolStartMs;
+    private readonly toolExecutionsByToolCallId;
     /**
      * Tracks the `(toolName, serverName?)` of every tool call currently awaiting
      * approval, keyed by `toolCallId`. Populated when a `tool-approval-request`
@@ -412,10 +414,12 @@ export declare class DefaultChatSession implements ChatSession {
      *   before returning a stream result.
      * - WHEN `options.remember` is `true`, MUST append a `'deny'` `'remember'` rule and persist it
      *   BEFORE delegating the settle to the harness — symmetric with {@link approveToolCall}.
+     * - WHEN `options.reason` is present, MUST forward it without persisting a remembered rule,
+     *   including when untyped JavaScript also supplies `remember: true`.
+     * - A resolved organization-policy message MUST stay on the public tool result but be omitted
+     *   from derived telemetry and logs without suppressing unrelated tool diagnostics.
      */
-    declineToolCall(toolCallId: string, options?: {
-        remember?: boolean;
-    }): Promise<void>;
+    declineToolCall(toolCallId: string, options?: DeclineToolCallOptions): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
@@ -489,8 +493,8 @@ export declare class DefaultChatSession implements ChatSession {
     private emitToolApprovalResolved;
     /**
      * Clears the per-turn tracking maps at a terminal `finish`. Both maps are
-     * scoped to one logical chat turn: `toolStartMs` pairs `tool-call` with
-     * `tool-result` for `tool-execution-completed.durationMs`, and
+     * scoped to one logical chat turn: `toolExecutionsByToolCallId` pairs a
+     * `tool-call` with its result for duration and policy-message redaction, and
      * `pendingApprovalsByToolCallId` lets a `remember` settle build the right
      * matcher. A stale entry surviving into the next turn would mispair a
      * duration or remember the wrong tool, so the two clears must always fire
@@ -503,7 +507,7 @@ export declare class DefaultChatSession implements ChatSession {
      * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
      *
      * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
-     * `tool-result` using `this.clock`. The tracking map (`this.toolStartMs`) lives on the
+     * `tool-result` using `this.clock`. The tracking map (`this.toolExecutionsByToolCallId`) lives on the
      * session, so a `tool-call` on the initial stream pairs with a `tool-result` on the
      * approval-continuation / submit-tool-result continuation stream — those are continuations
      * of the same logical chat turn. The map is cleared on every terminal `finish` ChatEvent

package/dist/chat-session.js

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import { backfillCreatedAt, EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { resolveToolDeclineModelMessage } from './harness/tool-decline.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { createTelemetryBus, } from './types/telemetry-events.js';
 /**
@@ -24,16 +25,18 @@ export class DefaultChatSession {
     clock;
     idGenerator;
     /**
-     * Tracks the start timestamp of every in-flight `tool-call` keyed by `toolCallId`,
-     * used by `deriveToolTelemetry` to compute `tool-execution-completed.durationMs`.
+     * Tracks observability state for every in-flight `tool-call` keyed by `toolCallId`.
+     * The start timestamp drives `tool-execution-completed.durationMs`; an optional
+     * exact policy-message set lets the same derivation omit only that text from telemetry.
      *
      * Lifetime is per-session (not per-stream) so a `tool-call` on the initial chat stream
      * pairs with a `tool-result` on the approval-continuation / submit-tool-result
      * continuation stream — those are continuations of the same logical chat turn. Cleared
      * on every terminal `finish` ChatEvent (the turn closed cleanly; any unmatched entries
-     * are stale and should not bleed into the next turn).
+     * are stale and should not bleed into the next turn). Attempted policy messages remain
+     * until result/turn cleanup because another concurrent settle for the same id may succeed.
      */
-    toolStartMs = new Map();
+    toolExecutionsByToolCallId = new Map();
     /**
      * Tracks the `(toolName, serverName?)` of every tool call currently awaiting
      * approval, keyed by `toolCallId`. Populated when a `tool-approval-request`
@@ -319,13 +322,22 @@ export class DefaultChatSession {
      *   before returning a stream result.
      * - WHEN `options.remember` is `true`, MUST append a `'deny'` `'remember'` rule and persist it
      *   BEFORE delegating the settle to the harness — symmetric with {@link approveToolCall}.
+     * - WHEN `options.reason` is present, MUST forward it without persisting a remembered rule,
+     *   including when untyped JavaScript also supplies `remember: true`.
+     * - A resolved organization-policy message MUST stay on the public tool result but be omitted
+     *   from derived telemetry and logs without suppressing unrelated tool diagnostics.
      */
     async declineToolCall(toolCallId, options) {
         this.assertNotDisposed();
         // issue #529 contract change: see `submitToolResult` for the rationale.
-        const policyWritten = await this.maybePersistRememberedRule(toolCallId, 'deny', options?.remember === true);
+        const reason = options?.reason;
+        const policyWritten = await this.maybePersistRememberedRule(toolCallId, 'deny', reason === undefined && options?.remember === true);
+        const trackedExecution = this.toolExecutionsByToolCallId.get(toolCallId);
+        if (reason !== undefined && trackedExecution !== undefined) {
+            (trackedExecution.policyMessages ??= new Set()).add(resolveToolDeclineModelMessage(reason));
+        }
         try {
-            await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
+            await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId, reason);
         }
         catch (err) {
             this.notifySettleRejection(err);
@@ -503,15 +515,15 @@ export class DefaultChatSession {
     }
     /**
      * Clears the per-turn tracking maps at a terminal `finish`. Both maps are
-     * scoped to one logical chat turn: `toolStartMs` pairs `tool-call` with
-     * `tool-result` for `tool-execution-completed.durationMs`, and
+     * scoped to one logical chat turn: `toolExecutionsByToolCallId` pairs a
+     * `tool-call` with its result for duration and policy-message redaction, and
      * `pendingApprovalsByToolCallId` lets a `remember` settle build the right
      * matcher. A stale entry surviving into the next turn would mispair a
      * duration or remember the wrong tool, so the two clears must always fire
      * together — hence one helper rather than two call sites.
      */
     clearPerTurnTracking() {
-        this.toolStartMs.clear();
+        this.toolExecutionsByToolCallId.clear();
         this.pendingApprovalsByToolCallId.clear();
     }
     /**
@@ -520,7 +532,7 @@ export class DefaultChatSession {
      * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
      *
      * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
-     * `tool-result` using `this.clock`. The tracking map (`this.toolStartMs`) lives on the
+     * `tool-result` using `this.clock`. The tracking map (`this.toolExecutionsByToolCallId`) lives on the
      * session, so a `tool-call` on the initial stream pairs with a `tool-result` on the
      * approval-continuation / submit-tool-result continuation stream — those are continuations
      * of the same logical chat turn. The map is cleared on every terminal `finish` ChatEvent
@@ -530,7 +542,7 @@ export class DefaultChatSession {
      */
     deriveToolTelemetry(event) {
         if (event.type === 'tool-call') {
-            this.toolStartMs.set(event.toolCallId, this.clock.now().getTime());
+            this.toolExecutionsByToolCallId.set(event.toolCallId, { startedAtMs: this.clock.now().getTime() });
             // No Tier-1 logBus sibling: tool-execution-started pairs 1:1 with
             // tool-execution-completed; the completion (isError=true) is the triage signal
             this.telemetryBus.emitTelemetry({
@@ -544,13 +556,16 @@ export class DefaultChatSession {
             });
         }
         else if (event.type === 'tool-result') {
-            const start = this.toolStartMs.get(event.toolCallId);
-            if (start === undefined)
+            const trackedExecution = this.toolExecutionsByToolCallId.get(event.toolCallId);
+            if (trackedExecution === undefined)
                 return;
-            this.toolStartMs.delete(event.toolCallId);
+            this.toolExecutionsByToolCallId.delete(event.toolCallId);
             const completedAt = this.clock.now();
-            const durationMs = completedAt.getTime() - start;
+            const durationMs = completedAt.getTime() - trackedExecution.startedAtMs;
             const isError = event.isError === true;
+            const observableError = typeof event.result === 'string' && trackedExecution.policyMessages?.has(event.result) === true
+                ? undefined
+                : event.error;
             this.telemetryBus.emitTelemetry({
                 type: 'tool-execution-completed',
                 agentId: this.agentId,
@@ -559,7 +574,7 @@ export class DefaultChatSession {
                 toolName: event.toolName,
                 durationMs,
                 isError,
-                ...(event.error ? { error: event.error } : {}),
+                ...(observableError ? { error: observableError } : {}),
                 ...(event.annotations ? { annotations: event.annotations } : {}),
                 ...(event.serverName ? { serverName: event.serverName } : {}),
             }, completedAt);
@@ -579,7 +594,7 @@ export class DefaultChatSession {
                         ...(event.annotations ? { annotations: event.annotations } : {}),
                         ...(event.serverName ? { serverName: event.serverName } : {}),
                     },
-                    ...(event.error ? { error: event.error } : {}),
+                    ...(observableError ? { error: observableError } : {}),
                 }, completedAt);
             }
         }

package/dist/harness/agent-harness.d.ts

@@ -3,7 +3,7 @@ import type { McpServerInfo, McpAuthProviders } from '../mcp-config.js';
 import type { ChatStreamResult } from '../types/events.js';
 import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
-import type { ToolResultInfo } from '../types/tools.js';
+import type { ToolDeclineReason, ToolResultInfo } from '../types/tools.js';
 import type { AgentHooks } from '../types/redaction.js';
 import type { WireCommunicationEventCallback } from '../types/wire-communication-event.js';
 import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
@@ -419,8 +419,9 @@ export interface AgentHarness {
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolCallId - ID of the tool call to decline.
+     * @param reason - Optional organization-policy reason to deliver to the model and terminal error result.
      */
-    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string, reason?: ToolDeclineReason): Promise<void>;
     /**
      * Retrieve message history for a thread.
      *

package/dist/harness/public.d.ts

@@ -51,3 +51,4 @@ export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
 export { GenSink } from './gen-sink.js';
 export { matchesAlwaysActive, validateAlwaysActiveEntry, type AlwaysActiveEntry } from './always-active.js';
 export { splitToolResultsIntoToolMessages, mergeToolResultsIntoAssistant } from './tool-message-normalizer.js';
+export { resolveToolDeclineModelMessage } from './tool-decline.js';

package/dist/harness/public.js

@@ -10,4 +10,5 @@ export { lowerStreamInput } from './stream-input.js';
 export { GenSink } from './gen-sink.js';
 export { matchesAlwaysActive, validateAlwaysActiveEntry } from './always-active.js';
 export { splitToolResultsIntoToolMessages, mergeToolResultsIntoAssistant } from './tool-message-normalizer.js';
+export { resolveToolDeclineModelMessage } from './tool-decline.js';
 //# sourceMappingURL=public.js.map

package/dist/harness/tool-decline.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDeclineReason } from '../types/tools.js';
+/** Resolves the terminal model-visible message for an organization-policy decline. */
+export declare function resolveToolDeclineModelMessage(reason: ToolDeclineReason): string;

package/dist/harness/tool-decline.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+const ORGANIZATION_POLICY_DECLINE_INVARIANT = 'This block is enforced by organization policy, not by the user. Do not retry this tool call or attempt the same action using another tool or command.';
+/** Resolves the terminal model-visible message for an organization-policy decline. */
+export function resolveToolDeclineModelMessage(reason) {
+    const customMessage = reason.modelMessage?.trim();
+    return customMessage
+        ? `${customMessage}\n\n${ORGANIZATION_POLICY_DECLINE_INVARIANT}`
+        : ORGANIZATION_POLICY_DECLINE_INVARIANT;
+}
+//# sourceMappingURL=tool-decline.js.map

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { Message, MessagePart, MessageRole, ImagePart, FilePart } from './types/messages.js';
 export type { JsonValue, SessionContext } from './types/session-context.js';
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolCallDeltaEvent, ToolApprovalRequestEvent, ToolResultEvent, ToolProgressEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
-export type { Decision, ToolDefinition, ToolCallInfo, ToolMatcher, ToolPolicyRule, ToolResultInfo, } from './types/tools.js';
+export type { DeclineToolCallOptions, Decision, ToolDeclineReason, ToolDefinition, ToolCallInfo, ToolMatcher, ToolPolicyRule, ToolResultInfo, } from './types/tools.js';
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
 export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';

package/dist/types/tools.d.ts

@@ -58,6 +58,19 @@ export type ToolDefinition = {
  *   `declineToolCall`.
  */
 export type Decision = 'allow' | 'deny' | 'require-approval';
+/** A model-visible explanation for a tool decline enforced outside the user approval flow. */
+export type ToolDeclineReason = {
+    kind: 'organization-policy';
+    modelMessage?: string;
+};
+/** Options for declining a pending tool call. Policy declines cannot create remembered user rules. */
+export type DeclineToolCallOptions = {
+    remember?: boolean;
+    reason?: undefined;
+} | {
+    remember?: false;
+    reason: ToolDeclineReason;
+};
 /**
  * Structured matcher selecting which tool invocations a {@link ToolPolicyRule}
  * applies to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,13 +47,13 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.55.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.58.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.24.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.57.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.60.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.26.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
@@ -64,7 +64,7 @@
     "rimraf": "^6.1.3",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vitest": "^4.1.8"
   },
   "engines": {