@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/confinement.mjs

@@ -0,0 +1,196 @@
+// Claude Code's part of the shell tier's confinement probes (shell.mjs): a headless Claude Code with the evaluator's
+// guard hook runs every probe as a Bash call from a local scripted Anthropic endpoint, and reports what each returned.
+
+import { readFile, writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+
+import { baseProcessEnvironment } from "../../process.mjs";
+import { baseArguments, CLAUDE_CODE_ENVIRONMENT, settingsWithGuard } from "./launch.mjs";
+import { runClaudeOneShot } from "./session.mjs";
+
+// The stub answers every request, so no model is called; the name only keeps Claude Code on a model it knows.
+const PROBE_MODEL = "claude-haiku-5-5";
+
+function toolUseId(probe) {
+  return `toolu_probe_${probe.id.replaceAll("-", "_")}`;
+}
+
+/**
+ * Runs the probes through Claude Code. `guard` is the guard's environment for the probe workspace; `isolation` is
+ * the probe's prepared isolation, which carries no login.
+ *
+ * @returns {Promise<{observation: any, launchError: string | null, results: Map<string, {ran: boolean, isError: boolean, output: string}>}>}
+ */
+export async function probeClaudeShell({ probes, workspace, isolation, guard, eventsFile, stderrFile, signal }) {
+  const model = await startMessagesStub(probes);
+  try {
+    const settingsFile = path.join(isolation.evidence.root, "settings.json");
+    await writeFile(settingsFile, `${JSON.stringify(settingsWithGuard({}), null, 2)}\n`);
+    const args = [
+      ...baseArguments({ model: PROBE_MODEL, settingsFile }),
+      "--tools",
+      "Bash",
+      "--system-prompt",
+      "Run each confinement probe with Bash, exactly as given.",
+    ];
+    const noProxy = [process.env.NO_PROXY, "127.0.0.1", "localhost"].filter(Boolean).join(",");
+    const environment = {
+      ...baseProcessEnvironment(),
+      ...CLAUDE_CODE_ENVIRONMENT,
+      ...guard,
+      ...isolation.environment,
+      ANTHROPIC_API_KEY: "probe",
+      ANTHROPIC_BASE_URL: model.baseUrl,
+      NO_PROXY: noProxy,
+      no_proxy: noProxy,
+    };
+    let observation = null;
+    let launchError = null;
+    try {
+      observation = await runClaudeOneShot({
+        command: "claude",
+        args,
+        cwd: workspace,
+        eventsFile,
+        stderrFile,
+        signal,
+        prompts: ["Run the confinement probes."],
+        environment,
+      });
+    } catch (error) {
+      launchError = error instanceof Error ? error.message : String(error);
+    }
+    // Whatever Claude Code reported before a launch error still counts.
+    return { observation, launchError, results: await toolResults(eventsFile, probes) };
+  } finally {
+    await model.close();
+  }
+}
+
+function resultText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part?.type === "text")
+    .map((part) => part.text)
+    .join("");
+}
+
+/** Each probe's tool result from Claude Code's stream-json events, by probe ID. */
+async function toolResults(eventsFile, probes) {
+  const byToolUse = new Map(probes.map((probe) => [toolUseId(probe), probe.id]));
+  const results = new Map();
+  const contents = await readFile(eventsFile, "utf8").catch(() => "");
+  for (const line of contents.split("\n")) {
+    if (line.trim() === "") continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event.type !== "user" || !Array.isArray(event.message?.content)) continue;
+    for (const block of event.message.content) {
+      if (block?.type !== "tool_result" || !byToolUse.has(block.tool_use_id)) continue;
+      results.set(byToolUse.get(block.tool_use_id), {
+        ran: true,
+        isError: block.is_error === true,
+        output: resultText(block.content),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * A local Anthropic Messages endpoint that answers a request without tool results with every probe as a Bash
+ * tool call, and any request carrying tool results with a short final answer. No model is called.
+ */
+function startMessagesStub(probes) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((request, response) => {
+      let body = "";
+      request.setEncoding("utf8");
+      request.on("data", (chunk) => {
+        body += chunk;
+      });
+      request.on("end", () => {
+        if (request.method !== "POST" || !request.url.startsWith("/v1/messages")) {
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end("{}");
+          return;
+        }
+        let parsed = {};
+        try {
+          parsed = JSON.parse(body || "{}");
+        } catch {
+          // Answered as a first request.
+        }
+        if (request.url.includes("count_tokens")) {
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end(JSON.stringify({ input_tokens: 0 }));
+          return;
+        }
+        const followUp =
+          Array.isArray(parsed.messages) &&
+          parsed.messages.some(
+            (message) =>
+              Array.isArray(message?.content) && message.content.some((block) => block?.type === "tool_result"),
+          );
+        const content = followUp
+          ? [{ type: "text", text: "Probes finished." }]
+          : probes.map((probe) => ({
+              type: "tool_use",
+              id: toolUseId(probe),
+              name: "Bash",
+              input: { command: probe.command, description: probe.id },
+            }));
+        const stopReason = followUp ? "end_turn" : "tool_use";
+        const usage = { input_tokens: 0, output_tokens: 0 };
+        const message = {
+          id: "msg_probe",
+          type: "message",
+          role: "assistant",
+          model: parsed.model ?? PROBE_MODEL,
+          stop_sequence: null,
+        };
+        if (parsed.stream !== true) {
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end(JSON.stringify({ ...message, content, stop_reason: stopReason, usage }));
+          return;
+        }
+        response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+        const send = (type, data) => response.write(`event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`);
+        send("message_start", { message: { ...message, content: [], stop_reason: null, usage } });
+        for (const [index, block] of content.entries()) {
+          if (block.type === "text") {
+            send("content_block_start", { index, content_block: { type: "text", text: "" } });
+            send("content_block_delta", { index, delta: { type: "text_delta", text: block.text } });
+          } else {
+            send("content_block_start", { index, content_block: { ...block, input: {} } });
+            send("content_block_delta", {
+              index,
+              delta: { type: "input_json_delta", partial_json: JSON.stringify(block.input) },
+            });
+          }
+          send("content_block_stop", { index });
+        }
+        send("message_delta", { delta: { stop_reason: stopReason, stop_sequence: null }, usage: { output_tokens: 0 } });
+        send("message_stop", {});
+        response.end();
+      });
+    });
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      resolve({
+        baseUrl: `http://127.0.0.1:${server.address().port}`,
+        close: () =>
+          new Promise((done) => {
+            server.closeAllConnections?.();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/constraints.mjs

@@ -0,0 +1,111 @@
+// What a definition may ask of the Claude Code host, checked when it loads (definitions.mjs reads this file without
+// loading the adapter). Anything Claude Code cannot run the way the evaluator records it is refused here, with the
+// reason, rather than approximated at run time.
+
+/** The evaluator's tool names and the Claude Code built-in each one runs as. Claude Code has no separate ls. */
+export const CLAUDE_CODE_TOOLS = Object.freeze({
+  read: "Read",
+  write: "Write",
+  edit: "Edit",
+  ls: "Glob",
+  find: "Glob",
+  grep: "Grep",
+  bash: "Bash",
+});
+
+/** `model.thinking` values Claude Code accepts as `--effort`. */
+export const CLAUDE_CODE_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+
+// Settings that would replace the evaluator's guard, login, permissions or environment, or load something the
+// definition did not declare. A comparison changes them through the evaluator's own fields, or not at all.
+const REFUSED_SETTINGS = [
+  "hooks",
+  "disableAllHooks",
+  "permissions",
+  "env",
+  "apiKeyHelper",
+  "awsAuthRefresh",
+  "awsCredentialExport",
+  "otelHeadersHelper",
+  "forceLoginMethod",
+  "enabledPlugins",
+  "extraKnownMarketplaces",
+  "enableAllProjectMcpServers",
+  "enabledMcpjsonServers",
+  "statusLine",
+  "sandbox",
+];
+
+/**
+ * The Claude Code model name for a declared model: `anthropic/<name>` or a bare name. Throws for another provider,
+ * since Claude Code calls only Anthropic's API.
+ */
+export function claudeCodeModel(model) {
+  if (!model.includes("/")) return model;
+  const [provider, ...rest] = model.split("/");
+  if (provider !== "anthropic" || rest.length !== 1 || rest[0] === "") {
+    throw new Error(`Claude Code runs only Anthropic models (anthropic/<model>), not ${model}`);
+  }
+  return rest[0];
+}
+
+/** Problems with a host setup (model and settings) that is to run on Claude Code, or [] when there are none. */
+export function claudeCodeSetupProblems({ label, model, extensions = [], settings = {} }) {
+  const problems = [];
+  if (extensions.length > 0) problems.push(`${label}.host.extensions are Pi packages; Claude Code loads none`);
+  for (const key of REFUSED_SETTINGS) {
+    if (Object.hasOwn(settings, key)) problems.push(`${label}.host.settings cannot set ${key} on Claude Code`);
+  }
+  if (model !== undefined && model !== null) {
+    try {
+      claudeCodeModel(model.model);
+    } catch (error) {
+      problems.push(`${label}.model: ${error.message}`);
+    }
+    if (model.thinking !== undefined && !CLAUDE_CODE_EFFORTS.has(model.thinking)) {
+      problems.push(`${label}.model.thinking must be one of ${[...CLAUDE_CODE_EFFORTS].join(", ")} on Claude Code`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Problems with a group that runs its subjects on Claude Code, or [] when there are none: tools Claude Code has,
+ * a model for every arm, no Pi extensions, bash only in a container environment, and none of the features the
+ * adapter does not support yet (declared commands, runtime extension bundles, Freeflow).
+ */
+export function claudeCodeGroupProblems(group, configurations) {
+  const problems = [];
+  for (const tool of group.tools) {
+    if (!Object.hasOwn(CLAUDE_CODE_TOOLS, tool)) {
+      problems.push(
+        `group.tools ${tool} is not available on Claude Code (it has ${Object.keys(CLAUDE_CODE_TOOLS).join(", ")})`,
+      );
+    }
+  }
+  if (group.commands !== undefined) problems.push("group.commands are not supported on Claude Code yet");
+  for (const [arm, configuration] of Object.entries(configurations)) {
+    const label = `group.arms.${arm}`;
+    if (configuration.model === undefined) problems.push(`${label} needs a model on Claude Code`);
+    problems.push(
+      ...claudeCodeSetupProblems({
+        label,
+        model: configuration.model,
+        extensions: configuration.host.extensions,
+        settings: configuration.host.settings,
+      }),
+    );
+    if (configuration.shell !== undefined) {
+      problems.push(
+        `${label}.shell needs a Pi isolation extension; on Claude Code, bash runs in a container environment`,
+      );
+    }
+    if ((configuration.runtime?.extensions?.length ?? 0) > 0) {
+      problems.push(`${label}.runtime.extensions are Pi extensions; Claude Code loads none`);
+    }
+    if (configuration.freeflow !== undefined && configuration.freeflow !== null) {
+      problems.push(`${label}.freeflow is not supported on Claude Code yet`);
+    }
+  }
+  return problems;
+}

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/index.mjs

@@ -0,0 +1,48 @@
+// The Claude Code host adapter: subjects, judges and simulated users run in headless Claude Code (`claude -p`),
+// behind the interface in ../index.mjs. Logins come only from the evaluator's environment (isolation.mjs); what a
+// definition may ask of this host is in constraints.mjs.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { baseProcessEnvironment } from "../../process.mjs";
+import { probeClaudeShell } from "./confinement.mjs";
+import { prepareClaudeIsolation } from "./isolation.mjs";
+import { prepareClaudeLaunch } from "./launch.mjs";
+import { launchClaudeModel } from "./model-call.mjs";
+import { runClaudeOneShot, runClaudeSession } from "./session.mjs";
+
+const run = promisify(execFile);
+
+export const claudeCodeHost = Object.freeze({
+  name: "claude-code",
+  label: "Claude Code",
+  command: "claude",
+
+  /** The installed Claude Code's version: the first word `claude --version` prints, such as 2.1.296. */
+  async version(environment = baseProcessEnvironment()) {
+    const { stdout } = await run("claude", ["--version"], { env: environment, timeout: 30000 });
+    return stdout.trim().split(/\s+/)[0] ?? "";
+  },
+
+  /** Claude Code loads no Pi packages; definitions refuse them, so any reaching here is an error. */
+  async resolveExtensions(declared) {
+    if (declared.length > 0) throw new Error("Claude Code loads no host extensions");
+    return [];
+  },
+
+  /** Logins come from the environment and are never copied, so there is nothing to refresh. */
+  async refreshLogins() {},
+
+  /** No evaluator defaults are settings; Claude Code's switches are environment variables (launch.mjs). */
+  effectiveSettings: (declared = {}) => ({ ...declared }),
+  prepareIsolation: prepareClaudeIsolation,
+  /** No credential is ever written into the isolation, so nothing is removed. */
+  async removeCredentials() {},
+
+  prepareLaunch: prepareClaudeLaunch,
+  runOneShot: runClaudeOneShot,
+  runSession: runClaudeSession,
+  modelCall: launchClaudeModel,
+  probeShell: probeClaudeShell,
+});

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/isolation.mjs

@@ -0,0 +1,74 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+// Claude Code's login reaches a subject only through these variables, passed from the evaluator's own environment.
+// No credential file is copied: a refresh inside a copy would rotate the token there and revoke the user's own.
+// On a machine whose Claude Code login lives in the keychain, `claude setup-token` prints a token for
+// CLAUDE_CODE_OAUTH_TOKEN.
+export const LOGIN_VARIABLES = [
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_SESSION_INGRESS_TOKEN_FILE",
+];
+// Where the API is and how the machine reaches the network; passed when set, so a subject connects as the user does.
+const CONNECTION_VARIABLES = [
+  "ANTHROPIC_BASE_URL",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+];
+
+/**
+ * Creates a private home, temp and Claude Code configuration directory for one process, and the environment that
+ * points the process at them, with the login and connection variables of the evaluator's environment. A process
+ * with a model needs a login; the confinement probe, which answers from a local stub, runs with none.
+ *
+ * @param {string} directory where the isolation root is created
+ * @param {string | null} model the declared model, or null for a probe
+ * @param {{settings?: Record<string, unknown>}} [options]
+ * @returns {Promise<{environment: Record<string, string>, evidence: any, loginDirectory: string}>}
+ */
+export async function prepareClaudeIsolation(directory, model, { settings = {} } = {}) {
+  const root = path.join(directory, "isolation");
+  const home = path.join(root, "home");
+  const config = path.join(root, "config");
+  const tmp = path.join(root, "tmp");
+  for (const entry of [home, config, tmp]) await mkdir(entry, { recursive: true });
+
+  const login = model === null ? [] : LOGIN_VARIABLES.filter((name) => process.env[name]);
+  if (model !== null && login.length === 0) {
+    throw new Error(
+      `Claude Code needs a login in the evaluator's environment: set one of ${LOGIN_VARIABLES.join(", ")} (on a Mac, \`claude setup-token\` prints a token for CLAUDE_CODE_OAUTH_TOKEN)`,
+    );
+  }
+  const passed = [...login, ...CONNECTION_VARIABLES.filter((name) => process.env[name] !== undefined)];
+  return {
+    environment: {
+      HOME: home,
+      TMPDIR: tmp,
+      TMP: tmp,
+      TEMP: tmp,
+      XDG_CONFIG_HOME: path.join(home, ".config"),
+      XDG_DATA_HOME: path.join(home, ".local", "share"),
+      XDG_CACHE_HOME: path.join(home, ".cache"),
+      CLAUDE_CONFIG_DIR: config,
+      ...Object.fromEntries(passed.map((name) => [name, process.env[name]])),
+    },
+    // The names of the variables passed, never their values.
+    evidence: {
+      root,
+      provider: model === null ? null : "anthropic",
+      credentials: login.map((variable) => ({ variable })),
+      passed,
+      settings,
+    },
+    // Where the host keeps its configuration and any login file: the confinement probe plants a marker here.
+    loginDirectory: config,
+  };
+}

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/launch.mjs

@@ -0,0 +1,123 @@
+// How the evaluator launches Claude Code for a subject: headless (`claude -p`) with stream-json in and out, only the
+// declared tools, no settings, instructions, plugins' skills, MCP servers or slash commands from anywhere on the
+// machine, the evaluator's guard as a PreToolUse hook, and the system prompt the runtime's prompt mode asks for.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadDeclaredContext, renderDeclaredContext } from "../../../guard-rules.mjs";
+import { CLAUDE_CODE_TOOLS, claudeCodeModel } from "./constraints.mjs";
+import { readSkill, skillListing } from "./skills.mjs";
+
+const guardHook = fileURLToPath(new URL("../../../claude-guard.mjs", import.meta.url));
+
+// Claude Code switches every subject gets: no automatic compaction, no updater or nonessential traffic, and no
+// CLAUDE.md or memory, which the isolated config directory would not hold anyway. Retries stay at Claude Code's own
+// default, which the run records with the version.
+export const CLAUDE_CODE_ENVIRONMENT = Object.freeze({
+  DISABLE_AUTO_COMPACT: "1",
+  DISABLE_AUTOUPDATER: "1",
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+  CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
+});
+
+const TOOL_LINES = {
+  Read: "Read a file",
+  Write: "Create or overwrite a file",
+  Edit: "Replace exact text in a file",
+  Glob: "Find files by name pattern",
+  Grep: "Search file contents",
+  Bash: "Run a shell command",
+};
+
+/** The Claude Code built-ins a group's evaluator tools run as, in a stable order. */
+export function hostTools(tools) {
+  return [...new Set(tools.map((tool) => CLAUDE_CODE_TOOLS[tool]))];
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+/** The settings file every Claude Code process the evaluator starts reads: declared settings and the guard hook. */
+export function settingsWithGuard(settings) {
+  return {
+    ...settings,
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "*",
+          hooks: [{ type: "command", command: `${shellQuote(process.execPath)} ${shellQuote(guardHook)}` }],
+        },
+      ],
+    },
+  };
+}
+
+/** The headless arguments every Claude Code process shares; `--tools` and the prompt flags are the caller's. */
+export function baseArguments({ model, thinking = null, settingsFile, session = false }) {
+  const args = ["-p", "--verbose", "--output-format", "stream-json", "--input-format", "stream-json"];
+  args.push("--model", claudeCodeModel(model));
+  if (thinking !== null && thinking !== undefined) args.push("--effort", thinking);
+  args.push("--setting-sources", "", "--settings", settingsFile);
+  args.push("--strict-mcp-config", "--disable-slash-commands", "--permission-mode", "dontAsk");
+  if (!session) args.push("--no-session-persistence");
+  return args;
+}
+
+function isolatedPrompt(tools, listing, declaredContext, cwd) {
+  const lines = [
+    "You are an expert coding assistant operating inside Claude Code, a coding agent harness.",
+    "Help the user with the task using only the tools and resources listed below.",
+    "",
+    "Available tools:",
+    ...(tools.length > 0 ? tools.map((tool) => `- ${tool}: ${TOOL_LINES[tool]}`) : ["(none)"]),
+    "",
+    "Guidelines:",
+    "- Use Read to load a skill's SKILL.md when the task matches its description.",
+    "- Resolve relative skill resources from the skill directory.",
+    "- Be concise in your response.",
+  ];
+  if (listing !== "") lines.push("", listing);
+  if (declaredContext.length > 0) lines.push("", renderDeclaredContext(declaredContext));
+  lines.push(`Current working directory: ${cwd}`);
+  return lines.join("\n");
+}
+
+/**
+ * One subject's arguments and Claude Code's own variables. "isolated" replaces Claude Code's system prompt with the
+ * evaluator's; "host" keeps Claude Code's and appends the declared skills and context. Claude Code still adds its
+ * own identity line and an environment note to every request; the run's host-context record shows them.
+ */
+export async function prepareClaudeLaunch({ group, environment, runtime, model, workspace, isolation }) {
+  const directory = path.join(isolation.root, "launch");
+  await mkdir(directory, { recursive: true });
+  const settingsFile = path.join(directory, "settings.json");
+  await writeFile(settingsFile, `${JSON.stringify(settingsWithGuard(isolation.settings ?? {}), null, 2)}\n`);
+
+  const skills = [];
+  for (const skill of environment.skills) skills.push(await readSkill(skill.path));
+  const declaredContext = loadDeclaredContext(environment.contextDelivery.manifestPath);
+  const tools = hostTools(group.tools);
+  const listing = skillListing(skills);
+  const promptFile = path.join(directory, "system-prompt.md");
+  const isolated = runtime.prompt !== "host";
+  const appended = [listing, declaredContext.length > 0 ? renderDeclaredContext(declaredContext) : ""]
+    .filter(Boolean)
+    .join("\n\n");
+  if (isolated) await writeFile(promptFile, isolatedPrompt(tools, listing, declaredContext, workspace));
+  else if (appended !== "") await writeFile(promptFile, appended);
+
+  const args = baseArguments({
+    model: model.model,
+    thinking: model.thinking ?? null,
+    settingsFile,
+    session: runtime.session,
+  });
+  args.push("--tools", tools.join(","));
+  if (isolated) args.push("--system-prompt-file", promptFile);
+  else if (appended !== "") args.push("--append-system-prompt-file", promptFile);
+  return { args, environment: { ...CLAUDE_CODE_ENVIRONMENT } };
+}

package/skills/evaluate-behavior/scripts/lib/hosts/claude-code/model-call.mjs

@@ -0,0 +1,73 @@
+// One model call through Claude Code that is not a subject: a judge, a reviewer, or a simulated user. It runs
+// headless without tools, settings sources, MCP servers or slash commands, in its own isolated home and
+// configuration directory, with Claude Code's own system prompt (as a Pi judge has Pi's).
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { writeText } from "../../evidence.mjs";
+import { baseProcessEnvironment } from "../../process.mjs";
+import { prepareClaudeIsolation } from "./isolation.mjs";
+import { baseArguments, CLAUDE_CODE_ENVIRONMENT, settingsWithGuard } from "./launch.mjs";
+import { runClaudeOneShot } from "./session.mjs";
+
+/**
+ * Starts one model call on a prompt in its own directory, which keeps the prompt, events, final response and stderr.
+ *
+ * @param {string} directory replaced on every call
+ * @param {string} prompt
+ * @param {{model: string, thinking: string | null, settings: object, signal?: AbortSignal, role?: string}} options
+ * @returns {Promise<{response: string | null, errors: string[], usage: any, isolation: any}>}
+ */
+export async function launchClaudeModel(directory, prompt, options) {
+  const { model, thinking, settings = {}, signal, role = "reviewer" } = options;
+  await rm(directory, { recursive: true, force: true });
+  await mkdir(directory, { recursive: true });
+  await writeText(path.join(directory, "prompt.md"), prompt);
+
+  let isolation;
+  let args;
+  try {
+    isolation = await prepareClaudeIsolation(directory, model, { settings });
+    const settingsFile = path.join(isolation.evidence.root, "settings.json");
+    await writeFile(settingsFile, `${JSON.stringify(settingsWithGuard(settings), null, 2)}\n`);
+    args = [...baseArguments({ model, thinking, settingsFile }), "--tools", ""];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { response: null, errors: [message], usage: null, isolation: isolation?.evidence ?? null };
+  }
+  const observation = await runClaudeOneShot({
+    command: "claude",
+    args,
+    cwd: directory,
+    eventsFile: path.join(directory, "events.jsonl"),
+    stderrFile: path.join(directory, "stderr.log"),
+    signal,
+    prompts: [prompt],
+    environment: {
+      ...baseProcessEnvironment(),
+      PWD: directory,
+      ...CLAUDE_CODE_ENVIRONMENT,
+      // No tools, so the guard has nothing to allow; it still refuses anything Claude Code would try.
+      SKILL_EVAL_ALLOWED_ROOTS: JSON.stringify([directory]),
+      SKILL_EVAL_WRITABLE_ROOT: directory,
+      SKILL_EVAL_ALLOWED_TOOLS: "[]",
+      ...isolation.environment,
+    },
+  });
+  await writeText(path.join(directory, "final.md"), `${observation.response}\n`);
+
+  const errors = [];
+  if (
+    observation.exitCode !== 0 ||
+    !observation.settled ||
+    observation.assistantError !== null ||
+    observation.protocolErrors.length > 0
+  ) {
+    const protocol = observation.protocolErrors.map((error) => error.reason).join(",") || "none";
+    errors.push(
+      `${role} did not complete: exit=${observation.exitCode} settled=${observation.settled} error=${observation.assistantError} protocol=${protocol}`,
+    );
+  }
+  return { response: observation.response, errors, usage: observation.usage, isolation: isolation.evidence };
+}