@salesforce/sfdx-agent-sdk 0.15.0 → 0.17.0

package/dist/agent-manager.d.ts

@@ -3,6 +3,7 @@ import { type AgentHarness, type ConfigOf } from './harness/agent-harness.js';
 import type { HarnessFactory } from './harness/harness-factory.js';
 import { type AgentConfig } from './harness/harness-config.js';
 import { type Agent } from './agent.js';
+import type { HooksForAgent } from './types/redaction.js';
 import type { TelemetryEventCallback } from './types/telemetry-events.js';
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
@@ -124,6 +125,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
     private readonly harness;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
+    private readonly hooksForAgent;
     private readonly clock;
     private readonly identityStore;
     private readonly agents;
@@ -144,7 +146,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static __build<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    static __build<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
     private init;
     shutdown(): Promise<void>;
     createAgent(projectRoot: string, config?: ConfigOf<H> & {
@@ -189,14 +191,25 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
  * function returns; failures are queryable via
  * {@link AgentManager.getRestoreFailures}.
  *
- * The optional `connectivityResolver` overrides the default
- * `DefaultAgentConnectivityResolver` — used by e2e tests and custom-auth
- * deployments where the SDK should not run sf-CLI-based org resolution.
- * Production callers leave it unset.
+ * The optional third-positional `options` bag carries the SDK's per-manager
+ * opt-ins. Production callers typically leave it unset:
+ *
+ * - `connectivityResolver` — overrides the default
+ *   `DefaultAgentConnectivityResolver`; used by e2e tests and custom-auth
+ *   deployments where the SDK should not run sf-CLI-based org resolution.
+ * - `hooksForAgent` — sync callback resolving a per-agent
+ *   {@link AgentHooks} bag (today carries `onToolResult`); invoked once per
+ *   `createAgent`, boot-time restore, and `Agent.updateAgentConfig`. The
+ *   resolved bag threads through to `AgentHarness.createAgent`'s
+ *   `options.hooks` and reaches the harness's native seam (Claude
+ *   `PostToolUse`, Mastra `processInputStep`).
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager<H>>;
+export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, options?: {
+    connectivityResolver?: AgentConnectivityResolver;
+    hooksForAgent?: HooksForAgent;
+}): Promise<AgentManager<H>>;

package/dist/agent-manager.js

@@ -25,6 +25,7 @@ export class DefaultAgentManager {
     harness;
     agentIdGenerator;
     agentConnectivityResolver;
+    hooksForAgent;
     clock;
     identityStore;
     agents = new Map();
@@ -34,9 +35,10 @@ export class DefaultAgentManager {
     router;
     unroutedUnsubs;
     disposed = false;
-    constructor(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus) {
+    constructor(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus) {
         this.harness = harness;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
         this.agentIdGenerator = agentIdGenerator;
         this.clock = clock;
@@ -57,9 +59,9 @@ export class DefaultAgentManager {
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static async __build(harness, agentConnectivityResolver, storageRootFolder, agentIdGenerator, clock, logBus) {
+    static async __build(harness, agentConnectivityResolver, hooksForAgent, storageRootFolder, agentIdGenerator, clock, logBus) {
         const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
-        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus);
+        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus);
         await manager.init();
         return manager;
     }
@@ -155,9 +157,10 @@ export class DefaultAgentManager {
             throw new Error(`projectRoot is not a directory: "${projectRoot}"`);
         }
         const runtime = await this.agentConnectivityResolver.resolve(projectRoot, config);
-        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : undefined);
+        const hooks = this.hooksForAgent?.(agentId, config) ?? {};
+        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks });
         const agentSlice = this.router.registerAgent(agentId);
-        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         this.telemetryBus.emit({
             type: 'agent-created',
@@ -262,17 +265,25 @@ export class DefaultAgentManager {
  * function returns; failures are queryable via
  * {@link AgentManager.getRestoreFailures}.
  *
- * The optional `connectivityResolver` overrides the default
- * `DefaultAgentConnectivityResolver` — used by e2e tests and custom-auth
- * deployments where the SDK should not run sf-CLI-based org resolution.
- * Production callers leave it unset.
+ * The optional third-positional `options` bag carries the SDK's per-manager
+ * opt-ins. Production callers typically leave it unset:
+ *
+ * - `connectivityResolver` — overrides the default
+ *   `DefaultAgentConnectivityResolver`; used by e2e tests and custom-auth
+ *   deployments where the SDK should not run sf-CLI-based org resolution.
+ * - `hooksForAgent` — sync callback resolving a per-agent
+ *   {@link AgentHooks} bag (today carries `onToolResult`); invoked once per
+ *   `createAgent`, boot-time restore, and `Agent.updateAgentConfig`. The
+ *   resolved bag threads through to `AgentHarness.createAgent`'s
+ *   `options.hooks` and reaches the harness's native seam (Claude
+ *   `PostToolUse`, Mastra `processInputStep`).
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export async function createAgentManager(storageRootFolder, harnessFactory, connectivityResolver) {
+export async function createAgentManager(storageRootFolder, harnessFactory, options) {
     let stats;
     try {
         stats = await stat(storageRootFolder);
@@ -306,8 +317,8 @@ export async function createAgentManager(storageRootFolder, harnessFactory, conn
             `advertised version ${factoryVersion} (SDK supports: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}). ` +
             `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
     }
-    const agentConnectivityResolver = connectivityResolver ?? new DefaultAgentConnectivityResolver();
-    return DefaultAgentManager.__build(harness, agentConnectivityResolver, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
+    const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
+    return DefaultAgentManager.__build(harness, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/dist/agent.d.ts

@@ -7,6 +7,7 @@ import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gatewa
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
+import type { HooksForAgent } from './types/redaction.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
 /**
  * Parent bus pair wired at construction time so an agent's events bubble upward into the manager's buses.
@@ -44,8 +45,13 @@ export interface Agent {
     /**
      * Request a reconnect of one MCP server on this agent without recycling
      * any other server, custom tool, instruction, or skill. Useful for
-     * recovering a single failed MCP server without paying the full
-     * `updateAgentConfig` destroy/recreate cost.
+     * recovering a single failed MCP server after a transport-level error
+     * (e.g. JWT-rotation timing on stdio servers, transient EOF on remote
+     * transports). For the diff-driven case — `Agent.updateAgentConfig`
+     * applying a new `MCPConfiguration` — the harness already preserves any
+     * server whose config is structurally unchanged and cycles only the
+     * changed/added/removed servers; an explicit `reconnectMcpServer` call
+     * is **not** required there.
      *
      * Throws if `serverName` is not configured on this agent or if the named
      * server is disabled (`enabled: false`).
@@ -132,6 +138,7 @@ export declare class DefaultAgent implements Agent {
     private orgConnection;
     private orgJwt;
     private readonly agentConnectivityResolver;
+    private readonly hooksForAgent;
     private readonly identityStore;
     private readonly sessions;
     private readonly sessionSliceUnregisters;
@@ -152,13 +159,17 @@ export declare class DefaultAgent implements Agent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
+     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
+     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
+     *     the consumer didn't pass a `hooksForAgent`.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements
      * - MUST return the agent's ID.
@@ -178,11 +189,17 @@ export declare class DefaultAgent implements Agent {
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
-     * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
-     * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
-     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
-     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
+     * - MUST apply the merged config to the harness via `this.harness.updateAgent(...)` — a single primitive
+     *   that preserves any MCP client whose `MCPServerConfig` is structurally equal to the currently-applied one.
+     *   The destroy+recreate shape this method used pre-#541 closed every MCP client on a model-only or
+     *   instructions-only or org-connect-only change; the new shape preserves them and only cycles servers
+     *   that actually changed.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after `harness.updateAgent` succeeds
+     *   and before the in-memory swaps, so a write failure rolls back through the same catch path as an
+     *   `updateAgent` failure.
+     * - MUST preserve the previous in-memory config state if `updateAgent` or persistence fails. Rollback
+     *   uses the same `harness.updateAgent` primitive against the previous config — the harness re-diffs
+     *   against its current (possibly partially-updated) state and reverts only the actual deltas.
      */
     updateAgentConfig(config?: AgentConfig, options?: {
         abortSignal?: AbortSignal;

package/dist/agent.js

@@ -21,6 +21,7 @@ export class DefaultAgent {
     orgConnection;
     orgJwt;
     agentConnectivityResolver;
+    hooksForAgent;
     identityStore;
     sessions = new Map();
     sessionSliceUnregisters = new Map();
@@ -41,13 +42,17 @@ export class DefaultAgent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
+     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
+     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
+     *     the consumer didn't pass a `hooksForAgent`.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
@@ -56,6 +61,7 @@ export class DefaultAgent {
         this.orgConnection = orgConnection;
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
@@ -100,11 +106,17 @@ export class DefaultAgent {
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
-     * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
-     * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
-     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
-     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
+     * - MUST apply the merged config to the harness via `this.harness.updateAgent(...)` — a single primitive
+     *   that preserves any MCP client whose `MCPServerConfig` is structurally equal to the currently-applied one.
+     *   The destroy+recreate shape this method used pre-#541 closed every MCP client on a model-only or
+     *   instructions-only or org-connect-only change; the new shape preserves them and only cycles servers
+     *   that actually changed.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after `harness.updateAgent` succeeds
+     *   and before the in-memory swaps, so a write failure rolls back through the same catch path as an
+     *   `updateAgent` failure.
+     * - MUST preserve the previous in-memory config state if `updateAgent` or persistence fails. Rollback
+     *   uses the same `harness.updateAgent` primitive against the previous config — the harness re-diffs
+     *   against its current (possibly partially-updated) state and reverts only the actual deltas.
      */
     async updateAgentConfig(config = {}, options) {
         this.assertNotDisposed();
@@ -129,13 +141,14 @@ export class DefaultAgent {
             // (If modelId is omitted, the resolver pinned the default at creation time.)
             nextClient.setModel(nextModel);
         }
-        await this.harness.destroyAgent(this.agentId);
-        let nextConfigRegistered = false;
         try {
-            await this.harness.createAgent(this.agentId, this.projectRoot, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), options);
-            nextConfigRegistered = true;
+            const nextHooks = this.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            await this.harness.updateAgent(this.agentId, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), {
+                ...(options?.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
+                hooks: nextHooks,
+            });
             // Persist before the in-memory swaps so a write failure flows through the same
-            // catch block as a recreate failure: the rollback restores the harness with
+            // catch block as an updateAgent failure: the rollback re-runs updateAgent against
             // previousConfig and disk state remains the pre-update record.
             await this.identityStore.write(this.agentId, this.projectRoot, nextConfig);
             this.config = nextConfig;
@@ -158,15 +171,11 @@ export class DefaultAgent {
                 if (nextClient === previousClient) {
                     previousClient.setModel(previousModel);
                 }
-                // Clear nextConfig registration only when the harness recreate
-                // actually succeeded (identityStore.write-failure path) — the
-                // harness throws on unknown id, so calling destroyAgent on the
-                // harness-recreate-failure path would short-circuit the rollback
-                // createAgent below.
-                if (nextConfigRegistered) {
-                    await this.harness.destroyAgent(this.agentId);
-                }
-                await this.harness.createAgent(this.agentId, this.projectRoot, previousClient, toHarnessConfig(previousConfig, previousOrgJwt));
+                // Re-apply the previous config through the same primitive. The harness re-diffs
+                // against its current state — if updateAgent partially applied (e.g. some MCP
+                // servers were already cycled), reverting via updateAgent restores them too.
+                const previousHooks = this.hooksForAgent?.(this.agentId, previousConfig) ?? {};
+                await this.harness.updateAgent(this.agentId, previousClient, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
             }
             catch {
                 // Ignore restoration errors; rethrow the original failure.

package/dist/chat-session.d.ts

@@ -62,11 +62,17 @@ export interface ChatSession {
      *
      * "Client-side tool" means a tool you declared in {@link AgentConfig.tools}
      * without an `execute` function — the SDK registers its name + schema with the
-     * model but does not run it. When the model calls one, the chat eventStream
-     * emits a `tool-call` event and ends with `finishReason: 'tool-calls'`. Your
-     * application runs the tool however it likes (HTTP call, DB query, UI prompt,
-     * etc.) and calls this method with the result; the agent loop resumes and
-     * produces its next turn on the returned `ChatStreamResult.eventStream`.
+     * model but does not run it. When the model calls one, the chat `eventStream`
+     * emits a `tool-call` event. Your application runs the tool however it likes
+     * (HTTP call, DB query, UI prompt, etc.) and calls this method with the result;
+     * the agent loop resumes and the post-resume events (`tool-result`, model
+     * follow-up text, terminal `finish`) arrive on the **same** `eventStream`
+     * the original {@link chat} call returned. The consumer keeps iterating it.
+     *
+     * Returns `Promise<void>` once the harness has accepted the result. The
+     * promise rejects on pre-stream failure (the `chat()`-returned subscribers
+     * still observe `ErrorEvent` + `FinishEvent` before the rejection so the
+     * subscribe-side contract holds).
      *
      * Use this method ONLY for client-side tools. Tools provided via
      * {@link AgentConfig.mcpServers} are executed by the harness — their results
@@ -74,23 +80,22 @@ export interface ChatSession {
      * Human-in-the-loop approval of harness-executed tools uses
      * {@link approveToolCall} / {@link declineToolCall}, not this method.
      *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
-     *
      * @param toolResult - The completed tool execution result. `toolCallId` and
      *   `toolName` MUST match the values from the originating `tool-call` event.
      */
-    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(toolResult: ToolResultInfo): Promise<void>;
     /**
      * Approve a pending tool call, allowing the harness to execute it.
      * Called after receiving a `tool-approval-request` event from the stream.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * executes the approved tool, generates the model's follow-up response, and
-     * streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the approval. The
+     * harness then executes the tool and emits the resulting events
+     * (`tool-result`, model follow-up text, terminal `finish`) on the **same**
+     * `eventStream` the original {@link chat} call returned. The consumer keeps
+     * iterating it.
      *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     * The promise rejects on pre-stream failure; subscribers still observe
+     * `ErrorEvent` + `FinishEvent` on the chat stream before the rejection.
      *
      * @param toolCallId - ID of the pending tool call to approve.
      * @param options - Optional approval metadata.
@@ -101,21 +106,20 @@ export interface ChatSession {
      */
     approveToolCall(toolCallId: string, options?: {
         remember?: boolean;
-    }): Promise<ChatStreamResult>;
+    }): Promise<void>;
     /**
      * Decline a pending tool call. The stream resumes with the model
-     * acknowledging the decline and potentially suggesting alternatives.
+     * acknowledging the decline and potentially suggesting alternatives —
+     * those events arrive on the **same** `eventStream` the original
+     * {@link chat} call returned.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * cancels the pending tool call, generates the model's acknowledgement response,
-     * and streams both the text and events back to the caller.
-     *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     * Returns `Promise<void>` once the harness has accepted the decline. The
+     * promise rejects on pre-stream failure; subscribers still observe
+     * `ErrorEvent` + `FinishEvent` on the chat stream before the rejection.
      *
      * @param toolCallId - ID of the pending tool call to decline.
      */
-    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(toolCallId: string): Promise<void>;
     /**
      * Retrieve message history for this session.
      *
@@ -246,7 +250,7 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
      */
-    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(toolResult: ToolResultInfo): Promise<void>;
     /**
      * @requirements
      * - MUST yield each event from the provided `stream`.
@@ -290,7 +294,7 @@ export declare class DefaultChatSession implements ChatSession {
      */
     approveToolCall(toolCallId: string, _options?: {
         remember?: boolean;
-    }): Promise<ChatStreamResult>;
+    }): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.declineToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
@@ -302,7 +306,7 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
      */
-    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(toolCallId: string): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
@@ -395,5 +399,18 @@ export declare class DefaultChatSession implements ChatSession {
      * measures real elapsed time even for pre-stream rejections.
      */
     private notifyPreStreamError;
+    /**
+     * issue #529 contract change: a settle call (`approveToolCall` /
+     * `declineToolCall` / `submitToolResult`) rejected. The settle's
+     * Promise is the consumer's primary failure surface, but subscribers
+     * registered via {@link ChatSession.subscribe} also expect to observe
+     * `error + finish` events so a UI bound to the chat stream can
+     * render the failure. Emit those without firing
+     * `chat-stream-error` telemetry — chat-stream-* telemetry is owned
+     * by the chat() lifecycle, not by settle calls (issue #529: one
+     * chat-stream-started/completed/error pair per turn, not per
+     * settle).
+     */
+    private notifySettleRejection;
     private assertNotDisposed;
 }

package/dist/chat-session.js

@@ -109,16 +109,16 @@ export class DefaultChatSession {
      */
     async submitToolResult(toolResult) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('submit-tool-result');
+        // issue #529 contract change: settle calls are control messages on the
+        // existing chat() turn's stream — they don't open a new stream and
+        // they don't emit chat-stream-started/completed. The post-resume
+        // events flow through the harness's existing turn sink, which the
+        // consumer's chat()-returned eventStream is already iterating.
         try {
-            const result = await this.harness.submitToolResult(this.agentId, this.threadId, toolResult);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.submitToolResult(this.agentId, this.threadId, toolResult);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
     }
@@ -246,19 +246,17 @@ export class DefaultChatSession {
      */
     async approveToolCall(toolCallId, _options) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('approve-tool-call');
+        // issue #529 contract change: see `submitToolResult` for the rationale.
+        // Settle is a control message on the existing turn; events flow on
+        // the chat()-returned stream.
         try {
-            const result = await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
-            this.emitToolApprovalResolved(toolCallId, true);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
+        this.emitToolApprovalResolved(toolCallId, true);
     }
     /**
      * @requirements
@@ -273,19 +271,15 @@ export class DefaultChatSession {
      */
     async declineToolCall(toolCallId) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('decline-tool-call');
+        // issue #529 contract change: see `submitToolResult` for the rationale.
         try {
-            const result = await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
-            this.emitToolApprovalResolved(toolCallId, false);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
+        this.emitToolApprovalResolved(toolCallId, false);
     }
     /**
      * @requirements
@@ -527,6 +521,23 @@ export class DefaultChatSession {
             error,
         });
     }
+    /**
+     * issue #529 contract change: a settle call (`approveToolCall` /
+     * `declineToolCall` / `submitToolResult`) rejected. The settle's
+     * Promise is the consumer's primary failure surface, but subscribers
+     * registered via {@link ChatSession.subscribe} also expect to observe
+     * `error + finish` events so a UI bound to the chat stream can
+     * render the failure. Emit those without firing
+     * `chat-stream-error` telemetry — chat-stream-* telemetry is owned
+     * by the chat() lifecycle, not by settle calls (issue #529: one
+     * chat-stream-started/completed/error pair per turn, not per
+     * settle).
+     */
+    notifySettleRejection(err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.chatEventBus.emit({ type: 'error', error });
+        this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
+    }
     assertNotDisposed() {
         if (this.disposed) {
             throw new AgentSDKError('ChatSession has been disposed.', AgentSDKErrorType.DISPOSED);