llm-cli-gateway 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.9.0] - 2026-06-14: MCP-surface red-team remediation
+
+This release remediates all 17 findings of a multi-LLM red-team of the gateway's
+external and internal MCP surface. Every change is material only in the opt-in
+remote/OAuth/multi-tenant modes or under `approvalStrategy:"mcp_managed"`; the
+default local-stdio path is unaffected. Provider CLI release targets are
+unchanged from 2.8.0 (see `docs/upstream/release-targets.md`).
+
+### Security
+
+- Per-principal isolation (F3): `session_*`, `llm_job_*`, and
+  `llm_request_result` now resolve a calling owner principal and enforce
+  own-or-not-found access, so one OAuth client can no longer read or mutate
+  another client's sessions, jobs, or persisted request results. Owner columns
+  are additive and nullable; legacy unowned rows remain accessible to local
+  callers. The shared static bearer is one principal by design.
+- Built-in OAuth server hardening (F14): the authorization-code flow gains an
+  opt-in human-consent gate (dedicated consent password, default off) and a
+  trusted-principal-header seam so a proxy front door can attribute requests
+  without the gateway shipping any identity-provider configuration.
+- Approval-gate hard boundary (F15): under `approvalStrategy:"mcp_managed"` a
+  full permission/sandbox bypass request is now denied by default regardless of
+  heuristic score, and the managed strategy no longer force-sets each provider's
+  most-permissive mode. See "Changed" for the per-provider defaults.
+- Secret redaction (F4): prompts and responses are redacted before they are
+  written to the flight-recorder database.
+- Remote-exposure fail-closed (F17): a remotely-exposed open OAuth configuration
+  refuses to start, and the `Host` header is no longer trusted for loopback
+  determination.
+- MCP surface hardening (F1/F2/F10): request bodies are capped to prevent a
+  memory DoS, `cli_upgrade` targets are clamped to block arbitrary-package
+  installation, and a committed NUL byte in `config.ts` (which rendered the file
+  binary and invisible to gitleaks/SAST/grep) was removed.
+
+### Changed
+
+- Under `approvalStrategy:"mcp_managed"`, every provider now defaults to an
+  accept-edits-level mode (auto-accept file edits, dangerous tools still gated)
+  instead of full auto-approve: Claude `--permission-mode acceptEdits`, Grok
+  `--permission-mode acceptEdits`, Mistral `--agent accept-edits`, and Gemini
+  prompted `default` (the `agy` CLI has no accept-edits rung, so without the
+  opt-in Gemini cannot auto-approve mutating tools under `mcp_managed`). Each
+  escalates to its full auto-approve mode only when the operator sets
+  `LLM_GATEWAY_APPROVAL_ALLOW_BYPASS`. The `legacy` strategy is unchanged.
+
+## [2.8.0] - 2026-06-14: HTTP workspace gating and ACP transport
+
+### Added
+
+- Added ACP gateway extension foundations, including the contract, config and
+  capability surface, and transport core.
+- Added provider CLI release-target evidence for release validation: exact
+  probed Claude Code, Codex, Antigravity (`agy`), Grok, and Mistral Vibe
+  versions plus artifact SHA-256 values.
+- Added Gemini, Grok, and Mistral pricing families and Codex token/cache usage
+  telemetry extraction.
+
+### Changed
+
+- HTTP and tunnel provider execution now uses explicit request transport
+  metadata and requires a registered workspace, default workspace, or session
+  workspace before spawning a provider across sync/async request tools and
+  `codex_fork_session`. Local stdio keeps the prior unrestricted
+  `workingDir`/`addDir` behavior.
+- Replaced the OAuth-only remote workspace guard with transport-based HTTP
+  workspace gating, so bearer, OAuth, auth-disabled, and configured no-auth
+  connector HTTP paths all fail closed before provider spawn.
+- Replaced CodeQL with the OSS SAST workflow using OpenGrep, gosec, and
+  govulncheck.
+
+### Fixed
+
+- Corrected Claude default pricing/cache classification and Grok API pricing
+  bucket handling.
+- Preserved captured async orphan readbacks as completed flight-recorder rows
+  when stdout was captured and no failure was recorded.
+
+### Documentation
+
+- Documented Grok CLI prompt-surface telemetry limitations.
+- Documented ACP gateway extension research, design, and smoke validation.
+
 ## [2.7.0] - 2026-06-12: Provider capability inventory
 
 ### Added

package/README.md

@@ -45,7 +45,7 @@ Or use directly with `npx` from an MCP client:
 - Can run requests inside gateway-managed git worktrees for isolated multi-agent review and implementation loops.
 - Ships personal-appliance setup surfaces: HTTP transport with bearer-token auth, `doctor --json`, setup UI artifacts, provider setup snippets, Docker fallback, and checked release bundles.
 - Remote web connectors use MCP OAuth discovery and authorization-code setup with static client or shared-secret gates. Client secrets are generated locally, stored only as hashes, and printed only by explicit copy-once commands.
-- Provider CLI requests can select registered workspaces by alias via `workspace`; remote requests should use aliases, not arbitrary filesystem paths. New local folder/Git workspaces can be created only under configured allowed roots.
+- Provider CLI requests can select registered workspaces by alias via `workspace`; every HTTP/tunnel request must use a registered alias, session workspace, or `[workspaces].default` before provider execution. Local unrestricted filesystem access is the stdio transport.
 
 ## Workflow Assets
 
@@ -337,6 +337,8 @@ For clients that already support local stdio MCP servers, add a configuration li
 }
 ```
 
+Stdio is the recommended path for unrestricted machine-local development access. HTTP MCP, including localhost HTTP and tunneled HTTPS, is treated as remote-capable for provider execution: provider tools must resolve a registered workspace alias, a session workspace, or `[workspaces].default` before spawning a CLI. Remote clients should pass relative `workingDir`, `addDir`, and include-directory values inside the selected workspace; disabling auth or using a no-auth connector path is not a filesystem bypass.
+
 This generic stdio example is not provider-support verification for the Personal MCP Appliance. Client-specific setup guides for ChatGPT, Claude web, Claude Desktop, Codex, Gemini CLI, Gemini web, and Grok remain gated by the provider-support matrix in [docs/personal-mcp/PRODUCT_CONTRACT.md](docs/personal-mcp/PRODUCT_CONTRACT.md).
 
 ### Available Tools
@@ -399,6 +401,8 @@ Execute a Claude Code request with optional session management.
 - `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
+Workspace boundary: stdio callers may use machine-local paths directly. HTTP/tunnel callers must pass `workspace` or rely on a configured default/session workspace; path fields are then validated relative to that workspace. `[workspaces].allow_unregistered_working_dir` is a stdio/local legacy setting and does not allow arbitrary HTTP working directories or additional directories.
+
 **Response extras:**
 
 - `approval`: Approval decision record when `approvalStrategy="mcp_managed"`
@@ -1156,6 +1160,24 @@ await callTool("session_delete", {
   ```bash
   LLM_GATEWAY_APPROVAL_POLICY=strict node dist/index.js
   ```
+- `LLM_GATEWAY_APPROVAL_ALLOW_BYPASS`: Under `approvalStrategy:"mcp_managed"`, a full permission / sandbox bypass request (e.g. `dangerouslyBypassApprovalsAndSandbox`, `dangerouslySkipPermissions`) is **denied by default** regardless of approval score, **and** `mcp_managed` no longer force-bypasses any provider — each defaults to an auto-accept-edits-level mode (auto-accept file edits, still gate Bash and other dangerous tools) instead of full auto-approve:
+  - **Claude** → `--permission-mode acceptEdits` (was `bypassPermissions`)
+  - **Grok** → `--permission-mode acceptEdits` (was `--always-approve`)
+  - **Mistral (Vibe)** → `--agent accept-edits` (was `--agent auto-approve`)
+  - **Gemini (Antigravity)** → `default` / prompted, i.e. **no** `--dangerously-skip-permissions` (the `agy` CLI has no accept-edits middle rung, so the safe default is prompted execution; without the opt-in, Gemini cannot auto-approve mutating tools under `mcp_managed`)
+
+  Set to `1`/`true` to let the operator opt back in: this permits bypass requests through the approval gate **and** restores each provider's full auto-approve mode under `mcp_managed` (Claude `bypassPermissions`, Grok `--always-approve`, Mistral `--agent auto-approve`, Gemini `--dangerously-skip-permissions`). Sandboxed auto modes (e.g. codex `--sandbox workspace-write`) are unaffected.
+  ```bash
+  LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1 node dist/index.js
+  ```
+- `LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER`: Name of an HTTP header carrying the authenticated user identity asserted by a **trusted front door** (any identity-aware reverse proxy / IdP). When set, the gateway adopts that header value as the request's ownership principal — but **only** for requests authenticated with the gateway's own static bearer token (i.e. the trusted upstream proxy), never from an arbitrary remote client. Off by default; IdP-agnostic. Lets a proxy-fronted multi-user deployment carry per-user identity into the gateway.
+  ```bash
+  LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER=x-gateway-principal node dist/index.js
+  ```
+- `LLM_GATEWAY_OAUTH_REQUIRE_CONSENT` / `LLM_GATEWAY_OAUTH_CONSENT_SECRET`: Opt-in human-consent gate for the built-in OAuth server. When enabled (`REQUIRE_CONSENT=1`, or implied by setting `CONSENT_SECRET`), `/oauth/authorize` renders an operator approval page (CSRF-protected) and issues an authorization code **only** after the dedicated consent password is entered — instead of auto-issuing. `CONSENT_SECRET` is the plaintext password (hashed in memory; or persist a `consent_secret_hash` in `[http.oauth]`). Off by default; remote OAuth refuses to enable consent without a secret to verify.
+  ```bash
+  LLM_GATEWAY_OAUTH_REQUIRE_CONSENT=1 LLM_GATEWAY_OAUTH_CONSENT_SECRET='choose-a-strong-code' node dist/index.js
+  ```
 - `LLM_GATEWAY_CONFIG`: Path to the gateway TOML config (default: `~/.llm-cli-gateway/config.toml`). See **Persistence configuration** above for the `[persistence]` schema.
 - `LLM_GATEWAY_LOGS_DB`: **Deprecated** — overrides `[persistence].path` and selects `backend = "sqlite"` (or `backend = "none"` when set to `none`). Emits a deprecation warning at startup; migrate to `config.toml`.
   ```bash
@@ -1164,6 +1186,11 @@ await callTool("session_delete", {
   # Disable durable persistence (also disables *_request_async tools)
   LLM_GATEWAY_LOGS_DB=none node dist/index.js
   ```
+- `LLM_GATEWAY_REDACT_LOGGED_SECRETS`: Redact recognisable secrets (provider/cloud/VCS keys, bearer tokens, JWTs, PEM private keys, `key=value` secret assignments) from the prompt/system/response copies written to the flight-recorder log. **Enabled by default**; set to `0`/`false`/`off`/`no` to store content verbatim. Only the audit log is affected — live sync responses and async `llm_job_result` output are never altered.
+  ```bash
+  # Opt out of flight-recorder secret redaction
+  LLM_GATEWAY_REDACT_LOGGED_SECRETS=0 node dist/index.js
+  ```
 
 ### CLI-Specific Settings
 

package/dist/acp/client.d.ts

@@ -0,0 +1,78 @@
+import { AcpError } from "./errors.js";
+import type { JsonRpcStdioTransport, JsonRpcId } from "./json-rpc-stdio.js";
+import { type ContentBlock, type InitializeResponse, type ReadTextFileRequest, type ReadTextFileResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionLoadResponse, type SessionNewResponse, type SessionPromptResponse, type SessionUpdateNotification, type WriteTextFileRequest, type WriteTextFileResponse } from "./types.js";
+import type { Logger } from "../logger.js";
+import type { CliType } from "../session-manager.js";
+export declare const DEFAULT_ACP_PROTOCOL_VERSION = 1;
+export interface HostServices {
+    readTextFile?(request: ReadTextFileRequest, context: HostCallbackContext): Promise<ReadTextFileResponse>;
+    writeTextFile?(request: WriteTextFileRequest, context: HostCallbackContext): Promise<WriteTextFileResponse>;
+    requestPermission?(request: RequestPermissionRequest, context: HostCallbackContext): Promise<RequestPermissionResponse>;
+}
+export interface HostCallbackContext {
+    readonly provider: CliType;
+    readonly method: string;
+}
+export interface AcpClientCallbacks {
+    readonly onSessionUpdate?: (update: SessionUpdateNotification) => void;
+    readonly onProcessExit?: (error: AcpError) => void;
+}
+export interface AcpClientOptions {
+    readonly transport: JsonRpcStdioTransport;
+    readonly provider: CliType;
+    readonly hostServices: HostServices;
+    readonly callbacks?: AcpClientCallbacks;
+    readonly logger?: Logger;
+    readonly protocolVersion?: number;
+    readonly timeouts?: AcpClientTimeouts;
+}
+export interface AcpClientTimeouts {
+    readonly initializeMs?: number;
+    readonly sessionNewMs?: number;
+    readonly sessionLoadMs?: number;
+    readonly promptMs?: number;
+}
+export interface InitializeOptions {
+    readonly readTextFile?: boolean;
+    readonly writeTextFile?: boolean;
+    readonly terminal?: boolean;
+}
+export interface NewSessionParams {
+    readonly cwd: string;
+    readonly mcpServers?: ReadonlyArray<Record<string, unknown>>;
+}
+export interface LoadSessionParams extends NewSessionParams {
+    readonly sessionId: string;
+}
+export interface PromptParams {
+    readonly sessionId: string;
+    readonly prompt: ReadonlyArray<ContentBlock>;
+}
+export declare class AcpClient {
+    private readonly transport;
+    private readonly provider;
+    private readonly hostServices;
+    private readonly callbacks?;
+    private readonly logger;
+    private readonly protocolVersion;
+    private readonly timeouts;
+    private initialized;
+    private initializeResult;
+    constructor(options: AcpClientOptions);
+    get isInitialized(): boolean;
+    get agentInfo(): InitializeResponse | null;
+    initialize(options?: InitializeOptions): Promise<InitializeResponse>;
+    newSession(params: NewSessionParams): Promise<SessionNewResponse>;
+    loadSession(params: LoadSessionParams): Promise<SessionLoadResponse>;
+    prompt(params: PromptParams): Promise<SessionPromptResponse>;
+    cancel(sessionId: string): void;
+    private send;
+    private normalizeError;
+    private assertInitialized;
+    handleNotification(method: string, params: unknown): void;
+    private handleSessionUpdate;
+    handleRequest(id: JsonRpcId, method: string, params: unknown): void;
+    private dispatchRequest;
+    private requireHandler;
+    notifyProcessExit(error: AcpError): void;
+}

package/dist/acp/client.js

@@ -0,0 +1,201 @@
+import { AcpProtocolError, isAcpError } from "./errors.js";
+import { parseInitializeResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionUpdateNotification, parseWriteTextFileRequest, } from "./types.js";
+import { noopLogger } from "../logger.js";
+export const DEFAULT_ACP_PROTOCOL_VERSION = 1;
+export class AcpClient {
+    transport;
+    provider;
+    hostServices;
+    callbacks;
+    logger;
+    protocolVersion;
+    timeouts;
+    initialized = false;
+    initializeResult = null;
+    constructor(options) {
+        this.transport = options.transport;
+        this.provider = options.provider;
+        this.hostServices = options.hostServices;
+        this.callbacks = options.callbacks;
+        this.logger = options.logger ?? noopLogger;
+        this.protocolVersion = options.protocolVersion ?? DEFAULT_ACP_PROTOCOL_VERSION;
+        this.timeouts = options.timeouts ?? {};
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    get agentInfo() {
+        return this.initializeResult;
+    }
+    async initialize(options = {}) {
+        if (this.initialized && this.initializeResult) {
+            return this.initializeResult;
+        }
+        const params = {
+            protocolVersion: this.protocolVersion,
+            clientCapabilities: {
+                fs: {
+                    readTextFile: options.readTextFile ?? false,
+                    writeTextFile: options.writeTextFile ?? false,
+                },
+                terminal: options.terminal ?? false,
+            },
+        };
+        const raw = await this.send("initialize", params, this.timeouts.initializeMs);
+        const result = parseInitializeResponse(raw, this.provider);
+        this.initialized = true;
+        this.initializeResult = result;
+        return result;
+    }
+    async newSession(params) {
+        this.assertInitialized("session/new");
+        const raw = await this.send("session/new", { cwd: params.cwd, mcpServers: params.mcpServers ?? [] }, this.timeouts.sessionNewMs);
+        return parseSessionNewResponse(raw, this.provider);
+    }
+    async loadSession(params) {
+        this.assertInitialized("session/load");
+        const raw = await this.send("session/load", {
+            sessionId: params.sessionId,
+            cwd: params.cwd,
+            mcpServers: params.mcpServers ?? [],
+        }, this.timeouts.sessionLoadMs);
+        return parseSessionLoadResponse(raw, this.provider);
+    }
+    async prompt(params) {
+        this.assertInitialized("session/prompt");
+        const raw = await this.send("session/prompt", { sessionId: params.sessionId, prompt: params.prompt }, this.timeouts.promptMs);
+        return parseSessionPromptResponse(raw, this.provider);
+    }
+    cancel(sessionId) {
+        this.transport.notify("session/cancel", { sessionId });
+    }
+    async send(method, params, timeoutMs) {
+        try {
+            return await this.transport.request(method, params, timeoutMs);
+        }
+        catch (err) {
+            throw this.normalizeError(method, err);
+        }
+    }
+    normalizeError(method, err) {
+        if (isAcpError(err)) {
+            return err;
+        }
+        return new AcpProtocolError(`ACP request ${method} failed unexpectedly.`, {
+            provider: this.provider,
+            debug: { method, errorClass: err instanceof Error ? err.name : "unknown" },
+        });
+    }
+    assertInitialized(method) {
+        if (!this.initialized) {
+            throw new AcpProtocolError(`ACP ${method} requires initialize to complete first.`, {
+                provider: this.provider,
+                debug: { method, reason: "not_initialized" },
+            });
+        }
+    }
+    handleNotification(method, params) {
+        if (method === "session/update") {
+            this.handleSessionUpdate(params);
+            return;
+        }
+        this.logger.debug("acp.client.unknown_notification", {
+            provider: this.provider,
+            method,
+        });
+    }
+    handleSessionUpdate(params) {
+        let parsed;
+        try {
+            parsed = parseSessionUpdateNotification(params, this.provider);
+        }
+        catch (err) {
+            this.logger.error("acp.client.session_update.parse_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+            return;
+        }
+        try {
+            this.callbacks?.onSessionUpdate?.(parsed);
+        }
+        catch (err) {
+            this.logger.error("acp.client.session_update.handler_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    handleRequest(id, method, params) {
+        void this.dispatchRequest(id, method, params);
+    }
+    async dispatchRequest(id, method, params) {
+        const context = { provider: this.provider, method };
+        try {
+            switch (method) {
+                case "fs/read_text_file": {
+                    const request = parseReadTextFileRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.readTextFile, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                case "fs/write_text_file": {
+                    const request = parseWriteTextFileRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.writeTextFile, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                case "session/request_permission": {
+                    const request = parseRequestPermissionRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.requestPermission, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                default: {
+                    this.logger.debug("acp.client.unknown_host_request", {
+                        provider: this.provider,
+                        method,
+                    });
+                    this.transport.respondError(id, {
+                        code: -32601,
+                        message: "Method not found",
+                    });
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            const acpError = isAcpError(err) ? err : this.normalizeError(method, err);
+            this.logger.error("acp.client.host_request.failed", {
+                provider: this.provider,
+                method,
+                errorClass: acpError.name,
+                kind: acpError.kind,
+            });
+            this.transport.respondError(id, {
+                code: -32000,
+                message: acpError.userMessage,
+            });
+        }
+    }
+    requireHandler(handler, method) {
+        if (!handler) {
+            throw new AcpProtocolError(`Host does not support ACP ${method}.`, {
+                provider: this.provider,
+                debug: { method, reason: "unsupported_host_method" },
+            });
+        }
+        return handler.bind(this.hostServices);
+    }
+    notifyProcessExit(error) {
+        try {
+            this.callbacks?.onProcessExit?.(error);
+        }
+        catch (err) {
+            this.logger.error("acp.client.process_exit.handler_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+}

package/dist/acp/errors.d.ts

@@ -0,0 +1,63 @@
+import type { CliType } from "../session-manager.js";
+export type AcpErrorKind = "acp_disabled" | "provider_acp_disabled" | "provider_acp_unsupported" | "provider_runtime_disabled" | "provider_unavailable" | "protocol" | "timeout" | "permission_denied" | "process_exit";
+export declare function redactAcpMessage(input: string): string;
+export declare function redactAcpDebug(value: unknown): unknown;
+export declare function redactAcpCause(cause: unknown): unknown;
+export interface AcpErrorDebug {
+    readonly [key: string]: unknown;
+}
+export declare class AcpError extends Error {
+    readonly kind: AcpErrorKind;
+    readonly provider?: CliType;
+    readonly debug: AcpErrorDebug;
+    constructor(kind: AcpErrorKind, userMessage: string, options?: {
+        provider?: CliType;
+        debug?: AcpErrorDebug;
+        cause?: unknown;
+    });
+    get userMessage(): string;
+}
+export declare class AcpDisabledError extends AcpError {
+    constructor(debug?: AcpErrorDebug);
+}
+export declare class ProviderAcpDisabledError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderAcpUnsupportedError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderRuntimeDisabledError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderUnavailableError extends AcpError {
+    constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
+}
+export declare class AcpProtocolError extends AcpError {
+    readonly code?: number;
+    constructor(userMessage: string, options?: {
+        provider?: CliType;
+        code?: number;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare class AcpTimeoutError extends AcpError {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number, options?: {
+        provider?: CliType;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare class AcpPermissionDeniedError extends AcpError {
+    constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
+}
+export declare class AcpProcessExitError extends AcpError {
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    constructor(provider: CliType, options?: {
+        exitCode?: number | null;
+        signal?: string | null;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare function isAcpError(value: unknown): value is AcpError;

package/dist/acp/errors.js

@@ -0,0 +1,139 @@
+export function redactAcpMessage(input) {
+    let out = input;
+    out = out.replace(/\{[\s\S]*?\}/g, "<redacted-json>");
+    out = out.replace(/\[[\s\S]*?\]/g, "<redacted-json>");
+    out = out.replace(/\b(bearer|token|api[_-]?key|secret)\b\s*[:=]?\s*\S+/gi, "$1 <redacted>");
+    out = out.replace(/\b(sk|xai|gsk|key)-[A-Za-z0-9_-]{8,}\b/gi, "<redacted-token>");
+    out = out.replace(/(^|[^A-Za-z0-9._~\\/-])[A-Za-z]:\\[^\s"')\]}>]*/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~\\/-])\\\\[^\s"')\]}>]+/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~/-])~\/[^\s"')\]}>]+/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~/-])\/[A-Za-z0-9._/-]{2,}/g, "$1<redacted-path>");
+    out = out.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "<redacted-email>");
+    return out;
+}
+export function redactAcpDebug(value) {
+    const sensitiveKey = /(payload|body|prompt|content|token|secret|api[_-]?key|credential|auth|cwd|path)/i;
+    if (typeof value === "string") {
+        return redactAcpMessage(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => redactAcpDebug(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            if (sensitiveKey.test(key)) {
+                out[key] = "<redacted>";
+                continue;
+            }
+            out[key] = redactAcpDebug(inner);
+        }
+        return out;
+    }
+    return value;
+}
+export function redactAcpCause(cause) {
+    if (cause instanceof Error) {
+        const redacted = new Error(redactAcpMessage(cause.message));
+        redacted.name = redactAcpMessage(cause.name);
+        if (typeof cause.stack === "string") {
+            redacted.stack = redactAcpMessage(cause.stack);
+        }
+        return redacted;
+    }
+    return redactAcpDebug(cause);
+}
+export class AcpError extends Error {
+    kind;
+    provider;
+    debug;
+    constructor(kind, userMessage, options) {
+        super(redactAcpMessage(userMessage));
+        this.name = "AcpError";
+        this.kind = kind;
+        this.provider = options?.provider;
+        this.debug = redactAcpDebug(options?.debug ?? {}) ?? {};
+        if (options?.cause !== undefined) {
+            this.cause = redactAcpCause(options.cause);
+        }
+    }
+    get userMessage() {
+        return this.message;
+    }
+}
+export class AcpDisabledError extends AcpError {
+    constructor(debug) {
+        super("acp_disabled", "ACP transport is disabled. Enable [acp] in the gateway config to use transport=acp, or omit transport to use the default CLI path.", { debug });
+        this.name = "AcpDisabledError";
+    }
+}
+export class ProviderAcpDisabledError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_acp_disabled", `ACP is disabled for provider ${provider}. Enable it under [acp.providers.${provider}] or omit transport to use the default CLI path.`, { provider, debug });
+        this.name = "ProviderAcpDisabledError";
+    }
+}
+export class ProviderAcpUnsupportedError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_acp_unsupported", `Provider ${provider} has no native ACP support at its target version. Use the default CLI transport for this provider.`, { provider, debug });
+        this.name = "ProviderAcpUnsupportedError";
+    }
+}
+export class ProviderRuntimeDisabledError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_runtime_disabled", `ACP runtime routing is not enabled for provider ${provider}. Set runtime_enabled=true under [acp.providers.${provider}] to allow prompt routing.`, { provider, debug });
+        this.name = "ProviderRuntimeDisabledError";
+    }
+}
+export class ProviderUnavailableError extends AcpError {
+    constructor(provider, reason, debug) {
+        super("provider_unavailable", `Provider ${provider} ACP entrypoint is unavailable: ${reason}`, {
+            provider,
+            debug,
+        });
+        this.name = "ProviderUnavailableError";
+    }
+}
+export class AcpProtocolError extends AcpError {
+    code;
+    constructor(userMessage, options) {
+        super("protocol", userMessage, { provider: options?.provider, debug: options?.debug });
+        this.name = "AcpProtocolError";
+        this.code = options?.code;
+    }
+}
+export class AcpTimeoutError extends AcpError {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs, options) {
+        super("timeout", `ACP request ${method} timed out after ${timeoutMs}ms.`, {
+            provider: options?.provider,
+            debug: options?.debug,
+        });
+        this.name = "AcpTimeoutError";
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class AcpPermissionDeniedError extends AcpError {
+    constructor(provider, reason, debug) {
+        super("permission_denied", `ACP permission request was denied: ${reason}`, { provider, debug });
+        this.name = "AcpPermissionDeniedError";
+    }
+}
+export class AcpProcessExitError extends AcpError {
+    exitCode;
+    signal;
+    constructor(provider, options) {
+        super("process_exit", `Provider ${provider} ACP process exited before the request completed.`, {
+            provider,
+            debug: options?.debug,
+        });
+        this.name = "AcpProcessExitError";
+        this.exitCode = options?.exitCode ?? null;
+        this.signal = options?.signal ?? null;
+    }
+}
+export function isAcpError(value) {
+    return value instanceof AcpError;
+}