@salesforce/sfdx-agent-harness-openai 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -3,21 +3,48 @@
 All notable changes to `@salesforce/sfdx-agent-harness-openai` are documented in this file. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.2.0] - 2026-07-27
+
+### Features
+- **chat-generations**: GovCloud chat/generations fallback @W-23560954@ ([#695](https://github.com/forcedotcom/agentic-dx/pull/695))
+- **harness-openai**: multimodal image/file input support @W-23546665 ([#702](https://github.com/forcedotcom/agentic-dx/pull/702))
+
+## [0.1.0] - 2026-07-27
+
+### Features
+
+- **harness-openai**: skills bridge (AgentConfig.skills + multi-file skills) @W-23546666
+  ([#694](https://github.com/forcedotcom/agentic-dx/pull/694))
+- **harness-openai**: rules loader (AgentConfig.rules support) @W-23546667@
+  ([#689](https://github.com/forcedotcom/agentic-dx/pull/689))
+- **harness-openai**: MCP-tool approval gating @W-23546664@ ([#688](https://github.com/forcedotcom/agentic-dx/pull/688))
+
 ## [0.0.1] - 2026-07-22
 
 ### Features
-- **harness-openai**: full conformance gate + e2e closeout @W-23447579@ ([#684](https://github.com/forcedotcom/agentic-dx/pull/684))
-- **harness-openai**: compaction, telemetry, hooks @W-23447576@ ([#683](https://github.com/forcedotcom/agentic-dx/pull/683))
-- **harness-openai**: MCP lifecycle + updateAgent preservation @W-23447574@ ([#678](https://github.com/forcedotcom/agentic-dx/pull/678))
-- **harness-openai**: approval + consumer tools @W-23447572@ ([#677](https://github.com/forcedotcom/agentic-dx/pull/677))
-- **harness-openai**: sessions, tools, history + isError sidecar @W-23447571@ ([#676](https://github.com/forcedotcom/agentic-dx/pull/676))
-- **harness-openai**: scaffold OpenAI Agents SDK harness with connectivity + streamed turn @W-23447570@ ([#675](https://github.com/forcedotcom/agentic-dx/pull/675))
+
+- **harness-openai**: full conformance gate + e2e closeout @W-23447579@
+  ([#684](https://github.com/forcedotcom/agentic-dx/pull/684))
+- **harness-openai**: compaction, telemetry, hooks @W-23447576@
+  ([#683](https://github.com/forcedotcom/agentic-dx/pull/683))
+- **harness-openai**: MCP lifecycle + updateAgent preservation @W-23447574@
+  ([#678](https://github.com/forcedotcom/agentic-dx/pull/678))
+- **harness-openai**: approval + consumer tools @W-23447572@
+  ([#677](https://github.com/forcedotcom/agentic-dx/pull/677))
+- **harness-openai**: sessions, tools, history + isError sidecar @W-23447571@
+  ([#676](https://github.com/forcedotcom/agentic-dx/pull/676))
+- **harness-openai**: scaffold OpenAI Agents SDK harness with connectivity + streamed turn @W-23447570@
+  ([#675](https://github.com/forcedotcom/agentic-dx/pull/675))
 
 ### Fixes
-- **ci**: bump openai harness off seed version so it can publish @W-23447579@ ([#686](https://github.com/forcedotcom/agentic-dx/pull/686))
+
+- **ci**: bump openai harness off seed version so it can publish @W-23447579@
+  ([#686](https://github.com/forcedotcom/agentic-dx/pull/686))
 
 ### Chores
-- **deps-dev**: bump eslint from 10.6.0 to 10.7.0 in the eslint group ([#680](https://github.com/forcedotcom/agentic-dx/pull/680))
+
+- **deps-dev**: bump eslint from 10.6.0 to 10.7.0 in the eslint group
+  ([#680](https://github.com/forcedotcom/agentic-dx/pull/680))
 
 ## [Unreleased]
 

package/README.md

@@ -10,10 +10,21 @@ OpenAI Agents SDK-backed `AgentHarness` implementation for [`@salesforce/sfdx-ag
 > lifecycle + `updateAgent` preservation (#541), E's compaction / telemetry / hooks, and F's full conformance-gate + e2e
 > closeout. Every `AgentHarness` method has a working implementation, the shared cross-harness conformance gate is
 > green, and the harness passes the SDK's `describe.each` e2e matrix under `--harness openai` against the real gateway.
-> **Known deferred gaps** (each excluded from the e2e matrix with a documented rationale, not a silent skip): MCP-tool
-> **approval gating** (the `@openai/agents` native `Agent({ mcpServers })` attach exposes no per-tool `needsApproval`
-> hook), **multimodal** input (the harness is text-only), `AgentConfig.rules` / `skills` composition, and MCP
-> `tool-progress`. Consumer-tool approval + `submitToolResult`, and tool-result redaction, ARE supported.
+> **MCP-tool approval gating IS supported** (added post-F): a `require-approval` / `deny` policy on an MCP tool surfaces
+> a `tool-approval-request` and honors the parked-approval lifecycle. When a policy gates MCP tools (or a redaction hook
+> is set), the harness materializes MCP tools via `getAllMcpTools(...)` and stamps a `needsApproval` predicate on each,
+> so the run loop raises the interruption the coordinator already routes. Consumer-tool approval + `submitToolResult`,
+> and tool-result redaction, are likewise supported. **`AgentConfig.rules` composition IS supported** (added post-F,
+> W-23546667): `createAgent` / `updateAgent` load each rule file/directory, strip YAML frontmatter, and compose the
+> bodies onto the effective system prompt — so the harness rejoins the dual-harness rules e2e. **`AgentConfig.skills`
+> composition IS supported** (added post-F, W-23546666): `createAgent` / `updateAgent` load `config.skills` into a skill
+> catalog exposed to the model as `load_skill` / `read_skill_file` function tools (the latter serving a skill's sibling
+> files), so the harness rejoins the dual-harness skills e2e including multi-file skill reachability. **Multimodal
+> image/file input IS supported** (added post-F, W-23546665): `chat()` / `stream()` and `addContext` accept `image` /
+> `file` `MessagePart`s and round-trip them to the model, so the harness rejoined the multimodal e2e matrix. **Known
+> deferred gap** (excluded from the e2e matrix with a documented rationale, not a silent skip): MCP **`tool-progress`**
+> — blocked UPSTREAM (`@openai/agents` 0.13.x exposes no seam to reach MCP `notifications/progress`) and tracked as
+> W-23558557, not a harness gap.
 
 ## What it is
 

package/dist/openai-agents-harness.d.ts

@@ -179,19 +179,20 @@ export declare class OpenAIAgentsHarness implements OpenAIAgentsAgentHarness {
      * request) with tracing off. `tools` carries the turn's consumer-executed
      * tools (mapped from `config.tools`).
      *
-     * **MCP attach, two paths.** Without a redaction hook (`redaction`
-     * undefined — the common case), the agent's live MCP server instances attach
-     * via the native `mcpServers` field; the SDK fetches their tools per run.
-     * Because each instance has `cacheToolsList: true` (cache keyed by
+     * **MCP attach, two paths.** With neither a redaction hook nor an active
+     * approval gate (the common case), the agent's live MCP server instances
+     * attach via the native `mcpServers` field; the SDK fetches their tools per
+     * run. Because each instance has `cacheToolsList: true` (cache keyed by
      * `server.name`) and this harness reuses the SAME connected instances across
      * turns, a rebuilt `Agent` here does not re-run `tools/list` for a preserved
-     * server — the #541 preservation mechanic. MCP tools are NOT approval-gated
-     * this milestone (the native attach exposes no per-tool `needsApproval`).
+     * server — the #541 preservation mechanic.
      *
-     * **When a redaction hook is set,** the native attach exposes no per-result
-     * rewrite seam, so MCP tools are materialized via `getAllMcpTools(...)` and
-     * their `invoke` wrapped with the redactor (see {@link buildRedactedMcpTools});
-     * they attach as `tools` rather than `mcpServers`. #541 is preserved because
+     * **When a redaction hook OR an approval gate is set,** the native attach
+     * exposes neither a per-result rewrite seam nor a per-tool `needsApproval`
+     * seam, so MCP tools are materialized via `getAllMcpTools(...)` and rebuilt
+     * with the active hooks (see {@link buildManagedMcpTools}): a redaction shim
+     * on `invoke` and/or a `needsApproval` predicate driven by the policy. They
+     * attach as `tools` rather than `mcpServers`. #541 is preserved because
      * `getAllMcpTools` reads each server's warm `cacheToolsList` cache with no
      * network `tools/list`. This makes the method async (the materialize awaits
      * `listTools()`), so `stream()` awaits it.
@@ -274,7 +275,16 @@ export declare class OpenAIAgentsHarness implements OpenAIAgentsAgentHarness {
     private diffMcpServers;
     /** Close every MCP server on an agent, awaiting in-flight discovery first. */
     private closeMcpServers;
-    /** Rebuild the catalog entries for one server from its freshly-discovered tools. */
+    /**
+     * Rebuild the catalog entries for one server from its freshly-discovered
+     * tools. Keys each entry by the tool's **sanitized display name** (what
+     * `@openai/agents` registers on materialized tools and run-item events — see
+     * {@link toFunctionToolName}), while preserving the original bare MCP name as
+     * `toolName`. Keying by the raw name would miss enrichment for any tool whose
+     * name carries a character the SDK sanitizes to `_` (e.g. `get-sum` →
+     * `get_sum`), so neither the event adapter nor the approval gate would see
+     * its `serverName`.
+     */
     private refreshCatalogForServer;
     /** Drop every catalog entry that points at `serverName`. */
     private removeCatalogForServer;

package/dist/openai-agents-harness.js

@@ -4,17 +4,20 @@
  */
 import { backfillCreatedAt, buildSummaryPrompt, getErrorMessage, isAbortError, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { Agent, Runner } from '@openai/agents';
-import { AgentSDKError, AgentSDKErrorType, mcpServerConfigEqual, McpServerStatus, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
-import { HarnessBusOwner, SUPPORTED_PROTOCOL_VERSIONS } from '@salesforce/sfdx-agent-sdk/harness';
+import { AgentSDKError, AgentSDKErrorType, mcpServerConfigEqual, McpServerStatus, resolveToolApprovalPolicy, validateMultimodalFiles, } from '@salesforce/sfdx-agent-sdk';
+import { HarnessBusOwner, lowerStreamInput, SUPPORTED_PROTOCOL_VERSIONS } from '@salesforce/sfdx-agent-sdk/harness';
 import { OpenAIApprovalCoordinator } from './openai-approval-coordinator.js';
 import { OPENAI_BUILT_IN_TOOL_POLICIES } from './openai-built-in-policies.js';
 import { buildMcpErrorDetail, sanitizeMcpErrorMessage } from './mcp-error-classifier.js';
 import { hasEnabledServers, mapToOpenAIMcpServers } from './openai-mcp-config-mapper.js';
-import { MAX_TRANSCRIPT_CHARS, messagesToRecords, partToTranscriptText, recordsToMessages, splitIntoChunks, } from './openai-message-mapper.js';
+import { lowerInputPartToContent, MAX_TRANSCRIPT_CHARS, messagesToRecords, partToTranscriptText, recordsToMessages, splitIntoChunks, } from './openai-message-mapper.js';
 import { buildOpenAIModelProvider } from './openai-model-provider.js';
+import { composeRulesAppend, composeSystemPrompt } from './rule-composer.js';
 import { OpenAISessionStore } from './openai-session-store.js';
+import { buildSkillMap } from './skill-loader.js';
+import { buildSkillTools } from './openai-skill-tools.js';
 import { ConsumerToolRegistry, mapConsumerTools } from './openai-tool-mapper.js';
-import { buildRedactedMcpTools } from './openai-tool-redaction.js';
+import { buildManagedMcpTools } from './openai-tool-redaction.js';
 /**
  * OpenAI Agents SDK-backed implementation of the SDK's `AgentHarness` contract.
  *
@@ -119,11 +122,21 @@ export class OpenAIAgentsHarness {
         if (this.agents.has(agentId)) {
             throw new Error(`Agent with id "${agentId}" is already registered`);
         }
+        options?.abortSignal?.throwIfAborted();
+        // Compose `config.rules` and load `config.skills` BEFORE registering
+        // state or starting MCP servers, so a bad/unreadable rule or skill path
+        // rejects `createAgent` before any MCP client is constructed (matching
+        // Mastra's Phase-0 posture — a non-MCP input failure can't leave servers
+        // half-cycled).
+        const rulesAppend = await composeRulesAppend(config?.rules);
+        const skillMap = await buildSkillMap(config?.skills, projectRoot, this.buses.getLogBus());
         const state = {
             projectRoot,
             config: config ?? {},
             modelConnectivityInfo,
             hooks: options?.hooks ?? {},
+            rulesAppend,
+            skillMap,
             // The provider reads the live bag on every `getModel()` so a
             // within-shape modelId swap / JWT rotation lands without a rebuild.
             modelProvider: this.modelProviderFactory(() => this.getAgentOrThrow(agentId).modelConnectivityInfo),
@@ -218,7 +231,29 @@ export class OpenAIAgentsHarness {
         // fresh id must still persist under that thread rather than silently
         // dropping history.
         state.threads.add(threadId);
-        const input = lowerMessageToText(message);
+        // Debug-emit the composed system prompt (config.instructions, with any
+        // rule bodies folded in by composeSystemPrompt) so consumers — notably
+        // the dual-harness rules e2e (#493) — can deterministically assert that
+        // `AgentConfig.rules` / `AgentConfig.instructions` reached the underlying
+        // runtime, without model-output marker assertions. The Mastra and Claude
+        // harnesses emit the equivalent `assembled systemPrompt` record from
+        // their own `stream()`, so the e2e captures the same record shape on
+        // every harness. Skip when the assembled body is empty (no instructions,
+        // no rules) so the emit guard matches the sibling harnesses' "skip when
+        // no system prompt is configured" posture.
+        const composedSystemPrompt = composeSystemPrompt(state.config.instructions, state.rulesAppend);
+        if (composedSystemPrompt.length > 0) {
+            this.buses.getLogBus()?.debug('openai harness assembled systemPrompt', {
+                agentId,
+                threadId,
+                systemPrompt: composedSystemPrompt,
+            });
+        }
+        // Lower the user message to the run-loop input. A plain string passes
+        // through; a `MessagePart[]` runs the shared `lowerStreamInput` (file-cap
+        // validation against the live model's `supportedFormats` + the input-part
+        // guard) and lowers text/image/file parts to one multimodal user item.
+        const input = lowerMessage(message, state.modelConnectivityInfo.model);
         // The disk-backed Session the runner reads history from and appends new
         // items to. Passing it to `run(..., { session })` is what makes the turn
         // multi-turn-aware and persistent (the runner owns the write).
@@ -227,13 +262,10 @@ export class OpenAIAgentsHarness {
         // interruption, or `undefined` when gating is off for this turn (the
         // SDK's "no policy ⇒ no gating" back-compat path). Frozen at stream start;
         // the closure reads `state.config` live per call so a mid-turn
-        // `updateAgentConfig` ("Allow always") is honored. Note: no tool the
-        // harness registers today carries a `needsApproval` predicate — MCP tools
-        // attach via the SDK's native path, which exposes no per-tool
-        // `needsApproval` hook, so they are NOT approval-gated this milestone
-        // (gating is a deferred follow-up). This decider is therefore dormant in
-        // production, though the coordinator plumbing it drives is exercised by
-        // the coordinator unit tests.
+        // `updateAgentConfig` ("Allow always") is honored. When active, the same
+        // decider also drives the `needsApproval` predicate on materialized MCP
+        // tools (below), so a `require-approval` / `deny` MCP tool raises the
+        // interruption this decider then routes.
         const policy = this.buildPolicyGate(state);
         // The tool-result redaction context, or `undefined` when the agent has no
         // `onToolResult` hook (both redaction seams then take their zero-cost
@@ -253,7 +285,14 @@ export class OpenAIAgentsHarness {
             ? new ConsumerToolRegistry(new Set(consumerToolDefs.map((t) => t.name)))
             : undefined;
         const tools = consumerTools ? mapConsumerTools(consumerToolDefs, consumerTools, redaction) : [];
-        const { agent, runner } = await this.buildAgent(agentId, state, tools, redaction);
+        // MCP-tool approval gate: when a policy is active, each materialized MCP
+        // tool gets a `needsApproval` predicate resolving this same decider over
+        // the enriched invocation (bare name → `{ serverName, annotations }` via
+        // the live catalog). `undefined` when gating is off, so MCP tools carry
+        // no predicate and never suspend. Materialization is forced whenever this
+        // OR `redaction` is set — the native attach exposes neither hook.
+        const mcpApproval = policy !== undefined ? { policy, mcpCatalog: state.mcpCatalog } : undefined;
+        const { agent, runner } = await this.buildAgent(agentId, state, tools, redaction, mcpApproval);
         // One coordinator owns this turn's run stream + sink + teardown. Dispose
         // any prior coordinator on the same thread first so a re-`stream()`
         // mid-turn can't leave a stale pump running against the old sink.
@@ -265,25 +304,20 @@ export class OpenAIAgentsHarness {
             session,
             policy,
             consumerTools,
-            onConsumerToolErrors: (toolCallIds) => {
+            onToolResultErrors: (toolCallIds) => {
                 // Stamp `isError` onto the persisted `function_call_result`
-                // records for consumer tools the consumer settled with an error —
-                // the run loop wrote them without it (the OpenAI item shape has no
-                // `isError` field). Best-effort: a persistence failure here must
-                // not fail the settled turn, and the store's per-thread queue
-                // orders this after the run's writes.
-                void this.sessions.markToolResultError(agentId, threadId, toolCallIds).catch((error) => this.buses.getLogBus()?.warn('Failed to persist consumer-tool isError', {
+                // records the run loop wrote without it (the OpenAI item shape
+                // has no `isError` field): consumer tools the consumer settled
+                // with an error, plus MCP tools the coordinator rejected (policy
+                // deny / user decline). Best-effort: a persistence failure here
+                // must not fail the settled turn, and the store's per-thread
+                // queue orders this after the run's writes.
+                void this.sessions.markToolResultError(agentId, threadId, toolCallIds).catch((error) => this.buses.getLogBus()?.warn('Failed to persist tool-result isError', {
                     agentId,
                     threadId,
                     error: getErrorMessage(error),
                 }));
             },
-            onSettled: () => {
-                // The coordinator removes its own entry when the turn settles —
-                // guard against a newer turn having already replaced it.
-                if (state.coordinators.get(threadId) === coordinator)
-                    state.coordinators.delete(threadId);
-            },
             externalSignal: abortSignal,
             // Live catalog reference so a mid-turn discovery settle enriches
             // later MCP tool events; empty when the agent has no MCP servers.
@@ -291,6 +325,10 @@ export class OpenAIAgentsHarness {
             // Factory-configured per-`toolCallId` approval timeout; the
             // coordinator falls back to its own default when undefined.
             toolApprovalTimeoutMs: this.toolApprovalTimeoutMs,
+            // Emission shape for a parallel `tool_use` batch's approvals: batch
+            // (all requests up front) vs serial (one at a time). Defaults to
+            // serial when unset, mirroring the sibling harnesses.
+            batchApprovals: options?.batchApprovals,
             // The turn's step limit → `run(..., { maxTurns })`. Undefined leaves
             // the SDK default in place; a hit surfaces as `finish('max-steps')`.
             maxTurns: options?.maxSteps,
@@ -344,12 +382,16 @@ export class OpenAIAgentsHarness {
     async updateAgent(agentId, modelConnectivityInfo, config, options) {
         const state = this.getAgentOrThrow(agentId);
         options?.abortSignal?.throwIfAborted();
-        // Phase 0 — validate non-MCP inputs BEFORE touching any MCP client, so a
-        // bad input can't leave servers half-cycled. This harness has no
-        // rules/skills/workspace to load (unlike Mastra), and `instructions` is a
-        // plain string, so there is nothing to validate today — the phase is a
-        // deliberate no-op. Kept as an explicit ordering anchor so a future
-        // non-MCP validation lands here, before Phase 1.
+        // Phase 0 — load non-MCP inputs BEFORE touching any MCP client, so a bad
+        // input can't leave servers half-cycled. Re-compose `config.rules` and
+        // re-load `config.skills`: a bad/unreadable rule or skill path rejects
+        // here, before the Phase 1 MCP diff cycles any transport (mirrors
+        // Mastra's Phase 0). `updateAgent` is atomic — a bad skill path in the
+        // new config rejects the whole update rather than applying the MCP delta
+        // and silently dropping the skill delta. Neither result is stamped onto
+        // state until Phase 2, so a rejection leaves the live agent untouched.
+        const rulesAppend = await composeRulesAppend(config?.rules);
+        const skillMap = await buildSkillMap(config?.skills, state.projectRoot, this.buses.getLogBus());
         // Phase 1 — diff the next MCP config against the applied one, preserving
         // structurally-equal servers and cycling the rest. Per-server Map
         // mutations are synchronous so a re-entrant rollback `updateAgent`
@@ -358,11 +400,16 @@ export class OpenAIAgentsHarness {
         this.diffMcpServers(agentId, state, next, config?.orgJwt, options?.abortSignal);
         // Phase 2 — apply non-MCP changes. The model provider closure and
         // `buildAgent` both read these live, so no provider/agent rebuild is
-        // required; `hooks` is re-stamped for the next turn's tool-result seam.
+        // required; `hooks` is re-stamped for the next turn's tool-result seam,
+        // the freshly-composed `rulesAppend` is folded onto the next turn's
+        // instructions, and the reloaded `skillMap` backs the next turn's skill
+        // tools.
         state.config = config ?? {};
         state.mcpConfig = config?.mcpServers;
         state.modelConnectivityInfo = modelConnectivityInfo;
         state.hooks = options?.hooks ?? {};
+        state.rulesAppend = rulesAppend;
+        state.skillMap = skillMap;
     }
     // ── MCP Introspection / Reconnect ────────────────────────────────────
     /**
@@ -558,47 +605,57 @@ export class OpenAIAgentsHarness {
      * request) with tracing off. `tools` carries the turn's consumer-executed
      * tools (mapped from `config.tools`).
      *
-     * **MCP attach, two paths.** Without a redaction hook (`redaction`
-     * undefined — the common case), the agent's live MCP server instances attach
-     * via the native `mcpServers` field; the SDK fetches their tools per run.
-     * Because each instance has `cacheToolsList: true` (cache keyed by
+     * **MCP attach, two paths.** With neither a redaction hook nor an active
+     * approval gate (the common case), the agent's live MCP server instances
+     * attach via the native `mcpServers` field; the SDK fetches their tools per
+     * run. Because each instance has `cacheToolsList: true` (cache keyed by
      * `server.name`) and this harness reuses the SAME connected instances across
      * turns, a rebuilt `Agent` here does not re-run `tools/list` for a preserved
-     * server — the #541 preservation mechanic. MCP tools are NOT approval-gated
-     * this milestone (the native attach exposes no per-tool `needsApproval`).
+     * server — the #541 preservation mechanic.
      *
-     * **When a redaction hook is set,** the native attach exposes no per-result
-     * rewrite seam, so MCP tools are materialized via `getAllMcpTools(...)` and
-     * their `invoke` wrapped with the redactor (see {@link buildRedactedMcpTools});
-     * they attach as `tools` rather than `mcpServers`. #541 is preserved because
+     * **When a redaction hook OR an approval gate is set,** the native attach
+     * exposes neither a per-result rewrite seam nor a per-tool `needsApproval`
+     * seam, so MCP tools are materialized via `getAllMcpTools(...)` and rebuilt
+     * with the active hooks (see {@link buildManagedMcpTools}): a redaction shim
+     * on `invoke` and/or a `needsApproval` predicate driven by the policy. They
+     * attach as `tools` rather than `mcpServers`. #541 is preserved because
      * `getAllMcpTools` reads each server's warm `cacheToolsList` cache with no
      * network `tools/list`. This makes the method async (the materialize awaits
      * `listTools()`), so `stream()` awaits it.
      */
-    async buildAgent(agentId, state, tools = [], redaction) {
+    async buildAgent(agentId, state, tools = [], redaction, mcpApproval) {
         const mcpServerInstances = [...state.mcpServers.values()].map((s) => s.server);
-        // Redaction path: materialize + wrap MCP tools so their result passes
-        // through the redactor (the native `mcpServers` attach has no such seam).
-        // Only CONNECTED servers are materialized: their `cacheToolsList` cache is
-        // warm (discovery succeeded), so `getAllMcpTools` reads it with no network
-        // `tools/list` and cannot throw — where an errored / still-connecting
-        // server would make `getAllMcpTools` (which fails fast on the first
-        // server's throw) reject the whole turn PRE-stream. Skipping them keeps a
-        // failed MCP server from failing the turn (the WI-D contract) and matches
-        // the Claude harness's "only connected servers surface" posture; an
-        // errored server contributes no usable tools on the native path either.
+        // Materialize + manage MCP tools when EITHER a redaction hook or an
+        // approval gate is active — the native `mcpServers` attach exposes
+        // neither the per-result rewrite seam nor the per-tool `needsApproval`
+        // seam. Only CONNECTED servers are materialized: their `cacheToolsList`
+        // cache is warm (discovery succeeded), so `getAllMcpTools` reads it with
+        // no network `tools/list` and cannot throw — where an errored /
+        // still-connecting server would make `getAllMcpTools` (which fails fast
+        // on the first server's throw) reject the whole turn PRE-stream. Skipping
+        // them keeps a failed MCP server from failing the turn (the WI-D
+        // contract) and matches the Claude harness's "only connected servers
+        // surface" posture; an errored server contributes no usable tools on the
+        // native path either.
+        const manageMcp = redaction !== undefined || mcpApproval !== undefined;
         const connectedMcpServers = [...state.mcpServers.values()]
             .filter((s) => s.status === McpServerStatus.Connected)
             .map((s) => s.server);
-        const redactedMcpTools = redaction !== undefined && connectedMcpServers.length > 0
-            ? await buildRedactedMcpTools(connectedMcpServers, redaction)
+        const managedMcpTools = manageMcp && connectedMcpServers.length > 0
+            ? await buildManagedMcpTools(connectedMcpServers, { redaction, approval: mcpApproval })
             : [];
-        const allTools = [...tools, ...redactedMcpTools];
-        // Attach MCP natively only when we did NOT materialize them for redaction.
-        const attachMcpServers = redaction === undefined && mcpServerInstances.length > 0;
+        // Skill tools (`load_skill` / `read_skill_file`) surface the agent's
+        // configured skills to the model. Built fresh per turn from the live
+        // `state.skillMap` — never cached — so an `updateAgent` that changes
+        // `config.skills` lands on the next turn. Empty when the agent has no
+        // skills, so a skill-less agent's tool surface is unchanged.
+        const skillTools = buildSkillTools(state.skillMap);
+        const allTools = [...tools, ...skillTools, ...managedMcpTools];
+        // Attach MCP natively only when we did NOT materialize them for a hook.
+        const attachMcpServers = !manageMcp && mcpServerInstances.length > 0;
         const agent = new Agent({
             name: agentId,
-            instructions: state.config.instructions ?? '',
+            instructions: composeSystemPrompt(state.config.instructions, state.rulesAppend),
             model: state.modelConnectivityInfo.nativeModelId,
             ...(allTools.length > 0 ? { tools: allTools } : {}),
             ...(attachMcpServers ? { mcpServers: mcpServerInstances } : {}),
@@ -888,19 +945,32 @@ export class OpenAIAgentsHarness {
         state.mcpServers.clear();
         state.mcpCatalog.clear();
     }
-    /** Rebuild the catalog entries for one server from its freshly-discovered tools. */
+    /**
+     * Rebuild the catalog entries for one server from its freshly-discovered
+     * tools. Keys each entry by the tool's **sanitized display name** (what
+     * `@openai/agents` registers on materialized tools and run-item events — see
+     * {@link toFunctionToolName}), while preserving the original bare MCP name as
+     * `toolName`. Keying by the raw name would miss enrichment for any tool whose
+     * name carries a character the SDK sanitizes to `_` (e.g. `get-sum` →
+     * `get_sum`), so neither the event adapter nor the approval gate would see
+     * its `serverName`.
+     */
     refreshCatalogForServer(state, serverName, tools) {
         this.removeCatalogForServer(state, serverName);
         for (const tool of tools) {
             const annotations = tool.annotations;
-            state.mcpCatalog.set(tool.name, { serverName, ...(annotations !== undefined ? { annotations } : {}) });
+            state.mcpCatalog.set(toFunctionToolName(tool.name), {
+                serverName,
+                toolName: tool.name,
+                ...(annotations !== undefined ? { annotations } : {}),
+            });
         }
     }
     /** Drop every catalog entry that points at `serverName`. */
     removeCatalogForServer(state, serverName) {
-        for (const [bareToolName, entry] of state.mcpCatalog) {
+        for (const [displayName, entry] of state.mcpCatalog) {
             if (entry.serverName === serverName)
-                state.mcpCatalog.delete(bareToolName);
+                state.mcpCatalog.delete(displayName);
         }
     }
     /**
@@ -993,22 +1063,38 @@ function isJsonObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
- * Lowers a `stream()` message to the plain-text `input` the OpenAI Agents run
- * loop takes. Only `text` parts are supported; multimodal input is not yet
- * implemented.
+ * Sanitize an MCP tool name to the function-tool identifier `@openai/agents`
+ * registers it under. A byte-identical copy of the SDK's internal
+ * `toFunctionToolName` (`@openai/agents-core` `utils/tools.ts`), which is not
+ * exported: whitespace and every non-alphanumeric character become `_`. The
+ * SDK applies this to both the materialized function tool's `name` and the
+ * `tool_called` / `tool_output` run-item names, so the harness must key its MCP
+ * catalog by the same transformed name for enrichment + approval lookups to hit
+ * (e.g. a `tools/list` name `get-sum` surfaces as `get_sum`). Kept local rather
+ * than reached through a deep import per the harness-isolation rule; the
+ * transform is a stable identifier-safety rule unlikely to drift.
  */
-function lowerMessageToText(message) {
+function toFunctionToolName(name) {
+    return name.replace(/\s/g, '_').replace(/[^a-zA-Z0-9]/g, '_');
+}
+/**
+ * Lowers a `stream()` message to the `input` the OpenAI Agents run loop takes.
+ *
+ * A plain `string` passes through unchanged (the common text turn). A
+ * `MessagePart[]` runs the shared `lowerStreamInput`, which validates any
+ * `image` / `file` parts against the model's `supportedFormats` + the global
+ * gateway caps (throwing `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)` pre-stream on a
+ * violation) and rejects non-input parts (`reasoning` / `tool-call` /
+ * `tool-result`) with `INVALID_MESSAGE_CONTENT`, then lowers each valid part to an
+ * `@openai/agents` `UserContent` block. The blocks are wrapped in one `user`
+ * message item, so a mixed text-plus-attachment turn reaches the model as a single
+ * multimodal user message. See {@link lowerInputPartToContent} for the wire shape
+ * (notably the mandatory `data:` URL for images).
+ */
+function lowerMessage(message, model) {
     if (typeof message === 'string')
         return message;
-    const texts = [];
-    for (const part of message) {
-        if (part.type === 'text') {
-            texts.push(part.text);
-        }
-        else {
-            throw new AgentSDKError(`The OpenAI harness does not yet support "${part.type}" message parts (text only).`, AgentSDKErrorType.INVALID_MESSAGE_CONTENT);
-        }
-    }
-    return texts.join('\n');
+    const content = lowerStreamInput(message, (files) => validateMultimodalFiles(files, model), lowerInputPartToContent);
+    return [{ role: 'user', content }];
 }
 //# sourceMappingURL=openai-agents-harness.js.map