@zhijiewang/openharness 2.19.0 → 2.21.0

package/dist/harness/hooks.js

@@ -10,6 +10,7 @@
  * - prompt: LLM yes/no check via provider.complete()
  */
 import { spawn, spawnSync } from "node:child_process";
+import { debug } from "../utils/debug.js";
 import { readOhConfig } from "./config.js";
 let cachedHooks;
 export function getHooks() {
@@ -22,6 +23,18 @@ export function getHooks() {
 /** Clear hook cache (call after config changes) */
 export function invalidateHookCache() {
     cachedHooks = undefined;
+    cachedDisableAllHooks = undefined;
+}
+let cachedDisableAllHooks;
+/**
+ * Whether the configured `disableAllHooks` kill switch is set.
+ * Cached so the per-emit cost is a single boolean read.
+ */
+export function areHooksEnabled() {
+    if (cachedDisableAllHooks === undefined) {
+        cachedDisableAllHooks = readOhConfig()?.disableAllHooks === true;
+    }
+    return !cachedDisableAllHooks;
 }
 function buildEnv(event, ctx) {
     const env = {
@@ -71,6 +84,12 @@ function buildEnv(event, ctx) {
         env.OH_TURN_NUMBER = ctx.turnNumber;
     if (ctx.turnReason !== undefined)
         env.OH_TURN_REASON = ctx.turnReason;
+    if (ctx.worktreePath !== undefined)
+        env.OH_WORKTREE_PATH = ctx.worktreePath;
+    if (ctx.worktreeParent !== undefined)
+        env.OH_WORKTREE_PARENT = ctx.worktreeParent;
+    if (ctx.worktreeForced !== undefined)
+        env.OH_WORKTREE_FORCED = ctx.worktreeForced;
     return env;
 }
 /**
@@ -400,10 +419,14 @@ async function executeHookDef(def, event, ctx) {
  * All other hooks run asynchronously to avoid blocking the event loop.
  */
 export function emitHook(event, ctx = {}) {
+    if (!areHooksEnabled())
+        return true;
     const hooks = getHooks();
     if (!hooks)
         return true;
     const defs = hooks[event] ?? [];
+    if (defs.length > 0)
+        debug("hooks", "fire", { event, count: defs.length, tool: ctx.toolName });
     const env = buildEnv(event, ctx);
     if (event === "preToolUse") {
         // preToolUse command hooks must be synchronous — they gate tool execution
@@ -456,6 +479,8 @@ export function emitHook(event, ctx = {}) {
  * Supports all hook types (command, HTTP, prompt).
  */
 export async function emitHookAsync(event, ctx = {}) {
+    if (!areHooksEnabled())
+        return true;
     const hooks = getHooks();
     if (!hooks)
         return true;
@@ -570,6 +595,8 @@ async function runHookForOutcome(def, event, ctx) {
  *   from hooks is ignored — outcome.allowed is always true. additionalContext is still collected.
  */
 export async function emitHookWithOutcome(event, ctx = {}) {
+    if (!areHooksEnabled())
+        return { allowed: true };
     const hooks = getHooks();
     const list = hooks?.[event];
     if (!list || list.length === 0)

package/dist/harness/rules.js

@@ -106,8 +106,24 @@ export function loadRulesAsPrompt(projectPath) {
     const rules = loadRules(projectPath);
     if (rules.length === 0)
         return "";
-    return ("# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
-        rules.join("\n\n---\n\n"));
+    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
+        rules.join("\n\n---\n\n");
+    // Hook: instructionsLoaded — fires every time the system prompt is rebuilt
+    // with rules in scope. Useful for compliance/audit hooks that want to log
+    // "session X is operating under these rules". Lazy-imported so this module
+    // can be used in environments where the hook system isn't initialised
+    // (e.g., one-shot rules loaders in tooling).
+    void import("./hooks.js")
+        .then(({ emitHook }) => {
+        emitHook("instructionsLoaded", {
+            rulesCount: String(rules.length),
+            rulesChars: String(body.length),
+        });
+    })
+        .catch(() => {
+        /* hook system unavailable — never fail rule loading */
+    });
+    return body;
 }
 export function createRulesFile(projectPath) {
     const root = projectPath ?? process.cwd();

package/dist/harness/submit-handler.js

@@ -6,7 +6,7 @@ import { processSlashCommand } from "../commands/index.js";
 import { cybergotchiEvents } from "../cybergotchi/events.js";
 import { resolveMcpMention } from "../mcp/loader.js";
 import { createInfoMessage, createUserMessage } from "../types/message.js";
-import { emitHookWithOutcome } from "./hooks.js";
+import { emitHook, emitHookWithOutcome } from "./hooks.js";
 /**
  * Process user input: handle exit, companion mentions, slash commands,
  * @mentions, and prepare the prompt for the LLM.
@@ -80,6 +80,19 @@ export async function handleUserInput(input, ctx) {
             if (result.prependToPrompt) {
                 messages = [...messages, createUserMessage(input)];
                 const prependPrompt = result.prependToPrompt;
+                // Slash command produced an expanded prompt — fire userPromptExpansion
+                // before userPromptSubmit so audit hooks can see the (input → expanded)
+                // boundary that's otherwise hidden from observers.
+                const slashCommand = trimmed.split(/\s/)[0] ?? trimmed;
+                emitHook("userPromptExpansion", {
+                    slashCommand,
+                    originalInput: input.slice(0, 1000),
+                    prompt: prependPrompt.slice(0, 1000),
+                    sessionId: ctx.sessionId,
+                    model: ctx.currentModel,
+                    provider: ctx.providerName,
+                    permissionMode: ctx.permissionMode,
+                });
                 const prependOutcome = await emitHookWithOutcome("userPromptSubmit", {
                     prompt: prependPrompt,
                     sessionId: ctx.sessionId,

package/dist/main.js

@@ -23,9 +23,10 @@ import { detectProject, projectContextToPrompt } from "./harness/onboarding.js";
 import { discoverSkills, skillsToPrompt } from "./harness/plugins.js";
 import { createRulesFile, loadRules, loadRulesAsPrompt } from "./harness/rules.js";
 import { listSessions } from "./harness/session.js";
-import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpTools } from "./mcp/loader.js";
+import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpPrompts, loadMcpTools, parseMcpConfigFile, } from "./mcp/loader.js";
 import { loadOutputStyle } from "./outputStyles/index.js";
 import { getAllTools } from "./tools.js";
+import { configureDebug, debug } from "./utils/debug.js";
 import { validateAgainstJsonSchema } from "./utils/json-schema.js";
 import { parseMaxBudgetUsd } from "./utils/parse-budget.js";
 const _require = createRequire(import.meta.url);
@@ -75,6 +76,40 @@ You have access to tools for reading, writing, and searching files, running shel
 - When referencing code, include file_path:line_number.
 - Do not restate what the user said. Do not add trailing summaries unless asked.
 - Keep responses short and direct. If you can say it in one sentence, don't use three.`;
+/**
+ * Read a system prompt from a file path, or exit 2 with a stderr message.
+ * Used by `--system-prompt-file` / `--append-system-prompt-file` so callers
+ * can keep prompts as version-controlled files instead of stuffing them on
+ * the command line. Trailing newline is stripped (most editors add one).
+ */
+function readSystemPromptFile(path, label) {
+    try {
+        return readFileSync(path, "utf8").replace(/\n$/, "");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${label} '${path}' could not be read: ${message}\n`);
+        process.exit(2);
+    }
+}
+/**
+ * Parse `--mcp-config <path>` (and the optional `--strict-mcp-config` flag)
+ * into a `LoadMcpOptions` shape ready to pass to `loadMcpTools`. Returns
+ * undefined when the user didn't pass `--mcp-config`. Exits 2 with a stderr
+ * message on parse / shape errors.
+ */
+function buildMcpLoadOpts(opts) {
+    if (!opts.mcpConfig)
+        return undefined;
+    try {
+        const extraServers = parseMcpConfigFile(opts.mcpConfig);
+        return { extraServers, strict: opts.strictMcpConfig === true };
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+}
 /**
  * Parse the `--max-budget-usd` CLI argument into a positive USD amount, or
  * exit 2 with an error message. The pure parser lives in
@@ -89,7 +124,19 @@ function parseMaxBudgetUsdOrExit(raw) {
     }
     return result.value;
 }
-function buildSystemPrompt(model) {
+/**
+ * Build the assembled system prompt for a session.
+ *
+ * In `bare` mode (audit A4 — `--bare`) every optional contributor is skipped:
+ * no project context, no rules, no user profile, no remembered memories, no
+ * skill catalog, no MCP server instructions, no language directive, no output
+ * style. The result is exactly `DEFAULT_SYSTEM_PROMPT`. Used for fast SDK /
+ * CI invocations where the model just needs the tool-use baseline and the
+ * caller will supply its own context.
+ */
+function buildSystemPrompt(model, opts = {}) {
+    if (opts.bare)
+        return DEFAULT_SYSTEM_PROMPT;
     const cfg = readOhConfig();
     // Output-style preface (first — sets personality for everything that follows).
     // Skipped silently for the "default" style (empty prompt).
@@ -146,13 +193,27 @@ program
     .addOption(new Option("--output-format <format>", "Output format").choices(["json", "text", "stream-json"]).default("text"))
     .option("--max-turns <n>", "Maximum turns", "20")
     .option("--system-prompt <prompt>", "Override the system prompt")
+    .option("--system-prompt-file <path>", "Read the system prompt from a file (overrides --system-prompt)")
     .option("--append-system-prompt <text>", "Append text to the system prompt")
+    .option("--append-system-prompt-file <path>", "Append the contents of a file to the system prompt")
     .option("--allowed-tools <tools>", "Comma-separated list of allowed tools")
     .option("--disallowed-tools <tools>", "Comma-separated list of disallowed tools")
     .option("--resume <id>", "Resume a saved session (replays its message history before this prompt)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (e.g. 'user,project,local'). Mirrors Claude Code's setting_sources.")
     .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. The agent halts with reason 'budget_exceeded' once totalCost reaches this amount. Mirrors Claude Code's --max-budget-usd.")
+    .option("--no-session-persistence", "Skip writing the session to disk under ~/.oh/sessions/. Useful for ephemeral CI runs that don't need resume.")
+    .option("--mcp-config <path>", 'Load MCP servers from a JSON file (in addition to .oh/config.yaml). File format: {"mcpServers": [...]} or a bare array.')
+    .option("--strict-mcp-config", "With --mcp-config, ignore .oh/config.yaml mcpServers — use only the file's servers.")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline. Useful for fast CI / SDK invocations.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
     .action(async (promptArg, opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh run", { bare, model: opts.model });
     // Read from stdin if prompt is "-" or omitted and stdin is not a TTY
     let prompt;
     if (!promptArg || promptArg === "-" || !process.stdin.isTTY) {
@@ -189,8 +250,14 @@ program
         overrides.baseUrl = savedConfig.baseUrl;
     const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
     const { query } = await import("./query.js");
-    // Tool filtering
-    let tools = getAllTools();
+    // Tool list = built-ins + MCP server tools (project config + --mcp-config).
+    // Previously oh run skipped MCP entirely, which silently broke the SDK
+    // `tools=[...]` feature (the SDK injects mcpServers into a temp config but
+    // the CLI never read it back). `--bare` opts back out — built-ins only.
+    const mcpLoadOpts = buildMcpLoadOpts(opts);
+    const mcpTools = bare ? [] : await loadMcpTools(mcpLoadOpts);
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
+    let tools = [...getAllTools(), ...mcpTools];
     if (opts.allowedTools) {
         const allowed = new Set(opts.allowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => allowed.has(t.name));
@@ -199,13 +266,22 @@ program
         const disallowed = new Set(opts.disallowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => !disallowed.has(t.name));
     }
-    // System prompt
+    process.on("exit", () => disconnectMcpClients());
+    // System prompt — file variants take precedence over inline string variants
+    // so callers can override-from-file without removing a stale --system-prompt
+    // they were previously passing.
     let systemPrompt;
-    if (opts.systemPrompt) {
+    if (opts.systemPromptFile) {
+        systemPrompt = readSystemPromptFile(opts.systemPromptFile, "--system-prompt-file");
+    }
+    else if (opts.systemPrompt) {
         systemPrompt = opts.systemPrompt;
     }
     else {
-        systemPrompt = buildSystemPrompt(model);
+        systemPrompt = buildSystemPrompt(model, { bare });
+    }
+    if (opts.appendSystemPromptFile) {
+        systemPrompt += `\n\n${readSystemPromptFile(opts.appendSystemPromptFile, "--append-system-prompt-file")}`;
     }
     if (opts.appendSystemPrompt) {
         systemPrompt += `\n\n${opts.appendSystemPrompt}`;
@@ -233,6 +309,8 @@ program
     // --resume <id> on a later run. Without this, every fresh `oh run` was
     // a programmatic dead-end for resumption (issue #60).
     const { createSession, loadSession, saveSession } = await import("./harness/session.js");
+    // Commander rewrites --no-session-persistence to opts.sessionPersistence === false.
+    const persistSession = opts.sessionPersistence !== false;
     let priorMessages;
     let sessionId;
     let sessionRecord;
@@ -250,7 +328,8 @@ program
     else {
         sessionRecord = createSession(provider.name, model);
         sessionId = sessionRecord.id;
-        saveSession(sessionRecord);
+        if (persistSession)
+            saveSession(sessionRecord);
     }
     if (outputFormat === "stream-json") {
         // Emit a session_start event so SDK callers can capture the id for
@@ -352,16 +431,18 @@ program
     // they're per-tool ephemerals; the assistant's final text is what
     // matters for context resumption. Mirrors the REPL's save-on-exit pattern
     // (src/components/REPL.tsx:120) but at one-shot scope.
-    try {
-        const { createUserMessage, createAssistantMessage } = await import("./types/message.js");
-        const newMessages = [...(priorMessages ?? []), createUserMessage(prompt)];
-        if (fullOutput)
-            newMessages.push(createAssistantMessage(fullOutput));
-        sessionRecord.messages = newMessages;
-        saveSession(sessionRecord);
-    }
-    catch {
-        /* persistence is best-effort — never fail the user's run on a save error */
+    if (persistSession) {
+        try {
+            const { createUserMessage, createAssistantMessage } = await import("./types/message.js");
+            const newMessages = [...(priorMessages ?? []), createUserMessage(prompt)];
+            if (fullOutput)
+                newMessages.push(createAssistantMessage(fullOutput));
+            sessionRecord.messages = newMessages;
+            saveSession(sessionRecord);
+        }
+        catch {
+            /* persistence is best-effort — never fail the user's run on a save error */
+        }
     }
 });
 // ── `oh session`: long-lived stateful session for the Python SDK ──
@@ -376,10 +457,25 @@ program
     .option("--disallowed-tools <tools>", "Comma-separated disallowed tool names")
     .option("--max-turns <n>", "Maximum turns per prompt", "20")
     .option("--system-prompt <prompt>", "Override the system prompt")
+    .option("--system-prompt-file <path>", "Read the system prompt from a file (overrides --system-prompt)")
+    .option("--append-system-prompt <text>", "Append text to the system prompt")
+    .option("--append-system-prompt-file <path>", "Append the contents of a file to the system prompt")
     .option("--resume <id>", "Resume a saved session (seeds the conversation with its prior message history)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (mirrors Claude Code's setting_sources).")
     .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. Each prompt's cost accumulates; the agent halts with reason 'budget_exceeded' once totalCost reaches this amount.")
+    .option("--no-session-persistence", "Skip writing the session to disk under ~/.oh/sessions/. Useful for ephemeral SDK clients that don't need resume.")
+    .option("--mcp-config <path>", 'Load MCP servers from a JSON file (in addition to .oh/config.yaml). File format: {"mcpServers": [...]} or a bare array.')
+    .option("--strict-mcp-config", "With --mcp-config, ignore .oh/config.yaml mcpServers — use only the file's servers.")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
     .action(async (opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh session", { bare, model: opts.model });
     const settingSources = parseSettingSources(opts.settingSources);
     const savedConfig = readOhConfig(undefined, settingSources);
     const permissionMode = (opts.permissionMode ??
@@ -395,7 +491,14 @@ program
     const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
     const { query } = await import("./query.js");
     const { createAssistantMessage, createToolResultMessage, createUserMessage } = await import("./types/message.js");
-    let tools = getAllTools();
+    // Tool list = built-ins + MCP server tools (project config + --mcp-config).
+    // Same fix as `oh run` — `oh session` previously skipped MCP entirely,
+    // which silently broke the SDK `tools=[...]` feature for stateful clients.
+    // `--bare` opts back out — built-ins only.
+    const mcpLoadOpts = buildMcpLoadOpts(opts);
+    const mcpTools = bare ? [] : await loadMcpTools(mcpLoadOpts);
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
+    let tools = [...getAllTools(), ...mcpTools];
     if (opts.allowedTools) {
         const allowed = new Set(opts.allowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => allowed.has(t.name));
@@ -404,7 +507,23 @@ program
         const disallowed = new Set(opts.disallowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => !disallowed.has(t.name));
     }
-    const systemPrompt = opts.systemPrompt ?? buildSystemPrompt(model);
+    process.on("exit", () => disconnectMcpClients());
+    let systemPrompt;
+    if (opts.systemPromptFile) {
+        systemPrompt = readSystemPromptFile(opts.systemPromptFile, "--system-prompt-file");
+    }
+    else if (opts.systemPrompt) {
+        systemPrompt = opts.systemPrompt;
+    }
+    else {
+        systemPrompt = buildSystemPrompt(model, { bare });
+    }
+    if (opts.appendSystemPromptFile) {
+        systemPrompt += `\n\n${readSystemPromptFile(opts.appendSystemPromptFile, "--append-system-prompt-file")}`;
+    }
+    if (opts.appendSystemPrompt) {
+        systemPrompt += `\n\n${opts.appendSystemPrompt}`;
+    }
     const config = {
         provider,
         tools,
@@ -420,6 +539,8 @@ program
     // event for later resume (issue #60).
     const conversation = [];
     const { createSession, loadSession, saveSession } = await import("./harness/session.js");
+    // Commander rewrites --no-session-persistence to opts.sessionPersistence === false.
+    const persistSession = opts.sessionPersistence !== false;
     let sessionId;
     let sessionRecord;
     if (opts.resume) {
@@ -436,7 +557,8 @@ program
     else {
         sessionRecord = createSession(provider.name, model);
         sessionId = sessionRecord.id;
-        saveSession(sessionRecord);
+        if (persistSession)
+            saveSession(sessionRecord);
     }
     let turnCounter = 0;
     // Will be set to the current prompt id before each turn so hook_decision
@@ -549,12 +671,15 @@ program
         }
         // Persist after every completed turn so a later --resume picks up the
         // history. Best-effort — a save failure shouldn't break the live session.
-        try {
-            sessionRecord.messages = conversation.slice();
-            saveSession(sessionRecord);
-        }
-        catch {
-            /* save errors don't propagate to the client */
+        // Skipped entirely when --no-session-persistence was passed.
+        if (persistSession) {
+            try {
+                sessionRecord.messages = conversation.slice();
+                saveSession(sessionRecord);
+            }
+            catch {
+                /* save errors don't propagate to the client */
+            }
         }
     }
 });
@@ -578,7 +703,16 @@ program
     .option("--json-schema <schema>", "Constrain output to match a JSON schema (headless mode)")
     .option("--input-format <format>", "Input format: text (default) or stream-json (NDJSON on stdin)")
     .option("--replay-user-messages", "Re-emit user messages on stdout (requires stream-json output)")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
     .action(async (opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh chat", { bare, model: opts.model, print: !!opts.print });
     // Load saved config as defaults (env vars + CLI flags override)
     const savedConfig = readOhConfig();
     const effectiveModel = opts.model ?? savedConfig?.model;
@@ -648,11 +782,31 @@ program
             process.exit(0);
         }
     }
-    const mcpTools = await loadMcpTools();
-    const mcpNames = connectedMcpServers();
-    if (mcpNames.length > 0) {
-        console.log(`[mcp] Connected: ${mcpNames.join(", ")}`);
+    // `--bare` skips MCP entirely (servers, prompts, instructions). The
+    // built-in tool set is still loaded — bare is about reducing optional
+    // startup work, not stripping the agent's tool surface.
+    const mcpTools = bare ? [] : await loadMcpTools();
+    if (!bare) {
+        const mcpNames = connectedMcpServers();
+        if (mcpNames.length > 0) {
+            console.log(`[mcp] Connected: ${mcpNames.join(", ")}`);
+        }
+        // Surface MCP-server prompts (`prompts/list`) as `/server:prompt` slash
+        // commands. Errors are swallowed inside loadMcpPrompts — servers that
+        // don't implement the prompts capability return [] without throwing.
+        try {
+            const { registerMcpPromptCommands } = await import("./commands/index.js");
+            const prompts = await loadMcpPrompts();
+            registerMcpPromptCommands(prompts);
+            if (prompts.length > 0) {
+                console.log(`[mcp] Prompts: ${prompts.map((p) => `/${p.qualifiedName}`).join(", ")}`);
+            }
+        }
+        catch {
+            /* prompt registration is best-effort; never block the REPL */
+        }
     }
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
     const tools = [...getAllTools(), ...mcpTools];
     process.on("exit", () => disconnectMcpClients());
     // Compute working directory and git branch
@@ -714,7 +868,7 @@ program
         const qConfig = {
             provider,
             tools,
-            systemPrompt: buildSystemPrompt(resolvedModel),
+            systemPrompt: buildSystemPrompt(resolvedModel, { bare }),
             permissionMode: effectivePermMode,
             maxTurns: 20,
             model: resolvedModel,

package/dist/mcp/client.d.ts

@@ -31,6 +31,29 @@ export declare class McpClient {
         description?: string;
     }>>;
     readResource(uri: string): Promise<string>;
+    /**
+     * List the prompts an MCP server exposes. Returns `[]` for servers that
+     * don't implement the `prompts/list` capability — this is a normal case
+     * (most non-prompt-aware MCP servers throw a method-not-found error).
+     *
+     * Each prompt may declare named arguments; surfaced via `arguments`.
+     */
+    listPrompts(): Promise<Array<{
+        name: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    }>>;
+    /**
+     * Get the rendered text of an MCP prompt. Server-side templates are
+     * applied with the supplied arguments. Multiple message turns are
+     * concatenated with double-newline separators — same shape OH uses for
+     * other prepended prompts.
+     */
+    getPrompt(name: string, args?: Record<string, string>): Promise<string>;
     callTool(name: string, args: Record<string, unknown>): Promise<string>;
     disconnect(): void;
 }

package/dist/mcp/client.js

@@ -91,6 +91,43 @@ export class McpClient {
             .map((c) => c.text)
             .join("\n");
     }
+    /**
+     * List the prompts an MCP server exposes. Returns `[]` for servers that
+     * don't implement the `prompts/list` capability — this is a normal case
+     * (most non-prompt-aware MCP servers throw a method-not-found error).
+     *
+     * Each prompt may declare named arguments; surfaced via `arguments`.
+     */
+    async listPrompts() {
+        try {
+            const res = await this.sdk.listPrompts();
+            return (res?.prompts ?? []);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get the rendered text of an MCP prompt. Server-side templates are
+     * applied with the supplied arguments. Multiple message turns are
+     * concatenated with double-newline separators — same shape OH uses for
+     * other prepended prompts.
+     */
+    async getPrompt(name, args = {}) {
+        const res = await this.sdk.getPrompt({ name, arguments: args });
+        const messages = (res?.messages ?? []);
+        const parts = [];
+        for (const m of messages) {
+            const content = m.content;
+            if (typeof content === "string") {
+                parts.push(content);
+            }
+            else if (content && content.type === "text" && typeof content.text === "string") {
+                parts.push(content.text);
+            }
+        }
+        return parts.join("\n\n");
+    }
     async callTool(name, args) {
         // Retry up to 2 times on transport-closed / timeout errors
         let lastErr = null;

package/dist/mcp/loader.d.ts

@@ -1,10 +1,57 @@
+import type { McpServerConfig } from "../harness/config.js";
 import type { Tool } from "../Tool.js";
-/** Load MCP tools from .oh/config.yaml mcpServers list. Returns empty array if none configured. */
-export declare function loadMcpTools(): Promise<Tool[]>;
+/**
+ * Parse a `--mcp-config <path>` file. Format:
+ *   - `{ "mcpServers": [...] }` — Claude Code convention (preferred)
+ *   - `[ ... ]` — bare array of server configs (also accepted)
+ *   - `{ "name": ..., ... }` — single-server object (also accepted)
+ *
+ * Validation is shape-only: each entry must be an object with a `name`.
+ * Connection-time validation happens in `McpClient.connect`. Throws on
+ * malformed JSON or unrecognised top-level shape.
+ */
+export declare function parseMcpConfigFile(path: string): McpServerConfig[];
+export interface LoadMcpOptions {
+    /**
+     * MCP servers loaded from sources outside `.oh/config.yaml` — typically
+     * a `--mcp-config <path>` file. Merged with the config-file servers
+     * unless `strict` is set, in which case these REPLACE the config-file
+     * servers entirely.
+     */
+    extraServers?: import("../harness/config.js").McpServerConfig[];
+    /**
+     * When `true`, ignore `cfg.mcpServers` and use only `extraServers`.
+     * No-op when `extraServers` is undefined (the config-file servers
+     * still load). Mirrors Claude Code's `--strict-mcp-config`.
+     */
+    strict?: boolean;
+}
+/** Load MCP tools from .oh/config.yaml mcpServers list (and/or `--mcp-config` overrides). Returns empty array if none configured. */
+export declare function loadMcpTools(opts?: LoadMcpOptions): Promise<Tool[]>;
 /** Disconnect all MCP clients (call on exit) */
 export declare function disconnectMcpClients(): void;
 /** Names of connected MCP servers */
 export declare function connectedMcpServers(): string[];
+export type McpPromptHandle = {
+    /** `<server>:<prompt>` qualified name — the slash command is `/<server>:<prompt>`. */
+    qualifiedName: string;
+    description: string;
+    /** List of named arguments the prompt template expects. */
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    /** Render the prompt with the supplied named arguments. */
+    render(args?: Record<string, string>): Promise<string>;
+};
+/**
+ * Enumerate prompts on every already-connected MCP server. Servers that don't
+ * implement the `prompts/list` capability return an empty list (handled
+ * inside `client.listPrompts`). Call AFTER `loadMcpTools()` so the client
+ * connections are warm.
+ */
+export declare function loadMcpPrompts(): Promise<McpPromptHandle[]>;
 /** Get MCP server instructions to inject into system prompt (sandboxed with origin markers) */
 export declare function getMcpInstructions(): string[];
 /** List all available resources across connected MCP servers */