@prohost/cli 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.8.3
+
+A paired agent's shell steps read as what they do, not "Running a command".
+
+- **Shell calls report their description.** A `Bash` call's tool event now
+  carries Claude Code's own one-line `description` of the call beside the
+  command in `args_preview` (`{"command": …, "description": "Find the
+  handler"}`). The server uses it as the step's label in the live run view and
+  keeps "Running a command" when it is absent. Nothing else in the event
+  changes.
+
+## 0.8.2
+
+A ProhostAI back-office agent is told its cross-account reads are allowed.
+
+- **Back-office read tools change the credential sentence.** Before each run
+  whose ProhostAI tools are wired, the harness asks the MCP server's own
+  `tools/list` (cached 10 minutes; a failure reads as "absent" and is retried
+  after a minute). When it lists both `backoffice_describe_readonly_schema` and
+  `backoffice_query_readonly` — shown only to an agent-bound key on ProhostAI's
+  internal account holding `backoffice:read` — and a read-only call to the
+  schema tool goes through (its rollout flag is enforced only at call time),
+  the prompt replaces "your
+  credential is deliberately narrow" with: read-only cross-account
+  investigation is pre-authorized, look before answering (schema, then a query
+  filtered to the customer's account), never ask a human before a read-only
+  query, writes and customer-facing sends still follow approval discipline,
+  and summarize rather than paste rows. Ungated runs are also told that
+  read-only tools on the machine (operator-added MCP servers, CLIs) serve the
+  same purpose. Every other agent's prompt is byte-for-byte unchanged.
+
 ## 0.8.1
 
 A long message no longer reaches a paired agent as a fragment it can't recover.

package/README.md

@@ -172,6 +172,12 @@ reservations or listings — those tools return a permission error. The prompt
 tells the agent to say what it couldn't reach rather than answer as if it had,
 and refused tools are printed in the run log.
 
+The one exception is a ProhostAI back-office agent. Before a run, the CLI asks
+the MCP server's `tools/list` (cached for ten minutes). If the list includes the
+back-office read tools, which only an internal key with `backoffice:read` sees,
+and a read-only call to the schema tool is allowed, the prompt tells the agent that read-only cross-account investigation is
+pre-authorized. Writes and customer-facing sends still go through approval.
+
 **It reads the reply out of JSON.** The run is invoked with
 `--output-format json`, and the `result` field is what gets posted. If that
 output isn't JSON — a login prompt, a crash banner — the run is reported failed

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the paired credential can reach, as far as the prompt needs to know.
+ *
+ * Today that is one question: does this agent hold ProhostAI's back-office
+ * read tools (`backoffice_describe_readonly_schema` + `backoffice_query_readonly`)?
+ * The answer changes what the prompt says — an agent told its credential is
+ * "deliberately narrow" refuses or hedges on exactly the cross-account
+ * investigations those tools exist for.
+ *
+ * Nothing the CLI stores can answer it. The pairing response carries no scopes,
+ * and the gate is not a scope alone: the server shows the tools only to an
+ * agent-bound key on ProhostAI's internal account, holding the literal
+ * `backoffice:read` scope, with a flag on — any of which can change after
+ * pairing. So the server is asked: `tools/list` first, and — because its
+ * visibility check leaves out the rollout flag, which is enforced only when a
+ * tool is called — then the read-only, side-effect-free
+ * `backoffice_describe_readonly_schema`, which runs the whole gate. Two small
+ * requests, cached, and every failure reads as "absent": the prompt then says
+ * what it has always said.
+ */
+/** Both have to be listed — the schema call is what makes the query usable. */
+export declare const BACKOFFICE_READ_TOOLS: readonly ["backoffice_describe_readonly_schema", "backoffice_query_readonly"];
+export interface RunCapabilities {
+    /** The back-office read tools are in this credential's `tools/list`. */
+    backofficeRead: boolean;
+}
+export declare const NO_CAPABILITIES: RunCapabilities;
+/** Short: a run waits on this before its agent starts. */
+export declare const CAPABILITY_PROBE_TIMEOUT_MS = 5000;
+/** How long an answer is reused. A grant or revoke shows up within this. */
+export declare const CAPABILITY_CACHE_MS: number;
+/** How long a failed probe is reused, so an outage costs one timeout a minute, not one per run. */
+export declare const CAPABILITY_FAILURE_CACHE_MS = 60000;
+export interface ToolListOptions {
+    mcpUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** The tool names the server lists for this key, or `null` when it could not be asked. */
+export declare function listMcpToolNames(options: ToolListOptions): Promise<string[] | null>;
+/**
+ * Whether a back-office read actually goes through for this key: `true` when
+ * the schema call answers with its schema, `false` when the server refuses it
+ * (`backoffice_forbidden` — e.g. the rollout flag is off), `null` when it could
+ * not be asked.
+ */
+export declare function backofficeReadAllowed(options: ToolListOptions): Promise<boolean | null>;
+export declare function capabilitiesFromToolNames(names: readonly string[]): RunCapabilities;
+/**
+ * A cached `tools/list` probe for one daemon's credential.
+ *
+ * A daemon is long-lived, so the answer is re-asked every
+ * {@link CAPABILITY_CACHE_MS} rather than fixed at start-up: a scope granted or
+ * revoked on the server reaches the prompt without a restart.
+ */
+export declare function capabilityProbe(options: ToolListOptions & {
+    now?: () => number;
+}): () => Promise<RunCapabilities>;

package/dist/agent/capabilities.js

@@ -0,0 +1,158 @@
+/**
+ * What the paired credential can reach, as far as the prompt needs to know.
+ *
+ * Today that is one question: does this agent hold ProhostAI's back-office
+ * read tools (`backoffice_describe_readonly_schema` + `backoffice_query_readonly`)?
+ * The answer changes what the prompt says — an agent told its credential is
+ * "deliberately narrow" refuses or hedges on exactly the cross-account
+ * investigations those tools exist for.
+ *
+ * Nothing the CLI stores can answer it. The pairing response carries no scopes,
+ * and the gate is not a scope alone: the server shows the tools only to an
+ * agent-bound key on ProhostAI's internal account, holding the literal
+ * `backoffice:read` scope, with a flag on — any of which can change after
+ * pairing. So the server is asked: `tools/list` first, and — because its
+ * visibility check leaves out the rollout flag, which is enforced only when a
+ * tool is called — then the read-only, side-effect-free
+ * `backoffice_describe_readonly_schema`, which runs the whole gate. Two small
+ * requests, cached, and every failure reads as "absent": the prompt then says
+ * what it has always said.
+ */
+import { USER_AGENT } from '../version.js';
+/** Both have to be listed — the schema call is what makes the query usable. */
+export const BACKOFFICE_READ_TOOLS = ['backoffice_describe_readonly_schema', 'backoffice_query_readonly'];
+export const NO_CAPABILITIES = { backofficeRead: false };
+/** Short: a run waits on this before its agent starts. */
+export const CAPABILITY_PROBE_TIMEOUT_MS = 5_000;
+/** How long an answer is reused. A grant or revoke shows up within this. */
+export const CAPABILITY_CACHE_MS = 10 * 60_000;
+/** How long a failed probe is reused, so an outage costs one timeout a minute, not one per run. */
+export const CAPABILITY_FAILURE_CACHE_MS = 60_000;
+/** Cap on the body read — a full catalog is well under this. */
+const MAX_BODY_CHARS = 2_000_000;
+/**
+ * Pull the JSON-RPC result out of a response that may be plain JSON or a
+ * streamable-HTTP SSE stream (`data: {...}` lines). `undefined` when neither
+ * shape holds a result.
+ */
+function jsonRpcResult(body) {
+    const candidates = body.trimStart().startsWith('{')
+        ? [body]
+        : body
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice('data:'.length).trim());
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed.result === 'object' && parsed.result !== null) {
+                return parsed.result;
+            }
+        }
+        catch {
+            // Not JSON — keep looking.
+        }
+    }
+    return undefined;
+}
+/**
+ * One JSON-RPC request to the ProhostAI MCP server; its `result`, or `null`
+ * when it could not be asked (network, timeout, non-2xx, unparseable, error).
+ *
+ * Authenticates exactly as the brain's own MCP config does (`X-API-Key`), so
+ * the answer is what the agent itself will see. The server runs stateless
+ * HTTP, so no `initialize` round-trip is needed first.
+ */
+async function mcpRequest(options, method, params) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? CAPABILITY_PROBE_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(options.mcpUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json, text/event-stream',
+                'X-API-Key': options.apiKey,
+                'User-Agent': USER_AGENT,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+            signal: controller.signal,
+        });
+        if (response.status < 200 || response.status >= 300)
+            return null;
+        return jsonRpcResult((await response.text()).slice(0, MAX_BODY_CHARS)) ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The tool names the server lists for this key, or `null` when it could not be asked. */
+export async function listMcpToolNames(options) {
+    const tools = (await mcpRequest(options, 'tools/list', {}))?.tools;
+    if (!Array.isArray(tools))
+        return null;
+    return tools
+        .map((tool) => (tool && typeof tool === 'object' ? tool.name : undefined))
+        .filter((name) => typeof name === 'string');
+}
+/**
+ * Whether a back-office read actually goes through for this key: `true` when
+ * the schema call answers with its schema, `false` when the server refuses it
+ * (`backoffice_forbidden` — e.g. the rollout flag is off), `null` when it could
+ * not be asked.
+ */
+export async function backofficeReadAllowed(options) {
+    const result = await mcpRequest(options, 'tools/call', {
+        name: 'backoffice_describe_readonly_schema',
+        arguments: {},
+    });
+    if (!result)
+        return null;
+    if (result.isError === true)
+        return false;
+    const content = Array.isArray(result.content) ? result.content : [];
+    const text = content
+        .map((part) => (part && typeof part === 'object' ? part.text : undefined))
+        .filter((part) => typeof part === 'string')
+        .join('');
+    try {
+        const parsed = JSON.parse(text);
+        return parsed.error === undefined && parsed.tables !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function capabilitiesFromToolNames(names) {
+    return { backofficeRead: BACKOFFICE_READ_TOOLS.every((tool) => names.includes(tool)) };
+}
+/**
+ * A cached `tools/list` probe for one daemon's credential.
+ *
+ * A daemon is long-lived, so the answer is re-asked every
+ * {@link CAPABILITY_CACHE_MS} rather than fixed at start-up: a scope granted or
+ * revoked on the server reaches the prompt without a restart.
+ */
+export function capabilityProbe(options) {
+    const now = options.now ?? Date.now;
+    let cached;
+    return async () => {
+        if (cached && now() < cached.until)
+            return cached.value;
+        const names = await listMcpToolNames(options);
+        let value = names ? capabilitiesFromToolNames(names) : NO_CAPABILITIES;
+        let answered = names !== null;
+        if (value.backofficeRead) {
+            // Listed is not the same as allowed: confirm the gate end to end.
+            const allowed = await backofficeReadAllowed(options);
+            answered = allowed !== null;
+            value = { backofficeRead: allowed === true };
+        }
+        cached = { value, until: now() + (answered ? CAPABILITY_CACHE_MS : CAPABILITY_FAILURE_CACHE_MS) };
+        return value;
+    };
+}

package/dist/agent/claude.js

@@ -358,8 +358,16 @@ export function toolArgsPreview(name, input) {
         for (const key of headline) {
             const value = args[key];
             const text = typeof value === 'string' ? preview(value) : undefined;
-            if (text)
-                return JSON.stringify({ [key]: text });
+            if (!text)
+                continue;
+            // The tool's own one-line summary of the call ("Find the failing test"),
+            // which the server prefers over the generic "Running a command" label.
+            // Capped shorter than the headline so the object stays under the
+            // server's 500-char preview bound and still parses there.
+            const description = DESCRIBED_TOOLS.has(name) && typeof args.description === 'string'
+                ? preview(args.description)?.slice(0, MAX_PREVIEW_VALUE_CHARS)
+                : undefined;
+            return JSON.stringify(description ? { [key]: text, description } : { [key]: text });
         }
         // A headline-only tool with no headline shows nothing rather than its
         // whole input — that input is the file content this field exists to keep
@@ -410,6 +418,8 @@ const HEADLINE_FIELDS = {
     Task: ['description'],
     Agent: ['description'],
 };
+/** Tools whose input carries a human `description` of the call alongside the headline. */
+const DESCRIBED_TOOLS = new Set(['Bash', 'shell']);
 /** The text of a `tool_result` block — a string, or its `text` parts joined. */
 function toolResultText(content) {
     if (typeof content === 'string')

package/dist/agent/contract.d.ts

@@ -325,6 +325,8 @@ export interface AgentRunRequest {
     recent_messages?: RunMessage[];
     /** What the account remembers that bears on this run. Absent on older servers. */
     memories?: RunMemory[];
+    /** Selected records omitted whole by the server's inline context budget. */
+    memories_omitted?: number;
 }
 /** Reply destinations the server can bind a run to, including future surfaces. */
 export type ReplySurface = 'conversation' | 'task' | 'cleaning' | 'none' | (string & {});

package/dist/agent/contract.js

@@ -280,6 +280,11 @@ function parseMemory(entry) {
         return null;
     return { content, scope: str(entry.scope) };
 }
+function omittedMemoryCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+        ? value
+        : undefined;
+}
 /**
  * Extract the event body from a websocket frame's payload.
  *
@@ -368,5 +373,6 @@ export function parseRunRequest(data) {
         // CLI cannot be redeployed to follow.
         recent_messages: contextList(data.recent_messages ?? context.recent_messages, parseMessage),
         memories: contextList(data.memories ?? context.memories, parseMemory),
+        memories_omitted: omittedMemoryCount(data.memories_omitted ?? context.memories_omitted),
     };
 }

package/dist/agent/prompt.d.ts

@@ -30,6 +30,17 @@ export interface PromptContext {
      * to guess at it.
      */
     mcpToolPattern?: string;
+    /**
+     * The ProhostAI tools include the back-office read pair
+     * (`backoffice_describe_readonly_schema` → `backoffice_query_readonly`).
+     *
+     * Taken from the server's own `tools/list` for this key (see
+     * `capabilities.ts`), never assumed. It changes what the prompt says about
+     * the credential: an agent told its access is "deliberately narrow" refused
+     * or asked permission for exactly the cross-account reads these tools
+     * pre-authorize. Unset or false, the prompt is byte-for-byte what it was.
+     */
+    backofficeRead?: boolean;
     /**
      * Tools are behind permission prompts this run (`--safe-tools`).
      *

package/dist/agent/prompt.js

@@ -193,6 +193,9 @@ export function buildPrompt(run, context) {
     if (run.memories?.length) {
         lines.push('Things you remember (from earlier work in this workspace):', ...run.memories.map(renderMemory), '');
     }
+    if (run.memories_omitted) {
+        lines.push(`Incomplete memory recall: selected records omitted whole to fit the inline budget: ${run.memories_omitted}.`, 'If your tools and permissions allow, use full-memory reads or POST /v1/memories/search (memories:read) to recover relevant context. Check each result’s scope and target before applying it; exact recovery is not guaranteed. Omitted context is not evidence that no rule applies.', '');
+    }
     if (run.recent_messages?.length) {
         lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
     }
@@ -328,10 +331,13 @@ export function buildPrompt(run, context) {
         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 ' +
-            'look up instead of retrying it or answering as if you had.'
+            'way to look up workspace data, so use them rather than guessing. ' +
+            (context.backofficeRead
+                ? backofficeGuidance(Boolean(context.toolsGated))
+                : '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 ' +
+                    'look up instead of retrying it or answering as if you had.')
         : '- You have no ProhostAI tools in this run. Everything you know about this ' +
             'workspace is what is written above.', '');
     // Postability is a separate question from what the run is about: a task run
@@ -351,6 +357,29 @@ export function buildPrompt(run, context) {
         : 'stdout is recorded but not posted anywhere — act through your own tools.');
     return `${lines.join('\n')}\n`;
 }
+/**
+ * What replaces the "deliberately narrow" sentence for a back-office agent.
+ *
+ * Field-observed 2026-10-01: an internal support agent holding these tools
+ * answered "I couldn't read the workflow" and asked a human before a read-only
+ * query, because the only thing the prompt said about its access was that it
+ * was narrow. The read is pre-authorized, so the prompt says so — and keeps
+ * writes, customer-facing sends and personal data exactly as guarded as before.
+ */
+function backofficeGuidance(toolsGated) {
+    return ('You are a ProhostAI back-office agent: read-only cross-account investigation is ' +
+        'pre-authorized and expected. When a support or engineering question is about a ' +
+        'specific customer account, look before you answer — backoffice_describe_readonly_schema ' +
+        'for the tables, then backoffice_query_readonly filtered to that customer\'s account. ' +
+        'Never ask a human for permission to run a read-only query. ' +
+        (toolsGated
+            ? ''
+            : 'Read-only investigation tools on this machine — MCP servers your operator added, ' +
+                'CLIs such as `gh` — are usable for the same purpose. ') +
+        'Writes and anything sent to a customer still follow approval discipline. Keep personal ' +
+        'data and secrets out of your reply: summarize what you found, do not paste rows. If a ' +
+        'tool returns a permission error, that is a real limit — say what you could not look up.');
+}
 /**
  * Normalize an agent's stdout into a postable message.
  *

package/dist/agent/run.d.ts

@@ -26,6 +26,7 @@ import type { spawn } from 'node:child_process';
 import WebSocket from 'ws';
 import type { CommandRunner } from './accounts.js';
 import type { AgentCredentials } from './credentials.js';
+import type { RunCapabilities } from './capabilities.js';
 import type { QuotaProvider } from './runtime_status.js';
 /**
  * Default ceiling on one agent invocation: none.
@@ -144,6 +145,12 @@ export interface AgentRunOptions {
      * `codex login status`). Tests inject a fake so no real CLI is asked.
      */
     accountCommandRunner?: CommandRunner;
+    /**
+     * Asks what the paired credential can reach (see `capabilities.ts`).
+     * Defaults to a cached `tools/list` against the pairing's MCP endpoint; tests
+     * inject a fake so no extra request lands in their recorded calls.
+     */
+    capabilityProbe?: () => Promise<RunCapabilities>;
 }
 export interface AgentRunMetrics {
     connections: number;

package/dist/agent/run.js

@@ -38,6 +38,7 @@ import { ensureWorkspace, streamUrlFor, workspacePath } from './credentials.js';
 import { execAgent } from './exec.js';
 import { HeartbeatLoop } from './heartbeat.js';
 import { buildPrompt, replyFromStdout } from './prompt.js';
+import { NO_CAPABILITIES, capabilityProbe } from './capabilities.js';
 import { RunStore } from './runstore.js';
 import { RUNTIME_STATUS_FEATURE, RuntimeStatusReporter, claudeQuotaProvider, codexConfiguredModel, codexQuotaProvider, modelFromExec, parseVersion, readCodexObservation, } from './runtime_status.js';
 import { SessionStore, sessionKeyFor } from './sessionstore.js';
@@ -255,6 +256,7 @@ function buildRuntime(options, log) {
             brain,
             skipPermissions,
             prepareMcp: () => ({ mcpWired: false }),
+            capabilities: async () => NO_CAPABILITIES,
             runtimeName,
             observe,
             model,
@@ -336,6 +338,10 @@ function buildRuntime(options, log) {
         sessions,
         brain,
         prepareMcp: prepareWithAccount,
+        capabilities: options.capabilityProbe ??
+            (mcpUrl
+                ? capabilityProbe({ mcpUrl, apiKey: options.credentials.api_key, fetchImpl: options.fetchImpl })
+                : async () => NO_CAPABILITIES),
         skipPermissions,
         runtimeName,
         observe,
@@ -841,6 +847,8 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
     const surface = run.conversation_id ?? run.kind ?? 'no conversation';
     log(`${timestamp()} ▶ ${label} started (${surface})`);
     const mcp = runtime.prepareMcp();
+    // Only worth asking when the tools it describes are wired into this run.
+    const capabilities = mcp.mcpWired ? await runtime.capabilities() : NO_CAPABILITIES;
     const prompt = buildPrompt(run, {
         agentName: options.credentials.agent?.name ?? 'your agent',
         // Named only when the tools are actually reachable from this invocation.
@@ -852,6 +860,7 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // `plain` command is still told the server name only: we have no idea what
         // it is. See PromptContext.mcpToolPattern.
         mcpToolPattern: runtime.brain !== 'plain' && mcp.mcpWired ? MCP_TOOL_PATTERN : undefined,
+        backofficeRead: capabilities.backofficeRead,
         toolsGated: !runtime.skipPermissions,
         // The real numbers, not a vague "there is a limit" — see PromptContext.
         timeoutMs: options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.8.1";
+export declare const CLI_VERSION = "0.8.3";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.8.1";
+export declare const USER_AGENT = "prohost-cli/0.8.3";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.8.1';
+export const CLI_VERSION = '0.8.3';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",