@prohost/cli 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,108 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.2.2
+
+Two agents paired to the same workspace behaved like different products: the
+one on Claude Code remembered its threads and could look things up, the one on
+Codex ran bare. And neither knew who its operator had hired it to be — the
+persona configured in the ProhostAI agent profile never left the server.
+
+- **Your agent gets its soul.** `agent.run_requested` may now carry
+  `system_prompt` — the standing instructions written in the agent's ProhostAI
+  profile — and `agent_title`. The instructions render at the very top of the
+  prompt, above memories and history, fenced off from the server-generated
+  sections so the agent can always tell where its operator stops talking. The
+  title renders alongside the name: `You are "Ada" (Guest Experience Lead)`. The
+  fence is followed by a line stating that what comes after is generated for
+  this run and describes what is actually true about it — a soul configures the
+  agent, it does not get to talk it out of reporting a lookup it never made.
+  Both fields are optional in both directions, so an older server behaves
+  exactly as before.
+- **Attachments are visible.** `recent_messages[].attachments` and
+  `trigger_attachments` render as `[attached image "boiler.jpg": <url>]` inline
+  in the thread and as a list under the triggering message. An image-only
+  message — a guest who sends a photo of a broken boiler and nothing else —
+  used to be dropped entirely by the parser for having no text; it now survives
+  as the attachment it is, and the prompt says so rather than reporting the text
+  as missing. The agent is told plainly that a URL is not something it can see,
+  and to download one to a local file before opening it, because vision works on
+  local files and not on links.
+- **The agent stops claiming it has no access to your machine.** A brain
+  running unsandboxed on a laptop that holds the checkout, the credentials and
+  the CLI was still answering "I don't have access to the codebase". Ungated
+  runs are now told they are on the operator's own machine, in their shell, and
+  to take a *quick* look — usual checkout locations, `gh auth status`, whether
+  the command is on PATH — before declaring a capability missing. A quick look,
+  not an audit: the run has a hard time cap. Under `--safe-tools` the licence is
+  withheld, because there the looking would itself sit waiting on an approval
+  nobody is there to give.
+- **Codex gets the harness Claude Code has had since 0.2.0.** A `--exec` of
+  `codex exec` is now detected and shaped, with the same `--safe-tools` opt-out:
+
+  | | Claude Code | Codex |
+  |---|---|---|
+  | Structured output | `--output-format json` | `--json` (JSONL) |
+  | Session continuity | `--resume <id>` | `codex exec resume <thread>` |
+  | Tools | `--mcp-config` + `--strict-mcp-config` | `-c mcp_servers.prohost={…}` |
+  | Credential | `X-API-Key` in a `0600` file | `X-API-Key` via `env_http_headers` |
+  | Ungated by default | `--dangerously-skip-permissions` | `--yolo` |
+
+  Three things worth knowing about the Codex path. `--skip-git-repo-check` is
+  passed unconditionally, because the harness workspace is not a git repository
+  and Codex otherwise exits before the model is ever reached. `--yolo` is a
+  hidden alias of `--dangerously-bypass-approvals-and-sandbox` and passing both
+  spellings is a hard argument error, so a host who already wrote either one
+  never gets a second. And `resume` is appended *after* the host's own flags,
+  since `codex exec resume` accepts a strict subset of `codex exec`'s — a flag
+  that is legal before `resume` is rejected after it. When a resume is rejected
+  anyway, the run falls back to a fresh thread instead of failing the surface.
+- **`--safe-tools` now removes a bypass you wrote yourself.** It used to only
+  decline to *add* one, so `--exec 'codex exec - --yolo' --safe-tools` ran fully
+  unsandboxed while the harness logged "tools are permission-gated" and the
+  prompt told the agent approvals would stop it. Since this README recommended
+  exactly that `--exec` until now, the flag is sitting in existing installs. A
+  safety switch that quietly does nothing is worse than not having one, so both
+  `--yolo` / `--dangerously-bypass-approvals-and-sandbox` (Codex) and
+  `--dangerously-skip-permissions` (Claude Code) are now stripped when
+  `--safe-tools` is passed. Note this covers the full bypass only —
+  `--full-auto` still auto-approves inside Codex's sandbox.
+- **A Codex command carrying its own prompt is left alone.** `codex exec 'Be
+  terse'` keeps the plain stdin/stdout contract: Codex takes exactly one prompt
+  positional, so the `-` this harness appends would be a second one and the run
+  would fail outright with `unexpected argument '-'`. Standing instructions
+  belong in the agent's ProhostAI profile now, which is where `system_prompt`
+  comes from.
+- **The Codex credential never touches the command line.** Codex can read an
+  MCP header out of the environment (`env_http_headers`), so the API key is
+  passed to the child that way rather than inside the `-c` override. A command
+  line is world-readable out of `ps`; a process environment is not. This makes
+  the Codex path slightly *safer* than the Claude one, which still has to keep
+  the key in a `0600` file on disk.
+
+**Residual gaps on the Codex path**, both stated at start-up or in the prompt
+rather than papered over:
+
+- **No `--strict-mcp-config` equivalent.** Codex's `--ignore-user-config` was
+  the obvious candidate and does not work: it drops the `-c` overrides along
+  with the user config, taking the ProhostAI server with it. So a Codex run also
+  holds whatever MCP servers `~/.codex/config.toml` defines, with approvals
+  bypassed. The harness prints this at start-up rather than leaving an operator
+  to assume the Claude Code isolation applies.
+- **Codex's MCP tool naming is unverified**, so the prompt names the server
+  (`registered as "prohost"`) instead of asserting a `mcp__prohost__*` pattern
+  it has not confirmed. The agent can read its own tool list; a wrong tool name
+  is the same failure as a wrong endpoint.
+- **No permission-denial reporting.** Claude Code returns `permission_denials`
+  and the harness prints them; Codex's event stream has no equivalent, so a
+  refused tool stays as invisible on that path as it was before 0.2.0.
+
+## 0.2.1
+
+- Prompt: tell brains with a ToolSearch tool that part of their toolkit
+  (notably WebSearch/WebFetch) is deferred and must be loaded before use, so
+  a paired agent stops telling customers it cannot browse the web when it can.
+
 ## 0.2.0
 
 The harness stopped being a one-shot prompt pipe. 0.1.x answered every mention

package/README.md

@@ -87,7 +87,7 @@ in a team thread, a 1:1 DM, a task comment, a trigger — you'll see:
 Other agents, same command:
 
 ```bash
-npx @prohost/cli agent run --exec 'codex exec - --yolo'
+npx @prohost/cli agent run --exec 'codex exec'
 npx @prohost/cli agent run --exec 'goose run -i -'
 npx @prohost/cli agent run --exec './my-agent.sh'
 ```
@@ -109,13 +109,14 @@ nothing is posted and the run is left open.
 2. The CLI verifies the event's HMAC signature. An event that doesn't verify is
    **not executed** — the whole point of the signature is that a run event makes
    your machine execute a command.
-3. It builds a prompt — who your agent is, what it's replying to, the recent
-   messages in the thread, anything the account remembers that bears on it, and
-   the message that mentioned it — and runs your `--exec` command with that
-   prompt on **stdin**.
+3. It builds a prompt — who your agent is, the standing instructions you wrote
+   in its ProhostAI profile, what it's replying to, the recent messages in the
+   thread, anything the account remembers that bears on it, and the message that
+   mentioned it — and runs your `--exec` command with that prompt on **stdin**.
+   Images and files on those messages appear as URLs the agent can download.
 4. Your command's **stdout** is the reply. It's posted into the conversation
    verbatim, so print the message and nothing else — no preamble, no reasoning.
-   (Claude Code is the exception: see below.)
+   (Claude Code and Codex are the exceptions: see below.)
 5. The run is completed either way. A command that crashes, times out, or prints
    nothing reports `failed`; a run is never left hanging.
 
@@ -135,8 +136,9 @@ directory. Just choose it deliberately.
 ### If your agent is Claude Code
 
 When `--exec` starts with `claude` and asks for print mode (`-p` / `--print`),
-the CLI does three extra things. Every other command — Codex, goose, your own
-script — is left exactly alone.
+the CLI does three extra things. Codex gets the same three through its own
+flags — see "If your agent is Codex" below. Every other command — goose, your
+own script — is left exactly alone.
 
 **It keeps the conversation.** Each run is a fresh process, so without this your
 agent meets every message as its first: someone answers its clarifying question
@@ -177,6 +179,54 @@ word of the command *and* print mode is asked for. Anything else — `npx claude
 redirect, or `&&` — keeps the plain stdin/stdout contract untouched. So
 `--exec 'sh -c "claude -p"'` is the way to opt out.
 
+### If your agent is Codex
+
+When `--exec` starts with `codex` and uses the `exec` subcommand, the CLI does
+the same three things it does for Claude Code, through Codex's own flags. The
+detection is just as narrow: interactive `codex`, a wrapper script, a pipeline,
+a command that already says `codex exec resume` / `codex exec review`, or one
+carrying its own prompt (`codex exec 'Be terse'`) all keep the plain
+stdin/stdout contract untouched. That last one matters: Codex takes exactly one
+prompt positional, so the CLI cannot add its own alongside yours. Put standing
+instructions in the agent's ProhostAI profile instead — they arrive at the top
+of the prompt, ahead of everything else.
+
+| | Claude Code | Codex |
+| --- | --- | --- |
+| Reply read from | `--output-format json` | `--json` (JSONL event stream) |
+| Conversation kept with | `--resume <id>` | `codex exec resume <thread>` |
+| Tools wired via | `--mcp-config` | `-c mcp_servers.prohost={…}` |
+| API key travels in | `~/.prohost/mcp.json` (`chmod 600`) | the child's environment |
+| Tools ungated by | `--dangerously-skip-permissions` | `--yolo` |
+
+`--skip-git-repo-check` is also passed on every Codex run, and it is not
+optional: your agent works in `~/.prohost/workspace`, which is not a git
+repository, and Codex refuses to start there without it.
+
+If you already pass `--yolo` (or `--dangerously-bypass-approvals-and-sandbox`)
+in your own `--exec`, the CLI won't add a second one — passing both is an
+argument error that would fail every run. `--safe-tools` works the same way it
+does for Claude Code, and it *removes* a bypass flag you wrote yourself rather
+than just declining to add one, so the gating it promises is real. (It covers
+the full bypass only; `--full-auto` still auto-approves inside Codex's sandbox.)
+
+**Two things Codex cannot do that Claude Code can**, both worth knowing before
+you leave it running:
+
+- **Your own MCP servers come along.** There is no Codex equivalent of
+  `--strict-mcp-config`. `--ignore-user-config` looks like one but drops the
+  `-c` overrides too, taking the ProhostAI server with them — so a Codex run
+  also holds whatever servers your `~/.codex/config.toml` defines, with
+  approvals bypassed. The CLI prints this at start-up so it isn't a surprise.
+  If that matters, keep `~/.codex/config.toml` free of servers you would not
+  hand to a teammate's message.
+- **Refused tools stay invisible.** Claude Code reports what it was denied and
+  the CLI prints it; Codex's event stream has no equivalent.
+
+Your ProhostAI API key is passed to Codex in the child process's environment
+rather than in the `-c` override, because a command line is readable by anyone
+on the machine via `ps` and a process environment is not.
+
 Runs are handled one at a time, and each run executes **at most once on this
 machine** — even across restarts. Started runs are recorded in
 `~/.prohost/runs.json` before the command launches, so a webhook redelivery
@@ -193,8 +243,11 @@ someone in your ProhostAI workspace asks. Be clear-eyed about what that means:
 - **The agent runs as you.** Same user, same filesystem, same SSH keys, same
   logged-in CLIs. It is not sandboxed.
 - **By default its tools are not gated.** With `--dangerously-skip-permissions`
-  (the default for Claude Code) nothing pauses for confirmation. That is what
-  makes it useful and it is also the whole risk.
+  (Claude Code) or `--yolo` (Codex) nothing pauses for confirmation. That is
+  what makes it useful and it is also the whole risk.
+- **Its standing instructions come from the ProhostAI agent profile.** Whoever
+  can edit that profile is configuring a brain that runs unsandboxed on this
+  machine. Treat edit access to it as access to your laptop.
 - **The instructions come from other people.** The prompt carries a message a
   teammate wrote, plus thread history. Treat all of it as untrusted input — the
   same judgement you'd apply to any agent reading text from the internet. A
@@ -204,16 +257,17 @@ someone in your ProhostAI workspace asks. Be clear-eyed about what that means:
 What the harness does to bound this: the message reaches your command on
 **stdin only**, never the shell, so it cannot inject a command; runs execute at
 most once each; every event's signature is verified before anything runs; the
-agent works in `~/.prohost/workspace` rather than your code; and
-`--strict-mcp-config` keeps your own MCP servers out of the run.
+agent works in `~/.prohost/workspace` rather than your code; and, on Claude
+Code, `--strict-mcp-config` keeps your own MCP servers out of the run. Codex has
+no equivalent — see "If your agent is Codex".
 
 What it does **not** do: sandbox the process. If that matters for your machine,
 run `agent run` inside a container or a dedicated user account, or use
 `--safe-tools` and accept that the agent will answer rather than act.
 
-Other agents: the CLI shapes no command but Claude Code's, so give yours its own
-equivalent flag — `codex --yolo` for Codex CLI, whatever your runner calls it —
-and apply the same judgement.
+Other agents: the CLI shapes no command but Claude Code's and Codex's, so give
+yours its own equivalent flag — whatever your runner calls it — and apply the
+same judgement.
 
 ### `agent run` flags
 
@@ -227,7 +281,7 @@ and apply the same judgement.
 | `--machine` | OS hostname | Name shown next to the connection in ProhostAI. |
 | `--url` | paired value | Websocket endpoint override. Pairing stores the URL the server reports, so you should not normally need this. |
 | `--allow-unverified` | off | Run events whose signature can't be verified. See below. |
-| `--safe-tools` | off | Gate the agent's tools behind permission prompts instead of bypassing them. Claude Code only. Alias: `--no-skip-permissions`. |
+| `--safe-tools` | off | Gate the agent's tools behind permission prompts instead of bypassing them. Claude Code and Codex only. Alias: `--no-skip-permissions`. |
 
 ### Keeping it running
 
@@ -307,7 +361,7 @@ Everything the CLI stores lives under `~/.prohost` (`$PROHOST_HOME` moves it):
 | --- | --- |
 | `agent.json` | Credentials. Delete to un-pair locally; revoke in ProhostAI to invalidate the key itself. |
 | `runs.json` | Runs already executed on this machine, so a redelivery can't run your agent twice. |
-| `sessions.json` | Conversation → Claude Code session, for continuity. Safe to delete; costs the agent its memory of open threads. |
+| `sessions.json` | Conversation → Claude Code session / Codex thread, for continuity. Safe to delete; costs the agent its memory of open threads. |
 | `mcp.json` | Generated MCP config. Holds your API key — `chmod 600`. |
 | `workspace/` | Where your agent command runs by default. |
 | `agent.log` | Daemon output. |

package/dist/agent/claude.d.ts

@@ -14,13 +14,8 @@
  * session is unresumable, if the JSON is not what we expect — the run still
  * happens and still completes. These are enhancements that must fail soft.
  */
-/**
- * Name the ProhostAI MCP server is registered under, which is also what makes
- * its tools appear as `mcp__prohost__<tool>`. Referenced in the prompt, in the
- * `--allowedTools` pattern, and in the config file — keep them in sync from
- * here rather than by hand.
- */
-export declare const MCP_SERVER_NAME = "prohost";
+import { MCP_SERVER_NAME } from './mcp.js';
+export { MCP_SERVER_NAME };
 /**
  * What goes to `--allowedTools` so the ProhostAI tools are callable.
  *

package/dist/agent/claude.js

@@ -17,13 +17,9 @@
 import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { prohostHome } from './credentials.js';
-/**
- * Name the ProhostAI MCP server is registered under, which is also what makes
- * its tools appear as `mcp__prohost__<tool>`. Referenced in the prompt, in the
- * `--allowedTools` pattern, and in the config file — keep them in sync from
- * here rather than by hand.
- */
-export const MCP_SERVER_NAME = 'prohost';
+import { MCP_SERVER_NAME } from './mcp.js';
+import { SHELL_CONTROL_OPERATORS, shellQuote } from './shell.js';
+export { MCP_SERVER_NAME };
 /**
  * What goes to `--allowedTools` so the ProhostAI tools are callable.
  *
@@ -75,27 +71,6 @@ export function isClaudeExec(command) {
         return false;
     return words.some((word) => word === '-p' || word === '--print');
 }
-/** Pipes, lists, redirections, subshells — anything that makes "append to the end" wrong. */
-const SHELL_CONTROL_OPERATORS = /[|&;<>(){}`]|\$\(/;
-/**
- * Quote a value for a `shell: true` command line on this platform.
- *
- * Every value that goes through here is ours or the operator's — a session id
- * we stored, a path under `$PROHOST_HOME` — never event-derived text. It is
- * quoted anyway: a home directory with a space in it is ordinary, and "the
- * inputs are trusted" is the assumption that stops being true the first time
- * someone extends this.
- *
- * Windows needs its own branch. `shell: true` there runs `cmd.exe`, where a
- * single quote is an ordinary character rather than a quoting one — POSIX
- * quoting would hand Claude Code a config path with literal apostrophes around
- * it, and the tools would simply never load.
- */
-function shellQuote(value, platform) {
-    if (platform === 'win32')
-        return `"${value.replace(/"/g, '""')}"`;
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 /**
  * Append the flags this harness needs to a Claude Code command.
  *
@@ -118,7 +93,20 @@ export function claudeCommand(base, flags = {}) {
     const platform = flags.platform ?? process.platform;
     const quote = (value) => shellQuote(value, platform);
     const skipPermissions = flags.skipPermissions !== false;
-    const parts = [base.trim(), '--output-format', 'json'];
+    // `--safe-tools` removes the bypass rather than merely declining to add it.
+    // A host who wrote `--dangerously-skip-permissions` into their own `--exec`
+    // and *also* passed `--safe-tools` is contradicting themselves, and the only
+    // safe way to resolve that is in favour of the flag whose entire purpose is
+    // to gate — otherwise the harness announces "tools are permission-gated" over
+    // a run that bypasses every one of them.
+    const command = skipPermissions
+        ? base.trim()
+        : base
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word !== '--dangerously-skip-permissions')
+            .join(' ');
+    const parts = [command, '--output-format', 'json'];
     if (skipPermissions)
         parts.push('--dangerously-skip-permissions');
     if (flags.sessionId)

package/dist/agent/codex.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The one place that knows anything about Codex CLI specifically.
+ *
+ * The sibling of `claude.ts`, and it exists for the same reason: `exec.ts` is
+ * deliberately agent-agnostic — prompt on stdin, reply on stdout — and that
+ * lowest common denominator costs a Codex run the two things it can actually
+ * have. A run has no memory of the previous one, and it has no tools for
+ * looking anything up in the workspace it is answering about. Until this
+ * module existed, a `codex` brain ran bare while a `claude` brain got both, so
+ * the same mention answered by two hosts produced visibly different work.
+ *
+ * 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.
+ */
+/**
+ * Environment variable the API key is handed to Codex in.
+ *
+ * Codex resolves MCP headers from the environment at request time
+ * (`env_http_headers`), which is why the key travels this way rather than in
+ * the config override. The override is part of the command line, and a command
+ * line is world-readable out of `ps`; a child's environment is not. This is the
+ * one place the Codex path is meaningfully *safer* than the Claude one, which
+ * has to keep the key in a `0600` file on disk.
+ */
+export declare const MCP_API_KEY_ENV_VAR = "PROHOST_MCP_API_KEY";
+/**
+ * Is this exec command Codex CLI in non-interactive mode?
+ *
+ * A **heuristic**, and deliberately as narrow as {@link isClaudeExec}: it
+ * matches when the first word of the command is `codex` (or a path ending in
+ * `/codex`) *and* the command uses the `exec` subcommand (or its `e` alias).
+ * 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:
+ *
+ *  * 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
+ *    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.
+ */
+export declare function isCodexExec(command: string): boolean;
+/**
+ * The `-c` override that registers the ProhostAI MCP server.
+ *
+ * Codex takes a streamable-HTTP MCP server with **arbitrary** headers, which is
+ * what makes this possible at all: `codex mcp add --url` offers only
+ * `--bearer-token-env-var`, and a bearer token is the *wrong credential* for
+ * this endpoint — the server validates `Authorization: Bearer` as an OAuth
+ * access token, checks it first, and does not fall through to `X-API-Key` when
+ * it fails. A pairing hands out an `X-API-Key`. The `-c` path reaches the same
+ * config layer with none of that restriction.
+ *
+ * `env_http_headers` rather than `http_headers`: both work and both were
+ * verified against the running binary, but the former names an environment
+ * variable to read the value from instead of carrying the value itself, which
+ * keeps a live API key off a command line that anyone on the machine can read
+ * out of `ps`.
+ */
+export declare function buildMcpOverride(mcpUrl: string): string;
+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;
+    /**
+     * Run with approvals and the sandbox bypassed. Default ON — see
+     * {@link codexCommand}. Set false by `agent run --safe-tools`.
+     */
+    skipPermissions?: boolean;
+    /** Quoting target. Defaults to the running platform; tests set it. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Append the flags this harness needs to a Codex command.
+ *
+ * Four things get added, and each one is load-bearing:
+ *
+ * `--json` turns stdout into a JSONL event stream, which is the only way to
+ * read the thread id back out (and so the only way sessions can continue).
+ *
+ * `--skip-git-repo-check` is not optional. The harness runs the agent in
+ * `$PROHOST_HOME/workspace`, which is not a git repository, and Codex refuses
+ * to start there — `Not inside a trusted directory and --skip-git-repo-check
+ * was not specified.` Without this flag **every** Codex run fails before the
+ * model is ever reached.
+ *
+ * `--yolo` mirrors Claude Code's `--dangerously-skip-permissions`, for the same
+ * reason: in a non-interactive run nobody is there to approve a command, so a
+ * sandboxed brain silently declines the work it was hired for. It is a hidden
+ * alias of `--dangerously-bypass-approvals-and-sandbox`, and passing both spells
+ * is a hard clap error (`cannot be used multiple times`) — so a host who already
+ * wrote either one must not get ours on top, or every run of theirs fails.
+ *
+ * `resume` goes **after** the host's own flags, not before them. `codex exec
+ * resume` accepts a strict subset of `codex exec`'s flags (no `-s`, `-C`,
+ * `--add-dir`, `-p`), and a flag placed after `resume` is parsed by `resume`.
+ * `codex exec -s workspace-write resume <id>` parses; `codex exec resume <id>
+ * -s workspace-write` is rejected. Appending keeps the host's flags where Codex
+ * still understands them.
+ */
+export declare function codexCommand(base: string, flags?: CodexFlags): string;
+/** What the harness got back from one Codex invocation. */
+export type CodexOutput = {
+    ok: true;
+    text: string;
+    sessionId?: string;
+} | {
+    ok: false;
+    error: string;
+    sessionId?: string;
+};
+/**
+ * Read the reply and the thread id out of `--json` stdout.
+ *
+ * Codex emits **JSONL**, not one object: `thread.started` (carrying
+ * `thread_id`), `turn.started`, an `item.completed` per item the turn produced,
+ * then `turn.completed`. Only `agent_message` items are the answer — reasoning
+ * and command items share the stream — and the last one is what a person would
+ * have seen at the end of the run.
+ *
+ * Lines that are not JSON are skipped rather than treated as corruption,
+ * because they are *expected*: an unreachable MCP server puts `ERROR
+ * rmcp::transport::worker: …` straight into this stream, and the run around it
+ * succeeds normally. This was observed, not guessed at.
+ *
+ * As in `parseClaudeOutput`, output with no reply in it is a **failure** rather
+ * 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.
+ */
+export declare function parseCodexOutput(stdout: string): CodexOutput;
+/**
+ * Does this look like the resume having been rejected, rather than the agent
+ * having failed at its actual work?
+ *
+ * Two ways a Codex resume can fail where a fresh run would have worked: the
+ * thread is gone (rollout files get cleaned up and the ledger cannot know), or
+ * the host's own flags are ones `codex exec resume` does not accept, which clap
+ * reports as `unexpected argument`. Both must degrade to a fresh session
+ * instead of breaking that surface forever.
+ *
+ * The `thread.started` guard is what keeps this from firing on an ordinary bad
+ * turn. Codex echoes the thread id in that event on **success**, so the
+ * "output mentions the session id" heuristic — which is all `claude.ts` can
+ * do — would match a resumed run that started fine and then failed at its
+ * work, and retrying that runs the agent, and its tools, a second time for
+ * nothing.
+ */
+export declare function looksLikeCodexResumeFailure(output: string, sessionId: string): boolean;