@salesforce/sfdx-agent-harness-claude 0.45.0 → 0.47.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.47.0] - 2026-08-18
+
+### Features
+- **harness-claude**: opt-in approvalHookTimeoutMs to outlast SDK per-hook timeout @W-23848717@ ([#755](https://github.com/forcedotcom/agentic-dx/pull/755))
+
+### Chores
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#754](https://github.com/forcedotcom/agentic-dx/pull/754))
+- **deps-dev**: bump the dev-dependencies group with 2 updates ([#753](https://github.com/forcedotcom/agentic-dx/pull/753))
+
+## [0.46.0] - 2026-08-17
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: session-context contract + conformance gate @W-23632685@ ([#747](https://github.com/forcedotcom/agentic-dx/pull/747))
+
 ## [0.45.0] - 2026-08-14
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -51,7 +51,7 @@ cross-harness comparison.
 | 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`, `subprocessEnv`).                                                                                                                 |
+| `ClaudeHarnessFactoryConfig`    | interface | Configuration for `ClaudeHarnessFactory` (`permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `approvalHookTimeoutMs`, `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'`.                                                                                                                                                                      |
@@ -246,6 +246,13 @@ Each pending approval is auto-denied after `ClaudeHarnessFactoryConfig.toolAppro
 Calling `approveToolCall` or `declineToolCall` before the timeout cancels the timer — no spurious error event surfaces
 afterwards.
 
+> **SDK hook-timeout interaction:** `toolApprovalTimeoutMs` is the harness's own auto-deny timer, but the parked
+> approval is a Claude SDK `PreToolUse` hook, and the SDK aborts a hook after its own per-hook timeout (~60s) regardless
+> of the harness timer. A `toolApprovalTimeoutMs` above that default therefore does nothing on its own — the SDK tears
+> the hook down first. Set `ClaudeHarnessFactoryConfig.approvalHookTimeoutMs` (milliseconds; typically equal to
+> `toolApprovalTimeoutMs`) to raise the SDK's per-hook timeout so the parked approval survives long enough for the
+> harness timer to own the deadline. Left unset, the SDK default is preserved.
+
 > **Consumer pattern:** to observe the timeout (or `abort` / `dispose`) error on the `eventStream`, iterate the stream
 > to its natural end rather than `break`ing out after the `tool-approval-request` event. Calling `iterator.return()`
 > (which `break` does inside `for await`) finalizes the harness's source generator before the terminal event can reach

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

@@ -20,6 +20,17 @@ export interface ClaudeHarnessFactoryConfig {
      * Defaults to `600_000` (10 minutes), matching the Mastra MCP timeout.
      */
     toolApprovalTimeoutMs?: number;
+    /**
+     * Opt-in override (milliseconds) for the SDK's per-hook timeout on the
+     * approval-gating `PreToolUse` hook. The SDK aborts a parked hook after
+     * its own default (~60s) regardless of {@link toolApprovalTimeoutMs} — so
+     * a consumer whose human-in-the-loop approval window must outlast that
+     * default has to raise this too, or the parked approval is torn down
+     * before {@link toolApprovalTimeoutMs} can fire. Undefined leaves the
+     * SDK default in place (unchanged behavior for existing consumers);
+     * typically set equal to `toolApprovalTimeoutMs`.
+     */
+    approvalHookTimeoutMs?: number;
     /**
      * 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

@@ -32,7 +32,7 @@ export class ClaudeHarnessFactory {
                 ? { allowDangerouslySkipPermissions: true }
                 : {}),
         };
-        const optionsBuilder = new ClaudeQueryOptionsBuilder({ ...permissionDefaults, ...this.config.queryDefaults });
+        const optionsBuilder = new ClaudeQueryOptionsBuilder({ ...permissionDefaults, ...this.config.queryDefaults }, this.config.approvalHookTimeoutMs);
         // Bind `innerFetch` into the mcp-client factory closure so every
         // call site inside `ClaudeHarness` (createAgent, reconnect, updateAgent)
         // routes MCP HTTP transports through the same proxy-aware fetch.

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;AAkCjD,MAAM,OAAO,oBAAoB;IAYA,MAAM;IAX1B,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;sBAAlC,MAAM;IAA+B,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"}
+{"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;AA6CjD,MAAM,OAAO,oBAAoB;IAYA,MAAM;IAX1B,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;sBAAlC,MAAM;IAA+B,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,CAChD,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EACvD,IAAI,CAAC,MAAM,CAAC,qBAAqB,CACpC,CAAC;QACF,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

@@ -1,5 +1,5 @@
 import { type Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
-import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks, type WithAgentConfig } from '@salesforce/sfdx-agent-sdk/harness';
 import type { ClaudeAgentConfig } from './claude-config.js';
 import type { ClaudeQueryEnvBuilder } from './claude-query-env-builder.js';
@@ -222,16 +222,36 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      */
     cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
     /**
-     * Write the sidecar for a thread so its `contextHistory`,
-     * `pendingContext`, AND `claudeSessionId` survive across restart.
+     * Allocate and register a fresh `ThreadState` for `threadId`, mirroring
+     * `createThread`'s initial shape (legacy 1:1 `claudeSessionId === threadId`,
+     * empty context arrays, `sessionContext` absent). Used by `setSessionContext`
+     * to seed a thread the consumer references before `createThread` / the first
+     * `stream()` — the session-context contract allows seeding context on an
+     * as-yet-unregistered thread.
+     */
+    private allocateThreadState;
+    /**
+     * Project a `ThreadState` into the on-disk `ThreadContextRecord`. Every
+     * sidecar write goes through this one builder so all persisted channels —
+     * addContext arrays, the `claudeSessionId` mapping, AND `sessionContext` —
+     * travel together and no write site can silently drop one. `sessionContext`
+     * is included only when set, so a thread that never set it writes no field
+     * (and reads back `{}`).
+     */
+    private threadContextRecordFrom;
+    /**
+     * Write the sidecar for a thread so its `contextHistory`, `pendingContext`,
+     * `claudeSessionId`, AND `sessionContext` survive across restart.
      *
-     * The early-return optimization for "nothing to persist" only fires
-     * when ALL three pieces of state match the legacy default
-     * (no addContext history AND `claudeSessionId === threadId`). The
-     * `claudeSessionId` check matters post-#511: a thread that has had
-     * its sessionId reassigned by `clearMessages()` MUST write a sidecar
-     * so the next `createAgent` rehydrates with the divergent mapping
-     * even when the thread otherwise has no addContext data.
+     * The early-return optimization for "nothing to persist" only fires when
+     * EVERY channel matches the legacy default: no addContext history, an
+     * un-rotated `claudeSessionId` (`=== threadId`), and no session context set.
+     * The `claudeSessionId` check matters post-#511 (a thread whose sessionId
+     * was rotated by `clearMessages()` MUST write a sidecar even with no
+     * addContext data); the `sessionContext` check matters symmetrically — a
+     * thread carrying only session context MUST persist it. `setSessionContext`
+     * itself writes unconditionally rather than through this helper, so this
+     * guard is for the incidental persist sites (stream-consume, clone).
      */
     private persistThreadContextIfPresent;
     /**
@@ -384,7 +404,11 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
     getMessages(agentId: string, threadId: string): Promise<Message[]>;
     clearMessages(agentId: string, threadId: string): Promise<void>;
     private buildContextPrompt;
+    addMessages(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
     addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    setSessionContext(agentId: string, threadId: string, content: SessionContext): Promise<void>;
+    getSessionContext(agentId: string, threadId: string): Promise<SessionContext>;
     /**
      * Synchronously flips `serverState.currentStatus` (no-op when the next
      * status equals the current) and returns a closure that, when invoked,

package/dist/claude-harness.js

@@ -48,6 +48,24 @@ function extractSystemPromptBody(systemPrompt) {
     }
     return undefined;
 }
+/**
+ * Deep-copy a `SessionContext` at the harness's public boundary so the consumer
+ * and the in-memory `ThreadState.sessionContext` never share a reference — a
+ * caller mutating either the object it passed to `setSessionContext` or the one
+ * `getSessionContext` returns must not reach into harness-internal state (which
+ * would silently diverge from what is persisted to disk until the next write).
+ * A JSON round-trip is the right copy here: `SessionContext` is a `JsonValue`
+ * object by contract (no functions / `Date` / class instances), so the round-trip
+ * is lossless AND it normalizes the object to the exact shape a post-restart read
+ * off disk would produce — so `getSessionContext` returns an identical value
+ * whether or not a restart intervened. Caveat: `JSON.stringify` drops keys whose
+ * value is `undefined`; type-safe here because `JsonValue` excludes `undefined`,
+ * but an `any`-typed caller that smuggles one in would see that key silently
+ * dropped rather than preserved as `undefined`.
+ */
+function cloneSessionContext(content) {
+    return JSON.parse(JSON.stringify(content));
+}
 export class ClaudeHarness {
     envBuilder;
     optionsBuilder;
@@ -319,6 +337,11 @@ export class ClaudeHarness {
                 claudeSessionId,
                 pendingContext: ctx.pendingContext,
                 contextHistory: ctx.contextHistory,
+                // Rehydrate the session-context channel so a set survives
+                // restart. Absent on the record (never set, or a pre-session-
+                // context sidecar) leaves `ThreadState.sessionContext`
+                // undefined → `getSessionContext` reads back `{}`.
+                ...(ctx.sessionContext !== undefined ? { sessionContext: ctx.sessionContext } : {}),
             });
             consumedSessionIds.add(claudeSessionId);
         }
@@ -415,6 +438,13 @@ export class ClaudeHarness {
             await closeClientWithTimeout(s.client);
             await s.ready.catch(() => undefined);
         }));
+        // Session context now shares the `ThreadContextStore` sidecar with the
+        // addContext channel (the spike's "extend the existing sidecar" for
+        // Claude), so it inherits that channel's lifecycle: sidecars are cleaned
+        // per-thread by `destroyThread`, NOT wiped en masse here. `destroyAgent`
+        // already leaves addContext sidecars on disk so a recreate over the same
+        // `projectRoot` rehydrates the threads (#455); session context rides the
+        // same durability. There is deliberately no agent-level sidecar wipe.
         return this.agents.delete(agentId);
     }
     async getAgentIds() {
@@ -642,6 +672,17 @@ export class ClaudeHarness {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
         }
         const id = threadId ?? this.idGenerator.getUniqueId();
+        // A thread id may already carry state if the consumer seeded session
+        // context before creating the thread — `setSessionContext` lazily
+        // allocates a `ThreadState` for an unregistered id (the contract allows
+        // seeding pre-`createThread`). Carry that `sessionContext` forward so a
+        // later `createThread` on the same id does not silently drop the last
+        // object the consumer set — `getSessionContext` MUST still return it
+        // (and its persisted sidecar copy stays consistent with memory). The
+        // message channels DO reset here: `createThread` semantically starts a
+        // fresh conversation, and session context is the one out-of-history
+        // piece that outlives that reset.
+        const existingSessionContext = agent.threads.get(id)?.sessionContext;
         // claudeSessionId starts equal to threadId — only diverges after a
         // `clearMessages()` cycle (see issue #511 / ThreadState docstring).
         agent.threads.set(id, {
@@ -649,6 +690,7 @@ export class ClaudeHarness {
             claudeSessionId: id,
             pendingContext: [],
             contextHistory: [],
+            ...(existingSessionContext !== undefined ? { sessionContext: existingSessionContext } : {}),
         });
         return id;
     }
@@ -669,10 +711,11 @@ export class ClaudeHarness {
                 sessionStore: this.sessionStore,
             });
         }
-        // Delete the addContext sidecar regardless of `hasStreamed` — a
-        // thread can have addContext-injected turns without ever being
-        // streamed, and leaving the sidecar would resurrect them on the
-        // next createAgent rehydrate pass.
+        // Delete the sidecar regardless of `hasStreamed` — a thread can have
+        // addContext-injected turns OR setSessionContext state without ever
+        // being streamed, and leaving the sidecar would resurrect either on the
+        // next createAgent rehydrate pass (or if the thread id is recreated).
+        // Both channels share this one sidecar, so a single delete covers them.
         await this.threadContextStore.delete(agent.projectRoot, threadId);
         agent.threads.delete(threadId);
     }
@@ -707,6 +750,12 @@ export class ClaudeHarness {
         if (!sourceState) {
             throw new Error(`Thread "${sourceThreadId}" not found`);
         }
+        // Both branches below build the clone's `ThreadState` inline rather than
+        // through `threadContextRecordFrom`, and deliberately do NOT copy
+        // `sourceState.sessionContext`: session-context carry-forward is deferred
+        // to this harness's render PR (W-23632691). When it lands, copy
+        // `sessionContext` here too. Until then a clone starts with empty session
+        // context by design, not by omission.
         if (!sourceState.hasStreamed) {
             const newId = this.idGenerator.getUniqueId();
             agent.threads.set(newId, {
@@ -739,27 +788,60 @@ export class ClaudeHarness {
         return result.sessionId;
     }
     /**
-     * Write the sidecar for a thread so its `contextHistory`,
-     * `pendingContext`, AND `claudeSessionId` survive across restart.
+     * Allocate and register a fresh `ThreadState` for `threadId`, mirroring
+     * `createThread`'s initial shape (legacy 1:1 `claudeSessionId === threadId`,
+     * empty context arrays, `sessionContext` absent). Used by `setSessionContext`
+     * to seed a thread the consumer references before `createThread` / the first
+     * `stream()` — the session-context contract allows seeding context on an
+     * as-yet-unregistered thread.
+     */
+    allocateThreadState(agent, threadId) {
+        const state = {
+            hasStreamed: false,
+            claudeSessionId: threadId,
+            pendingContext: [],
+            contextHistory: [],
+        };
+        agent.threads.set(threadId, state);
+        return state;
+    }
+    /**
+     * Project a `ThreadState` into the on-disk `ThreadContextRecord`. Every
+     * sidecar write goes through this one builder so all persisted channels —
+     * addContext arrays, the `claudeSessionId` mapping, AND `sessionContext` —
+     * travel together and no write site can silently drop one. `sessionContext`
+     * is included only when set, so a thread that never set it writes no field
+     * (and reads back `{}`).
+     */
+    threadContextRecordFrom(source) {
+        return {
+            contextHistory: source.contextHistory,
+            pendingContext: source.pendingContext,
+            claudeSessionId: source.claudeSessionId,
+            ...(source.sessionContext !== undefined ? { sessionContext: source.sessionContext } : {}),
+        };
+    }
+    /**
+     * Write the sidecar for a thread so its `contextHistory`, `pendingContext`,
+     * `claudeSessionId`, AND `sessionContext` survive across restart.
      *
-     * The early-return optimization for "nothing to persist" only fires
-     * when ALL three pieces of state match the legacy default
-     * (no addContext history AND `claudeSessionId === threadId`). The
-     * `claudeSessionId` check matters post-#511: a thread that has had
-     * its sessionId reassigned by `clearMessages()` MUST write a sidecar
-     * so the next `createAgent` rehydrates with the divergent mapping
-     * even when the thread otherwise has no addContext data.
+     * The early-return optimization for "nothing to persist" only fires when
+     * EVERY channel matches the legacy default: no addContext history, an
+     * un-rotated `claudeSessionId` (`=== threadId`), and no session context set.
+     * The `claudeSessionId` check matters post-#511 (a thread whose sessionId
+     * was rotated by `clearMessages()` MUST write a sidecar even with no
+     * addContext data); the `sessionContext` check matters symmetrically — a
+     * thread carrying only session context MUST persist it. `setSessionContext`
+     * itself writes unconditionally rather than through this helper, so this
+     * guard is for the incidental persist sites (stream-consume, clone).
      */
     async persistThreadContextIfPresent(projectRoot, threadId, source) {
         const hasContext = source.contextHistory.length > 0 || source.pendingContext.length > 0;
         const hasDivergedSessionId = source.claudeSessionId !== threadId;
-        if (!hasContext && !hasDivergedSessionId)
+        const hasSessionContext = source.sessionContext !== undefined;
+        if (!hasContext && !hasDivergedSessionId && !hasSessionContext)
             return;
-        await this.threadContextStore.write(projectRoot, threadId, {
-            contextHistory: source.contextHistory,
-            pendingContext: source.pendingContext,
-            claudeSessionId: source.claudeSessionId,
-        });
+        await this.threadContextStore.write(projectRoot, threadId, this.threadContextRecordFrom(source));
     }
     /**
      * Compacts a thread into a new thread seeded with an LLM-generated summary
@@ -815,7 +897,7 @@ export class ClaudeHarness {
         const newThreadId = await this.createThread(agentId);
         const userTs = this.clock.now();
         const assistantTs = this.clock.nextAfter(userTs);
-        await this.addContext(agentId, newThreadId, [
+        await this.addMessages(agentId, newThreadId, [
             {
                 id: this.idGenerator.getUniqueId(),
                 role: 'user',
@@ -1261,12 +1343,11 @@ export class ClaudeHarness {
             // systemPrompt. contextHistory persists unchanged and verbatim —
             // structured MessagePart[] content (incl. image/file base64) is
             // preserved so the getMessages() round-trip stays lossless across a
-            // restart, matching Mastra's persist-verbatim behavior.
-            await this.threadContextStore.write(projectRoot, threadId, {
-                pendingContext: [],
-                contextHistory: threadState.contextHistory,
-                claudeSessionId: threadState.claudeSessionId,
-            });
+            // restart, matching Mastra's persist-verbatim behavior. Routed
+            // through `threadContextRecordFrom` (reading the just-cleared
+            // in-memory `pendingContext`) so any `sessionContext` on the thread
+            // survives the clear.
+            await this.threadContextStore.write(projectRoot, threadId, this.threadContextRecordFrom(threadState));
         }
         // Wire-communication monitoring on Claude (subscriber-gated): the Claude Agent SDK runs
         // the model client in a subprocess with no programmatic HTTP-interception seam, so we
@@ -1445,7 +1526,14 @@ export class ClaudeHarness {
         // the contract's ascending-by-createdAt post-condition under stable
         // sort, so step the fallback per-position via `clock.nextAfter`.
         let lastFallback = this.clock.now();
-        const persisted = sessionMessages.map((msg) => {
+        const persisted = sessionMessages.flatMap((msg) => {
+            // The SDK's `MessageRole` is `'user' | 'assistant' | 'tool'` — `'system'`
+            // is not a consumer-visible transcript role (system state rides
+            // `instructions` / session context). The Anthropic transcript never
+            // stores a bare `system` turn on this path, but drop it defensively
+            // rather than surface an off-contract role across the SDK boundary.
+            if (msg.type !== 'user' && msg.type !== 'assistant')
+                return [];
             const recorded = timestamps.get(msg.uuid);
             let createdAt;
             if (recorded) {
@@ -1455,12 +1543,14 @@ export class ClaudeHarness {
                 lastFallback = this.clock.nextAfter(lastFallback);
                 createdAt = lastFallback;
             }
-            return {
-                id: msg.uuid,
-                role: msg.type,
-                content: mapSessionMessageContent(msg.message),
-                createdAt,
-            };
+            return [
+                {
+                    id: msg.uuid,
+                    role: msg.type,
+                    content: mapSessionMessageContent(msg.message),
+                    createdAt,
+                },
+            ];
         });
         // Merge the addContext-injected mirror with the persisted transcript
         // and sort chronologically (#464). The Claude SDK has no public API
@@ -1542,7 +1632,7 @@ export class ClaudeHarness {
         const prefix = baseInstructions ? `${baseInstructions}\n\n` : '';
         return `${prefix}<prior-context>\n${contextBlock}\n</prior-context>`;
     }
-    async addContext(agentId, threadId, messages) {
+    async addMessages(agentId, threadId, messages) {
         const agent = this.agents.get(agentId);
         if (!agent) {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
@@ -1578,12 +1668,59 @@ export class ClaudeHarness {
         // restart — matching Mastra's persist-verbatim (LibSQL) behavior. The
         // earlier placeholder-flattening (#491) was a premature optimization that
         // silently destroyed structured tool parts on rehydrate and diverged from
-        // Mastra; removed in favor of cross-harness correctness.
-        await this.threadContextStore.write(agent.projectRoot, threadId, {
-            pendingContext: threadState.pendingContext,
-            contextHistory: threadState.contextHistory,
-            claudeSessionId: threadState.claudeSessionId,
-        });
+        // Mastra; removed in favor of cross-harness correctness. Routed through
+        // `threadContextRecordFrom` so any `sessionContext` on the thread is
+        // carried in the same write and never clobbered by this addContext path.
+        await this.threadContextStore.write(agent.projectRoot, threadId, this.threadContextRecordFrom(threadState));
+    }
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
+    async addContext(agentId, threadId, messages) {
+        await this.addMessages(agentId, threadId, messages);
+    }
+    async setSessionContext(agentId, threadId, content) {
+        // AGENT_NOT_FOUND guard runs before any state touch — matches the
+        // cross-harness contract (#464) that every agent-scoped method throws
+        // on an unknown id. threadId is NOT validated: session context is a
+        // per-thread channel the consumer can seed before a thread's first
+        // stream (or before `createThread`), so an arbitrary threadId is a
+        // legal write target — a `ThreadState` is allocated lazily for it,
+        // mirroring `createThread`'s initial shape (`claudeSessionId ===
+        // threadId`, empty context arrays), and only its `sessionContext`
+        // field is set. An existing thread keeps all its other state.
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        const threadState = agent.threads.get(threadId) ?? this.allocateThreadState(agent, threadId);
+        // Update the in-memory source of truth first, then persist — mirrors
+        // `addMessages`, which mutates the arrays before writing the sidecar.
+        // Store a DEEP COPY, not the caller's reference: the consumer keeps
+        // ownership of the object it passed, so a later mutation of it must not
+        // reach into harness-internal state (and diverge from what was written
+        // to disk). The deleted `SessionContextStore` got this for free by
+        // JSON-serializing to disk on every write; `cloneSessionContext`
+        // preserves that isolation now that the object is held in memory.
+        threadState.sessionContext = cloneSessionContext(content);
+        // Unconditional write (not `persistThreadContextIfPresent`): an explicit
+        // set MUST be durable even when the thread has no addContext history and
+        // an un-rotated `claudeSessionId`.
+        await this.threadContextStore.write(agent.projectRoot, threadId, this.threadContextRecordFrom(threadState));
+    }
+    async getSessionContext(agentId, threadId) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        // In-memory `ThreadState` is the source of truth (rehydrated from the
+        // sidecar at `createAgent`, same as `contextHistory` / `pendingContext`).
+        // `{}`-on-miss — never `null`/`undefined`, never throws — for a thread
+        // that was never registered or never had context set. Return a DEEP COPY
+        // so a caller mutating the result can't reach into harness-internal state
+        // (which would silently diverge from disk until the next persist); this
+        // matches the fresh-object-per-read the deleted `SessionContextStore`
+        // gave via its `JSON.parse` read path.
+        const current = agent.threads.get(threadId)?.sessionContext;
+        return current === undefined ? {} : cloneSessionContext(current);
     }
     /**
      * Synchronously flips `serverState.currentStatus` (no-op when the next