@prohost/cli 0.1.0 → 0.2.0

package/dist/agent/claude.js

@@ -0,0 +1,336 @@
+/**
+ * The one place that knows anything about Claude Code specifically.
+ *
+ * `exec.ts` is deliberately agent-agnostic — prompt on stdin, reply on stdout,
+ * the lowest common denominator every CLI agent already speaks — and it stays
+ * that way. But that contract costs two things Claude Code can actually
+ * provide: 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. Both are fixed
+ * with flags, and flags are not portable. So the knowledge lives here, behind a
+ * detection function, and every other exec command keeps the exact behaviour it
+ * had before this module existed.
+ *
+ * Nothing in here 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. These are enhancements that must fail soft.
+ */
+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';
+/**
+ * What goes to `--allowedTools` so the ProhostAI tools are callable.
+ *
+ * Two spellings, comma-joined. `mcp__<server>` is the documented way to approve
+ * a whole MCP server and is the one expected to do the work; `mcp__<server>__*`
+ * is a pattern people write by analogy with `Bash(git *)`. Sending both costs
+ * a few bytes and removes an entire class of silent failure: an unapproved tool
+ * in print mode is not an error the agent reports, it is a tool the agent
+ * quietly never calls — and the visible symptom is an answer that sounds like
+ * the model just didn't feel like looking anything up.
+ *
+ * Comma-joined into ONE argument rather than passed as two, because
+ * `--allowedTools` is variadic (`<tools...>`) and would otherwise keep eating
+ * whatever followed it on the command line.
+ */
+export const MCP_ALLOWED_TOOLS = `mcp__${MCP_SERVER_NAME},mcp__${MCP_SERVER_NAME}__*`;
+/** Filename of the generated MCP config, inside `$PROHOST_HOME`. */
+export const MCP_CONFIG_FILENAME = 'mcp.json';
+/**
+ * Is this exec command Claude Code in print mode?
+ *
+ * A **heuristic**, and intentionally a narrow one: it matches when the first
+ * word of the command is `claude` (or a path ending in `/claude`) *and* the
+ * command asks for print mode. Both halves matter. The first because the whole
+ * point of `--exec` is that it takes an arbitrary command, and the second
+ * because `--output-format` is a print-mode flag — appending it to an
+ * interactive invocation would break a command that works today.
+ *
+ * Things this deliberately does **not** match: `env X=1 claude -p`,
+ * `npx claude -p`, a wrapper script that calls Claude Code internally,
+ * `sh -c 'claude -p'`. Each of those keeps the plain stdin/stdout behaviour —
+ * which is correct output, just without session continuity or MCP tools. The
+ * failure direction is what was chosen here: a missed detection costs features,
+ * while a false positive would append flags to somebody's shell script and
+ * break their agent outright.
+ *
+ * Nor does it match a command containing shell control operators, even one that
+ * starts with `claude`. Flags are appended to the *end* of the string, so for
+ * `claude -p | jq -r .result` they would land on `jq` — breaking a command that
+ * works today, which is precisely the outcome the narrowness is for.
+ */
+export function isClaudeExec(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 !== 'claude' && base !== 'claude.cmd' && base !== 'claude.exe')
+        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.
+ *
+ * `--dangerously-skip-permissions` is on by default, by explicit product
+ * decision: a paired brain is hired to *do* things, and in print mode there is
+ * nobody to approve a tool call — so without it the agent silently declines to
+ * act and the feature is a chat box. The trust model this assumes is stated
+ * plainly in the README: the brain runs as the host user with that user's full
+ * local permissions, on prompts written by workspace teammates. `--safe-tools`
+ * opts out for hosts who want prompt-gated behaviour instead.
+ *
+ * `--strict-mcp-config` is not optional decoration, and matters *more* under
+ * skipped permissions rather than less. Without it Claude Code merges the
+ * servers in the operator's own configuration with ours, so a run answering a
+ * customer's question would hold whatever MCP servers they use for their day
+ * job — with permission checks off. Ours is the only one this run is entitled
+ * to.
+ */
+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'];
+    if (skipPermissions)
+        parts.push('--dangerously-skip-permissions');
+    if (flags.sessionId)
+        parts.push('--resume', quote(flags.sessionId));
+    if (flags.mcpConfigPath) {
+        parts.push('--mcp-config', quote(flags.mcpConfigPath), '--strict-mcp-config');
+        // Redundant once permissions are bypassed — nothing is gated, so there is
+        // nothing to pre-approve. Kept for the `--safe-tools` path, where it is the
+        // only thing that makes the MCP tools callable at all: in print mode a tool
+        // awaiting approval is never called and the turn just succeeds more quietly.
+        if (!skipPermissions) {
+            // Last on the line on purpose: both this and `--mcp-config` are variadic,
+            // so anything appended after them would be swallowed as another value.
+            parts.push('--allowedTools', quote(MCP_ALLOWED_TOOLS));
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * Tool names the run wanted and was refused.
+ *
+ * Worth pulling out because a denial is otherwise invisible: in print mode
+ * there is nobody to approve anything, so a tool the agent is not allowed to
+ * call simply doesn't get called, the turn succeeds, and the reply reads like
+ * the model chose not to look something up. Logging the denial is what turns
+ * "the agent seems dumb" into "the agent asked for WebSearch and was refused".
+ */
+function denialNames(value) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    for (const entry of value) {
+        if (typeof entry === 'string')
+            names.push(entry);
+        else if (entry && typeof entry === 'object') {
+            const name = entry.tool_name;
+            if (typeof name === 'string' && name)
+                names.push(name);
+        }
+    }
+    return [...new Set(names)];
+}
+function asObject(candidate) {
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the result envelope in stdout.
+ *
+ * Normally stdout is exactly one JSON object and the first branch takes it.
+ * The line scan is for the case where something else got a word in first — a
+ * Node deprecation warning, a corporate-proxy notice, an npm banner. Those go
+ * to stderr *usually*, and "usually" is not good enough when the consequence is
+ * that every single run fails.
+ *
+ * The scan runs backwards and requires the object to look like a result
+ * envelope, so it can only ever match the thing we asked for. Anything it
+ * doesn't recognise still falls through to being reported as a failure, which
+ * is the safe direction: unparseable output must never be posted as a reply.
+ */
+function resultEnvelope(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    const whole = asObject(trimmed);
+    if (whole)
+        return whole;
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const candidate = asObject(lines[i].trim());
+        if (candidate && (candidate.type === 'result' || 'result' in candidate || 'is_error' in candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Read the reply and the session id out of `--output-format json` stdout.
+ *
+ * Unparseable output is a **failure**, not a fallback to posting the raw text.
+ * We asked for JSON; stdout that isn't JSON means something went wrong that we
+ * do not understand — a crash banner, a login prompt, an npm warning — and the
+ * one thing that must not happen is that being posted verbatim into a customer's
+ * conversation. Reporting the run failed is recoverable; sending a stack trace
+ * to a guest is not.
+ */
+export function parseClaudeOutput(stdout) {
+    const parsed = resultEnvelope(stdout);
+    if (!parsed) {
+        const sample = stdout.trim().slice(0, 200);
+        return {
+            denials: [],
+            ok: false,
+            error: sample
+                ? `claude did not return JSON (asked for --output-format json). First 200 chars: ${sample}`
+                : 'claude returned no output',
+        };
+    }
+    const sessionId = text(parsed.session_id);
+    const result = text(parsed.result);
+    const denials = denialNames(parsed.permission_denials);
+    // A run can fail while still exiting 0 — a hit turn limit, a refusal, an API
+    // error mid-turn — and the `result` field then holds the explanation rather
+    // than an answer. Posting that as the agent's reply would put "Error:
+    // exceeded max turns" in front of a customer.
+    if (parsed.is_error === true) {
+        return {
+            ok: false,
+            sessionId,
+            denials,
+            error: result ?? `claude reported an error (${String(parsed.subtype ?? 'unknown')})`,
+        };
+    }
+    if (!result) {
+        return { ok: false, sessionId, denials, error: 'claude returned JSON with no result text' };
+    }
+    return { ok: true, text: result, sessionId, denials };
+}
+/**
+ * Does this look like the resume having been rejected, rather than the agent
+ * having failed at its actual work?
+ *
+ * Sessions do not live forever: the transcript is on disk and gets cleaned up,
+ * and the ledger has no way to know. A stale entry must not turn into a
+ * permanently broken surface, so the caller retries once without `--resume`.
+ *
+ * The observed failure is exit 1, empty stdout, and
+ * `No conversation found with session ID: <uuid>` on stderr. Matching is
+ * broader than that string because the wording is not ours to depend on, and it
+ * is gated by the caller on the run having actually failed — so a *successful*
+ * run whose reply text happens to quote a session id is never mistaken for one.
+ */
+export function looksLikeResumeFailure(output, sessionId) {
+    if (!sessionId)
+        return false;
+    if (output.includes(sessionId))
+        return true;
+    return /no (conversation|session)[^\n]{0,40}found|session[^\n]{0,40}not found|--resume|resume[^\n]{0,20}(failed|invalid|expired)/i.test(output);
+}
+/** Absolute path of the generated MCP config. */
+export function mcpConfigPath(env = process.env) {
+    return path.join(prohostHome(env), MCP_CONFIG_FILENAME);
+}
+/**
+ * The config object handed to `--mcp-config`.
+ *
+ * Split out from the write so a test can assert on the shape without going near
+ * the filesystem, and so the header scheme is stated in exactly one place.
+ */
+export function buildMcpConfig(options) {
+    return {
+        mcpServers: {
+            [MCP_SERVER_NAME]: {
+                type: 'http',
+                // Verbatim, exactly as pairing reported it. An earlier revision appended
+                // a trailing slash on the theory that `/mcp` is a mounted sub-app and
+                // would 308 to `/mcp/`. That premise is false for this server:
+                // `api_public/main.py` registers a `_McpNoSlashDelegator` on the exact
+                // path `/mcp` *before* the mount, precisely so there is no redirect —
+                // because Claude Code's SDK drops the auth header across one. `/mcp` is
+                // also the form the public docs and `pairing_endpoints()` both use, so
+                // rewriting a server-supplied URL here buys nothing and risks diverging
+                // from wherever the server points next.
+                url: options.mcpUrl,
+                headers: {
+                    // `X-API-Key` and ONLY `X-API-Key`.
+                    //
+                    // The server accepts two credentials on this endpoint, and they are
+                    // not interchangeable: `Authorization: Bearer` is validated as an
+                    // **OAuth access token**, while `X-API-Key` is hashed and matched
+                    // against `AccountApiKey`. A pairing hands out the latter.
+                    //
+                    // Sending both would be worse than sending the wrong one. Both the
+                    // middleware (`api_public/middleware/mcp_auth.py`) and the tool layer
+                    // (`api_public/mcp/server.py::_resolve_auth_full`) check
+                    // `Authorization` **first** and do not fall through to `X-API-Key`
+                    // when it fails — so a `ph_live_…` key in the bearer slot is looked
+                    // up as an OAuth token, misses, and 401s the whole session while a
+                    // perfectly good API key sits in the next header down.
+                    'X-API-Key': options.apiKey,
+                },
+            },
+        },
+    };
+}
+/**
+ * Write the MCP config and return its path.
+ *
+ * The file holds a live API key, so it gets the same treatment as
+ * `agent.json`: `0600` inside a `0700` directory, written with the mode set at
+ * create time rather than chmod'ed afterwards — and chmod'ed anyway, because
+ * `writeFileSync`'s mode is masked by the umask and is ignored outright when
+ * the file already exists.
+ */
+export function writeMcpConfig(options) {
+    const env = options.env ?? process.env;
+    const dir = prohostHome(env);
+    const file = mcpConfigPath(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    writeFileSync(file, `${JSON.stringify(buildMcpConfig(options), null, 2)}\n`, { mode: 0o600 });
+    chmodSync(file, 0o600);
+    return file;
+}

package/dist/agent/command.js

@@ -4,26 +4,184 @@
  * Kept separate from the harness itself so `pair.ts` / `run.ts` stay callable
  * (and testable) as plain async functions with no argv or process concerns.
  */
+import { mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { agentLogPath, buildSystemdUnit, harnessArguments, installLaunchdDaemon, launchdLabel, uninstallLaunchdDaemon, } from './daemon.js';
 import { PairError, runPair } from './pair.js';
-import { CredentialsMissingError, loadCredentials } from './credentials.js';
+import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome } from './credentials.js';
 import { DEFAULT_EXEC_TIMEOUT_MS, runAgentHarness } from './run.js';
 function flagString(flags, name) {
     const value = flags[name];
     return typeof value === 'string' ? value : undefined;
 }
+/**
+ * Working directory the operator asked for, if any.
+ *
+ * ``--cwd`` is the 0.1.x spelling and still honoured — it is in the published
+ * README and in whatever scripts people wrote against it — but ``--workdir`` is
+ * the documented name now. The *default* when neither is given is the harness's
+ * to pick, not this function's: see {@link workspacePath}.
+ */
+function requestedWorkdir(flags) {
+    return flagString(flags, 'workdir') ?? flagString(flags, 'cwd');
+}
+/** Returned by {@link parseTimeoutSeconds} for a value that isn't a timeout. */
+const INVALID_TIMEOUT = Symbol('invalid-timeout');
+/**
+ * Read `--timeout`, complaining once for both commands that take it.
+ *
+ * Returns ``undefined`` when the flag was absent (the harness applies its own
+ * default) and {@link INVALID_TIMEOUT} after printing the error.
+ */
+function parseTimeoutSeconds(flags) {
+    const raw = flagString(flags, 'timeout');
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        process.stderr.write('--timeout must be a positive number of seconds.\n');
+        return INVALID_TIMEOUT;
+    }
+    return seconds;
+}
+/**
+ * Environment the daemon must be given explicitly.
+ *
+ * launchd starts a job with almost nothing — notably a minimal `PATH` of
+ * `/usr/bin:/bin:/usr/sbin:/sbin`, which contains no `claude`. Installed from
+ * npm, Homebrew, or the official installer it lives in `~/.local/bin`,
+ * `/opt/homebrew/bin`, or `/usr/local/bin`, so without this the daemon
+ * installs cleanly, reports success, and then crash-loops on
+ * `claude: command not found` in a log nobody is watching.
+ *
+ * The `PATH` captured is the one in effect when the operator ran
+ * `install-daemon` — i.e. the one in which their `--exec` command actually
+ * works. `PROHOST_HOME` is pinned for the same reason it is used for the label:
+ * a daemon must keep serving the home it was installed from, whatever the
+ * environment of a later login happens to say.
+ */
+function daemonEnvironment() {
+    const env = { PROHOST_HOME: prohostHome() };
+    if (process.env.PATH)
+        env.PATH = process.env.PATH;
+    return env;
+}
+/** Absolute path of this CLI's entrypoint, for a daemon to exec. */
+function cliEntrypoint() {
+    // Resolved from this module rather than from `process.argv[1]`, which under
+    // `npx`/`npm i -g` is a symlink in a bin directory. launchd does not care,
+    // but a plist naming a path that a later npm operation replaces would leave a
+    // daemon pointed at nothing.
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
+}
 /** Dispatch an ``agent`` subcommand. Returns the process exit code. */
 export async function runAgent(subcommand, flags, printHelp) {
     if (subcommand === 'pair')
         return pairCommand(flags);
     if (subcommand === 'run')
         return runCommand(flags);
+    if (subcommand === 'install-daemon')
+        return installDaemonCommand(flags);
+    if (subcommand === 'uninstall-daemon')
+        return uninstallDaemonCommand();
     process.stderr.write(subcommand
         ? `Unknown agent subcommand: ${subcommand}\n\n`
-        : 'Missing agent subcommand — expected `pair` or `run`.\n\n');
+        : 'Missing agent subcommand — expected `pair`, `run`, `install-daemon`, or `uninstall-daemon`.\n\n');
     printHelp();
     return 1;
 }
+/** Load credentials, reporting the "you haven't paired" case as an exit code. */
+function loadOrExplain() {
+    try {
+        return loadCredentials();
+    }
+    catch (err) {
+        if (err instanceof CredentialsMissingError) {
+            process.stderr.write(`✗ ${err.message}\n`);
+            return null;
+        }
+        throw err;
+    }
+}
+async function installDaemonCommand(flags) {
+    const exec = flagString(flags, 'exec');
+    if (!exec) {
+        process.stderr.write("Missing required flag: --exec. Example: prohost agent install-daemon --exec 'claude -p'\n");
+        return 1;
+    }
+    const credentials = loadOrExplain();
+    if (!credentials)
+        return 1;
+    // Validated here and not only in `agent run`, because the consequence differs:
+    // a bad --timeout typed at a terminal prints an error, while one baked into a
+    // plist makes every launch exit on that same validation and KeepAlive restart
+    // it forever.
+    const timeoutSeconds = parseTimeoutSeconds(flags);
+    if (timeoutSeconds === INVALID_TIMEOUT)
+        return 1;
+    // Absolute, and created now. A supervisor does not inherit the installing
+    // shell's current directory, so a relative `--workdir .` copied verbatim into
+    // the plist names a directory that either doesn't exist or isn't the one the
+    // operator meant — and launchd reports that as a job that won't start, long
+    // after this command said it succeeded.
+    const workdir = path.resolve(requestedWorkdir(flags) ?? ensureWorkspace());
+    try {
+        mkdirSync(workdir, { recursive: true });
+    }
+    catch (err) {
+        process.stderr.write(`✗ Cannot use ${workdir} as the working directory ` +
+            `(${err instanceof Error ? err.message : String(err)}).\n`);
+        return 1;
+    }
+    const invocation = {
+        execPath: process.execPath,
+        scriptPath: cliEntrypoint(),
+        exec,
+        workdir,
+        timeoutSeconds,
+        machine: flagString(flags, 'machine'),
+        url: flagString(flags, 'url'),
+        allowUnverified: flags['allow-unverified'] === true,
+        safeTools: flags['safe-tools'] === true || flags['no-skip-permissions'] === true,
+    };
+    const spec = {
+        label: launchdLabel(prohostHome()),
+        programArguments: harnessArguments(invocation),
+        workdir,
+        logPath: agentLogPath(),
+        env: daemonEnvironment(),
+    };
+    if (os.platform() !== 'darwin') {
+        // Unit name derived from the same per-home label as the macOS one. A fixed
+        // `prohost-agent.service` would have a second $PROHOST_HOME overwrite and
+        // restart the first agent's unit — the exact collision the per-home
+        // scoping exists to prevent.
+        process.stdout.write(`Automatic install is macOS-only. On Linux, save this as ` +
+            `~/.config/systemd/user/${spec.label}.service and run:\n` +
+            `  systemctl --user daemon-reload && systemctl --user enable --now ${spec.label}\n` +
+            '  loginctl enable-linger "$USER"   # so it survives logout\n\n' +
+            `${buildSystemdUnit(spec)}\n`);
+        return 0;
+    }
+    const result = installLaunchdDaemon(spec);
+    process.stdout.write(`${result.message}\n`);
+    return result.ok ? 0 : 1;
+}
+async function uninstallDaemonCommand() {
+    // Deliberately does not require credentials: the most likely reason to want
+    // this is that pairing was deleted or revoked and a daemon is still running.
+    const label = launchdLabel(prohostHome());
+    if (os.platform() !== 'darwin') {
+        process.stdout.write(`Automatic removal is macOS-only. On Linux:\n  systemctl --user disable --now ${label}\n`);
+        return 0;
+    }
+    const result = uninstallLaunchdDaemon(label);
+    process.stdout.write(`${result.message}\n`);
+    return result.ok ? 0 : 1;
+}
 async function pairCommand(flags) {
     const code = flagString(flags, 'code') ?? process.env.PROHOST_PAIRING_CODE;
     if (!code) {
@@ -53,23 +211,12 @@ async function runCommand(flags) {
         process.stderr.write("Missing required flag: --exec. Example: prohost agent run --exec 'claude -p'\n");
         return 1;
     }
-    let credentials;
-    try {
-        credentials = loadCredentials();
-    }
-    catch (err) {
-        if (err instanceof CredentialsMissingError) {
-            process.stderr.write(`✗ ${err.message}\n`);
-            return 1;
-        }
-        throw err;
-    }
-    const timeoutSeconds = flagString(flags, 'timeout');
-    const parsedTimeout = timeoutSeconds === undefined ? undefined : Number(timeoutSeconds);
-    if (parsedTimeout !== undefined && (!Number.isFinite(parsedTimeout) || parsedTimeout <= 0)) {
-        process.stderr.write('--timeout must be a positive number of seconds.\n');
+    const credentials = loadOrExplain();
+    if (!credentials)
+        return 1;
+    const parsedTimeout = parseTimeoutSeconds(flags);
+    if (parsedTimeout === INVALID_TIMEOUT)
         return 1;
-    }
     // First signal stops accepting work and lets the in-flight run finish
     // reporting itself (so the server doesn't wait on a run we abandoned); a
     // second one means the operator wants out now.
@@ -90,10 +237,13 @@ async function runCommand(flags) {
             credentials,
             url: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
             machine: flagString(flags, 'machine'),
-            cwd: flagString(flags, 'cwd'),
+            cwd: requestedWorkdir(flags),
             timeoutMs: parsedTimeout === undefined ? DEFAULT_EXEC_TIMEOUT_MS : parsedTimeout * 1000,
             dryRun: flags['dry-run'] === true,
             allowUnverified: flags['allow-unverified'] === true,
+            // Two spellings for the same opt-out: `--safe-tools` says what you get,
+            // `--no-skip-permissions` says what it turns off. Both were asked for.
+            safeTools: flags['safe-tools'] === true || flags['no-skip-permissions'] === true,
             signal: controller.signal,
         });
         process.stdout.write(`\nRuns: ${metrics.runsSucceeded} succeeded, ${metrics.runsFailed} failed, ` +

package/dist/agent/contract.d.ts

@@ -34,6 +34,38 @@ 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;
+/**
+ * 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.
+ */
+export interface RunMessage {
+    /** Display name of whoever wrote it. */
+    author?: string;
+    /** The writer's part in the thread — `user`, `agent`, `guest`, … */
+    role?: string;
+    /** ISO-8601 timestamp. */
+    at?: string;
+    text: string;
+}
+/** One memory the account has about this agent's work. */
+export interface RunMemory {
+    /** What the memory is scoped to — `account`, `listing`, `guest`, … */
+    scope?: string;
+    content: string;
+}
+/**
+ * Ceiling on how many context entries are kept from one payload.
+ *
+ * The server bounds these, but the prompt is written to a child process's
+ * stdin and the harness is the last thing standing between a pathological
+ * payload and an agent's context window. Entries past the limit are dropped
+ * from the *front*, because both lists are oldest-first and the recent end is
+ * the part worth spending prompt on.
+ */
+export declare const MAX_CONTEXT_ENTRIES = 50;
 /** The `agent.run_requested` payload, as far as the harness cares about it. */
 export interface AgentRunRequest {
     run_id: string;
@@ -57,10 +89,11 @@ export interface AgentRunRequest {
     trigger_entity_id?: string;
     /**
      * What the run is about, exactly as the server declared it. This is NOT the
-     * same question as "can the reply be posted": a task run is a task run even
-     * though the external API has no task-comment route yet, and the agent needs
-     * to be told that to answer sensibly. Postability is `reply_path` +
-     * `reply_body_key`.
+     * same question as "can the reply be posted": a task run is a task run
+     * whether or not the server gave it somewhere to post, and the agent needs to
+     * be told which it is to answer sensibly. Postability is `reply_path` +
+     * `reply_body_key`, both taken from the event — so a task surface gaining a
+     * real comment route server-side needs no change here.
      */
     reply_surface: ReplySurface;
     /** Server-supplied path to post the reply to. Absent when there is nowhere. */
@@ -72,8 +105,28 @@ export interface AgentRunRequest {
      * (`shared/comments/schemas.py`).
      */
     reply_body_key?: string;
+    /**
+     * Extra fields the server wants merged into the reply body alongside
+     * ``reply_body_key``. First use: ``{reply_to_message_id: "<uuid>"}`` so a
+     * team-chat reply lands in the right sub-thread instead of at the bottom of
+     * the channel.
+     *
+     * Deliberately opaque — the harness merges whatever it is given rather than
+     * knowing the keys, so the server can add threading, labelling or routing
+     * fields without a CLI release.
+     */
+    reply_body_extra?: Record<string, unknown>;
     /** Server-supplied path to complete the run at. */
     completion_path: string;
+    /**
+     * Earlier messages on this surface, oldest first. Absent on a server that
+     * predates the field — which is the case the harness shipped with, so an
+     * empty history has to keep meaning "answer from the trigger alone" rather
+     * than being treated as an error.
+     */
+    recent_messages?: RunMessage[];
+    /** What the account remembers that bears on this run. Absent on older servers. */
+    memories?: RunMemory[];
 }
 /** Reply destinations the server can bind a run to, including future surfaces. */
 export type ReplySurface = 'conversation' | 'task' | 'cleaning' | 'none' | (string & {});