@prohost/cli 0.2.1 → 0.2.3

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/extras.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export declare const EXTRA_MCP_FILENAME = "extra-mcp.json";
+/** One server definition, passed through to the brain untouched. */
+export type ExtraServer = Record<string, unknown>;
+export interface ExtraMcpServers {
+    /** Accepted definitions, keyed by server name. Empty when there are none. */
+    servers: Record<string, ExtraServer>;
+    /**
+     * Lines for the operator to see when the current grant set is loaded.
+     *
+     * Both the good news and the bad travel this way: which extras loaded is as
+     * worth printing as which were rejected, because "I added a server and the
+     * agent still can't use it" is otherwise a silent, unfalsifiable complaint.
+     */
+    warnings: string[];
+}
+/** Absolute path of the extras file. */
+export declare function extraMcpPath(env?: NodeJS.ProcessEnv): string;
+export interface LoadExtraOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Injectable read, so a test can exercise the parse without a filesystem. */
+    readImpl?: (file: string) => string;
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export declare function loadExtraMcpServers(options?: LoadExtraOptions): ExtraMcpServers;

package/dist/agent/extras.js

@@ -0,0 +1,118 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+import { MCP_SERVER_NAME } from './mcp.js';
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export const EXTRA_MCP_FILENAME = 'extra-mcp.json';
+/** Absolute path of the extras file. */
+export function extraMcpPath(env = process.env) {
+    return path.join(prohostHome(env), EXTRA_MCP_FILENAME);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export function loadExtraMcpServers(options = {}) {
+    const file = extraMcpPath(options.env ?? process.env);
+    const read = options.readImpl ?? ((target) => readFileSync(target, 'utf8'));
+    let raw;
+    try {
+        raw = read(file);
+    }
+    catch (err) {
+        // ENOENT is the normal state and must stay silent. Anything else — a
+        // permission problem, a directory where the file should be — the operator
+        // wants to hear about, because they put the file there on purpose.
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { servers: {}, warnings: [] };
+        return {
+            servers: {},
+            warnings: [`could not read ${file} (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            servers: {},
+            warnings: [`${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) {
+        return {
+            servers: {},
+            warnings: [`${file} has no "mcpServers" object; no extra MCP servers`],
+        };
+    }
+    const servers = {};
+    const warnings = [];
+    for (const [name, definition] of Object.entries(parsed.mcpServers)) {
+        if (name === MCP_SERVER_NAME) {
+            warnings.push(`${file} defines a server named "${MCP_SERVER_NAME}" — that name is reserved for the ` +
+                'ProhostAI server and the entry was ignored. Rename it to use it.');
+            continue;
+        }
+        if (!isPlainObject(definition)) {
+            warnings.push(`${file}: server "${name}" is not an object; the entry was ignored`);
+            continue;
+        }
+        servers[name] = definition;
+    }
+    const names = Object.keys(servers);
+    if (names.length > 0) {
+        warnings.push(`extra MCP servers loaded from ${EXTRA_MCP_FILENAME}: ${names.join(', ')} — ` +
+            'anyone who can trigger this agent can use them, with permission prompts off.');
+    }
+    return { servers, warnings };
+}

package/dist/agent/mcp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 both shaped brains spell the wired-in tools.
+ *
+ * Claude Code's spelling was known from its documentation. Codex's was an open
+ * question until 0.2.3 — the prompt named the server and left the pattern out
+ * rather than guess — and the answer, measured by registering a stub MCP server
+ * against a real `codex-cli 0.144.1` and asking the model what it had just
+ * called, is that Codex uses the same `mcp__<server>__<tool>` convention. So
+ * both brains now get the pattern. See {@link ../prompt.ts}.
+ */
+export declare const MCP_TOOL_PATTERN = "mcp__prohost__*";

package/dist/agent/mcp.js

@@ -0,0 +1,24 @@
+/**
+ * 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 both shaped brains spell the wired-in tools.
+ *
+ * Claude Code's spelling was known from its documentation. Codex's was an open
+ * question until 0.2.3 — the prompt named the server and left the pattern out
+ * rather than guess — and the answer, measured by registering a stub MCP server
+ * against a real `codex-cli 0.144.1` and asking the model what it had just
+ * called, is that Codex uses the same `mcp__<server>__<tool>` convention. So
+ * both brains now get the pattern. See {@link ../prompt.ts}.
+ */
+export const MCP_TOOL_PATTERN = `mcp__${MCP_SERVER_NAME}__*`;

package/dist/agent/prompt.d.ts

@@ -18,6 +18,18 @@ 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 and, since 0.2.3, Codex, which turned out to
+     * use the same convention. Left unset for every other `--exec` command,
+     * whose namespacing we have no way to know: 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`).
      *

package/dist/agent/prompt.js

@@ -6,6 +6,19 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+/**
+ * Describe one attachment.
+ *
+ * The URL is the point — it is the only part the agent can act on — so it goes
+ * last, where it is easy to copy out of, and it is never abbreviated.
+ */
+function renderAttachment(attachment) {
+    // `image/jpeg` and a bare `image` both count; anything else, including a
+    // missing type, is described as a file rather than guessed at.
+    const kind = attachment.type?.toLowerCase().startsWith('image') ? 'image' : 'file';
+    const name = attachment.name ? ` "${attachment.name}"` : '';
+    return `attached ${kind}${name}: ${attachment.url}`;
+}
 /**
  * Render one line of thread history.
  *
@@ -13,12 +26,18 @@
  * a row with a role and no author — which is what a system row like
  * `{role: "event", text: "Reservation confirmed"}` looks like — reads as
  * `event: …` rather than the nonsense `someone (event): …`.
+ *
+ * Attachments render inline, after the text. An image-only message has no text
+ * at all, so the parts are joined rather than concatenated — otherwise the line
+ * opens with a stray space where the message would have been.
  */
 function renderMessage(message) {
     const who = message.author ?? message.role ?? 'someone';
     const role = message.author && message.role ? ` (${message.role})` : '';
     const when = message.at ? `[${message.at}] ` : '';
-    return `${when}${who}${role}: ${message.text}`;
+    const attachments = (message.attachments ?? []).map((file) => `[${renderAttachment(file)}]`);
+    const body = [message.text, ...attachments].filter((part) => part.length > 0).join(' ');
+    return `${when}${who}${role}: ${body}`;
 }
 /** Render one remembered fact. */
 function renderMemory(memory) {
@@ -28,8 +47,9 @@ function renderMemory(memory) {
 export function buildPrompt(run, context) {
     const name = run.agent_name ?? context.agentName;
     const canReply = Boolean(run.reply_surface !== 'none' && run.reply_path && run.reply_body_key);
+    const title = run.agent_title ? ` (${run.agent_title})` : '';
     const lines = [
-        `You are "${name}", an AI teammate in a ProhostAI workspace.`,
+        `You are "${name}"${title}, an AI teammate in a ProhostAI workspace.`,
         canReply && run.reply_surface === 'conversation'
             ? 'You were mentioned in a conversation and someone is waiting on a reply.'
             : run.reply_surface === 'none'
@@ -39,6 +59,20 @@ export function buildPrompt(run, context) {
                     : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
         '',
     ];
+    // The operator's own configuration comes first, above everything the server
+    // generated. It is who this agent *is* — persona, house rules, escalation
+    // policy — and an agent that meets its standing instructions only after four
+    // blocks of run context reads them as an afterthought rather than as its
+    // brief.
+    //
+    // Rendered as instructions, not as quoted data: the text is written by the
+    // person who runs this machine, in their own agent profile, and reaches us
+    // over the same HMAC-verified channel as the rest of the run — the same trust
+    // as the `--exec` command they typed. It is fenced anyway, so the agent can
+    // always tell where its operator stops talking and the server starts.
+    if (run.system_prompt) {
+        lines.push('Your operator configured these standing instructions for you, in your', 'ProhostAI agent profile. Follow them — they define how you work here.', '--- begin operator instructions ---', run.system_prompt, '--- end operator instructions ---', 'Everything below this line is generated by ProhostAI for this one run. It', 'describes what is actually true about this turn and your access to it,', 'which the instructions above do not change.', '');
+    }
     const facts = [];
     if (run.kind)
         facts.push(`Why you woke up: ${run.kind}`);
@@ -72,14 +106,26 @@ export function buildPrompt(run, context) {
     if (run.recent_messages?.length) {
         lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
     }
+    const triggerAttachments = run.trigger_attachments ?? [];
     if (run.trigger_text) {
         // The server caps this excerpt, so say so rather than let an agent assume
         // it has the whole message.
         lines.push('Message that woke you (may be truncated by the server):', run.trigger_text, '');
     }
+    else if (triggerAttachments.length > 0) {
+        // Distinct from "the server didn't send the text": here the message really
+        // had none. An agent told the text was merely missing goes looking for it,
+        // or apologises for not having it, when the picture below IS the message.
+        lines.push('The message that woke you had no text — what follows is all of it.', '');
+    }
     else {
         lines.push('The message text was not included in the event.', '');
     }
+    if (triggerAttachments.length > 0) {
+        lines.push('Sent with that message:', ...triggerAttachments.map((file) => `- ${renderAttachment(file)}`), '');
+    }
+    const hasAttachments = triggerAttachments.length > 0 ||
+        Boolean(run.recent_messages?.some((message) => message.attachments?.length));
     // An agent that doesn't know it is headless narrates as if it were mid-
     // session — "let me connect to that", "I'll check once the tools load" —
     // and that text is what gets posted to a customer, describing a lookup that
@@ -98,7 +144,58 @@ export function buildPrompt(run, context) {
     // browse and says so to a customer, when one ToolSearch call away it
     // could. Field-observed on the first 0.2.0 deployment; phrased
     // conditionally because other `--exec` brains have no ToolSearch.
-    '- If you have a ToolSearch tool, part of your toolkit is deferred and', '  invisible until loaded — web browsing (WebSearch, WebFetch) usually', '  is. Search ToolSearch for a capability before telling anyone you', '  lack it.', "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
+    '- If you have a ToolSearch tool, part of your toolkit is deferred and', '  invisible until loaded — web browsing (WebSearch, WebFetch) usually', '  is. Search ToolSearch for a capability before telling anyone you', '  lack it.', 
+    // The correction to the bullet above, and it is here because the bullet
+    // above caused a real production failure. A paired brain searched
+    // ToolSearch for "bash", found nothing — ToolSearch indexes only the
+    // *deferred* tools, and Bash is a direct one — and concluded across a
+    // whole resumed session that it had no shell, while
+    // `--dangerously-skip-permissions` had been handing it the full toolset
+    // the entire time. "Search before you claim you lack it" quietly taught
+    // the opposite of what it meant: that a ToolSearch miss is evidence of
+    // absence. It is not evidence of anything.
+    '- A ToolSearch miss proves nothing. ToolSearch indexes only the deferred', '  tools; the tools listed directly to you are the authoritative set, and', '  a tool can be fully available while ToolSearch has never heard of it', '  (Bash is exactly this). Never reason from a ToolSearch miss to "I do', '  not have that tool".', 
+    // The counterpart to the ToolSearch bullet, and the same failure one level
+    // up: a brain that assumes it is boxed in reports "I have no access to the
+    // codebase" from a machine with the checkout, the credentials and the CLI
+    // all sitting right there. Only true when tools are ungated — under
+    // --safe-tools the looking-around itself would sit waiting on an approval
+    // nobody is there to give, so the licence is withheld rather than dangled.
+    ...(context.toolsGated
+        ? []
+        : [
+            "- You are running on your operator's own machine, in their shell, with",
+            '  whatever they have installed — not in an empty sandbox. Before you',
+            '  tell anyone you have no access to some repository, codebase, log, or',
+            '  capability, take a QUICK look for it: the usual places a checkout',
+            '  lives, `gh auth status`, whether the command is on PATH. A quick',
+            '  look, not an audit — this run has a hard time limit and somebody',
+            '  waiting at the end of it.',
+            '- "Looking" means running the command, not inspecting your own tool',
+            '  list. Say you have no shell, no file access, or no checkout only',
+            '  after an attempt failed and you can quote what it said. Introspection',
+            '  is not evidence here: you were started with your tools unrestricted,',
+            '  so a capability you cannot find in a list is far more likely to be',
+            '  one you have not tried.',
+        ]), 
+    // Only when there is something to look at. Said unconditionally it is a
+    // paragraph of advice about a situation that does not exist, which is how a
+    // prompt teaches an agent to mention attachments nobody sent.
+    ...(!hasAttachments
+        ? []
+        : context.toolsGated
+            ? [
+                '- Attachments above are given as URLs, not as pictures you can see.',
+                '  Fetching one needs a tool that may not run this turn, so if you',
+                '  could not view it, say so rather than guessing at what it shows.',
+            ]
+            : [
+                '- Attachments above are given as URLs, and a URL is not something you',
+                '  can see. To actually look at one, download it to a local file first',
+                '  (`curl -sL "<url>" -o /tmp/attachment.jpg`) and then open that file',
+                '  with your file-reading tool — your vision works on local files, not',
+                '  on links. Never describe an image you have not opened.',
+            ]), "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
     // Deliberately does not list which domains are reachable. A paired
     // credential holds a narrow, server-chosen scope set — the current default
     // covers conversations, tasks, cleanings and approvals but NOT reservations
@@ -107,7 +204,13 @@ export function buildPrompt(run, context) {
     // domains the credential can't reach is the same failure as naming an MCP
     // endpoint it can't call: the agent reports a lookup it never made.
     context.mcpServerName
-        ? `- You have ProhostAI tools (mcp__${context.mcpServerName}__*). They are the sanctioned ` +
+        ? `- You have ProhostAI tools${
+        // Named by pattern only where the harness has verified how this brain
+        // spells them; otherwise by server, which the agent can match against
+        // its own tool list without being told a name that might be wrong.
+        context.mcpToolPattern
+            ? ` (${context.mcpToolPattern})`
+            : `, from the MCP server registered as "${context.mcpServerName}"`}. They are the sanctioned ` +
             'way to look up workspace data, so use them rather than guessing. Your credential is ' +
             'deliberately narrow and does not reach every part of the workspace: if a tool returns ' +
             'a permission error, that is a real limit rather than a glitch — say what you could not ' +