@salesforce/sfdx-agent-harness-claude 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to `@salesforce/sfdx-agent-harness-claude` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.29.0] - 2026-07-14
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude**: cross-harness conformance test suite @W-23372341@ ([#663](https://github.com/forcedotcom/agentic-dx/pull/663))
+- **sdk,harness-mastra,harness-claude**: delete deprecated tool-approval surfaces @W-23090034 ([#637](https://github.com/forcedotcom/agentic-dx/pull/637))
+
+### Fixes
+- **harness-conformance**: static version instead of -dev.N so release check passes @W-23446682@ ([#670](https://github.com/forcedotcom/agentic-dx/pull/670))
+
+### Chores
+- **deps-dev**: bump typescript-eslint from 8.62.1 to 8.63.0 in the dev-dependencies group across 1 directory ([#665](https://github.com/forcedotcom/agentic-dx/pull/665))
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#659](https://github.com/forcedotcom/agentic-dx/pull/659))
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.22 to 1.6.23 in the vitest group ([#660](https://github.com/forcedotcom/agentic-dx/pull/660))
+- **deps-dev**: bump the vitest group across 1 directory with 3 updates ([#655](https://github.com/forcedotcom/agentic-dx/pull/655))
+
 ## [0.28.0] - 2026-07-08
 
 ### Fixes

package/README.md

@@ -29,8 +29,8 @@ const manager = await createAgentManager('/path/to/storage', harnessFactory, {
 
 Connectivity (gateway URL, JWT, headers, native model id) is resolved by an `AgentConnectivityResolver` on the SDK and
 handed to the harness as a `ModelConnectivityInfo` bag. The harness factory itself owns harness-only concerns
-(permission mode, tool-approval timeout, bypass list, query defaults). For BYOK / direct-Anthropic / LLMG-Express
-deployments use `ApiKeyConnectivityResolver`; for non-Salesforce hosts implement your own resolver. See the
+(permission mode, tool-approval timeout, query defaults). For BYOK / direct-Anthropic / LLMG-Express deployments use
+`ApiKeyConnectivityResolver`; for non-Salesforce hosts implement your own resolver. See the
 [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full resolver surface.
 
 See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
@@ -41,7 +41,7 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 | Export                          | Kind      | Description                                                                                                                                                                                                                                      |
 | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `ClaudeHarnessFactory`          | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                                                                                                           |
-| `ClaudeHarnessFactoryConfig`    | interface | Configuration for `ClaudeHarnessFactory` (`permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, deprecated `bypassApprovalTools`, `subprocessEnv`).                                                                               |
+| `ClaudeHarnessFactoryConfig`    | interface | Configuration for `ClaudeHarnessFactory` (`permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `subprocessEnv`).                                                                                                                 |
 | `CLAUDE_BUILT_IN_TOOL_POLICIES` | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `require-approval` rules for Claude's mutating built-ins `Bash` / `Edit` / `MultiEdit` / `Write` / `NotebookEdit`. |
 | `CLAUDE_BUILT_IN_TOOL_NAMES`    | const     | The five built-in tool names `CLAUDE_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                             |
 | `ClaudeHarnessPermissionMode`   | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                                                                                                      |
@@ -172,19 +172,14 @@ decision site: for each non-consumer tool it resolves a decision and acts on it:
 - **`require-approval`** — a `tool-approval-request` is emitted and the SDK hook parks until the consumer settles via
   `chatSession.approveToolCall(toolCallId)` / `declineToolCall(toolCallId)`.
 
-Gating is **opt-in**: it engages only when the agent's config sets `toolPolicies` or `defaultToolDecision`, or the
-`chat()` call sets the deprecated `requireToolApproval` or `batchApprovals`. With none configured, tools run without
-gating (no `PreToolUse` hook is installed), matching the SDK's "no policy ⇒ no gating" default. The harness adds
-`CLAUDE_BUILT_IN_TOOL_POLICIES` (`require-approval` rules for the mutating built-ins `Bash` / `Edit` / `MultiEdit` /
-`Write` / `NotebookEdit`) as the `tiers.harness` slice and the SDK's `skill_bridge` meta-tool rules as `allow` defaults,
-so capability-discovery never prompts and read-only built-ins (`Read` / `Glob` / `Grep` / `Task`) run free by absence.
-Consumer-executed tools (`AgentConfig.tools`) always bypass the gate — their execution is the consumer's responsibility
-via `submitToolResult`. Set `StreamOptions.batchApprovals: true` to surface parallel `require-approval` requests on one
-stream for a batch-approval UI.
-
-> `StreamOptions.requireToolApproval` is **deprecated** — superseded by per-tool `AgentConfig.toolPolicies`. It still
-> works for one release: a truthy value engages all-or-nothing gating (every non-consumer tool requires approval), and
-> `'batch'` maps onto `batchApprovals`.
+Gating is **opt-in**: it engages only when the agent's config sets `toolPolicies` or `defaultToolDecision`. With none
+configured, tools run without gating (no `PreToolUse` hook is installed), matching the SDK's "no policy ⇒ no gating"
+default. The harness adds `CLAUDE_BUILT_IN_TOOL_POLICIES` (`require-approval` rules for the mutating built-ins `Bash` /
+`Edit` / `MultiEdit` / `Write` / `NotebookEdit`) as the `tiers.harness` slice and the SDK's `skill_bridge` meta-tool
+rules as `allow` defaults, so capability-discovery never prompts and read-only built-ins (`Read` / `Glob` / `Grep` /
+`Task`) run free by absence. Consumer-executed tools (`AgentConfig.tools`) always bypass the gate — their execution is
+the consumer's responsibility via `submitToolResult`. Set `StreamOptions.batchApprovals: true` to surface parallel
+`require-approval` requests on one stream for a batch-approval UI.
 
 Unlike Mastra (which suspends every tool and re-stamps a declined native result), Claude's `deny` is the SDK's native
 `permissionDecision: 'deny'` — the Claude Agent SDK synthesizes the `tool_result(isError=true)` itself, so no
@@ -206,7 +201,7 @@ patterns. Single-tool approve / decline, parallel batches (`batchApprovals: true
 
 #### Abort signal
 
-When `StreamOptions.abortSignal` fires during an active turn with `requireToolApproval: true`:
+When `StreamOptions.abortSignal` fires during an active turn with approval gating on:
 
 - All pending permission Promises reject with an `AbortError`.
 - The underlying Claude subprocess is killed (existing `AbortController` wiring).
@@ -391,45 +386,16 @@ const agent = await manager.createAgent(projectRoot, {
 // `tool-approval-request`, regardless of any policy configured.
 ```
 
-This is the recommended pattern when the consumer wants identical behavior across Mastra and Claude. For Claude-only
-consumers who prefer to drive the built-in directly, see "Bypassing the approval gate for specific tools" below.
-
-### Bypassing the approval gate for specific tools (deprecated)
-
-> **Deprecated.** `ClaudeHarnessFactoryConfig.bypassApprovalTools` is superseded by per-tool `AgentConfig.toolPolicies`
-> (e.g. `definePolicy({ AskUserQuestion: 'allow' })`). It still works for one release — the harness runtime-merges the
-> list into the policy resolver as synthetic `'allow'` rules (the `tiers.factory` slice) and logs a once-per-process
-> warning pointing at `toolPolicies`. It is removed in a later phase. Prefer `toolPolicies` for new code.
-
-When gating is active, every built-in / MCP tool call reaches the `PreToolUse` hook, which resolves it against the
-policy resolver. (Consumer-declared tools from `AgentConfig.tools[i]` always bypass — see "Tool-approval policy" above.)
-`bypassApprovalTools` opts specific tool names to `'allow'`:
-
-```ts
-const harnessFactory = new ClaudeHarnessFactory({
-  permissionMode: 'bypassPermissions',
-  // DEPRECATED — equivalent to:
-  //   toolPolicies: definePolicy({ AskUserQuestion: 'allow' })
-  // Calls to these tools resolve to 'allow'; they still emit `tool-call` /
-  // `tool-result` ChatEvents so the consumer can drive UX off the `tool-call`.
-  bypassApprovalTools: ['AskUserQuestion'],
-});
-```
-
-The names become synthetic `{ type: 'builtin', name, decision: 'allow' }` rules in the resolver's `tiers.factory` slice.
-They sit below the SDK built-ins and the harness built-ins but above consumer `toolPolicies`, so a consumer `deny` of
-the same tool still wins (cross-tier deny-wins). Bare-name form only — consumer-declared tools already bypass via the
-always-on consumer-tool prefix, so the old dual-form (`mcp__sfdx-agent-sdk-consumer-tools__<name>`) expansion is no
-longer needed.
+This is the recommended pattern when the consumer wants identical behavior across Mastra and Claude. To auto-approve a
+specific built-in the consumer drives directly (e.g. `AskUserQuestion`), add an `'allow'` rule for it to
+`AgentConfig.toolPolicies` (e.g. `definePolicy({ AskUserQuestion: 'allow' })`) — it resolves to `'allow'` and still
+emits `tool-call` / `tool-result` ChatEvents so the consumer can drive UX off the `tool-call`.
 
 > **Note:** `permissionMode: 'plan'` denies mutating built-ins (`Edit`, `Write`, `Bash`, …) at the SDK's permission
 > cache rather than running them natively. Resolving such a tool to `'allow'` does not "unlock" it under plan mode — the
 > SDK still denies it. Plan mode applies to the whole subprocess; the policy resolver only chooses whether the harness's
 > coordinator gates the call.
 
-When `bypassApprovalTools` is undefined or empty and no `toolPolicies` / `defaultToolDecision` is set, gating is off and
-no `PreToolUse` hook is installed — no behavior change for existing consumers. (Consumer-declared tools always bypass.)
-
 ### Tool-result redaction
 
 Tool-result redaction is configured at the manager layer, not the factory. Pass a `hooksForAgent` callback to

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

@@ -37,10 +37,10 @@ export interface ClaudeApprovalCoordinatorOptions {
      * `tool_result(is_error=true)` natively, so no re-stamp is needed);
      * `'require-approval'` ⇒ emit `tool-approval-request` and park. The harness
      * supplies this (closing over the SDK's `resolveToolApprovalPolicy` +
-     * `CLAUDE_BUILT_IN_TOOL_POLICIES` + the deprecated `bypassApprovalTools`
-     * factory tier) only when its opt-in gating predicate engaged; the hook is
-     * wired iff this is present, so a missing resolver here can only be reached
-     * defensively (it falls back to `'require-approval'`).
+     * `CLAUDE_BUILT_IN_TOOL_POLICIES`) only when its opt-in gating predicate
+     * engaged; the hook is wired iff this is present, so a missing resolver
+     * here can only be reached defensively (it falls back to
+     * `'require-approval'`).
      */
     lookupPolicy?: (invocation: ToolInvocation) => Decision;
     /**

package/dist/claude-approval-coordinator.js

@@ -27,9 +27,9 @@ import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
  * `chat()`. There are no per-tool sinks and no `lastGenSinkStale` flag.
  *
  * Consumer-executed tools bypass the approval gate by construction
- * (issue #529 step 2b): `claude-query-options-builder.ts` adds the
- * consumer-tool wire prefix `mcp__sfdx-agent-sdk-consumer-tools__.*` to
- * the `bypassApprovalTools` matcher unconditionally, so the SDK skips
+ * (issue #529 step 2b): `claude-query-options-builder.ts` anchors the
+ * consumer-tool wire prefix `mcp__sfdx-agent-sdk-consumer-tools__.*` into
+ * the `PreToolUse` matcher's negative lookahead, so the SDK skips
  * `PreToolUse` for consumer tools entirely. This coordinator therefore
  * never sees a `PreToolUse` invocation for a consumer tool — the parker
  * path handles their lifecycle alone.

package/dist/claude-harness-factory.d.ts

@@ -5,36 +5,21 @@ import { type ClaudeAgentHarness } from './claude-harness.js';
  * Subset of the Claude SDK's `PermissionMode` enum that the harness supports.
  *
  * Excludes `'default'`, `'dontAsk'`, and `'auto'` because those require an
- * interactive prompt source that the harness does not provide. Use
- * `StreamOptions.requireToolApproval` for human-in-the-loop gating; the
- * harness overrides `permissionMode` to `'default'` per-turn when approval is
- * requested.
+ * interactive prompt source that the harness does not provide. Configure
+ * `AgentConfig.toolPolicies` / `defaultToolDecision` for human-in-the-loop
+ * gating; the harness wires the coordinator's `PreToolUse` hook per-turn when
+ * gating is active.
  */
 export type ClaudeHarnessPermissionMode = 'bypassPermissions' | 'acceptEdits' | 'plan';
 export interface ClaudeHarnessFactoryConfig {
     permissionMode: ClaudeHarnessPermissionMode;
     queryDefaults?: ClaudeQueryDefaults;
     /**
-     * How long to wait for a `requireToolApproval` consumer to call
+     * How long to wait for a consumer to call
      * `approveToolCall`/`declineToolCall` before auto-denying with interrupt.
      * Defaults to `600_000` (10 minutes), matching the Mastra MCP timeout.
      */
     toolApprovalTimeoutMs?: number;
-    /**
-     * @deprecated Use `AgentConfig.toolPolicies` (e.g.
-     * `definePolicy({ <tool>: 'allow' })`) instead. Runtime-merged into the
-     * tool-approval policy resolver as synthetic `'allow'` rules during the
-     * deprecation window; removed in Phase 4. Removing a name takes effect on
-     * the next stream (not persisted). A once-per-process `LogBus.warn` fires
-     * when a non-empty list is configured.
-     *
-     * Tool names that bypass the approval gate. Useful for built-ins like
-     * `AskUserQuestion` where the consumer drives the UX off the `tool-call`
-     * event directly and doesn't want a `tool-approval-request` for it. The
-     * subprocess runs these tools natively (per the factory-pinned
-     * `permissionMode`); they still emit `tool-call` / `tool-result` ChatEvents.
-     */
-    bypassApprovalTools?: string[];
     /**
      * Static operational environment variables to set on every Claude
      * subprocess spawn. Layered above the inherited host env (so these win

package/dist/claude-harness-factory.js

@@ -37,13 +37,7 @@ export class ClaudeHarnessFactory {
         // call site inside `ClaudeHarness` (createAgent, reconnect, updateAgent)
         // routes MCP HTTP transports through the same proxy-aware fetch.
         const mcpClientFactory = (config, orgJwt) => buildMcpClients(config, orgJwt, innerFetch);
-        return new ClaudeHarness(envBuilder, optionsBuilder, this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS, storageRootFolder, 
-        // `bypassApprovalTools` is now consumed by the harness (folded into
-        // the policy resolver as synthetic `tiers.factory` allow rules)
-        // rather than baked into a constructor-time options-builder regex —
-        // the matcher is per-stream now and the resolver is the decision
-        // site. Deprecated; removed in Phase 4.
-        { mcpClientFactory, bypassApprovalTools: this.config.bypassApprovalTools });
+        return new ClaudeHarness(envBuilder, optionsBuilder, this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS, storageRootFolder, { mcpClientFactory });
     }
 }
 //# sourceMappingURL=claude-harness-factory.js.map

package/dist/claude-harness-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAa1D,MAAM,gCAAgC,GAAG,OAAO,CAAC;AAiDjD,MAAM,OAAO,oBAAoB;IAYA;IAXpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,qBAAqB,CAAC,sBAAsB,EAAE,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,iBAAiB,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACtG,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAAC,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;QAC9G,iEAAiE;QACjE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,gBAAgB,GAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAChE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB;QACjB,oEAAoE;QACpE,gEAAgE;QAChE,oEAAoE;QACpE,iEAAiE;QACjE,wCAAwC;QACxC,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAC7E,CAAC;IACN,CAAC;CACJ"}
+{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAa1D,MAAM,gCAAgC,GAAG,OAAO,CAAC;AAkCjD,MAAM,OAAO,oBAAoB;IAYA;IAXpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,qBAAqB,CAAC,sBAAsB,EAAE,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,iBAAiB,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACtG,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAAC,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;QAC9G,iEAAiE;QACjE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,gBAAgB,GAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAChE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB,EACjB,EAAE,gBAAgB,EAAE,CACvB,CAAC;IACN,CAAC;CACJ"}

package/dist/claude-harness.d.ts

@@ -47,14 +47,6 @@ export interface ClaudeHarnessOptions {
     sessionStore?: DiskBackedSessionStore;
     mcpClientFactory?: typeof buildMcpClients;
     threadContextStore?: ThreadContextStore;
-    /**
-     * Deprecated `ClaudeHarnessFactoryConfig.bypassApprovalTools` names. The
-     * factory threads them here so the harness can fold them into the policy
-     * resolver as synthetic `'allow'` rules (the `tiers.factory` slice) during
-     * the deprecation window — runtime-merged, not persisted, removed in Phase
-     * 4. The deprecation `LogBus.warn` (once per process) fires from here.
-     */
-    bypassApprovalTools?: string[];
 }
 export declare class ClaudeHarness implements ClaudeAgentHarness {
     private readonly envBuilder;
@@ -94,13 +86,6 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
     private readonly mcpClientFactory;
     private readonly storageRootFolder;
     private shuttingDown;
-    /**
-     * Synthetic `'allow'` rules translated from the deprecated factory
-     * `bypassApprovalTools` list — the `tiers.factory` slice passed to
-     * `resolveToolApprovalPolicy`. Empty when no bypass list was configured;
-     * removed entirely in Phase 4. See {@link ClaudeHarnessOptions.bypassApprovalTools}.
-     */
-    private readonly bypassApprovalToolsFactoryTier;
     constructor(envBuilder: ClaudeQueryEnvBuilder, optionsBuilder: ClaudeQueryOptionsBuilder, toolApprovalTimeoutMs: number, storageRootFolder: string, opts?: ClaudeHarnessOptions);
     private coordinatorKey;
     /**
@@ -328,31 +313,19 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      */
     private buildPostToolUseRedactionHook;
     /**
-     * Phase 2b: decide whether the approval gate engages this turn and, if so,
-     * build the per-tool policy resolver the coordinator's `preToolUseHook`
-     * consults. Near-verbatim port of `MastraHarness.buildPolicyGate` so both
-     * harnesses share the same opt-in semantics and deprecation bridge.
+     * Decide whether the approval gate engages this turn and, if so, build the
+     * per-tool policy resolver the coordinator's `preToolUseHook` consults.
+     * Mirrors `MastraHarness.buildPolicyGate` so both harnesses share the same
+     * opt-in semantics.
      *
-     * Gating is **opt-in**. It engages when the consumer set any of:
-     *  - `config.toolPolicies` (non-empty),
-     *  - `config.defaultToolDecision`,
-     *  - the deprecated `StreamOptions.requireToolApproval` (any non-`false`
-     *    value — `deprecatedMode` is `'serial'` / `'batch'` / `undefined`), or
-     *  - `StreamOptions.batchApprovals: true`.
+     * Gating is **opt-in**. It engages when the consumer set either:
+     *  - `config.toolPolicies` (non-empty), or
+     *  - `config.defaultToolDecision`.
      *
-     * When none are set, returns `{ lookupPolicy: undefined }` — the caller
+     * When neither is set, returns `{ lookupPolicy: undefined }` — the caller
      * omits the `PreToolUse` hook and tools run free (the SDK's "no policy ⇒ no
      * gating" back-compat invariant), with no per-tool hook round-trip.
      *
-     * **Deprecation bridge.** When the gate engages *only* because the
-     * deprecated `requireToolApproval` was truthy (no `toolPolicies`, no
-     * `defaultToolDecision`), the effective default must be `'require-approval'`
-     * — legacy all-or-none — not the resolver's `'allow'` default. Built-in
-     * allow-rules (the skill_bridge meta-tools) and any consumer `toolPolicies`
-     * still win via within-tier last-wins / cross-tier deny-wins, so the
-     * capability-discovery meta-tools stay auto-approved even under legacy
-     * gating.
-     *
      * **Live config read (#638).** `lookupPolicy` reads `agentState.config` on
      * every call rather than closing over a snapshot taken at stream start. A
      * mid-turn `updateAgentConfig` — notably the `source: 'remember'` rule an
@@ -363,22 +336,12 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      * auto-resolve subsequent matching tool calls within the same turn. Mirrors
      * `MastraHarness.buildPolicyGate`.
      *
-     * Two decisions stay **frozen at stream start** and MUST NOT be recomputed
-     * live:
-     *  - `gatingActive` — the turn either installed the `PreToolUse` hook or it
-     *    didn't; gating cannot begin mid-turn. The closure is built (and
-     *    returned) iff gating engaged now.
-     *  - `applyLegacyBridge` (`!hasPolicy && legacyGating`) — whether the
-     *    deprecation bridge injects `defaultToolDecision: 'require-approval'`.
-     *    If this were recomputed live, the FIRST remembered rule would flip
-     *    `hasPolicy` false→true, turn the bridge OFF mid-turn, and silently drop
-     *    the effective default back to the resolver's `'allow'` — auto-approving
-     *    every remaining legacy-gated tool. Freezing the boolean and applying it
-     *    to the live config preserves legacy all-or-none semantics while still
-     *    honoring any rule the turn appends.
+     * `gatingActive` stays **frozen at stream start** — the turn either
+     * installed the `PreToolUse` hook or it didn't; gating cannot begin
+     * mid-turn. The closure is built (and returned) iff gating engaged now.
      *
-     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
-     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     * `batchApprovals` is the serial-vs-batch emission axis, read straight off
+     * `StreamOptions.batchApprovals`.
      */
     private buildPolicyGate;
     stream(agentId: string, threadId: string, message: string | MessagePart[], streamOptions?: StreamOptions): Promise<ChatStreamResult>;

package/dist/claude-harness.js

@@ -5,7 +5,7 @@
 import { appendFile, mkdir, realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { RealClock, UUIDGenerator, backfillCreatedAt, buildSummaryPrompt, getErrorMessage, isAbortError, } from '@salesforce/agentic-common';
-import { AgentSDKError, AgentSDKErrorType, McpServerStatus, resolveToolApprovalMode, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
+import { AgentSDKError, AgentSDKErrorType, McpServerStatus, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
 import { HarnessBusOwner, lowerStreamInput, matchesAlwaysActive, mcpServerConfigEqual, splitToolResultsIntoToolMessages, validateAlwaysActiveEntry, } from '@salesforce/sfdx-agent-sdk/harness';
 import { validateMultimodalFiles } from '@salesforce/sfdx-agent-sdk';
 import { deleteSession, forkSession, getSessionMessages, listSessions, query, } from '@anthropic-ai/claude-agent-sdk';
@@ -86,13 +86,6 @@ export class ClaudeHarness {
     mcpClientFactory;
     storageRootFolder;
     shuttingDown = false;
-    /**
-     * Synthetic `'allow'` rules translated from the deprecated factory
-     * `bypassApprovalTools` list — the `tiers.factory` slice passed to
-     * `resolveToolApprovalPolicy`. Empty when no bypass list was configured;
-     * removed entirely in Phase 4. See {@link ClaudeHarnessOptions.bypassApprovalTools}.
-     */
-    bypassApprovalToolsFactoryTier;
     constructor(envBuilder, optionsBuilder, toolApprovalTimeoutMs, storageRootFolder, opts = {}) {
         this.envBuilder = envBuilder;
         this.optionsBuilder = optionsBuilder;
@@ -109,28 +102,6 @@ export class ClaudeHarness {
         this.threadContextStore =
             opts.threadContextStore ?? new ThreadContextStore(storageRootFolder, this.buses.getLogBus());
         this.mcpClientFactory = opts.mcpClientFactory ?? buildMcpClients;
-        // Translate the deprecated `bypassApprovalTools` factory list into
-        // synthetic `'allow'` rules (the resolver's `tiers.factory` slice).
-        // Bare-name `builtin` matchers only: the always-on consumer-tool prefix
-        // bypass in the options builder's matcher already covers the
-        // consumer-tool-by-name case the old dual-form expansion served, so the
-        // bridge-prefixed form is unnecessary under the resolver. `source` is
-        // `'built-in'` (not `'agent-config'`) because these are harness-injected
-        // — "which tier fired" telemetry should attribute the bypass to the
-        // harness, not the consumer's AgentConfig.
-        const bypassNames = opts.bypassApprovalTools ?? [];
-        this.bypassApprovalToolsFactoryTier = Object.freeze(bypassNames.map((name) => ({
-            matcher: { type: 'builtin', name },
-            decision: 'allow',
-            source: 'built-in',
-        })));
-        if (bypassNames.length > 0) {
-            this.buses
-                .getLogBus()
-                ?.warn('ClaudeHarnessFactoryConfig.bypassApprovalTools is deprecated; it is runtime-merged into the ' +
-                'tool-approval policy resolver as synthetic allow rules and will be removed. Migrate to ' +
-                'AgentConfig.toolPolicies (e.g. definePolicy({ <tool>: "allow" })).', { bypassApprovalTools: bypassNames });
-        }
     }
     coordinatorKey(agentId, threadId) {
         return `${agentId}::${threadId}`;
@@ -1048,31 +1019,19 @@ export class ClaudeHarness {
         };
     }
     /**
-     * Phase 2b: decide whether the approval gate engages this turn and, if so,
-     * build the per-tool policy resolver the coordinator's `preToolUseHook`
-     * consults. Near-verbatim port of `MastraHarness.buildPolicyGate` so both
-     * harnesses share the same opt-in semantics and deprecation bridge.
+     * Decide whether the approval gate engages this turn and, if so, build the
+     * per-tool policy resolver the coordinator's `preToolUseHook` consults.
+     * Mirrors `MastraHarness.buildPolicyGate` so both harnesses share the same
+     * opt-in semantics.
      *
-     * Gating is **opt-in**. It engages when the consumer set any of:
-     *  - `config.toolPolicies` (non-empty),
-     *  - `config.defaultToolDecision`,
-     *  - the deprecated `StreamOptions.requireToolApproval` (any non-`false`
-     *    value — `deprecatedMode` is `'serial'` / `'batch'` / `undefined`), or
-     *  - `StreamOptions.batchApprovals: true`.
+     * Gating is **opt-in**. It engages when the consumer set either:
+     *  - `config.toolPolicies` (non-empty), or
+     *  - `config.defaultToolDecision`.
      *
-     * When none are set, returns `{ lookupPolicy: undefined }` — the caller
+     * When neither is set, returns `{ lookupPolicy: undefined }` — the caller
      * omits the `PreToolUse` hook and tools run free (the SDK's "no policy ⇒ no
      * gating" back-compat invariant), with no per-tool hook round-trip.
      *
-     * **Deprecation bridge.** When the gate engages *only* because the
-     * deprecated `requireToolApproval` was truthy (no `toolPolicies`, no
-     * `defaultToolDecision`), the effective default must be `'require-approval'`
-     * — legacy all-or-none — not the resolver's `'allow'` default. Built-in
-     * allow-rules (the skill_bridge meta-tools) and any consumer `toolPolicies`
-     * still win via within-tier last-wins / cross-tier deny-wins, so the
-     * capability-discovery meta-tools stay auto-approved even under legacy
-     * gating.
-     *
      * **Live config read (#638).** `lookupPolicy` reads `agentState.config` on
      * every call rather than closing over a snapshot taken at stream start. A
      * mid-turn `updateAgentConfig` — notably the `source: 'remember'` rule an
@@ -1083,49 +1042,26 @@ export class ClaudeHarness {
      * auto-resolve subsequent matching tool calls within the same turn. Mirrors
      * `MastraHarness.buildPolicyGate`.
      *
-     * Two decisions stay **frozen at stream start** and MUST NOT be recomputed
-     * live:
-     *  - `gatingActive` — the turn either installed the `PreToolUse` hook or it
-     *    didn't; gating cannot begin mid-turn. The closure is built (and
-     *    returned) iff gating engaged now.
-     *  - `applyLegacyBridge` (`!hasPolicy && legacyGating`) — whether the
-     *    deprecation bridge injects `defaultToolDecision: 'require-approval'`.
-     *    If this were recomputed live, the FIRST remembered rule would flip
-     *    `hasPolicy` false→true, turn the bridge OFF mid-turn, and silently drop
-     *    the effective default back to the resolver's `'allow'` — auto-approving
-     *    every remaining legacy-gated tool. Freezing the boolean and applying it
-     *    to the live config preserves legacy all-or-none semantics while still
-     *    honoring any rule the turn appends.
+     * `gatingActive` stays **frozen at stream start** — the turn either
+     * installed the `PreToolUse` hook or it didn't; gating cannot begin
+     * mid-turn. The closure is built (and returned) iff gating engaged now.
      *
-     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
-     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     * `batchApprovals` is the serial-vs-batch emission axis, read straight off
+     * `StreamOptions.batchApprovals`.
      */
-    buildPolicyGate(agentState, streamOptions, deprecatedMode) {
+    buildPolicyGate(agentState, streamOptions) {
         const config = agentState.config;
-        const hasPolicy = (config.toolPolicies?.length ?? 0) > 0 || config.defaultToolDecision !== undefined;
-        const legacyGating = deprecatedMode !== undefined;
-        const batchApprovals = streamOptions?.batchApprovals === true || deprecatedMode === 'batch';
-        const gatingActive = hasPolicy || legacyGating || batchApprovals;
+        const gatingActive = (config.toolPolicies?.length ?? 0) > 0 || config.defaultToolDecision !== undefined;
         if (!gatingActive) {
             return { batchApprovals: false };
         }
-        // Freeze the deprecation-bridge decision at stream start (see JSDoc) —
-        // whether to inject `defaultToolDecision: 'require-approval'` must not
-        // change when a mid-turn remember rule flips `hasPolicy`.
-        const applyLegacyBridge = !hasPolicy && legacyGating;
-        const lookupPolicy = (invocation) => {
-            // Read the config live so a mid-turn `updateAgentConfig` (e.g. a
-            // remembered rule) is honored for the rest of this turn.
-            const liveConfig = agentState.config;
-            const resolverConfig = applyLegacyBridge
-                ? { ...liveConfig, defaultToolDecision: 'require-approval' }
-                : liveConfig;
-            return resolveToolApprovalPolicy(invocation, resolverConfig, {
-                harness: CLAUDE_BUILT_IN_TOOL_POLICIES,
-                factory: this.bypassApprovalToolsFactoryTier,
-            }).decision;
-        };
-        return { lookupPolicy, batchApprovals };
+        const lookupPolicy = (invocation) => 
+        // Read the config live so a mid-turn `updateAgentConfig` (e.g. a
+        // remembered rule) is honored for the rest of this turn (#638).
+        resolveToolApprovalPolicy(invocation, agentState.config, {
+            harness: CLAUDE_BUILT_IN_TOOL_POLICIES,
+        }).decision;
+        return { lookupPolicy, batchApprovals: streamOptions?.batchApprovals === true };
     }
     async stream(agentId, threadId, message, streamOptions) {
         const agentState = this.agents.get(agentId);
@@ -1163,13 +1099,11 @@ export class ClaudeHarness {
         const lookup = (toolName) => lookupMcpToolMetadata(agentState.mcpServers, toolName);
         const adapter = new ClaudeEventAdapter(this.buses.getLogBus(), lookup);
         const controller = new AbortController();
-        // Phase 2b: resolve whether the approval gate engages this turn and, if
-        // so, build the per-tool policy resolver the coordinator consults.
-        // `resolveToolApprovalMode` still validates the deprecated
-        // `requireToolApproval` union (throws on garbage) and yields the
-        // serial/batch axis; gating itself is opt-in via `buildPolicyGate`.
-        const deprecatedMode = resolveToolApprovalMode(streamOptions?.requireToolApproval);
-        const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, streamOptions, deprecatedMode);
+        // Resolve whether the approval gate engages this turn and, if so, build
+        // the per-tool policy resolver the coordinator consults. Gating is
+        // opt-in via `buildPolicyGate` — active only when the consumer set
+        // `toolPolicies` or `defaultToolDecision`.
+        const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, streamOptions);
         const gatingActive = lookupPolicy !== undefined;
         const consumerTools = config.tools ?? [];
         // Always allocate a coordinator per turn (issue #591). The
@@ -1410,6 +1344,13 @@ export class ClaudeHarness {
      * onto the same `initial` sink the consumer is iterating from `chat()`.
      */
     async submitToolResult(agentId, threadId, toolResult) {
+        // Unknown agent → AGENT_NOT_FOUND first, so an unregistered agent is
+        // distinguishable from a registered agent with no in-flight run (#464
+        // cross-harness contract; matches Mastra's two-tier distinction and the
+        // shared conformance table in `@salesforce/harness-conformance`).
+        if (!this.agents.has(agentId)) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
         const coordinator = this.coordinators.get(this.coordinatorKey(agentId, threadId));
         if (!coordinator) {
             throw new Error(`ClaudeHarness.submitToolResult(): no active consumer-tool stream for thread "${threadId}" on agent "${agentId}"`);
@@ -1420,6 +1361,10 @@ export class ClaudeHarness {
         coordinator.submitToolResult(toolResult.toolCallId, toolResult.result, toolResult.isError);
     }
     async approveToolCall(agentId, threadId, toolCallId) {
+        // Unknown agent → AGENT_NOT_FOUND first (see submitToolResult above).
+        if (!this.agents.has(agentId)) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
         const coordinator = this.coordinators.get(this.coordinatorKey(agentId, threadId));
         if (!coordinator) {
             throw new Error(`ClaudeHarness.approveToolCall(): no active approval session for thread "${threadId}" on agent "${agentId}"`);
@@ -1427,6 +1372,10 @@ export class ClaudeHarness {
         coordinator.approve(toolCallId);
     }
     async declineToolCall(agentId, threadId, toolCallId) {
+        // Unknown agent → AGENT_NOT_FOUND first (see submitToolResult above).
+        if (!this.agents.has(agentId)) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
         const coordinator = this.coordinators.get(this.coordinatorKey(agentId, threadId));
         if (!coordinator) {
             throw new Error(`ClaudeHarness.declineToolCall(): no active approval session for thread "${threadId}" on agent "${agentId}"`);