@prohost/cli 0.2.0 → 0.2.2

package/dist/agent/codex.js

@@ -0,0 +1,369 @@
+/**
+ * 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.
+ */
+import { MCP_SERVER_NAME } from './mcp.js';
+import { SHELL_CONTROL_OPERATORS, shellQuote } from './shell.js';
+/**
+ * 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 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 function isCodexExec(command) {
+    if (SHELL_CONTROL_OPERATORS.test(command))
+        return false;
+    const words = command.trim().split(/\s+/);
+    const first = words[0] ?? '';
+    const base = first.split('/').pop() ?? '';
+    if (base !== 'codex' && base !== 'codex.cmd' && base !== 'codex.exe')
+        return false;
+    if (words.includes('--'))
+        return false;
+    const rest = words.slice(1);
+    if (!rest.includes('exec') && !rest.includes('e'))
+        return false;
+    // A host who already picked `resume` or `review` gets left alone entirely.
+    if (rest.includes('resume') || rest.includes('review'))
+        return false;
+    return !hasExplicitPrompt(words);
+}
+/**
+ * Does the command already carry a prompt of the host's own?
+ *
+ * Anything after the `exec` token that is not a flag, not a flag's value, and
+ * not the bare `-` stdin marker can only be Codex's one `[PROMPT]` positional.
+ */
+function hasExplicitPrompt(words) {
+    const execIndex = words.findIndex((word, index) => index > 0 && (word === 'exec' || word === 'e'));
+    if (execIndex === -1)
+        return false;
+    for (let i = execIndex + 1; i < words.length; i += 1) {
+        const word = words[i] ?? '';
+        if (word === '-' || word.startsWith('-'))
+            continue;
+        if (VALUE_TAKING_FLAGS.has(words[i - 1] ?? ''))
+            continue;
+        return true;
+    }
+    return false;
+}
+/**
+ * Flags that take a following value, for the bare-`-` scan below.
+ *
+ * Not a complete model of Codex's command line — just enough to tell the prompt
+ * positional `-` from a `-` that is somebody's argument.
+ */
+const VALUE_TAKING_FLAGS = new Set([
+    '-c',
+    '--config',
+    '-m',
+    '--model',
+    '-i',
+    '--image',
+    '-o',
+    '--output-last-message',
+    '-s',
+    '--sandbox',
+    '-C',
+    '--cd',
+    '-p',
+    '--profile',
+    '--add-dir',
+    '--output-schema',
+    '--color',
+    '--local-provider',
+    '--enable',
+    '--disable',
+]);
+/**
+ * Drop the prompt positional from the host's command.
+ *
+ * The README has recommended `codex exec -` since 0.2.0, and `codex exec -` is
+ * the form most people write anyway. We re-add the `-` ourselves at the very
+ * end, after any `resume <id>` — leaving the host's in place would make it the
+ * `SESSION_ID` positional and push `resume` into being a second one, which
+ * Codex rejects outright.
+ *
+ * A `-` that follows a value-taking flag is that flag's argument, not the
+ * prompt, so it stays.
+ */
+function withoutPromptPositional(words) {
+    return words.filter((word, index) => word !== '-' || VALUE_TAKING_FLAGS.has(words[index - 1] ?? ''));
+}
+/**
+ * Escape a value for a TOML basic string.
+ *
+ * The `-c` override is parsed as TOML, so the URL lands inside double quotes
+ * and has to survive that. Control characters are escaped rather than passed
+ * through because TOML rejects raw ones and the whole override would fail to
+ * parse — taking the agent's tools with it.
+ */
+function tomlString(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/[\u0000-\u001f\u007f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return `"${escaped}"`;
+}
+/**
+ * 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 function buildMcpOverride(mcpUrl) {
+    return (`mcp_servers.${MCP_SERVER_NAME}={url=${tomlString(mcpUrl)}, ` +
+        `env_http_headers={"X-API-Key"=${tomlString(MCP_API_KEY_ENV_VAR)}}}`);
+}
+/** Already present in the host's own command — never add a second one. */
+function has(words, ...flags) {
+    return flags.some((flag) => words.includes(flag));
+}
+/**
+ * Both spellings of "bypass approvals and the sandbox".
+ *
+ * `--yolo` is a hidden alias of the long form; Codex rejects the pair outright.
+ */
+const BYPASS_FLAGS = ['--yolo', '--dangerously-bypass-approvals-and-sandbox'];
+/**
+ * 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 function codexCommand(base, flags = {}) {
+    const platform = flags.platform ?? process.platform;
+    const quote = (value) => shellQuote(value, platform);
+    const gated = flags.skipPermissions === false;
+    // `--safe-tools` has to *remove* a bypass the host wrote, not merely decline
+    // to add one. Until 0.2.2 this README recommended `--exec 'codex exec -
+    // --yolo'`, so the flag is sitting in existing installs — and leaving it
+    // there would have the harness log "tools are permission-gated" and the
+    // prompt tell the agent that approvals will stop it, over a run that is in
+    // fact fully unsandboxed. A safety switch that quietly does nothing is worse
+    // than not having one.
+    const words = withoutPromptPositional(base.trim().split(/\s+/)).filter((word) => !gated || !BYPASS_FLAGS.includes(word));
+    const parts = [...words];
+    if (flags.sessionId)
+        parts.push('resume', quote(flags.sessionId));
+    if (!has(words, '--json'))
+        parts.push('--json');
+    if (!has(words, '--skip-git-repo-check'))
+        parts.push('--skip-git-repo-check');
+    if (!gated && !has(words, ...BYPASS_FLAGS)) {
+        parts.push('--yolo');
+    }
+    if (flags.mcpUrl)
+        parts.push('-c', quote(buildMcpOverride(flags.mcpUrl)));
+    // The prompt arrives on stdin, and `-` is how Codex is told to read it.
+    // Explicit rather than implied: `codex exec` with no positional does read
+    // stdin, but `codex exec resume <id>` treats a missing positional as "no
+    // prompt", and it also prints a `Reading prompt from stdin...` banner that
+    // the `-` form suppresses.
+    parts.push('-');
+    return parts.join(' ');
+}
+function asObject(candidate) {
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Pull a human-readable complaint out of whatever shape a failure event has. */
+function failureMessage(event) {
+    const error = event.error;
+    if (typeof error === 'string')
+        return text(error);
+    if (error && typeof error === 'object') {
+        const record = error;
+        return text(record.message) ?? text(record.reason);
+    }
+    return text(event.message);
+}
+/**
+ * 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 function parseCodexOutput(stdout) {
+    let sessionId;
+    let reply;
+    let failure;
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith('{'))
+            continue;
+        const event = asObject(trimmed);
+        if (!event)
+            continue;
+        const type = event.type;
+        if (type === 'thread.started') {
+            sessionId = text(event.thread_id) ?? sessionId;
+            continue;
+        }
+        if (type === 'turn.failed' || type === 'error') {
+            failure = failureMessage(event) ?? failure ?? 'codex reported a failed turn';
+            continue;
+        }
+        if (type === 'item.completed') {
+            const item = event.item;
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const record = item;
+                // Last one wins: a turn can emit several, and the final one is the
+                // answer the run ended on.
+                if (record.type === 'agent_message')
+                    reply = text(record.text) ?? reply;
+            }
+        }
+    }
+    // A failed turn that still produced a message is a failure. The message in
+    // that case is the explanation ("I ran out of…"), not an answer, and posting
+    // it would put the failure in front of a customer as if the agent had chosen
+    // to say it.
+    if (failure)
+        return { ok: false, sessionId, error: failure };
+    if (reply)
+        return { ok: true, sessionId, text: reply };
+    const sample = stdout.trim().slice(0, 200);
+    return {
+        ok: false,
+        sessionId,
+        error: sample
+            ? `codex produced no agent message (asked for --json). First 200 chars: ${sample}`
+            : 'codex returned no output',
+    };
+}
+/**
+ * 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 function looksLikeCodexResumeFailure(output, sessionId) {
+    if (!sessionId)
+        return false;
+    if (/"type"\s*:\s*"thread\.started"/.test(output))
+        return false;
+    if (/unexpected argument|unrecognized subcommand|invalid value|error: unexpected/i.test(output)) {
+        return true;
+    }
+    // The first branch is the message the binary actually prints for a thread it
+    // no longer has on disk, captured from a real run:
+    //   Error: thread/resume: thread/resume failed: no rollout found for thread
+    //   id <uuid> (code -32600)
+    // The rest are broader, because the wording is not ours to depend on.
+    if (/no rollout found|no (conversation|session|thread)[^\n]{0,40}found|(session|thread)[^\n]{0,40}not found|resume[^\n]{0,20}(failed|invalid|expired)/i.test(output)) {
+        return true;
+    }
+    return output.includes(sessionId);
+}

package/dist/agent/contract.d.ts

@@ -34,12 +34,33 @@ export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
 export declare function conversationMessagesPath(conversationId: string): string;
 /** `POST` — close out a run. Must be called for every run, success or not. */
 export declare function agentRunCompletePath(runId: string): string;
+/**
+ * A file or image hanging off a message.
+ *
+ * Only `url` is required, and it is the only field that does any work: it is
+ * what an agent can actually fetch. The type and name are labels for the
+ * prompt.
+ */
+export interface RunAttachment {
+    /** What the server called it — `image/jpeg`, `image`, `application/pdf`, … */
+    type?: string;
+    /** Where the bytes are. The agent downloads this to look at it. */
+    url: string;
+    /** Original filename, when the server kept one. */
+    name?: string;
+}
 /**
  * One earlier message on the surface the run is about.
  *
- * Only `text` is required. Everything else is decoration the server may or may
- * not have — an older server sends none of this at all, and a newer one may add
- * fields this build has never heard of.
+ * Everything except `text` is decoration the server may or may not have — an
+ * older server sends none of this at all, and a newer one may add fields this
+ * build has never heard of.
+ *
+ * `text` may be **empty**, which is new: a guest who sends only a photo
+ * produces a real message with nothing in it but `attachments`. Treating that
+ * as a malformed row (which is what requiring text amounts to) would delete the
+ * picture from the thread and leave the agent answering a message it cannot see
+ * any trace of.
  */
 export interface RunMessage {
     /** Display name of whoever wrote it. */
@@ -49,6 +70,8 @@ export interface RunMessage {
     /** ISO-8601 timestamp. */
     at?: string;
     text: string;
+    /** Images and files sent with it. Absent on a server that predates the field. */
+    attachments?: RunAttachment[];
 }
 /** One memory the account has about this agent's work. */
 export interface RunMemory {
@@ -66,12 +89,41 @@ export interface RunMemory {
  * the part worth spending prompt on.
  */
 export declare const MAX_CONTEXT_ENTRIES = 50;
+/** Ceiling on attachments kept from any one message. */
+export declare const MAX_ATTACHMENTS = 10;
+/**
+ * Ceiling on the operator-configured system prompt.
+ *
+ * Deliberately well above the server's own ~8000-character bound rather than
+ * equal to it. This is a backstop against a pathological payload, not a second
+ * copy of the product rule: matching the server's number exactly would mean a
+ * server that later raises its limit gets silently truncated by every CLI
+ * already on someone's laptop, and the operator would see their instructions
+ * quietly stop half-way through with nothing to explain it.
+ */
+export declare const MAX_SYSTEM_PROMPT_CHARS = 20000;
 /** The `agent.run_requested` payload, as far as the harness cares about it. */
 export interface AgentRunRequest {
     run_id: string;
     agent_id?: string;
     agent_user_id?: string;
     agent_name?: string;
+    /**
+     * The agent's job title, as the operator wrote it — "Guest Experience Lead".
+     * Rendered alongside the name so the agent knows what it was hired as.
+     */
+    agent_title?: string;
+    /**
+     * The operator-configured system prompt for this agent — its "soul".
+     *
+     * Written by the person who runs this machine, in the ProhostAI agent
+     * profile, and bounded server-side. Trusted to the same degree as the
+     * `--exec` command the host typed: it configures the agent rather than asking
+     * it for anything, and it arrives over the same authenticated, HMAC-verified
+     * channel as the rest of the run. Absent on an older server, and absent for
+     * an agent whose operator never wrote one.
+     */
+    system_prompt?: string;
     account_id?: string;
     /** Why the agent woke — `team_chat_mention`, `task_comment`, … */
     kind?: string;
@@ -82,6 +134,13 @@ export interface AgentRunRequest {
     trigger_message_id?: string;
     /** Capped inline excerpt of the message that woke the agent. */
     trigger_text?: string;
+    /**
+     * Images and files on the message that woke the agent.
+     *
+     * Can be the *whole* message: a guest who sends a photo of a broken boiler
+     * and nothing else produces an empty `trigger_text` and one attachment here.
+     */
+    trigger_attachments?: RunAttachment[];
     trigger_user_id?: string;
     /** For a trigger fan-out with no surface: the event type that fired it. */
     trigger_type?: string;

package/dist/agent/contract.js

@@ -48,6 +48,19 @@ export function agentRunCompletePath(runId) {
  * the part worth spending prompt on.
  */
 export const MAX_CONTEXT_ENTRIES = 50;
+/** Ceiling on attachments kept from any one message. */
+export const MAX_ATTACHMENTS = 10;
+/**
+ * Ceiling on the operator-configured system prompt.
+ *
+ * Deliberately well above the server's own ~8000-character bound rather than
+ * equal to it. This is a backstop against a pathological payload, not a second
+ * copy of the product rule: matching the server's number exactly would mean a
+ * server that later raises its limit gets silently truncated by every CLI
+ * already on someone's laptop, and the operator would see their instructions
+ * quietly stop half-way through with nothing to explain it.
+ */
+export const MAX_SYSTEM_PROMPT_CHARS = 20_000;
 /**
  * Fallback for a server that predates `reply_instructions.body_field`.
  *
@@ -112,11 +125,55 @@ function bodyExtra(value) {
     const entries = value;
     return Object.keys(entries).length > 0 ? entries : undefined;
 }
-function parseMessage(entry) {
-    const text = str(entry.text);
+/**
+ * Validate an attachment list.
+ *
+ * An entry with no `url` is dropped: the URL is the only part an agent can act
+ * on, so a nameless, typeless, linkless attachment is a line of prompt telling
+ * the agent something exists that it has no way to look at — worse than saying
+ * nothing.
+ *
+ * Trimmed from the front, unlike the two context lists: attachments on one
+ * message have no useful order, so the first few are as good as the last few.
+ */
+function attachmentList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const entry = raw;
+        const url = str(entry.url);
+        if (!url)
+            continue;
+        items.push({ url, type: str(entry.type), name: str(entry.name) });
+    }
+    return items.length > 0 ? items.slice(0, MAX_ATTACHMENTS) : undefined;
+}
+/**
+ * Bound the operator's system prompt.
+ *
+ * Truncated rather than dropped: half a set of standing instructions still
+ * describes the agent far better than none, and the alternative — an agent that
+ * silently loses its whole configured persona because someone pasted a novel
+ * into the box — is the worse failure of the two.
+ */
+function systemPrompt(value) {
+    const text = str(value);
     if (!text)
+        return undefined;
+    return text.length > MAX_SYSTEM_PROMPT_CHARS ? text.slice(0, MAX_SYSTEM_PROMPT_CHARS) : text;
+}
+function parseMessage(entry) {
+    const attachments = attachmentList(entry.attachments);
+    // Not `str()`: an image-only message carries an empty string here and is a
+    // real message, so emptiness disqualifies a row only when there is also
+    // nothing attached to it.
+    const text = typeof entry.text === 'string' ? entry.text : '';
+    if (!text && !attachments)
         return null;
-    return { text, author: str(entry.author), role: str(entry.role), at: str(entry.at) };
+    return { text, author: str(entry.author), role: str(entry.role), at: str(entry.at), attachments };
 }
 function parseMemory(entry) {
     const content = str(entry.content);
@@ -166,6 +223,11 @@ export function parseRunRequest(data) {
         agent_id: str(data.agent_id),
         agent_user_id: str(data.agent_user_id),
         agent_name: str(data.agent_name),
+        agent_title: str(data.agent_title),
+        // Accepted at the top level and under `agent`, on the same reasoning as the
+        // context lists below: the server can move it without a CLI release, and a
+        // published CLI cannot be redeployed to follow it.
+        system_prompt: systemPrompt(data.system_prompt ?? obj(data.agent).system_prompt),
         account_id: str(data.account_id),
         kind: str(data.kind),
         conversation_id: conversationId,
@@ -174,6 +236,7 @@ export function parseRunRequest(data) {
         trigger_source: str(trigger.source) ?? str(data.trigger_source),
         trigger_message_id: str(trigger.message_id),
         trigger_text: str(trigger.text_excerpt),
+        trigger_attachments: attachmentList(trigger.attachments ?? data.trigger_attachments),
         trigger_user_id: str(trigger.user_id),
         trigger_type: str(trigger.type),
         trigger_entity_id: str(trigger.entity_id),

package/dist/agent/mcp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the ProhostAI MCP server is called, in one place.
+ *
+ * Both brain harnesses register the same server under the same name, and the
+ * prompt describes it by that name — so a rename here is a rename everywhere
+ * rather than three edits that can drift apart.
+ */
+/**
+ * Name the ProhostAI MCP server is registered under, which is also what makes
+ * its tools appear as `mcp__prohost__<tool>` in Claude Code. Referenced in the
+ * prompt, in the `--allowedTools` pattern, and in both generated configs.
+ */
+export declare const MCP_SERVER_NAME = "prohost";
+/**
+ * How Claude Code spells the wired-in tools.
+ *
+ * Deliberately **not** used for Codex: that binary namespaces MCP tools its own
+ * way, and this harness has not verified the spelling against it. Telling an
+ * agent a tool is called something it isn't is the same class of failure as
+ * naming an endpoint it cannot call — so the prompt names the server instead
+ * and leaves the pattern out. See {@link ../prompt.ts}.
+ */
+export declare const MCP_TOOL_PATTERN = "mcp__prohost__*";

package/dist/agent/mcp.js

@@ -0,0 +1,23 @@
+/**
+ * What the ProhostAI MCP server is called, in one place.
+ *
+ * Both brain harnesses register the same server under the same name, and the
+ * prompt describes it by that name — so a rename here is a rename everywhere
+ * rather than three edits that can drift apart.
+ */
+/**
+ * Name the ProhostAI MCP server is registered under, which is also what makes
+ * its tools appear as `mcp__prohost__<tool>` in Claude Code. Referenced in the
+ * prompt, in the `--allowedTools` pattern, and in both generated configs.
+ */
+export const MCP_SERVER_NAME = 'prohost';
+/**
+ * How Claude Code spells the wired-in tools.
+ *
+ * Deliberately **not** used for Codex: that binary namespaces MCP tools its own
+ * way, and this harness has not verified the spelling against it. Telling an
+ * agent a tool is called something it isn't is the same class of failure as
+ * naming an endpoint it cannot call — so the prompt names the server instead
+ * and leaves the pattern out. See {@link ../prompt.ts}.
+ */
+export const MCP_TOOL_PATTERN = `mcp__${MCP_SERVER_NAME}__*`;

package/dist/agent/prompt.d.ts

@@ -18,6 +18,17 @@ export interface PromptContext {
      * nothing: the agent reports having looked something up when it did not.
      */
     mcpServerName?: string;
+    /**
+     * How this particular brain spells the wired-in tools, e.g. `mcp__prohost__*`.
+     *
+     * Set only when the harness has actually verified the spelling for the brain
+     * it is driving — Claude Code, today. Left unset for Codex, whose MCP tool
+     * namespacing this harness has not confirmed: the prompt then names the
+     * server without claiming a prefix, because a wrong tool name is the same
+     * failure as a wrong endpoint. The agent can see its own tool list; it does
+     * not need us to guess at it.
+     */
+    mcpToolPattern?: string;
     /**
      * Tools are behind permission prompts this run (`--safe-tools`).
      *