@prohost/cli 0.2.2 → 0.3.0

package/dist/agent/claude.d.ts

@@ -87,7 +87,10 @@ export interface ClaudeFlags {
  * servers in the operator's own configuration with ours, so a run answering a
  * customer's question would hold whatever MCP servers they use for their day
  * job — with permission checks off. Ours is the only one this run is entitled
- * to.
+ * to, plus whatever the operator listed in `extra-mcp.json` — a file they had
+ * to write by hand, which is the point: the boundary still holds, and crossing
+ * it is a decision somebody made on purpose rather than one their day-job
+ * config made for them.
  */
 export declare function claudeCommand(base: string, flags?: ClaudeFlags): string;
 /** What the harness got back from one Claude Code invocation. */
@@ -103,7 +106,7 @@ export type ClaudeOutput = {
     denials: string[];
 };
 /**
- * Read the reply and the session id out of `--output-format json` stdout.
+ * Read the reply and the session id out of a finished run's stdout.
  *
  * Unparseable output is a **failure**, not a fallback to posting the raw text.
  * We asked for JSON; stdout that isn't JSON means something went wrong that we
@@ -111,8 +114,60 @@ export type ClaudeOutput = {
  * one thing that must not happen is that being posted verbatim into a customer's
  * conversation. Reporting the run failed is recoverable; sending a stack trace
  * to a guest is not.
+ *
+ * Still whole-stdout rather than streaming, and still used: it is what
+ * {@link readClaudeStream} falls back to when a run produced no `result` event
+ * at all, and it reads a plain `--output-format json` envelope exactly as it
+ * always did.
  */
 export declare function parseClaudeOutput(stdout: string): ClaudeOutput;
+/** Cap on the activity line handed to the heartbeat. */
+export declare const MAX_ACTIVITY_CHARS = 120;
+/** Cap on the partial answer salvaged from a run that was killed. */
+export declare const MAX_SALVAGE_CHARS = 500;
+/**
+ * A run's stdout, read as it is produced.
+ *
+ * Everything here is an enhancement over reading stdout at exit, and every one
+ * of them fails soft: a stream we cannot parse costs progress reporting and
+ * salvage, never the run.
+ */
+export interface ClaudeStream {
+    /** Feed one stdout chunk. Never throws. */
+    push(chunk: string): void;
+    /**
+     * The session id, as soon as the run announced it.
+     *
+     * This is the whole reason the session id is read here rather than out of the
+     * final envelope: a run killed at hour two never produces a final envelope,
+     * and without the id its two hours of context are unreachable — the next turn
+     * on that surface starts from nothing.
+     */
+    sessionId(): string | undefined;
+    /**
+     * What the agent is doing right now, in one short line — the last tool it
+     * called, or the opening of the text it is writing.
+     */
+    activity(): string | undefined;
+    /** The tail of the last thing the agent wrote, for a run that was killed. */
+    salvage(): string | undefined;
+    /**
+     * The turn's outcome. ``stdout`` is the complete captured output, used only
+     * when the stream held no `result` event — a crashed binary, a login prompt,
+     * or a plain `--output-format json` envelope from a command we did not shape.
+     */
+    finish(stdout: string): ClaudeOutput;
+}
+/**
+ * Parse `--output-format stream-json` incrementally.
+ *
+ * Line-delimited JSON, one event per line, so the parser is a buffer and a
+ * split. Anything it doesn't recognise is skipped in silence: the event
+ * vocabulary belongs to Claude Code and grows without asking us, and a reader
+ * that failed on an unknown `type` would turn a Claude Code release into a
+ * fleet of broken laptops.
+ */
+export declare function readClaudeStream(): ClaudeStream;
 /**
  * Does this look like the resume having been rejected, rather than the agent
  * having failed at its actual work?
@@ -131,10 +186,25 @@ export declare function looksLikeResumeFailure(output: string, sessionId: string
 /** Absolute path of the generated MCP config. */
 export declare function mcpConfigPath(env?: NodeJS.ProcessEnv): string;
 export interface McpConfigOptions {
-    /** The MCP endpoint the pairing reported, e.g. `https://connect.prohost.ai/mcp`. */
-    mcpUrl: string;
+    /**
+     * The MCP endpoint the pairing reported, e.g. `https://connect.prohost.ai/mcp`.
+     *
+     * Optional, because a pairing can carry none — and a run with no ProhostAI
+     * server is still a run whose operator may have opted into extras. Omitted,
+     * the generated config holds only those, and `--strict-mcp-config` still
+     * keeps everything else out.
+     */
+    mcpUrl?: string;
     /** The paired API key. Written to a `0600` file and nowhere else. */
     apiKey: string;
+    /**
+     * Servers the operator opted into via `$PROHOST_HOME/extra-mcp.json`.
+     *
+     * Merged in *under* ours, never over it: {@link loadExtraMcpServers} already
+     * refuses an entry named `prohost`, and writing ours last means even a future
+     * bug there cannot end with a run's workspace tools pointed somewhere else.
+     */
+    extraServers?: Record<string, Record<string, unknown>>;
     env?: NodeJS.ProcessEnv;
 }
 /**

package/dist/agent/claude.js

@@ -87,7 +87,10 @@ export function isClaudeExec(command) {
  * servers in the operator's own configuration with ours, so a run answering a
  * customer's question would hold whatever MCP servers they use for their day
  * job — with permission checks off. Ours is the only one this run is entitled
- * to.
+ * to, plus whatever the operator listed in `extra-mcp.json` — a file they had
+ * to write by hand, which is the point: the boundary still holds, and crossing
+ * it is a decision somebody made on purpose rather than one their day-job
+ * config made for them.
  */
 export function claudeCommand(base, flags = {}) {
     const platform = flags.platform ?? process.platform;
@@ -106,7 +109,17 @@ export function claudeCommand(base, flags = {}) {
             .split(/\s+/)
             .filter((word) => word !== '--dangerously-skip-permissions')
             .join(' ');
-    const parts = [command, '--output-format', 'json'];
+    // `stream-json` rather than `json`, and the two flags travel together:
+    // Claude Code refuses `--output-format stream-json` in print mode without
+    // `--verbose`. What it buys is everything that cannot wait for the process to
+    // exit — the session id lands in the ledger on the first event rather than
+    // after the reply is posted, the heartbeat can say what the agent is doing,
+    // and a run that gets killed at hour two still has a partial answer to
+    // report. The final `result` event carries the same fields the single JSON
+    // envelope did, so the reply itself is unchanged.
+    const parts = [command, '--output-format', 'stream-json'];
+    if (!/(^|\s)--verbose(\s|$)/.test(command))
+        parts.push('--verbose');
     if (skipPermissions)
         parts.push('--dangerously-skip-permissions');
     if (flags.sessionId)
@@ -195,27 +208,13 @@ function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 /**
- * Read the reply and the session id out of `--output-format json` stdout.
+ * Turn a `result` envelope into the harness's view of the turn.
  *
- * Unparseable output is a **failure**, not a fallback to posting the raw text.
- * We asked for JSON; stdout that isn't JSON means something went wrong that we
- * do not understand — a crash banner, a login prompt, an npm warning — and the
- * one thing that must not happen is that being posted verbatim into a customer's
- * conversation. Reporting the run failed is recoverable; sending a stack trace
- * to a guest is not.
+ * Shared by the whole-stdout parser and the streaming reader, because the
+ * envelope is identical either way: `--output-format stream-json` ends with the
+ * same object `--output-format json` used to print on its own.
  */
-export function parseClaudeOutput(stdout) {
-    const parsed = resultEnvelope(stdout);
-    if (!parsed) {
-        const sample = stdout.trim().slice(0, 200);
-        return {
-            denials: [],
-            ok: false,
-            error: sample
-                ? `claude did not return JSON (asked for --output-format json). First 200 chars: ${sample}`
-                : 'claude returned no output',
-        };
-    }
+function outputFromEnvelope(parsed) {
     const sessionId = text(parsed.session_id);
     const result = text(parsed.result);
     const denials = denialNames(parsed.permission_denials);
@@ -236,6 +235,155 @@ export function parseClaudeOutput(stdout) {
     }
     return { ok: true, text: result, sessionId, denials };
 }
+/**
+ * Read the reply and the session id out of a finished run's stdout.
+ *
+ * Unparseable output is a **failure**, not a fallback to posting the raw text.
+ * We asked for JSON; stdout that isn't JSON means something went wrong that we
+ * do not understand — a crash banner, a login prompt, an npm warning — and the
+ * one thing that must not happen is that being posted verbatim into a customer's
+ * conversation. Reporting the run failed is recoverable; sending a stack trace
+ * to a guest is not.
+ *
+ * Still whole-stdout rather than streaming, and still used: it is what
+ * {@link readClaudeStream} falls back to when a run produced no `result` event
+ * at all, and it reads a plain `--output-format json` envelope exactly as it
+ * always did.
+ */
+export function parseClaudeOutput(stdout) {
+    const parsed = resultEnvelope(stdout);
+    if (!parsed) {
+        const sample = stdout.trim().slice(0, 200);
+        return {
+            denials: [],
+            ok: false,
+            error: sample
+                ? `claude did not return JSON (asked for --output-format stream-json). First 200 chars: ${sample}`
+                : 'claude returned no output',
+        };
+    }
+    return outputFromEnvelope(parsed);
+}
+/** Cap on the activity line handed to the heartbeat. */
+export const MAX_ACTIVITY_CHARS = 120;
+/** Cap on the partial answer salvaged from a run that was killed. */
+export const MAX_SALVAGE_CHARS = 500;
+/**
+ * Cap on a single buffered stdout line.
+ *
+ * A stream line is one JSON event, and a pathological one that never ends
+ * (binary output from a wrapper script, say) would otherwise accumulate
+ * unbounded between newlines. Dropped rather than truncated: half a JSON object
+ * parses as nothing useful anyway.
+ */
+const MAX_LINE_CHARS = 4 * 1024 * 1024;
+/** Text of an `assistant` event's message, and the last tool it invoked. */
+function assistantContent(event) {
+    const message = event.message;
+    if (!message || typeof message !== 'object')
+        return {};
+    const content = message.content;
+    if (!Array.isArray(content))
+        return {};
+    let latestText;
+    let latestTool;
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const entry = block;
+        if (entry.type === 'text' && typeof entry.text === 'string' && entry.text.trim()) {
+            latestText = entry.text;
+        }
+        else if (entry.type === 'tool_use' && typeof entry.name === 'string' && entry.name) {
+            latestTool = entry.name;
+        }
+    }
+    return { text: latestText, tool: latestTool };
+}
+/**
+ * Parse `--output-format stream-json` incrementally.
+ *
+ * Line-delimited JSON, one event per line, so the parser is a buffer and a
+ * split. Anything it doesn't recognise is skipped in silence: the event
+ * vocabulary belongs to Claude Code and grows without asking us, and a reader
+ * that failed on an unknown `type` would turn a Claude Code release into a
+ * fleet of broken laptops.
+ */
+export function readClaudeStream() {
+    let buffer = '';
+    let session;
+    let lastActivity;
+    let lastText;
+    let result;
+    const handle = (line) => {
+        const event = asObject(line);
+        if (!event)
+            return;
+        // Present on the `system`/`init` event, and repeated on most others. Taken
+        // from whichever arrives first — they all name the same session.
+        if (!session)
+            session = text(event.session_id);
+        if (event.type === 'result') {
+            result = event;
+            return;
+        }
+        if (event.type !== 'assistant')
+            return;
+        const { text: written, tool } = assistantContent(event);
+        if (written)
+            lastText = written;
+        // Whichever happened last within this message: a tool call after some text
+        // means the agent has moved on from writing to doing.
+        if (tool)
+            lastActivity = `using ${tool}`;
+        else if (written)
+            lastActivity = written.replace(/\s+/g, ' ').trim().slice(0, MAX_ACTIVITY_CHARS);
+    };
+    return {
+        push(chunk) {
+            buffer += chunk;
+            if (!buffer.includes('\n')) {
+                if (buffer.length > MAX_LINE_CHARS)
+                    buffer = '';
+                return;
+            }
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            if (buffer.length > MAX_LINE_CHARS)
+                buffer = '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    handle(trimmed);
+            }
+        },
+        sessionId: () => session,
+        activity: () => lastActivity,
+        salvage: () => {
+            const trimmed = lastText?.trim();
+            if (!trimmed)
+                return undefined;
+            return trimmed.length > MAX_SALVAGE_CHARS ? trimmed.slice(-MAX_SALVAGE_CHARS) : trimmed;
+        },
+        finish(stdout) {
+            // A trailing event with no newline after it is still an event — a binary
+            // that exits without flushing a final `\n` must not lose its result.
+            const tail = buffer.trim();
+            if (tail) {
+                handle(tail);
+                buffer = '';
+            }
+            if (result)
+                return outputFromEnvelope(result);
+            // No `result` event: either the command isn't emitting the stream we
+            // asked for, or it died before finishing. Either way the whole-output
+            // parser gives the better error message, and it still understands a
+            // single `json` envelope.
+            const parsed = parseClaudeOutput(stdout);
+            return session && !parsed.sessionId ? { ...parsed, sessionId: session } : parsed;
+        },
+    };
+}
 /**
  * Does this look like the resume having been rejected, rather than the agent
  * having failed at its actual work?
@@ -268,8 +416,11 @@ export function mcpConfigPath(env = process.env) {
  * the filesystem, and so the header scheme is stated in exactly one place.
  */
 export function buildMcpConfig(options) {
+    if (!options.mcpUrl)
+        return { mcpServers: { ...(options.extraServers ?? {}) } };
     return {
         mcpServers: {
+            ...(options.extraServers ?? {}),
             [MCP_SERVER_NAME]: {
                 type: 'http',
                 // Verbatim, exactly as pairing reported it. An earlier revision appended

package/dist/agent/codex.d.ts

@@ -11,9 +11,9 @@
  *
  * Everything here was verified against a real `codex-cli 0.144.1` rather than
  * taken from documentation; the surprises are called out where they are relied
- * on. As in `claude.ts`, nothing in this module is load-bearing for
- * correctness: if detection misses, if the session is unresumable, if the JSON
- * is not what we expect — the run still happens and still completes.
+ * on. Output and configuration used to prove the MCP boundary are deliberately
+ * load-bearing: if that proof is incomplete, the unsandboxed run must not
+ * start. Session continuity and reply parsing still fail independently.
  */
 /**
  * Environment variable the API key is handed to Codex in.
@@ -35,22 +35,35 @@ export declare const MCP_API_KEY_ENV_VAR = "PROHOST_MCP_API_KEY";
  * Both halves matter. Interactive `codex` has no `--json` and no `resume`
  * subcommand, so shaping it would break a command that works today.
  *
- * Three things this refuses to touch, each because appending to it would do
- * harm rather than nothing:
+ * Three things are deliberately not shaped, each because appending to it would
+ * do harm rather than nothing:
  *
- *  * Commands with shell control operators. Flags are appended to the *end* of
- *    the string, so for `codex exec | jq .` they would land on `jq`.
  *  * `codex exec resume …` and `codex exec review …`. The host already chose a
  *    sub-subcommand; appending our own `resume` would produce two of them.
  *  * Anything after a `--` sentinel, which is the host saying "stop parsing".
- *  * A command carrying its own prompt, e.g. `codex exec 'Be terse'`. Codex
+ *  * A command carrying its own unquoted prompt, e.g. `codex exec hello`. Codex
  *    takes exactly one prompt positional, so both the `-` this harness appends
  *    and a `resume <id>` would be a second one — `error: unexpected argument
  *    '-' found`, on a command that works today. Such a host keeps the plain
  *    contract; the place to put standing instructions is now the agent's
  *    ProhostAI profile, which arrives in the prompt itself.
+ *
+ * Shell syntax is different: recognisable Codex exec commands containing it
+ * stay classified as Codex so the harness can fail closed before spawn. Letting
+ * one fall through as a plain command would also drop the verified MCP boundary.
+ */
+export declare function isCodexExec(command: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Shell syntax a shaped Codex command cannot safely preserve.
+ *
+ * Codex commands are eventually executed with `shell: true`, while the harness
+ * currently operates on whitespace-delimited words. Quotes, escapes,
+ * expansions, globs, comments and control/redirection operators all make those
+ * two views differ. Rather than guess at POSIX plus cmd.exe tokenization, only
+ * the deliberately boring argv-shaped subset is accepted. A matching command
+ * is still classified as Codex and then rejected before spawn.
  */
-export declare function isCodexExec(command: string): boolean;
+export declare function codexShellSyntax(command: string, platform?: NodeJS.Platform): string | undefined;
 /**
  * The `-c` override that registers the ProhostAI MCP server.
  *
@@ -68,12 +81,192 @@ export declare function isCodexExec(command: string): boolean;
  * keeps a live API key off a command line that anyone on the machine can read
  * out of `ps`.
  */
+export declare function prohostMcpEntry(mcpUrl: string): string;
+/**
+ * The whole `mcp_servers` override for a run, ProhostAI server included.
+ *
+ * It is one override, and it has to be: `-c` overrides are applied in order,
+ * and a later whole-table assignment **replaces** an earlier dotted one rather
+ * than merging with it. `-c mcp_servers.prohost={…} -c mcp_servers={…}` — the
+ * shape this had until it was measured — therefore drops the ProhostAI server
+ * outright, on every run that disables anything, while the harness went on
+ * logging "ProhostAI tools wired in" and the prompt went on telling the agent
+ * it had them. (Deep-merging is what happens between the CLI override and the
+ * *config file*, which is what made the wrong shape look right.)
+ */
 export declare function buildMcpOverride(mcpUrl: string): string;
+/** Entries destined for the one `mcp_servers` table override. */
+export interface ExtraEntries {
+    /** `"name"={…}` fragments, for {@link mcpServersOverride}. */
+    entries: string[];
+    /** Names that could not be encoded, for the operator to see. */
+    skipped: string[];
+    /** Literal extra-server credentials, kept off the process command line. */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Turn `extra-mcp.json` entries into `mcp_servers` table fragments.
+ *
+ * The name is quoted rather than written as a dotted path, which is what lets
+ * *any* name work. `-c` splits on the first `=` and reads everything before it
+ * as a dotted path, so `-c mcp_servers.fly.io.enabled=false` addresses
+ * `mcp_servers.fly.io` — three segments, not two — and Codex rejects the whole
+ * config with `invalid transport in mcp_servers.fly`. Quoting the segment does
+ * not help either: `mcp_servers."fly.io"` fails the same way, because the
+ * splitting happens before any TOML is parsed. Putting the name inside the
+ * *value* sidesteps the path parser entirely.
+ *
+ * Claude's JSON shape carries literal `headers` and stdio `env` values. Those
+ * must not be copied literally into Codex's `-c` argument: command lines are
+ * readable by other local processes. Translate them to Codex's indirection
+ * fields and put the values in the child environment instead. `type` is also a
+ * Claude-only discriminator; Codex infers the transport from `url`/`command`.
+ */
+export declare function extraMcpEntries(servers: Record<string, Record<string, unknown>>, platform?: NodeJS.Platform): ExtraEntries;
+/**
+ * Table fragments that switch off the servers the operator's Codex install has.
+ *
+ * This is the Codex answer to `--strict-mcp-config`, and it took a real binary
+ * to find. Two mechanisms that look like they should work do not: replacing the
+ * table wholesale does **not** replace it — Codex deep-merges config overrides,
+ * so the operator's servers survive alongside whatever the override adds — and
+ * `--ignore-user-config` does work but drops the operator's *entire* config
+ * with it, taking their model, profile and sandbox settings along for a
+ * security fix they did not ask to pay for that way.
+ *
+ * Setting `enabled=false` per server is the surgical one, verified end to end
+ * against `codex-cli 0.144.1`: the server is then reported `disabled` by
+ * `codex mcp list`, its own definition is left intact, other servers are
+ * untouched, and its tools are genuinely absent from the model's tool list
+ * mid-run.
+ *
+ * Names the extras file defines are left alone. Codex would deep-merge
+ * `enabled=false` into the operator's definition of the same name and produce a
+ * server the operator asked for twice and got zero times, which is a worse
+ * outcome than the collision itself.
+ */
+export declare function disableMcpEntries(configuredNames: string[], keep?: string[]): string[];
+/**
+ * Fold every entry into the single `-c mcp_servers={…}` override.
+ *
+ * One override rather than one per server, because they all reach the same
+ * table and Codex merges rather than replaces — so the combined form is
+ * equivalent, shorter on the command line, and (unlike the dotted-path form)
+ * imposes no constraint on what a server may be called.
+ */
+export declare function mcpServersOverride(entries: string[]): string | undefined;
+/** One MCP server as Codex reports it, and whether this config leaves it on. */
+export interface CodexMcpServer {
+    name: string;
+    enabled: boolean;
+}
+/** Runs one short command in the same directory as Codex itself. */
+export type CommandRunner = (command: string, cwd?: string) => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * Ask the binary what MCP servers it has, optionally under a `-c` override.
+ *
+ * Asking rather than parsing `~/.codex/config.toml` is deliberate twice over.
+ * `codex mcp list --json` already honours `CODEX_HOME` and the binary's normal
+ * config layering — and, measured on an ordinary install, it
+ * reports servers that appear **nowhere** in that file (plugins contribute
+ * their own). A config file we half-understand is exactly how an isolation
+ * guarantee ends up with a hole in it.
+ *
+ * Passing an override makes this a *verifier*: the listing then reflects the
+ * config the run would actually get, so "did the disable take" is a question
+ * with an answer rather than an assumption.
+ *
+ * The working directory is equally load-bearing. Codex discovers trusted
+ * project `.codex/config.toml` layers from cwd, so a probe in the harness's
+ * launch directory cannot certify a run executed in `$PROHOST_HOME/workspace`
+ * or an explicit `--workdir`. Every probe uses the eventual run cwd.
+ *
+ * Returns `null` — distinct from `[]` — when the question could not be
+ * answered, which for an override also means "that override does not load".
+ * The caller must treat the two differently: an empty list means there is
+ * nothing to disable, while `null` means we do not know, and a run that cannot
+ * enumerate must say so rather than claim an isolation it did not apply.
+ */
+export declare function listMcpServers(binary: string, runner: CommandRunner, override?: string, cwd?: string): CodexMcpServer[] | null;
+/** Disable entries proven to work, and the servers that could not be disabled. */
+export interface VerifiedDisable {
+    entries: string[];
+    /** Servers still reachable from the run. Empty is the outcome we want. */
+    failed: string[];
+}
+/**
+ * Disable entries, checked against the binary before they are used.
+ *
+ * Not paranoia — a measured failure. `{enabled=false}` merges onto a server's
+ * existing definition, and a server contributed by a **plugin** has no entry in
+ * `mcp_servers` to merge onto, so the override defines a table with no
+ * transport and Codex refuses the entire config: `invalid transport in
+ * mcp_servers.github`. Shipped unverified, that would not have leaked a
+ * server — it would have broken *every* run for anyone with a Codex plugin
+ * installed, which is a far worse outcome than the hole it was closing.
+ *
+ * So the entries are tried before they are trusted: one probe for the whole
+ * set, and only if that fails, one probe per server to find which ones can be
+ * disabled and which cannot. The happy path costs a single extra command per
+ * survey; the slow path is paid only by installs that need it.
+ *
+ * `failed` is the honest part. A server that cannot be disabled is still
+ * reachable from the run, and the caller has to say so out loud rather than
+ * report an isolation it only partly achieved.
+ */
+export declare function disableEntriesThatLoad(binary: string, runner: CommandRunner, targets: string[], cwd?: string): VerifiedDisable;
+/**
+ * The `codex` binary out of the host's `--exec` command.
+ *
+ * The host may have written a path (`/opt/homebrew/bin/codex`), and the
+ * enumeration above has to ask the *same* binary the run will use — a different
+ * one on `PATH` could be a different version reading a different `CODEX_HOME`.
+ */
+export declare function codexBinary(command: string): string;
+/**
+ * Is the host running Codex under a named profile?
+ *
+ * Worth asking because it is a hole in the isolation that cannot be closed from
+ * here. `codex exec -p work` additionally loads `$CODEX_HOME/work.config.toml`,
+ * and `codex mcp list` has no way to be asked about a profile: `-p` and
+ * `--profile` are rejected outright, and `-c profile="work"` is refused as a
+ * removed legacy form. So a server defined only inside a profile is invisible
+ * to the enumeration and stays reachable from the run.
+ *
+ * Nothing here can fix that — reading the profile file ourselves is the
+ * config-parsing this deliberately avoids, and it is exactly how an isolation
+ * guarantee ends up with a hole nobody knows about. What it can do is tell the
+ * operator, which is what the caller does with this.
+ */
+export declare function codexProfileName(command: string): string | undefined;
+/**
+ * A host flag that can make the actual run's MCP inventory differ from the
+ * plain `codex mcp list` probe.
+ *
+ * Replaying arbitrary config arguments into a separate shell command would
+ * require parsing the operator's shell syntax exactly. Guessing is not an
+ * isolation boundary, so reject the small set of flags that can alter cwd,
+ * config, or plugin loading. `-C`/`--cd` matters because Codex discovers
+ * project-local config from the directory it runs in. Dedicated model/sandbox
+ * flags remain supported.
+ */
+export declare function codexMcpInventoryFlag(command: string): string | undefined;
 export interface CodexFlags {
     /** Session (Codex calls it a thread) to resume. Omitted for the first turn. */
     sessionId?: string;
-    /** The paired MCP endpoint, when tools are being wired in. */
-    mcpUrl?: string;
+    /**
+     * `mcp_servers` table entries for this run: the ProhostAI server, the
+     * operator's extras, and the `enabled=false` switches that keep their own
+     * config's servers out.
+     *
+     * Entries rather than complete overrides, and one list rather than several,
+     * because they must all land in a **single** `-c mcp_servers={…}` — see
+     * {@link buildMcpOverride} for what happens when they don't.
+     */
+    mcpEntries?: string[];
     /**
      * Run with approvals and the sandbox bypassed. Default ON — see
      * {@link codexCommand}. Set false by `agent run --safe-tools`.
@@ -116,10 +309,12 @@ export type CodexOutput = {
     ok: true;
     text: string;
     sessionId?: string;
+    denials: string[];
 } | {
     ok: false;
     error: string;
     sessionId?: string;
+    denials: string[];
 };
 /**
  * Read the reply and the thread id out of `--json` stdout.
@@ -139,6 +334,15 @@ export type CodexOutput = {
  * than a fallback to posting the raw text. We asked for JSON; anything else
  * means something went wrong that we do not understand, and the one thing that
  * must not happen is that reaching a customer's conversation.
+ *
+ * Refused tool calls come back too, as the Codex counterpart of Claude Code's
+ * `permission_denials`. Codex has no such field, but it does emit the fact: a
+ * refused call is an `item.completed` carrying a `mcp_tool_call` with
+ * `status: "failed"` and `error.message: "user cancelled MCP tool call"`, which
+ * is what a run with nobody at the terminal gets every time. Names are spelled
+ * `mcp__<server>__<tool>` so the harness's log line reads identically whichever
+ * brain produced it — and because that is genuinely how Codex names the tool to
+ * the model (verified against 0.144.1, same convention as Claude Code).
  */
 export declare function parseCodexOutput(stdout: string): CodexOutput;
 /**