@salesforce/sfdx-agent-harness-mastra 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.60.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.59.0] - 2026-08-28
 
 ### Fixes

package/README.md

@@ -249,6 +249,11 @@ Consumer-executed tools (`AgentConfig.tools`) always bypass the gate — their e
 via `submitToolResult`. Set `StreamOptions.batchApprovals: true` to surface parallel `require-approval` requests on one
 stream for a batch-approval UI.
 
+With `@mastra/core` 1.62.0, an organization-policy decline is passed through `agent.declineToolCall({ reason })`. Mastra
+emits one native `tool-output-denied` chunk; the adapter maps it to one `tool-result(isError=true)` carrying the same
+exact message the model sees. Automatic policy denies use `Denied by tool policy.`; reasonless consumer declines retain
+Mastra's `Tool call was not approved by the user` default.
+
 ### Tool approval timeout
 
 When the approval gate is engaged and a tool resolves to `require-approval`, the harness suspends the workflow on each

package/dist/mastra-approval-coordinator.d.ts

@@ -1,7 +1,7 @@
 import type { Agent } from '@mastra/core/agent';
 import type { RequestContext } from '@mastra/core/request-context';
 import type { ChunkType } from '@mastra/core/stream';
-import { type ChatEvent, type Decision as PolicyDecision, type McpToolAnnotations, type ToolInvocation, type WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+import { type ChatEvent, type Decision as PolicyDecision, type McpToolAnnotations, type ToolDeclineReason, type ToolInvocation, type WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
 import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
 import type { Clock, LogBus } from '@salesforce/agentic-common';
 /**
@@ -125,8 +125,8 @@ export interface MastraApprovalCoordinatorOptions {
  * Responsibilities:
  *  - Policy-driven approval gating (Phase 2a): for each non-consumer tool,
  *    consult `lookupPolicy` — `allow` silently approves, `deny` silently
- *    declines (the coordinator synthesizes a `tool-result(isError=true)` and
- *    drives `agent.declineToolCall` so the model sees the failed call),
+ *    declines through `agent.declineToolCall` so Mastra emits one native
+ *    `tool-output-denied` result for the model and event adapter,
  *    `require-approval` emits a `tool-approval-request` and drives
  *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
  *    settles. `batchApprovals` controls whether parallel `require-approval`
@@ -337,7 +337,7 @@ export declare class MastraApprovalCoordinator {
      */
     private teardown;
     approve(toolCallId: string): void;
-    decline(toolCallId: string): void;
+    decline(toolCallId: string, reason?: ToolDeclineReason): void;
     private recordDecision;
     /**
      * Parker callback the consumer-tool bridge `execute` handler invokes

package/dist/mastra-approval-coordinator.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import { AgentSDKError, AgentSDKErrorType, } from '@salesforce/sfdx-agent-sdk';
-import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+import { GenSink, resolveToolDeclineModelMessage } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraEventAdapter } from './mastra-event-adapter.js';
 import { SKILL_BRIDGE_SERVER_ID } from './skill-bridge.js';
 /**
@@ -22,13 +22,7 @@ function pickIdWithDecision(pendingIds, decisions) {
     }
     return undefined;
 }
-/**
- * Result text the coordinator stamps on the synthesized `tool-result` for a
- * policy-denied tool call. Matches the text Mastra folds into the model's
- * context on decline ("Tool call was not approved by the user") so the
- * consumer-facing event and the model's transcript stay consistent.
- */
-const POLICY_DENIED_RESULT_TEXT = 'Tool call was not approved by the user';
+const POLICY_DENIED_RESULT_TEXT = 'Denied by tool policy.';
 /**
  * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
  * `MastraStreamBroker` + `activeRuns` pair into one object owning a single
@@ -37,8 +31,8 @@ const POLICY_DENIED_RESULT_TEXT = 'Tool call was not approved by the user';
  * Responsibilities:
  *  - Policy-driven approval gating (Phase 2a): for each non-consumer tool,
  *    consult `lookupPolicy` — `allow` silently approves, `deny` silently
- *    declines (the coordinator synthesizes a `tool-result(isError=true)` and
- *    drives `agent.declineToolCall` so the model sees the failed call),
+ *    declines through `agent.declineToolCall` so Mastra emits one native
+ *    `tool-output-denied` result for the model and event adapter,
  *    `require-approval` emits a `tool-approval-request` and drives
  *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
  *    settles. `batchApprovals` controls whether parallel `require-approval`
@@ -353,8 +347,11 @@ export class MastraApprovalCoordinator {
     approve(toolCallId) {
         this.recordDecision('approve', toolCallId, { kind: 'approve' });
     }
-    decline(toolCallId) {
-        this.recordDecision('decline', toolCallId, { kind: 'decline' });
+    decline(toolCallId, reason) {
+        this.recordDecision('decline', toolCallId, {
+            kind: 'decline',
+            ...(reason ? { modelMessage: resolveToolDeclineModelMessage(reason) } : {}),
+        });
     }
     recordDecision(method, toolCallId, decision) {
         // Issue #589: idempotent settle. A tool call the coordinator
@@ -618,36 +615,12 @@ export class MastraApprovalCoordinator {
                         this.decisions.set(tc.toolCallId, { kind: 'approve' });
                     }
                     else if (decision === 'deny') {
-                        // Silent decline — no `tool-approval-request` surfaces.
-                        // The pump drives `agent.declineToolCall` so Mastra folds
-                        // the denial into the model's context (persisted as the
-                        // `role: 'tool'` message "Tool call was not approved by the
-                        // user"), letting the model recover on the resume stream.
-                        //
-                        // We synthesize the consumer-facing `tool-result(isError=true)`
-                        // ourselves rather than relying on Mastra to emit one:
-                        // @mastra/core 1.49 no longer emits a standalone
-                        // `tool-result` chunk on the decline-resume `fullStream`
-                        // (the denial text lives only inside the persisted
-                        // `messages.all` payload embedded in `step-finish`), so the
-                        // old "re-stamp Mastra's native result" path never fired and
-                        // the SDK `Decision` contract "a denied tool surfaces as
-                        // `tool-result(isError=true)`" was silently broken. Routing
-                        // it here — immediately after the already-routed `tool-call`
-                        // and before the decline resume — keeps the natural
-                        // tool-call → tool-result ordering the SDK telemetry deriver
-                        // matches on. The un-emitted approval is marked
-                        // coordinator-settled so a (spurious) consumer
-                        // `approveToolCall` for this id is a no-op rather than a
-                        // TOOL_CALL_NOT_FOUND throw.
+                        // Mastra emits the native `tool-output-denied` chunk
+                        // carrying this same reason on the resumed stream.
                         this.settledByCoordinator.add(tc.toolCallId);
-                        this.decisions.set(tc.toolCallId, { kind: 'decline' });
-                        this.routeEnriched({
-                            type: 'tool-result',
-                            toolCallId: tc.toolCallId,
-                            toolName: tc.toolName,
-                            result: POLICY_DENIED_RESULT_TEXT,
-                            isError: true,
+                        this.decisions.set(tc.toolCallId, {
+                            kind: 'decline',
+                            modelMessage: POLICY_DENIED_RESULT_TEXT,
                         });
                     }
                     else if (!this.batchApprovals && !this.emittedApprovals.has(tc.toolCallId)) {
@@ -710,6 +683,7 @@ export class MastraApprovalCoordinator {
                     toolCallId,
                     memory: this.memory,
                     requestContext: this.requestContext,
+                    ...(decision.modelMessage ? { reason: decision.modelMessage } : {}),
                 });
             // Post-await guard: abort/dispose may have fired during the
             // round-trip. Release the new run if so.

package/dist/mastra-event-adapter.d.ts

@@ -33,6 +33,7 @@ import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
  * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `tool-output-denied`    | `tool-result`             | `{ toolCallId, toolName, result: reason, isError: true}`|
  * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |
  * | `tool-call-delta`       | `tool-call-delta`         | `{ toolCallId, toolName?, argsTextDelta }`             |
  * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |

package/dist/mastra-event-adapter.js

@@ -35,6 +35,7 @@ import { isNetworkStreamError } from './stream-errors.js';
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
  * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `tool-output-denied`    | `tool-result`             | `{ toolCallId, toolName, result: reason, isError: true}`|
  * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |
  * | `tool-call-delta`       | `tool-call-delta`         | `{ toolCallId, toolName?, argsTextDelta }`             |
  * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |
@@ -117,6 +118,14 @@ export class MastraEventAdapter {
                     error,
                 };
             }
+            case 'tool-output-denied':
+                return {
+                    type: 'tool-result',
+                    toolCallId: chunk.payload.toolCallId,
+                    toolName: chunk.payload.toolName,
+                    result: chunk.payload.approval.reason ?? 'Tool call was not approved by the user',
+                    isError: true,
+                };
             case 'step-start':
                 return { type: 'step-start', stepIndex: this.stepIndex++ };
             case 'step-finish':

package/dist/mastra-harness.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MCPClient } from '@mastra/mcp';
-import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type McpAuthProviders, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type McpAuthProviders, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolDeclineReason, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
@@ -563,7 +563,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   except the coordinator drives `agent.declineToolCall()` instead of
      *   `agent.approveToolCall()`.
      */
-    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string, reason?: ToolDeclineReason): Promise<void>;
     private getCoordinatorOrThrow;
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -1751,9 +1751,12 @@ export class MastraHarness {
      *   except the coordinator drives `agent.declineToolCall()` instead of
      *   `agent.approveToolCall()`.
      */
-    async declineToolCall(agentId, threadId, toolCallId) {
+    async declineToolCall(agentId, threadId, toolCallId, reason) {
         const coordinator = this.getCoordinatorOrThrow(agentId, threadId, 'declineToolCall');
-        coordinator.decline(toolCallId);
+        if (reason)
+            coordinator.decline(toolCallId, reason);
+        else
+            coordinator.decline(toolCallId);
     }
     getCoordinatorOrThrow(agentId, threadId, method) {
         const agentState = this.getAgentStateOrThrow(agentId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,16 +42,16 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.60.0"
+    "@salesforce/sfdx-agent-sdk": "0.61.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.60.0",
+    "@salesforce/sfdx-agent-sdk": "0.61.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",
@@ -62,7 +62,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": {