weir-harness 2.0.0 → 2.1.0

package/src/capabilities/mcp-diagnostics.js

@@ -0,0 +1,169 @@
+// Secret-free, bounded MCP diagnostics. Raw Error objects, stacks, URLs with
+// credentials, and arbitrary cause chains never cross the operation boundary.
+export const MCP_DIAGNOSTIC_LIMIT = 8192
+const CAUSE_LIMIT = 6
+
+const MESSAGE = value => value instanceof Error ? value.message : String(value ?? 'unknown error')
+
+/** Known-secret metadata is internal, inherited through wrapped causes, and never enumerated on the wire. */
+function errorSecrets(error, initial = []) {
+  const secrets = [...initial]
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    if (Array.isArray(current?.secrets)) secrets.push(...current.secrets)
+    current = current?.cause
+  }
+  return secrets
+}
+
+/** Replace known secrets, then reduce sensitive URL tails to scheme/host/path. */
+function redactKnownAndUrls(text, secrets) {
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Any sensitive URL component makes the whole userinfo/query/fragment tail
+  // sensitive. Preserve only scheme/host/path for actionable diagnostics.
+  return text.replace(/\b(?:https?|wss?):\/\/[^\s<>"']+/gi, candidate => {
+    const trailing = candidate.match(/[.,;:!?)]*$/)?.[0] ?? ''
+    const raw = trailing ? candidate.slice(0, -trailing.length) : candidate
+    try {
+      const url = new URL(raw)
+      if (!url.username && !url.password && !url.search && !url.hash) return candidate
+      return `${url.protocol}//${url.host}${url.pathname}[redacted-url]${trailing}`
+    } catch {
+      return '[redacted-url]'
+    }
+  })
+}
+
+/** Free text: replace every known secret before applying pattern-based redaction. */
+export function sanitizeMcpText(value, secrets = []) {
+  let text = String(value ?? '')
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Authorization lines and common secret-bearing key/value spellings.
+  text = text.replace(/\b(?:proxy-)?authorization\s*:\s*[^\r\n,;}]+/gi, match => `${match.split(':')[0]}: [redacted]`)
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+  text = text.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted-jwt]')
+  text = text.replace(/\b(?:api[-_]?key|access[-_]?token|refresh[-_]?token|password|passwd|secret|client[-_]?secret)(\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}]+)/gi, (_match, key, separator) => `${key}${separator}[redacted]`)
+  // Shell/environment assignments. Values may be quoted; the key remains useful.
+  text = text.replace(/\b[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]+)/g, assignment => `${assignment.slice(0, assignment.indexOf('='))}=[redacted]`)
+  return redactKnownAndUrls(text, [])
+}
+
+/**
+ * Structured MCP configuration fields (argv, command, cwd, label, refs) are
+ * exact values the user must be able to read, edit and approve. Secret-bearing
+ * positions are already replaced structurally (secretRefs-indexed args, env/
+ * header values, sensitive URLs); here only known secret values and sensitive
+ * URL tails are removed. The generic KEY=VALUE patterns are for free text only:
+ * applying them to argv turned `--port=8080` into `--port=[redacted]`.
+ */
+export function sanitizeMcpConfigText(value, secrets = []) {
+  return redactKnownAndUrls(String(value ?? ''), secrets)
+}
+
+// Config projections produced by redactMcpEntry. Membership is process-local and
+// lost on clone/serialization, which only falls back to the stricter free-text
+// sanitizer — never to less redaction.
+const CONFIG_PROJECTIONS = new WeakSet()
+export function markMcpConfigProjection(value) {
+  if (value && typeof value === 'object') CONFIG_PROJECTIONS.add(value)
+  return value
+}
+function sanitizeConfigProjection(value, secrets) {
+  if (typeof value === 'string') return sanitizeMcpConfigText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeConfigProjection(item, secrets))
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeConfigProjection(item, secrets)]))
+  return value
+}
+
+export function sanitizeMcpPayload(value, secrets = []) {
+  if (typeof value === 'string') return sanitizeMcpText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeMcpPayload(item, secrets))
+  if (value && typeof value === 'object') {
+    if (CONFIG_PROJECTIONS.has(value)) return markMcpConfigProjection(sanitizeConfigProjection(value, secrets))
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeMcpPayload(item, secrets)]))
+  }
+  return value
+}
+
+const RULES = [
+  ['credential-missing', /credential[- ]missing|credential.*(?:not configured|empty|missing)|missing.*credential/i, 'Configure a non-empty credential reference, then retry.'],
+  ['name-conflict', /serverName.*(?:already in use|conflict)|name[- ]conflict|namespace.*conflict/i, 'Choose a unique public server name or remove the conflicting registration.'],
+  ['executable-not-found', /\bENOENT\b|executable.*(?:not found|unavailable)|command.*not found|cannot find.*(?:command|executable)/i, 'Check the command and its GUI PATH resolution, then retry.'],
+  ['permission-denied', /\bEACCES\b|\bEPERM\b|permission denied|access denied/i, 'Check executable and credential/file permissions, then retry.'],
+  ['connection-refused', /ECONNREFUSED|connection refused/i, 'Check that the server is listening and the endpoint is correct, then retry.'],
+  ['http-unauthorized', /\bHTTP\s*40[13]\b|\b40[13]\b|unauthorized|forbidden/i, 'Check the HTTP credential reference and server authorization policy.'],
+  ['timeout', /timeout|timed out|deadline exceeded/i, 'Inspect server startup and connectivity, then retry with a healthy server.'],
+  ['invalid-config', /invalid config|validation|unsupported transport|unknown (?:option|field)|initialDelayMs|maxDelayMs/i, 'Correct the marked configuration field and preview again.'],
+  ['cleanup-unknown', /cleanup-unknown|closure could not be confirmed|unconfirmed (?:transport )?clos/i, 'Inspect residue before retrying; an immediate same-name replacement is blocked.'],
+  ['cleanup-failed', /cleanup-failed|dispose(?:d|al)?(?: rejection| failed)|remove rejection/i, 'Inspect the cleanup diagnostic and recover the remaining Loader entry before retrying.'],
+  ['unsupported', /unsupported|ephemeral.*unavailable/i, 'Use a secret-free configuration or a Host with the required ephemeral Loader support.'],
+  ['owner-changed', /owner-changed|preset.*changed|ownership.*changed/i, 'Return to the original session/preset and preview again.'],
+]
+
+export function classifyMcpError(error, secrets = []) {
+  secrets = errorSecrets(error, secrets)
+  const evidence = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    evidence.push(`${current?.code ?? ''} ${MESSAGE(current)}`)
+    current = current?.cause
+  }
+  const text = sanitizeMcpText(evidence.join('\n'), secrets)
+  const match = RULES.find(([, pattern]) => pattern.test(text))
+  if (!match) return { code: 'unknown-error', hint: 'Inspect the sanitized diagnostic and retry after correcting the cause.' }
+  return { code: match[0], hint: match[2] }
+}
+
+function boundedMessage(text, max = 4096) {
+  const clean = String(text)
+  return Buffer.byteLength(clean) <= max ? clean : Buffer.from(clean).subarray(0, max - 1).toString().replace(/\uFFFD+$/g, '') + '…'
+}
+
+/**
+ * Convert an Error/cause chain into one stable secret-free diagnostic. Both
+ * individual strings and the complete JSON projection are bounded to 8 KiB.
+ */
+export function mcpDiagnostic(error, options = {}) {
+  const secrets = errorSecrets(error, options.secrets ?? [])
+  const classified = options.code ? { code: options.code, hint: options.hint } : classifyMcpError(error, secrets)
+  const causes = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    causes.push(boundedMessage(sanitizeMcpText(MESSAGE(current), secrets), 1024))
+    current = current?.cause
+  }
+  const first = causes[0] ?? boundedMessage(sanitizeMcpText(MESSAGE(error), secrets), 1024)
+  let diagnostic = {
+    code: classified.code ?? 'unknown-error',
+    message: boundedMessage(sanitizeMcpText(options.message ?? first, secrets)),
+    hint: boundedMessage(sanitizeMcpText(options.hint ?? classified.hint ?? 'Retry after correcting the cause.'), 1024),
+    recovery: { action: options.action ?? 'retry' },
+    causes,
+  }
+  while (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT && diagnostic.causes.length > 1) {
+    diagnostic.causes.pop()
+  }
+  if (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT) {
+    diagnostic.message = boundedMessage(diagnostic.message, 2048)
+    diagnostic.hint = boundedMessage(diagnostic.hint, 512)
+  }
+  return diagnostic
+}
+
+export class McpLifecycleError extends Error {
+  constructor(code, error, options = {}) {
+    const secrets = errorSecrets(error, options.secrets ?? [])
+    const diagnostic = mcpDiagnostic(error, { ...options, secrets, code, hint: options.hint })
+    super(diagnostic.message, options.cause === undefined && error instanceof Error ? { cause: error } : {})
+    this.name = 'McpLifecycleError'
+    this.code = code
+    this.status = options.status ?? code
+    this.diagnostic = diagnostic
+    Object.defineProperty(this, 'secrets', { value: Object.freeze([...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]), enumerable: false })
+    this.cleanup = options.cleanup === undefined ? undefined : sanitizeMcpPayload(options.cleanup, secrets)
+  }
+}

package/src/capabilities/mcp-drain.js

@@ -14,12 +14,13 @@
 export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
   /** @type {Map<string, { count: number, calls: Map<number, string>, closed: boolean }>} */
   const flights = new Map()
+  const closedServers = new Set()
   let sequence = 0
 
   const keyOf = (agentId, server) => `${agentId ?? 'unknown'}${server}`
   const stateOf = (agentId, server) => {
     const key = keyOf(agentId, server)
-    if (!flights.has(key)) flights.set(key, { count: 0, calls: new Map(), closed: false })
+    if (!flights.has(key)) flights.set(key, { server, count: 0, calls: new Map(), closed: false })
     return flights.get(key)
   }
 
@@ -30,7 +31,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
    */
   function enter(agentId, server, label = 'call') {
     const state = stateOf(agentId, server)
-    if (state.closed) return null
+    if (state.closed || closedServers.has(server)) return null
     sequence += 1
     state.count += 1
     state.calls.set(sequence, label)
@@ -68,7 +69,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
   }
 
   function isClosed(agentId, server) {
-    return stateOf(agentId, server).closed
+    return stateOf(agentId, server).closed || closedServers.has(server)
   }
 
   /** The Apply-time snapshot the response carries (sent at response time). */
@@ -77,7 +78,20 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
     return { server, state: state.count === 0 ? 'settled' : 'draining', inFlight: state.count }
   }
 
-  return { enter, exit, close, reopen, isClosed, drain, snapshot }
+  function closeAll(server) { closedServers.add(server) }
+  function reopenAll(server) { closedServers.delete(server) }
+  async function drainAll(server) {
+    const states = [...flights.values()].filter(state => state.server === server)
+    const started = now()
+    const totals = () => ({ count: states.reduce((sum, state) => sum + state.count, 0), calls: states.flatMap(state => [...state.calls.values()]) })
+    while (totals().count > 0 && now() - started < timeoutMs) await sleep(Math.min(50, timeoutMs))
+    const current = totals()
+    return current.count === 0
+      ? { drained: true, waitedMs: now() - started }
+      : { drained: false, inFlight: current.count, calls: current.calls, waitedMs: now() - started }
+  }
+
+  return { enter, exit, close, reopen, isClosed, drain, snapshot, closeAll, reopenAll, drainAll }
 }
 
 /**

package/src/capabilities/mcp-facade.js

@@ -32,8 +32,8 @@ const message = error => (error instanceof Error ? error.message : String(error)
  *   drain?: { enter(agentId: string, server: string, label?: string): number|null, exit(agentId: string, server: string, token: number|null): void },
  *   onError?: (reason: string, cause?: unknown) => void }} config
  */
-export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onError = () => {} }) {
-  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain })
+export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onError = () => {}, assertPermit }) {
+  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain, assertPermit })
 
   const unknown = (service, method) => {
     const reason = `facade-unknown-method:${service}.${method}`
@@ -91,7 +91,7 @@ export function createMcpFacade({ host, identity, generation, admit, isEnabledFo
       const gated = typeof request === 'function'
         ? { ...provider, async request(args, exec) {
             const admitted = await admit(exec?.agent)
-            if (!admitted) {
+            if (!admitted || (assertPermit && !assertPermit(admitted))) {
               const error = new Error(`MCP server "${identity}" resources are not enabled for this agent`)
               throw Object.assign(error, { code: 'mcp-admission-refused' })
             }

package/src/capabilities/mcp-gate.js

@@ -1,23 +1,30 @@
-// Task 8.2/8.5 of the session-capability-manager change: the admission gate
-// service the facades consume. The verdict for "is this managed server
-// usable by this agent" combines, in order:
-//   1. the registry's configured identity + current generation (8.1) — a
-//      reconnect mounts a NEW generation and every old-generation handle is
-//      rejected; a same-named DIFFERENT identity inherits nothing (8.5);
-//   2. the session lifecycle snapshot: BLOCKED sessions refuse every managed
-//      call (6.4); a dispose/reload window without an initialized snapshot
-//      refuses too (8.5);
-//   3. the session's accepted managed-MCP set (the selection record's
-//      mcpServers): a server not in the set is not enabled for that agent.
-// Connections stay shared at the host plane — a session losing a server
-// never disposes anything (8.5).
+// Managed MCP admission combines runtime registration generation/incarnation,
+// the accepted lifecycle selection, and (when mounted) the per-identity runtime
+// phase. Legacy compatibility exists only when BOTH sides lack incarnations.
 
-/**
- * @param {{ registry: { read(): Promise<any> },
- *   lifecycle: { snapshotFor(sessionId: string): any },
- *   sessionMcpServers?: (sessionId: string) => string[] | null }} options
- */
-export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
+export function mcpIncarnationMatches(snapshot, identity, entry) {
+  if (!entry) return false
+  const mapping = snapshot?.mcpIncarnations
+  if (mapping && typeof mapping === 'object' && !Array.isArray(mapping)) {
+    if (!Object.hasOwn(mapping, identity)) return false
+    return mapping[identity] === (entry.incarnation ?? null)
+  }
+  // A legacy selection without a mapping remains valid only for a legacy entry.
+  return entry.incarnation == null
+}
+
+function acceptedSnapshot(lifecycle, agent, { parentFallback = false } = {}) {
+  const sessionId = agent?.session?.id
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+  let snapshot = lifecycle.snapshotFor(sessionId)
+  if (snapshot == null && parentFallback) {
+    const parentId = agent?.session?.header?.parentSession
+    if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+  }
+  return snapshot?.state === 'ready' ? snapshot : null
+}
+
+export function createMcpGate({ registry, lifecycle, sessionMcpServers, registrationFor, runtime }) {
   const acceptedOf = sessionId => {
     if (typeof sessionMcpServers === 'function') return sessionMcpServers(sessionId)
     const snapshot = lifecycle.snapshotFor(sessionId)
@@ -25,47 +32,39 @@ export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
     return snapshot.mcpServers
   }
 
-  /**
-   * The facade-side verdict for one call.
-   * @param {unknown} agent @param {string} identity @param {number} generation
-   * @returns {Promise<boolean>}
-   */
-  async function admit(agent, identity, generation) {
+  async function permit(agent, identity, generation) {
     const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    const snapshot = lifecycle.snapshotFor(sessionId)
-    // BLOCKED (6.4) or no initialized snapshot (dispose/reload window, 8.5):
-    // every managed call is refused, never an unrestricted pass.
-    if (snapshot?.state !== 'ready') return false
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return null
+    const snapshot = acceptedSnapshot(lifecycle, agent)
+    if (!snapshot) return null
     const accepted = acceptedOf(sessionId)
-    if (!Array.isArray(accepted) || !accepted.includes(identity)) return false
+    if (!Array.isArray(accepted) || !accepted.includes(identity)) return null
+    if (runtime?.beforeRead && runtime.beforeRead(identity) === false) return null
     const current = await registry.read()
-    if (current.kind !== 'ok') return false
+    if (current.kind !== 'ok') return null
     const entry = current.servers[identity]
-    return Boolean(entry && entry.generation === generation)
+    if (!entry || entry.generation !== generation || !mcpIncarnationMatches(snapshot, identity, entry)) return null
+    if (runtime?.afterRead && runtime.afterRead(identity) === false) return null
+    if (runtime?.permit) return runtime.permit(identity, { generation, incarnation: entry.incarnation ?? null })
+    return { identity, generation, incarnation: entry.incarnation ?? null, operationId: null }
+  }
+  async function admit(agent, identity, generation) {
+    return (await permit(agent, identity, generation)) !== null
   }
 
-  /**
-   * Instruction-section filtering (8.4): is the server in the session's
-   * accepted set? At a subagent's creation the inherited capture is what the
-   * child gets — the parent's accepted set VERBATIM at that moment — so when
-   * the child's own snapshot is not visible yet (the creation-time
-   * schema-hiding listener races the capture listener), the parent's
-   * snapshot stands in. Call admission (admit) never uses this fallback: a
-   * snapshot-less child is refused, never granted the parent's set.
-   */
   function enabledFor(agent, identity) {
-    const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    let snapshot = lifecycle.snapshotFor(sessionId)
-    if (snapshot?.state !== 'ready') {
-      const parentId = agent?.session?.header?.parentSession
-      if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return false
+    const snapshot = acceptedSnapshot(lifecycle, agent, { parentFallback: true })
+    if (!snapshot || !Array.isArray(snapshot.mcpServers) || !snapshot.mcpServers.includes(identity)) return false
+    if (typeof registrationFor !== 'function') {
+      // Pure legacy tests without a runtime registry still get mapping-shape
+      // enforcement; production always supplies registrationFor below.
+      const mapping = snapshot.mcpIncarnations
+      return !(mapping && typeof mapping === 'object' && !Array.isArray(mapping) && !Object.hasOwn(mapping, identity))
     }
-    if (snapshot?.state !== 'ready') return false
-    const accepted = snapshot.mcpServers
-    return Array.isArray(accepted) && accepted.includes(identity)
+    return mcpIncarnationMatches(snapshot, identity, registrationFor(identity))
   }
 
-  return { admit, enabledFor }
+  return { admit, permit, enabledFor, assertPermit: value => runtime?.assertPermit ? runtime.assertPermit(value) : Boolean(value) }
 }

package/src/capabilities/mcp-install-tool.js

@@ -0,0 +1,276 @@
+// Primary-Orchestrator MCP installation. Preview is inert; install executes only
+// the Host-stored plan approved through userQuestions, never post-answer model input.
+import { createHash } from 'node:crypto'
+import { parseMcpDocument, fingerprintMcpEntry } from './mcp-config.js'
+import { mcpDiagnostic, sanitizeMcpPayload } from './mcp-diagnostics.js'
+
+export const MCP_INSTALL_TOOL_NAME = 'mcp_install'
+export const MCP_INSTALL_APPROVE_LABEL = 'Install MCP server'
+export const MCP_INSTALL_CANCEL_LABEL = 'Cancel'
+export const MCP_INSTALL_CONFIRMATION_TIMEOUT_MS = 5 * 60 * 1000
+
+const CREDENTIAL_REF = {
+  type: 'object',
+  properties: {
+    ref: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$', description: 'Existing DSH credential reference.' },
+    prefix: { type: 'string', description: 'Optional non-secret prefix, such as Bearer .' },
+  },
+  required: ['ref'], additionalProperties: false,
+}
+const REF_MAP = { type: 'object', additionalProperties: CREDENTIAL_REF }
+const RECONNECT = {
+  type: 'object',
+  properties: {
+    enabled: { type: 'boolean' },
+    initialDelayMs: { type: 'number', exclusiveMinimum: 0 },
+    maxDelayMs: { type: 'number', exclusiveMinimum: 0 },
+    maxAttempts: { type: 'integer', minimum: 0 },
+  },
+  additionalProperties: false,
+}
+
+export const MCP_INSTALL_PARAMETERS = {
+  type: 'object',
+  properties: {
+    action: {
+      type: 'string', enum: ['preview', 'install'],
+      description: 'preview only validates and returns a redacted plan; install requests Host confirmation before any probe or write.',
+    },
+    plan: {
+      type: 'object',
+      description: 'One fresh MCP server. Use credential references for every environment/header/secret-argument value and for any URL with userinfo, query, or fragment.',
+      properties: {
+        identity: { type: 'string', description: 'Fresh stable logical identity; installation never edits or replaces an existing registration.' },
+        label: { type: 'string' },
+        transport: { type: 'string', enum: ['stdio', 'streamable-http'] },
+        serverName: { type: 'string', pattern: '^[A-Za-z0-9_-]{1,32}$' },
+        command: { type: 'string', description: 'stdio executable; required for stdio and forbidden for HTTP.' },
+        args: {
+          type: 'array', maxItems: 128,
+          description: 'Non-secret stdio arguments. Use a credential-reference object instead of a string for every sensitive argument.',
+          items: { anyOf: [{ type: 'string' }, CREDENTIAL_REF] },
+        },
+        secretArgs: { type: 'object', description: 'Credential references keyed by sensitive argument index.', additionalProperties: CREDENTIAL_REF },
+        env: { ...REF_MAP, description: 'stdio environment values as credential references; literal values are not accepted.' },
+        cwd: { type: 'string' },
+        url: {
+          description: 'Non-sensitive absolute HTTP(S) URL, or a credential reference for any URL containing userinfo, query, or fragment.',
+          anyOf: [{ type: 'string', pattern: '^https?://' }, CREDENTIAL_REF],
+        },
+        headers: { ...REF_MAP, description: 'HTTP header values as credential references; literal values are not accepted.' },
+        toolCallTimeoutMs: { type: 'number', exclusiveMinimum: 0 },
+        maxInstructionBytes: { type: 'integer', minimum: 1 },
+        reconnect: RECONNECT,
+      },
+      required: ['identity', 'transport'], additionalProperties: false,
+    },
+  },
+  required: ['action', 'plan'], additionalProperties: false,
+}
+
+function failure(status, code, message, extra = {}) {
+  return {
+    status, saved: false,
+    error: mcpDiagnostic(new Error(message), { code, hint: code === 'DELEGATED_CALLER' ? 'Ask the parent Orchestrator to perform MCP setup.' : undefined }),
+    ...extra,
+  }
+}
+
+function delegated(agent) {
+  return (agent?.session?.header?.delegationDepth ?? 0) >= 1
+}
+
+function delegatedResult() {
+  return failure('unsupported', 'DELEGATED_CALLER', 'MCP installation belongs to the primary Orchestrator; delegate the setup request to the parent.', {
+    next: { action: 'delegate-to-parent-orchestrator' },
+  })
+}
+
+export function mcpInstallApproved(answer, questionId, approveLabel = MCP_INSTALL_APPROVE_LABEL) {
+  if (!Array.isArray(answer?.answers) || answer.answers.length !== 1) return false
+  const item = answer.answers[0]
+  return item?.id === questionId && Array.isArray(item.selected) && item.selected.length === 1 && item.selected[0] === approveLabel && !item.custom
+}
+
+export function assertMcpInstallStoredPlan(stored) {
+  const digest = createHash('sha256').update(JSON.stringify(stored?.plan)).digest('hex')
+  if (digest !== stored?.digest || fingerprintMcpEntry(stored?.entry) !== stored?.entryFingerprint) {
+    throw Object.assign(new Error('The stored MCP installation plan changed while confirmation was open'), { code: 'plan-changed' })
+  }
+  return true
+}
+
+function cancellation(execSignal, timeoutMs, setTimer, clearTimer) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(execSignal?.reason)
+  if (execSignal?.aborted) abort()
+  else execSignal?.addEventListener?.('abort', abort, { once: true })
+  const timer = setTimer(() => controller.abort(Object.assign(new Error('MCP installation confirmation timed out'), { code: 'confirmation-timeout' })), timeoutMs)
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimer(timer)
+      execSignal?.removeEventListener?.('abort', abort)
+    },
+  }
+}
+
+async function firstConfirmationSettlement(ask, signal) {
+  return new Promise(resolve => {
+    let settled = false
+    const finish = value => {
+      if (settled) return
+      settled = true
+      signal.removeEventListener('abort', aborted)
+      resolve(value)
+    }
+    const aborted = () => finish({ kind: 'cancelled', cause: signal.reason })
+    if (signal.aborted) { aborted(); return }
+    signal.addEventListener('abort', aborted, { once: true })
+    Promise.resolve().then(ask).then(
+      value => finish({ kind: 'answer', value }),
+      cause => finish({ kind: 'error', cause }),
+    )
+  })
+}
+
+function confirmationFailure(cause) {
+  const code = cause?.code ?? 'confirmation-failed'
+  if (code === 'NO_PROVIDER') return failure('unsupported', code, 'Host user confirmation is unavailable; MCP installation was not attempted.')
+  if (code === 'DELEGATED_CALLER') return delegatedResult()
+  if (code === 'CALLER_NOT_LIVE') return failure('owner-changed', code, 'The calling agent is no longer the exact live runtime root; MCP installation was not attempted.')
+  return failure('cancelled', code, 'MCP installation confirmation was cancelled, closed, timed out, or failed; no probe or write occurred.')
+}
+
+function questionFor(stored, execution) {
+  const entry = stored.entry
+  const transport = entry.transport.kind
+  const effect = transport === 'stdio'
+    ? `Process effect: run ${execution?.requestedCommand ?? entry.client.command} and perform MCP discovery.${execution?.resolvedCommand ? `\nResolved executable: ${execution.resolvedCommand}` : ''}`
+    : `Network effect: connect to ${entry.client.url ?? 'the credential-referenced endpoint'} and perform MCP discovery.`
+  const detail = [
+    `Plan digest: ${stored.digest}`,
+    effect,
+    ...(transport === 'stdio' ? [`Arguments (exact argv; credential-referenced positions show [redacted]): ${JSON.stringify(stored.plan?.[0]?.entry?.client?.args ?? [])}`] : []),
+    'Default for new sessions: off. No session selection or Apply is changed.',
+    `Exact redacted plan:\n${JSON.stringify(stored.plan, null, 2)}`,
+  ].join('\n')
+  return {
+    id: 'mcp-install-confirmation',
+    header: 'MCP server setup',
+    question: `Install MCP server "${stored.identity}" with exactly this plan?`,
+    detail,
+    options: [
+      { label: MCP_INSTALL_APPROVE_LABEL, description: 'Probe first; only a successful probe may register and strictly mount this server.' },
+      { label: MCP_INSTALL_CANCEL_LABEL, description: 'Do not probe, write credentials or registry records, or change selection.' },
+    ],
+    multiSelect: false,
+  }
+}
+
+function previewConflict(preview) {
+  const target = preview?.targets?.[0]
+  return target?.conflict || target?.namespaceConflict || null
+}
+
+export function createMcpInstallTool(dependencies) {
+  const timeoutMs = dependencies.timeoutMs ?? MCP_INSTALL_CONFIRMATION_TIMEOUT_MS
+  const setTimer = dependencies.setTimeout ?? setTimeout
+  const clearTimer = dependencies.clearTimeout ?? clearTimeout
+  return {
+    name: MCP_INSTALL_TOOL_NAME,
+    description: 'Preview or install one fresh MCP server using credential references. Install requires exact-plan Host user confirmation, probes before registration, and never changes defaults or session selection.',
+    parameters: MCP_INSTALL_PARAMETERS,
+    output: {
+      schema: { type: 'object' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    async execute(args, exec) {
+      const agent = exec?.agent
+      const session = agent?.session
+      if (delegated(agent)) return delegatedResult()
+      if (!session || !['preview', 'install'].includes(args?.action)) return failure('validation-failed', 'invalid-config', 'mcp_install requires a live session and action preview or install.')
+
+      let mutationStarted = false
+      try {
+        const operations = dependencies.operationsFor(session)
+        const parsed = parseMcpDocument(args.plan, { surface: 'refs' })
+        if (parsed.entries.length !== 1) return failure('validation-failed', 'invalid-config', 'mcp_install accepts exactly one server plan.')
+        const normalized = parsed.entries[0]
+        const identity = normalized.entry.identity
+        const request = { action: 'preview', mode: 'add', identity, config: args.plan, refsOnly: true, surface: 'refs' }
+        const preview = await operations.preview(request)
+        if (preview.digest !== parsed.digest) throw Object.assign(new Error('MCP preview normalization was not stable'), { code: 'plan-changed' })
+        if (args.action === 'preview') return sanitizeMcpPayload({ ...preview, next: { action: 'review-plan-then-install' } })
+        if (previewConflict(preview)) {
+          return failure('conflict', 'name-conflict', `MCP identity or namespace is already registered: ${previewConflict(preview)}`, { identity, registryRevision: preview.registryRevision })
+        }
+        if (dependencies.isLiveRoot?.(agent) !== true) return confirmationFailure({ code: 'CALLER_NOT_LIVE' })
+        const questions = dependencies.userQuestions?.()
+        if (typeof questions?.ask !== 'function') return confirmationFailure({ code: 'NO_PROVIDER' })
+        if (typeof dependencies.mutate !== 'function' || typeof dependencies.captureOwnership !== 'function') {
+          return failure('unsupported', 'ownership-unavailable', 'Exact MCP mutation ownership cannot be verified; installation was not attempted.')
+        }
+
+        const ownership = await dependencies.captureOwnership(session.id)
+        const execution = await dependencies.describeExecution?.(normalized.entry) ?? null
+        const stored = {
+          identity,
+          plan: structuredClone(preview.plan),
+          entry: structuredClone(normalized.entry),
+          digest: preview.digest,
+          entryFingerprint: fingerprintMcpEntry(normalized.entry),
+          registryRevision: preview.registryRevision,
+        }
+        const retained = dependencies.storePlan?.(stored) ?? stored
+        const question = questionFor(retained, execution)
+        const combined = cancellation(exec.signal, timeoutMs, setTimer, clearTimer)
+        let settlement
+        try {
+          settlement = await firstConfirmationSettlement(() => questions.ask({ agent, questions: [question], signal: combined.signal }), combined.signal)
+        } finally { combined.dispose() }
+        if (settlement.kind !== 'answer') return confirmationFailure(settlement.cause)
+        if (!mcpInstallApproved(settlement.value, question.id)) {
+          return failure('cancelled', 'confirmation-not-approved', 'The exact approval option was not selected alone; no probe or write occurred.')
+        }
+
+        if (dependencies.isLiveRoot?.(agent) !== true) return confirmationFailure({ code: 'CALLER_NOT_LIVE' })
+        assertMcpInstallStoredPlan(retained)
+        const currentOwner = await dependencies.captureOwnership(session.id)
+        if (!dependencies.sameOwnership(ownership, currentOwner)) {
+          return failure('owner-changed', 'owner-changed', 'MCP mutation ownership changed while confirmation was open; no probe or write occurred.', {
+            next: { action: 'preview-again' },
+          })
+        }
+        const current = await operations.preview({
+          action: 'preview', mode: 'add', identity, config: retained.entry, refsOnly: true, surface: 'refs',
+        })
+        if (current.digest !== retained.digest || current.registryRevision !== retained.registryRevision) {
+          return failure('revision-conflict', 'plan-or-revision-changed', 'The MCP plan or registry revision changed while confirmation was open; preview again.', {
+            identity, registryRevision: current.registryRevision, next: { action: 'preview-again' },
+          })
+        }
+        if (previewConflict(current)) {
+          return failure('conflict', 'name-conflict', `MCP identity or namespace changed while confirmation was open: ${previewConflict(current)}`, {
+            identity, registryRevision: current.registryRevision, next: { action: 'preview-again' },
+          })
+        }
+
+        mutationStarted = true
+        const outcome = await dependencies.mutate(session.id, {
+          action: 'installFromAgent', identity, config: retained.entry, refsOnly: true, surface: 'refs', targetFingerprint: null,
+        })
+        return sanitizeMcpPayload(outcome)
+      } catch (cause) {
+        const code = cause?.code ?? (mutationStarted ? 'indeterminate' : 'validation-failed')
+        if (code === 'CALLER_NOT_LIVE' || code === 'NO_PROVIDER' || code === 'DELEGATED_CALLER') return confirmationFailure(cause)
+        if (code === 'owner-changed') return failure('owner-changed', code, 'MCP mutation ownership changed; inspect actual state before retrying.', { next: { action: 'inspect-actual-state' } })
+        if (code === 'plan-changed') return failure('conflict', code, 'The approved MCP plan changed; no probe or write occurred.', { next: { action: 'preview-again' } })
+        return failure(mutationStarted ? 'indeterminate' : code === 'invalid-config' || code === 'executable-not-found' ? 'validation-failed' : 'indeterminate', code,
+          mutationStarted ? 'The confirmed MCP installation outcome is unavailable; inspect actual registry and mount state.' : 'MCP installation could not be prepared.', {
+            ...(mutationStarted ? { next: { action: 'reread-registry' } } : {}),
+          })
+      }
+    },
+  }
+}