aos-harness 0.5.2 → 0.7.0-rc.2

package/README.md

@@ -2,26 +2,36 @@
 
 **Agentic Orchestration System** — Assemble specialized AI agents into deliberation and execution teams.
 
+> **Breaking change in 0.6.0:** `aos-harness` no longer bundles adapter code. You must install the adapter(s) for the AI CLI(s) you want to use as separate packages. If you upgrade from 0.5.x and run `aos run` without the matching `@aos-harness/<name>-adapter` installed, the CLI will print an install hint and exit. See [CHANGELOG](../CHANGELOG.md#060) for the full migration note.
+
 ## Prerequisites
 
 - [Bun](https://bun.sh) 1.0+
 
-## Install
+## Getting Started
+
+### 1. Install the CLI
 
 ```bash
-bun add -g aos-harness
+npm i -g aos-harness
+# or: bun add -g aos-harness
 ```
 
-Or run directly:
+### 2. Install an adapter
+
+Pick the AI CLI you'll drive agents with and install the matching adapter. You can install more than one. Versions are lockstep — pin the adapter to the same version as the CLI.
 
 ```bash
-bunx aos-harness init
+npm i -g @aos-harness/claude-code-adapter   # Anthropic's Claude Code
+npm i -g @aos-harness/gemini-adapter         # Google's Gemini CLI
+npm i -g @aos-harness/codex-adapter          # OpenAI's Codex CLI
+npm i -g @aos-harness/pi-adapter             # Pi (pi-ai) — direct model SDK
 ```
 
-## Quick Start
+### 3. Initialize and run
 
 ```bash
-# Initialize a project
+# Initialize a project (writes .aos/ and copies core/ into the project)
 aos init
 
 # Run a strategic deliberation
@@ -41,6 +51,15 @@ aos create profile my-review
 aos validate
 ```
 
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Uncaught runtime error |
+| 2 | Invalid input (unknown adapter, bad path, bad URL, missing adapter package) |
+| 3 | Profile tool-policy error (malformed `tools:` block, flag cannot widen profile) |
+
 ## What It Does
 
 AOS Harness orchestrates multiple AI agents with distinct cognitive biases into structured deliberation and execution sessions:

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "aos-harness",
-  "version": "0.5.2",
+  "version": "0.7.0-rc.2",
   "description": "Agentic Orchestration System — assemble AI agents into deliberation and execution teams",
   "license": "MIT",
+  "publishConfig": { "access": "public" },
   "repository": {
     "type": "git",
     "url": "https://github.com/aos-engineer/aos-harness.git"
@@ -23,12 +24,11 @@
     "aos": "./src/index.ts"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.11"
   },
   "files": [
     "src/",
     "core/",
-    "adapters/",
     "README.md"
   ],
   "scripts": {
@@ -36,11 +36,23 @@
     "test": "bun run src/index.ts validate"
   },
   "dependencies": {
-    "@aos-harness/adapter-shared": "0.5.2",
-    "@aos-harness/runtime": "0.5.2",
+    "@aos-harness/adapter-shared": "0.7.0-rc.2",
+    "@aos-harness/runtime": "0.7.0-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0"
   },
+  "peerDependencies": {
+    "@aos-harness/claude-code-adapter": ">=0.6.0 <1.0.0",
+    "@aos-harness/codex-adapter": ">=0.6.0 <1.0.0",
+    "@aos-harness/gemini-adapter": ">=0.6.0 <1.0.0",
+    "@aos-harness/pi-adapter": ">=0.6.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aos-harness/claude-code-adapter": { "optional": true },
+    "@aos-harness/codex-adapter": { "optional": true },
+    "@aos-harness/gemini-adapter": { "optional": true },
+    "@aos-harness/pi-adapter": { "optional": true }
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "typescript": "^5.4.0"

package/src/adapter-config.ts

@@ -12,5 +12,5 @@ export interface AdapterConfig {
 export function readAdapterConfig(root: string): AdapterConfig | null {
   const p = join(root, ".aos", "adapter.yaml");
   if (!existsSync(p)) return null;
-  return yaml.load(readFileSync(p, "utf-8")) as AdapterConfig;
+  return yaml.load(readFileSync(p, "utf-8"), { schema: yaml.JSON_SCHEMA }) as AdapterConfig;
 }

package/src/adapter-session.ts

@@ -15,7 +15,7 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import readline from "node:readline";
 import {
   BaseEventBus,
@@ -24,6 +24,7 @@ import {
   composeAdapter,
   discoverAgents,
   createFlatAgentsDir,
+  type ToolPolicy,
 } from "@aos-harness/adapter-shared";
 import { AOSEngine } from "@aos-harness/runtime";
 import { loadAgent } from "@aos-harness/runtime/config-loader";
@@ -43,6 +44,18 @@ export interface AdapterSessionConfig {
   workflowConfig: any | null;
   workflowsDir: string;
   modelOverrides?: Partial<Record<string, string>>;
+  /**
+   * Tool policy resolved by the CLI from the profile's `tools:` block narrowed
+   * (optionally) by the `--allow-code-execution` flag. Passed straight into
+   * BaseWorkflow to gate tool access during the session (spec D3).
+   */
+  toolPolicy?: ToolPolicy;
+  /**
+   * Path where BaseWorkflow should append tool-decision audit events
+   * (one JSON object per line). Defaults to `<deliberationDir>/transcript.jsonl`
+   * when omitted.
+   */
+  transcriptPath?: string;
 }
 
 const ADAPTER_MAP: Record<string, { package: string; className: string }> = {
@@ -60,8 +73,8 @@ const ADAPTER_MAP: Record<string, { package: string; className: string }> = {
   },
 };
 
-// CLI version read once at module load, used in the 0.6.0 deprecation
-// warning so the suggested install command pins to the matching version.
+// CLI version read once at module load, used in the missing-adapter
+// install hint and the version-mismatch warning.
 function readCliVersion(): string {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -73,39 +86,64 @@ function readCliVersion(): string {
 }
 const CLI_VERSION = readCliVersion();
 
-// Session-level dedup for the deprecation warning. If the process uses
-// multiple adapters, we still only warn once per run.
-let deprecationWarnedThisSession = false;
+// Classify an error from a dynamic import() as "package not installed".
+// Bun 1.3.11 throws ResolveMessage with code=ERR_MODULE_NOT_FOUND. Older
+// Bun/Node and edge cases are caught by constructor-name and message-regex
+// fallbacks. Anything that doesn't match these patterns is a real error
+// (syntax error, missing transitive dep, etc.) and must surface with its
+// original stack — never swallowed as "not installed".
+function isModuleNotFound(err: any): boolean {
+  if (err?.code === "ERR_MODULE_NOT_FOUND") return true;
+  if (err?.code === "MODULE_NOT_FOUND") return true;
+  if (err?.constructor?.name === "ResolveMessage") return true;
+  const msg = typeof err?.message === "string" ? err.message : "";
+  return /Cannot find (module|package)/i.test(msg);
+}
 
-function maybeWarnAdapterDeprecation(pkg: string, projectRoot: string): void {
-  if (deprecationWarnedThisSession) return;
-  const flagPath = join(projectRoot, ".aos", "migration-warned-0.6");
-  if (existsSync(flagPath)) return;
-  deprecationWarnedThisSession = true;
+function printMissingAdapterError(pkg: string): void {
+  const useColor = !!process.stderr.isTTY;
+  const red = useColor ? "\x1b[31m" : "";
+  const bold = useColor ? "\x1b[1m" : "";
+  const reset = useColor ? "\x1b[0m" : "";
+  console.error(
+    `\n${red}${bold}✗ Adapter not installed: ${pkg}${reset}\n\n` +
+      `Install it:\n` +
+      `  npm i -g ${pkg}    # if aos-harness is installed globally\n` +
+      `  npm i    ${pkg}    # if aos-harness is a project dependency\n\n` +
+      `(or use bun / pnpm / yarn equivalents)\n\n` +
+      `CLI version: aos-harness@${CLI_VERSION}. Pin the adapter to the same version.\n`,
+  );
+}
 
+// Compare CLI and adapter versions. Under pre-1.0 lockstep, any minor or
+// major drift is a warning — patch drift is silent (expected during
+// quick-turnaround publishes).
+function versionMismatchSeverity(cliVer: string, adapterVer: string): "none" | "warn" {
+  const [cliMaj, cliMin] = cliVer.split(".").map(Number);
+  const [adaMaj, adaMin] = adapterVer.split(".").map(Number);
+  if (Number.isNaN(cliMaj) || Number.isNaN(adaMaj)) return "none";
+  if (cliMaj !== adaMaj) return "warn";
+  if (cliMin !== adaMin) return "warn";
+  return "none";
+}
+
+const mismatchWarnedPackages = new Set<string>();
+
+function maybeWarnVersionMismatch(pkg: string, adapterVer: string): void {
+  if (mismatchWarnedPackages.has(pkg)) return;
+  if (versionMismatchSeverity(CLI_VERSION, adapterVer) !== "warn") return;
+  mismatchWarnedPackages.add(pkg);
   const useColor = !!process.stderr.isTTY;
   const y = useColor ? "\x1b[33m" : "";
-  const b = useColor ? "\x1b[1m" : "";
   const r = useColor ? "\x1b[0m" : "";
-
   console.error(
-    `\n${y}${b}⚠ Deprecation: bundled adapters will be removed in aos-harness@0.6.0.${r}\n` +
-      `  This project is using the bundled copy of ${pkg}.\n` +
-      `  Install the standalone package to silence this warning and prepare for 0.6.0:\n\n` +
-      `    npm i -g ${pkg}@${CLI_VERSION}\n` +
-      `    # or in a project:  npm i ${pkg}@${CLI_VERSION}\n\n` +
-      `  This warning appears once per project. Delete .aos/migration-warned-0.6 to re-enable.\n`,
+    `\n${y}⚠ Version mismatch: aos-harness@${CLI_VERSION} and ${pkg}@${adapterVer}${r}\n` +
+      `  Adapters are published lockstep with the CLI. Install matching versions:\n` +
+      `  npm i -g ${pkg}@${CLI_VERSION}\n`,
   );
-
-  try {
-    mkdirSync(dirname(flagPath), { recursive: true });
-    writeFileSync(flagPath, new Date().toISOString() + "\n");
-  } catch {
-    // non-fatal — if we can't write the flag, the warning just repeats next run.
-  }
 }
 
-async function loadAdapterRuntime(platform: string, projectRoot: string): Promise<any> {
+async function loadAdapterRuntime(platform: string): Promise<any> {
   const entry = ADAPTER_MAP[platform];
   if (!entry) throw new Error(`Unknown adapter: ${platform}`);
 
@@ -120,21 +158,21 @@ async function loadAdapterRuntime(platform: string, projectRoot: string): Promis
     }
   }
 
+  let mod: any;
   try {
-    const mod = await import(entry.package);
-    const resolved = (import.meta as any).resolve?.(entry.package) ?? entry.package;
-    const version = await readAdapterVersion(resolved);
-    console.error(`[adapter] loaded ${entry.package}@${version} (standalone)`);
-    return mod[entry.className];
-  } catch {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const fallback = join(here, "..", "..", "adapters", platform, "src", "index.ts");
-    const mod = await import(fallback);
-    const version = await readAdapterVersion(`file://${fallback}`);
-    console.error(`[adapter] loaded ${entry.package}@${version} (bundled: ${fallback})`);
-    maybeWarnAdapterDeprecation(entry.package, projectRoot);
-    return mod[entry.className];
+    mod = await import(entry.package);
+  } catch (err) {
+    if (isModuleNotFound(err)) {
+      printMissingAdapterError(entry.package);
+      process.exit(2);
+    }
+    throw err; // real load error — surface it
   }
+  const resolved = (import.meta as any).resolve?.(entry.package) ?? entry.package;
+  const version = await readAdapterVersion(resolved);
+  console.error(`[adapter] loaded ${entry.package}@${version}`);
+  maybeWarnVersionMismatch(entry.package, version);
+  return mod[entry.className];
 }
 
 function toolNamesForPlatform(platform: string): { delegate: string; end: string } {
@@ -150,13 +188,17 @@ export async function runAdapterSession(config: AdapterSessionConfig): Promise<v
   };
 
   log("loading adapter runtime");
-  const RuntimeClass = await loadAdapterRuntime(config.platform, config.root);
+  const RuntimeClass = await loadAdapterRuntime(config.platform);
 
   // ── Layer composition ──────────────────────────────────────
   const eventBus = new BaseEventBus();
   const agentRuntime = new RuntimeClass(eventBus, config.modelOverrides);
   const ui = new TerminalUI();
-  const workflow = new BaseWorkflow(agentRuntime, config.root);
+  const workflow = new BaseWorkflow(agentRuntime, config.root, {
+    toolPolicy: config.toolPolicy,
+    transcriptPath:
+      config.transcriptPath ?? join(config.deliberationDir, "transcript.jsonl"),
+  });
   const adapter = composeAdapter(agentRuntime, eventBus, ui, workflow);
   log("layers composed");
 

package/src/colors.ts

@@ -28,7 +28,16 @@ export function parseArgs(argv: string[]): ParsedArgs {
   while (i < args.length) {
     const arg = args[i];
     if (arg.startsWith("--")) {
-      const key = arg.slice(2);
+      const body = arg.slice(2);
+      // Support --key=value (inline) as well as --key value (separate arg).
+      const eq = body.indexOf("=");
+      if (eq !== -1) {
+        const key = body.slice(0, eq);
+        flags[key] = body.slice(eq + 1);
+        i += 1;
+        continue;
+      }
+      const key = body;
       const next = args[i + 1];
       if (next && !next.startsWith("--")) {
         flags[key] = next;

package/src/commands/create.ts

@@ -377,6 +377,11 @@ export async function createCommand(args: ParsedArgs): Promise<void> {
   }
 
   const id = toKebabCase(name);
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+    console.error(c.red(`Invalid name "${name}": must kebab-case to /^[a-z0-9][a-z0-9-]*$/`));
+    console.error(c.dim(`Allowed characters: a-z, 0-9, hyphen. Must start with a letter or digit.`));
+    process.exit(2);
+  }
   const displayName = id
     .split("-")
     .map((w) => w.charAt(0).toUpperCase() + w.slice(1))

package/src/commands/init.ts

@@ -2,10 +2,21 @@
  * aos init — Initialize AOS configuration in the current project.
  */
 
-import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { c, type ParsedArgs } from "../colors";
-import { getHarnessRoot, getPackageCoreDir } from "../utils";
+import { ADAPTER_ALLOWLIST, getHarnessRoot, getPackageCoreDir, isValidAdapter } from "../utils";
+
+function readCliVersion(): string {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const raw = readFileSync(join(here, "..", "..", "package.json"), "utf-8");
+    return (JSON.parse(raw) as { version: string }).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 
 const HELP = `
 ${c.bold("aos init")} — Initialize AOS in the current project
@@ -14,7 +25,7 @@ ${c.bold("USAGE")}
   aos init [--adapter <adapter>] [--force]
 
 ${c.bold("OPTIONS")}
-  --adapter <name>    Adapter to use: pi (default), claude-code, gemini
+  --adapter <name>    Adapter to use: pi (default), claude-code, gemini, codex
   --force             Reinitialize even if AOS is already set up (overwrites existing core configs)
 
 ${c.bold("DESCRIPTION")}
@@ -27,8 +38,6 @@ ${c.bold("EXAMPLES")}
   aos init --adapter claude-code
 `;
 
-const VALID_ADAPTERS = ["pi", "claude-code", "gemini"];
-
 function generateConfig(adapter: string): string {
   return `# AOS Harness Configuration
 # Generated by: aos init
@@ -53,8 +62,8 @@ export async function initCommand(args: ParsedArgs): Promise<void> {
 
   const adapter = (args.flags.adapter as string) || "pi";
 
-  if (!VALID_ADAPTERS.includes(adapter)) {
-    console.error(c.red(`Invalid adapter: "${adapter}". Valid adapters: ${VALID_ADAPTERS.join(", ")}`));
+  if (!isValidAdapter(adapter)) {
+    console.error(c.red(`Invalid adapter: "${adapter}". Valid adapters: ${ADAPTER_ALLOWLIST.join(", ")}`));
     process.exit(1);
   }
 
@@ -156,4 +165,18 @@ ${c.bold("Customization")}
   Create domain packs:    ${c.cyan("aos create domain <name>")}
   Validate everything:    ${c.cyan("aos validate")}
 `);
+
+  // Adapter-install guidance. Starting in 0.6.0 the CLI no longer bundles
+  // adapter source — users must install the adapter(s) they want to use.
+  const v = readCliVersion();
+  console.log(`${c.bold("Next step: install an adapter")}
+  Adapters live as separate npm packages. Install the one(s) you'll use:
+
+    Claude Code:   ${c.cyan(`npm i -g @aos-harness/claude-code-adapter@${v}`)}
+    Gemini CLI:    ${c.cyan(`npm i -g @aos-harness/gemini-adapter@${v}`)}
+    Codex CLI:     ${c.cyan(`npm i -g @aos-harness/codex-adapter@${v}`)}
+    Pi (pi-ai):    ${c.cyan(`npm i -g @aos-harness/pi-adapter@${v}`)}
+
+  ${c.dim("Pick one (or more). Then run `aos run`.")}
+`);
 }

package/src/commands/replay.ts

@@ -169,6 +169,8 @@ export async function replayCommand(args: ParsedArgs): Promise<void> {
     process.exit(1);
   }
 
+  // Direct CLI arg — not passed through confinedResolve (spec D4: user is trusted
+  // at the CLI boundary). If this ever becomes config-driven, use confinedResolve.
   const resolved = filePath.startsWith("/") ? filePath : resolve(process.cwd(), filePath);
   if (!existsSync(resolved)) {
     console.error(c.red(`Transcript file not found: ${resolved}`));

package/src/commands/run.ts

@@ -5,10 +5,11 @@
 import { existsSync, readdirSync, mkdirSync } from "node:fs";
 import { join, resolve, basename } from "node:path";
 import { c, type ParsedArgs } from "../colors";
-import { getHarnessRoot, discoverDirs, promptSelect, getAdapterDir } from "../utils";
+import { getHarnessRoot, discoverDirs, promptSelect, getAdapterDir, ADAPTER_ALLOWLIST, isValidAdapter, validatePlatformUrl, parseAllowCodeExecutionFlag } from "../utils";
 import type { TranscriptEntry } from "@aos-harness/runtime/types";
 import { runAdapterSession } from "../adapter-session";
 import { readAdapterConfig } from "../adapter-config";
+import { buildToolPolicy, type ToolPolicy } from "@aos-harness/adapter-shared";
 
 function createEventBuffer(platformUrl: string, sessionId: string) {
   const buffer: TranscriptEntry[] = [];
@@ -59,6 +60,10 @@ ${c.bold("OPTIONS")}
   --dry-run             Validate config and print simulation summary without launching
   --workflow-dir <path> Directory containing workflow YAML files (default: core/workflows/)
   --platform-url <url> Platform API URL for live observability (e.g. http://localhost:3001)
+  --allow-code-execution[=<langs>|none]
+                        Narrow (never widen) the profile's code-execution allowlist
+                        for this session. Pass \`none\` to force-deny; pass a comma
+                        list like \`python,bash\` to intersect with the profile.
 
 ${c.bold("DESCRIPTION")}
   Launches a deliberation or execution session using the specified profile.
@@ -85,6 +90,17 @@ export async function runCommand(args: ParsedArgs): Promise<void> {
     return;
   }
 
+  // Validate --adapter flag early (spec D2) before any project resolution so
+  // unknown names are rejected regardless of workspace state.
+  if (args.flags["adapter"]) {
+    const flagAdapter = args.flags["adapter"] as string;
+    if (!isValidAdapter(flagAdapter)) {
+      console.error(c.red(`Unknown adapter: ${flagAdapter}`));
+      console.error(c.dim(`Allowed: ${ADAPTER_ALLOWLIST.join(", ")}`));
+      process.exit(2);
+    }
+  }
+
   const root = getHarnessRoot();
   const coreDir = join(root, "core");
 
@@ -166,7 +182,33 @@ export async function runCommand(args: ParsedArgs): Promise<void> {
 
   // ── Validate brief against profile ───────────────────────────
   const { loadProfile, loadWorkflow, validateBrief } = await import("@aos-harness/runtime/config-loader");
-  const profile = loadProfile(profileDir);
+  let profile: ReturnType<typeof loadProfile>;
+  try {
+    profile = loadProfile(profileDir);
+  } catch (err: any) {
+    // Malformed `tools:` block (and any other profile-schema failure) comes
+    // through as a ConfigError. Surface as exit 3 per spec D6 so CI can
+    // distinguish policy/config errors from runtime errors (exit 1) and
+    // invalid input (exit 2).
+    if (err?.name === "ConfigError") {
+      console.error(c.red(err.message));
+      process.exit(3);
+    }
+    throw err;
+  }
+
+  // ── Resolve tool policy (spec D3.2) ─────────────────────────
+  // Profile's `tools:` block is the ceiling; the CLI flag can narrow but
+  // never widen. Any widening attempt from buildToolPolicy is exit 3.
+  const allowCodeExec = parseAllowCodeExecutionFlag(args.flags["allow-code-execution"]);
+  let toolPolicy: ToolPolicy;
+  try {
+    toolPolicy = buildToolPolicy(profile.tools!, { allowCodeExecution: allowCodeExec });
+  } catch (err: any) {
+    console.error(c.red(err.message));
+    process.exit(3);
+  }
+
   const validation = validateBrief(briefPath, profile.input.required_sections);
 
   // ── Detect execution profile (has workflow field) ──────────
@@ -321,19 +363,38 @@ ${c.bold(`AOS ${sessionType} Session`)}
   }
   if (args.flags["adapter"]) adapter = args.flags["adapter"] as string;
 
-  const adapterName = adapter === "claude-code" ? "claude-code" : adapter;
-  // Resolve adapter from: 1) project dir, 2) installed package, 3) monorepo
-  const resolvedAdapterDir = existsSync(join(root, "adapters", adapterName, "src", "index.ts"))
-    ? join(root, "adapters", adapterName)
-    : getAdapterDir(adapterName);
+  // Validate platform URL (spec D5). Fires for both --platform-url flag
+  // and .aos/config.yaml platform.url after both sources are merged.
+  if (platformUrl) {
+    try {
+      validatePlatformUrl(platformUrl);
+    } catch (err: any) {
+      console.error(c.red(`Invalid platform.url: ${err.message}`));
+      process.exit(2);
+    }
+  }
+
+  if (!isValidAdapter(adapter)) {
+    console.error(c.red(`Unknown adapter: ${adapter}`));
+    console.error(c.dim(`Allowed: ${ADAPTER_ALLOWLIST.join(", ")}`));
+    process.exit(2);
+  }
+
+  const adapterName = adapter;
+  // Resolve from monorepo dev layout (CLI's own import.meta.dir) or installed
+  // @aos-harness/<name>-adapter. Project-local override is intentionally absent
+  // (spec D1 — workspace-trust hardening).
+  const resolvedAdapterDir = getAdapterDir(adapterName);
 
   if (adapter === "pi") {
     const adapterEntry = resolvedAdapterDir ? join(resolvedAdapterDir, "src", "index.ts") : null;
     if (!adapterEntry || !existsSync(adapterEntry)) {
       console.error(c.red(`Pi adapter not found.`));
       console.error(c.yellow("Make sure Pi CLI is installed: https://github.com/pi-agi/pi"));
-      console.error(c.dim("The adapter should be bundled with aos-harness. Try reinstalling: bun add -g aos-harness"));
-      process.exit(1);
+      console.error(c.dim("Install the adapter package:"));
+      console.error(c.dim("  npm i -g @aos-harness/pi-adapter"));
+      console.error(c.dim("  # or in a project: npm i @aos-harness/pi-adapter"));
+      process.exit(2);
     }
 
     console.log(c.dim(`Launching Pi adapter...`));
@@ -362,6 +423,11 @@ ${c.bold(`AOS ${sessionType} Session`)}
       env.AOS_WORKFLOW_ID = workflowConfig.id;
       env.AOS_WORKFLOWS_DIR = workflowsDir;
     }
+    // Pass the resolved ToolPolicy to the Pi adapter as JSON. The Pi adapter
+    // runs in a separate process; this env var is the contract. Pi-side
+    // consumption (gating executeCode + emitting tool-denied transcript
+    // events) is a future follow-up — see adapter-trust-model-plan.md.
+    env.AOS_TOOL_POLICY_JSON = JSON.stringify(toolPolicy);
 
     const proc = Bun.spawn(["pi", "-e", adapterEntry], {
       cwd: root,
@@ -390,6 +456,7 @@ ${c.bold(`AOS ${sessionType} Session`)}
       workflowConfig: isExecutionProfile ? workflowConfig : null,
       workflowsDir,
       modelOverrides: adapterConfig?.model_overrides,
+      toolPolicy,
     });
   }
 }