@toolu/core 6.8.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@toolu/core",
+  "version": "6.8.0",
+  "description": "Portable decision, policy and bridge core shared by toolu's host adapters.",
+  "keywords": [
+    "toolu",
+    "opencode",
+    "hooks",
+    "policy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Falconiere/toolu.git",
+    "directory": "packages/toolu-core"
+  },
+  "homepage": "https://github.com/Falconiere/toolu#readme",
+  "bugs": {
+    "url": "https://github.com/Falconiere/toolu/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./decision": "./src/decision/decision.ts",
+    "./events": "./src/events/events.ts",
+    "./bridge": "./src/bridge/bridge.ts",
+    "./policy": "./src/policy/policy.ts",
+    "./config": "./src/config/config.ts",
+    "./runner": "./src/runner/runner.ts"
+  },
+  "dependencies": {
+    "zod": "4.1.5"
+  }
+}

package/src/bridge/__tests__/bridge.integration.test.ts

@@ -0,0 +1,29 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runPreToolBridge } from "../bridge.ts";
+import { bridgeEnv, createProtectedFilesProject, REPO_ROOT } from "../test-helpers.ts";
+
+test("runPreToolBridge real mod.sh protected .env edit yields deny or ask", async () => {
+  const { projectRoot, envPath } = await createProtectedFilesProject();
+  const fixturePath = join(REPO_ROOT, "tooling/fixtures/portable-core/protected-files-pre.json");
+  const fixtureRaw: unknown = JSON.parse(readFileSync(fixturePath, "utf8"));
+  const spread =
+    typeof fixtureRaw === "object" && fixtureRaw !== null && !Array.isArray(fixtureRaw)
+      ? fixtureRaw
+      : {};
+
+  const response = await runPreToolBridge(
+    {
+      ...spread,
+      cwd: projectRoot,
+      projectRoot,
+      worktree: projectRoot,
+      toolInput: { file_path: envPath },
+    },
+    { repoRoot: REPO_ROOT, env: bridgeEnv() },
+  );
+
+  expect(response.ok).toBe(true);
+  expect(response.decision.kind === "deny" || response.decision.kind === "ask").toBe(true);
+});

package/src/bridge/__tests__/bridge.test.ts

@@ -0,0 +1,83 @@
+import { expect, test } from "bun:test";
+import { decisionFromHookResult, parseBridgeRequest, toHookStdin } from "../bridge.ts";
+
+test("parseBridgeRequest accepts protected-files fixture shape", () => {
+  const req = parseBridgeRequest({
+    protocolVersion: 1,
+    event: "tool/pre",
+    sessionId: "s",
+    toolCallId: "c",
+    cwd: "/repo",
+    projectRoot: "/repo",
+    worktree: "/repo",
+    toolName: "Edit",
+    toolInput: { file_path: "/repo/.env" },
+    host: "opencode",
+    deadlineMs: 15000,
+    maxStdoutBytes: 1048576,
+  });
+  expect(req.toolName).toBe("Edit");
+});
+
+test("parseBridgeRequest rejects bad protocolVersion", () => {
+  expect(() =>
+    parseBridgeRequest({
+      protocolVersion: 2,
+      event: "tool/pre",
+      sessionId: "s",
+      toolCallId: "c",
+      cwd: "/r",
+      projectRoot: "/r",
+      worktree: "/r",
+      toolName: "Edit",
+      host: "x",
+      deadlineMs: 1,
+      maxStdoutBytes: 1,
+    }),
+  ).toThrow();
+});
+
+test("toHookStdin maps Claude PreToolUse fields", () => {
+  expect(toHookStdin({ toolName: "Edit", toolInput: { file_path: "/a" } })).toBe(
+    JSON.stringify({ tool_name: "Edit", tool_input: { file_path: "/a" } }),
+  );
+});
+
+test("decisionFromHookResult exit 2 pre yields deny with stderr reason", () => {
+  expect(decisionFromHookResult(2, "", "protected file", "tool/pre")).toEqual({
+    kind: "deny",
+    reason: "protected file",
+  });
+});
+
+test("decisionFromHookResult exit 2 post yields post_block", () => {
+  expect(decisionFromHookResult(2, "", "blocked", "tool/post")).toEqual({
+    kind: "post_block",
+    reason: "blocked",
+  });
+});
+
+test("decisionFromHookResult exit 0 empty stdout yields allow", () => {
+  expect(decisionFromHookResult(0, "", "", "tool/pre")).toEqual({ kind: "allow" });
+});
+
+test("decisionFromHookResult permissionDecision deny", () => {
+  const stdout = JSON.stringify({
+    hookSpecificOutput: {
+      permissionDecision: "deny",
+      permissionDecisionReason: "no",
+    },
+  });
+  expect(decisionFromHookResult(0, stdout, "", "tool/pre")).toEqual({
+    kind: "deny",
+    reason: "no",
+  });
+});
+
+test("decisionFromHookResult malformed stdout yields runtime_failure parse", () => {
+  expect(decisionFromHookResult(0, "not-json", "", "tool/pre")).toEqual({
+    kind: "runtime_failure",
+    reason: "hook stdout was not valid JSON",
+    code: "parse",
+  });
+});

package/src/bridge/bridge.ts

@@ -0,0 +1,130 @@
+/** Bash bridge protocol v1 (#210). */
+import { z } from "zod";
+import { type Decision, DecisionSchema } from "../decision/decision.ts";
+import { BridgeEventSchema } from "../events/events.ts";
+import { createBunBashRunner, type BashRunner, type RawProcessResult } from "../runner/runner.ts";
+import { decisionFromHookResult, decisionFromRunnerFailure, toHookStdin } from "./hook-map.ts";
+
+export const BridgeRequestSchema = z.object({
+  protocolVersion: z.literal(1),
+  event: BridgeEventSchema,
+  sessionId: z.string().min(1),
+  toolCallId: z.string().min(1),
+  cwd: z.string().min(1),
+  projectRoot: z.string().min(1),
+  worktree: z.string().min(1),
+  toolName: z.string().min(1),
+  toolInput: z.record(z.string(), z.unknown()).default({}),
+  host: z.string().min(1),
+  deadlineMs: z.number().int().positive(),
+  maxStdoutBytes: z.number().int().positive(),
+});
+
+export type BridgeRequest = z.infer<typeof BridgeRequestSchema>;
+
+const BridgeMetaSchema = z.object({
+  exitCode: z.number().int().nullable(),
+  stdout: z.string(),
+  stderr: z.string(),
+  truncated: z.boolean().optional(),
+});
+
+export const BridgeResponseSchema = z.discriminatedUnion("ok", [
+  z
+    .object({
+      ok: z.literal(true),
+      decision: DecisionSchema,
+      meta: BridgeMetaSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ok: z.literal(false),
+      decision: DecisionSchema,
+      meta: BridgeMetaSchema,
+    })
+    .strict(),
+]);
+
+export type BridgeResponse = z.infer<typeof BridgeResponseSchema>;
+
+/** Parse a bridge request envelope. */
+export function parseBridgeRequest(input: unknown): BridgeRequest {
+  return BridgeRequestSchema.parse(input);
+}
+
+export { toHookStdin, decisionFromHookResult } from "./hook-map.ts";
+
+function responseFromProcess(event: BridgeRequest["event"], raw: RawProcessResult): BridgeResponse {
+  const meta = {
+    exitCode: raw.exitCode,
+    stdout: raw.stdout,
+    stderr: raw.stderr,
+    truncated: raw.truncated,
+  };
+
+  if (!raw.ok) {
+    const decision = decisionFromRunnerFailure(raw.code, raw.message);
+    return { ok: false, decision, meta };
+  }
+
+  const decision = decisionFromHookResult(raw.exitCode, raw.stdout, raw.stderr, event);
+  if (decision.kind === "runtime_failure") {
+    return { ok: false, decision, meta };
+  }
+  return { ok: true, decision, meta };
+}
+
+export type PreToolBridgeOptions = {
+  repoRoot: string;
+  runner?: BashRunner;
+  env?: Record<string, string>;
+  signal?: AbortSignal;
+};
+
+/** Resolve pre-tools/mod.sh under a toolu checkout. */
+export function resolvePreToolsModSh(repoRoot: string): string {
+  return `${repoRoot.replace(/\/$/, "")}/plugins/toolu/hooks/pre-tools/mod.sh`;
+}
+
+/** Run the real pre-tools dispatcher and map to BridgeResponse. */
+export async function runPreToolBridge(
+  requestInput: unknown,
+  opts: PreToolBridgeOptions,
+): Promise<BridgeResponse> {
+  const request = parseBridgeRequest(requestInput);
+  if (request.event !== "tool/pre") {
+    const decision: Decision = {
+      kind: "runtime_failure",
+      reason: `runPreToolBridge supports tool/pre only, got ${request.event}`,
+      code: "parse",
+    };
+    return {
+      ok: false,
+      decision,
+      meta: { exitCode: null, stdout: "", stderr: decision.reason, truncated: false },
+    };
+  }
+
+  const modSh = resolvePreToolsModSh(opts.repoRoot);
+  const runner = opts.runner ?? createBunBashRunner();
+  const stdin = toHookStdin({ toolName: request.toolName, toolInput: request.toolInput });
+
+  const env: Record<string, string> = {
+    ...opts.env,
+    TOOLU_PROJECT_DIR: request.projectRoot,
+    CLAUDE_PROJECT_DIR: request.projectRoot,
+  };
+
+  const raw = await runner.run({
+    argv: ["bash", modSh],
+    cwd: request.cwd,
+    env,
+    stdin,
+    deadlineMs: request.deadlineMs,
+    maxStdoutBytes: request.maxStdoutBytes,
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+  });
+
+  return responseFromProcess(request.event, raw);
+}

package/src/bridge/hook-map.ts

@@ -0,0 +1,178 @@
+/** Map hook stdout/exit codes to portable decisions (#210). */
+import { type Decision } from "../decision/decision.ts";
+import { type BridgeEvent } from "../events/events.ts";
+
+type HookJson = {
+  hookSpecificOutput?: {
+    permissionDecision?: string;
+    permissionDecisionReason?: string;
+    additionalContext?: string;
+  };
+  decision?: string;
+  reason?: string;
+  systemMessage?: string;
+};
+
+function readStringField(obj: Record<string, unknown>, key: string): string | undefined {
+  const v = obj[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+function objectToRecord(value: object): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value)) {
+    out[key] = val;
+  }
+  return out;
+}
+
+function parseHookObject(parsed: Record<string, unknown>): HookJson {
+  const out: HookJson = {};
+  const hso = parsed.hookSpecificOutput;
+  if (typeof hso === "object" && hso !== null && !Array.isArray(hso)) {
+    const h = objectToRecord(hso);
+    const hookOut: NonNullable<HookJson["hookSpecificOutput"]> = {};
+    const permissionDecision = readStringField(h, "permissionDecision");
+    const permissionDecisionReason = readStringField(h, "permissionDecisionReason");
+    const additionalContext = readStringField(h, "additionalContext");
+    if (permissionDecision !== undefined) {
+      hookOut.permissionDecision = permissionDecision;
+    }
+    if (permissionDecisionReason !== undefined) {
+      hookOut.permissionDecisionReason = permissionDecisionReason;
+    }
+    if (additionalContext !== undefined) {
+      hookOut.additionalContext = additionalContext;
+    }
+    out.hookSpecificOutput = hookOut;
+  }
+  const decision = readStringField(parsed, "decision");
+  const reason = readStringField(parsed, "reason");
+  const systemMessage = readStringField(parsed, "systemMessage");
+  if (decision !== undefined) {
+    out.decision = decision;
+  }
+  if (reason !== undefined) {
+    out.reason = reason;
+  }
+  if (systemMessage !== undefined) {
+    out.systemMessage = systemMessage;
+  }
+  return out;
+}
+
+function parseHookStdout(stdout: string): HookJson | null {
+  const trimmed = stdout.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return null;
+    }
+    return parseHookObject(objectToRecord(parsed));
+  } catch {
+    return null;
+  }
+}
+
+function runtimeFailure(
+  reason: string,
+  code: Extract<Decision, { kind: "runtime_failure" }>["code"],
+): Decision {
+  return { kind: "runtime_failure", reason, code };
+}
+
+function isPostEvent(event: BridgeEvent): boolean {
+  return event === "tool/post";
+}
+
+/** Claude PreToolUse / PostToolUse stdin JSON from a bridge request. */
+export function toHookStdin(request: {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+}): string {
+  return JSON.stringify({
+    tool_name: request.toolName,
+    tool_input: request.toolInput,
+  });
+}
+
+/** Normalize bash dispatch stdout + exit code into a Decision. */
+export function decisionFromHookResult(
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+  event: BridgeEvent,
+): Decision {
+  if (exitCode === 2) {
+    const reason = stderr.trim() || "hook blocked via exit code 2";
+    if (isPostEvent(event)) {
+      return { kind: "post_block", reason };
+    }
+    return { kind: "deny", reason };
+  }
+
+  if (exitCode !== 0) {
+    return runtimeFailure(stderr.trim() || `hook exited ${exitCode}`, "nonzero");
+  }
+
+  const payload = parseHookStdout(stdout);
+  if (stdout.trim() !== "" && payload === null) {
+    return runtimeFailure("hook stdout was not valid JSON", "parse");
+  }
+
+  if (payload === null) {
+    return { kind: "allow" };
+  }
+
+  const permission = payload.hookSpecificOutput?.permissionDecision;
+  if (permission === "deny") {
+    const fromHook = payload.hookSpecificOutput?.permissionDecisionReason?.trim();
+    const fromReason = payload.reason?.trim();
+    const reason =
+      fromHook && fromHook.length > 0
+        ? fromHook
+        : fromReason && fromReason.length > 0
+          ? fromReason
+          : "permission denied";
+    return { kind: "deny", reason };
+  }
+  if (permission === "ask") {
+    const fromHook = payload.hookSpecificOutput?.permissionDecisionReason?.trim();
+    const reason = fromHook && fromHook.length > 0 ? fromHook : "permission ask";
+    return { kind: "ask", reason };
+  }
+
+  if (isPostEvent(event) && payload.decision === "block") {
+    const fromReason = payload.reason?.trim();
+    const reason = fromReason && fromReason.length > 0 ? fromReason : "post-tool block";
+    return { kind: "post_block", reason };
+  }
+
+  const ctx = payload.hookSpecificOutput?.additionalContext?.trim();
+  const sys = payload.systemMessage?.trim();
+  const message = [ctx, sys].filter((part) => part && part.length > 0).join("\n\n");
+  if (message.length > 0) {
+    return { kind: "advisory", message };
+  }
+
+  return { kind: "allow" };
+}
+
+export function decisionFromRunnerFailure(code: string, message: string): Decision {
+  if (code === "timeout") {
+    return runtimeFailure(message, "timeout");
+  }
+  if (code === "spawn") {
+    return runtimeFailure(message, "spawn");
+  }
+  if (code === "truncated") {
+    return runtimeFailure(message, "truncated");
+  }
+  if (code === "cancelled") {
+    return runtimeFailure(message, "cancelled");
+  }
+  return runtimeFailure(message, "nonzero");
+}

package/src/bridge/test-helpers.ts

@@ -0,0 +1,32 @@
+/** Shared temp-repo setup for real bash bridge tests. */
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const REPO_ROOT = join(import.meta.dir, "../../../..");
+
+export async function createProtectedFilesProject(): Promise<{
+  projectRoot: string;
+  envPath: string;
+}> {
+  const base = process.env.TMPDIR ?? "/tmp";
+  const projectRoot = await mkdtemp(join(base, "toolu-bridge-"));
+  const envPath = join(projectRoot, ".env");
+  await writeFile(envPath, "SECRET=1\n", "utf8");
+  await mkdir(join(projectRoot, ".claude"), { recursive: true });
+  await writeFile(
+    join(projectRoot, ".claude/toolu.config.json"),
+    JSON.stringify({
+      version: 1,
+      gates: { protectedFiles: { mode: "block" } },
+    }),
+    "utf8",
+  );
+  return { projectRoot, envPath };
+}
+
+export function bridgeEnv(): Record<string, string> {
+  return {
+    TOOLU_SETTINGS_DIR: join(REPO_ROOT, "plugins/toolu/settings"),
+    TOOLU_HOST_OVERRIDE: "claude",
+  };
+}

package/src/config/__tests__/config.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "bun:test";
+import { parseTooluConfig } from "../config.ts";
+
+test("parseTooluConfig requires version 1", () => {
+  expect(parseTooluConfig({ version: 1 }).version).toBe(1);
+  expect(() => parseTooluConfig({ version: 2 })).toThrow();
+});
+
+test("parseTooluConfig rejects unknown top-level keys", () => {
+  expect(() => parseTooluConfig({ version: 1, extra: true })).toThrow();
+});
+
+test("parseTooluConfig accepts gates protectedFiles block", () => {
+  const cfg = parseTooluConfig({
+    version: 1,
+    gates: { protectedFiles: { mode: "block" } },
+  });
+  expect(cfg.gates?.protectedFiles?.mode).toBe("block");
+});
+
+test("parseTooluConfig rejects invalid gate mode", () => {
+  expect(() =>
+    parseTooluConfig({
+      version: 1,
+      gates: { protectedFiles: { mode: "maybe" } },
+    }),
+  ).toThrow();
+});

package/src/config/config.ts

@@ -0,0 +1,112 @@
+/** toolu.config.json v1 strict Zod (#210). */
+import { z } from "zod";
+
+const GateModeSchema = z.enum(["block", "ask", "advise", "off"]);
+const GatePresetSchema = z.enum(["strict", "balanced", "relaxed"]);
+const DocsSyncModeSchema = z.enum(["advise", "block", "off"]);
+const AgentTierModeSchema = z.enum(["advise", "block", "off"]);
+const ModelClassSchema = z.enum(["haiku", "sonnet", "opus", "fable", "inherit"]);
+const ReasoningEffortSchema = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
+
+const GateEntrySchema = z.object({ mode: GateModeSchema }).strict();
+
+const LangEntrySchema = z
+  .object({
+    maxFileLines: z.number().int().positive().optional(),
+    maxFnLines: z.number().int().positive().optional(),
+    maxImplLines: z.number().int().positive().optional(),
+    noMocks: z.boolean().optional(),
+  })
+  .strict();
+
+const CodexModelEntrySchema = z
+  .object({
+    model: z.string().min(1),
+    reasoningEffort: ReasoningEffortSchema.optional(),
+  })
+  .strict();
+
+export const TooluConfigSchema = z
+  .object({
+    version: z.literal(1),
+    skills: z.record(z.string(), z.boolean()).optional(),
+    hooks: z.record(z.string(), z.boolean()).optional(),
+    mcp: z.record(z.string(), z.boolean()).optional(),
+    agents: z.record(z.string(), z.boolean()).optional(),
+    models: z
+      .object({
+        enabled: z.boolean().optional(),
+        mechanical: ModelClassSchema.optional(),
+        exploration: ModelClassSchema.optional(),
+        implementation: ModelClassSchema.optional(),
+        review: ModelClassSchema.optional(),
+        synthesis: ModelClassSchema.optional(),
+        architecture: ModelClassSchema.optional(),
+        codex: z.record(z.string(), CodexModelEntrySchema).optional(),
+      })
+      .strict()
+      .optional(),
+    lang: z
+      .object({
+        ts: LangEntrySchema.optional(),
+        rust: LangEntrySchema.optional(),
+        python: LangEntrySchema.optional(),
+      })
+      .strict()
+      .optional(),
+    docsSync: z
+      .object({
+        mode: DocsSyncModeSchema.optional(),
+        surfaces: z.array(z.string()).optional(),
+        surfaceExcludes: z.array(z.string()).optional(),
+        codeSurfaces: z.array(z.string()).optional(),
+      })
+      .strict()
+      .optional(),
+    telemetry: z.object({ enabled: z.boolean().optional() }).strict().optional(),
+    agentTier: z.object({ mode: AgentTierModeSchema.optional() }).strict().optional(),
+    planLedger: z.object({ blockOnUncoveredAcs: z.boolean().optional() }).strict().optional(),
+    gates: z
+      .object({
+        preset: GatePresetSchema.optional(),
+        pushReview: GateEntrySchema.optional(),
+        qualityGate: GateEntrySchema.optional(),
+        commitGate: GateEntrySchema.optional(),
+        bashCommands: GateEntrySchema.optional(),
+        planLedger: GateEntrySchema.optional(),
+        docsSync: GateEntrySchema.optional(),
+        agentTier: GateEntrySchema.optional(),
+        protectedFiles: GateEntrySchema.optional(),
+        mcpBlocker: GateEntrySchema.optional(),
+        sweep: z.boolean().optional(),
+        stateTtlHours: z.number().int().positive().optional(),
+        telemetryRetentionDays: z.number().int().positive().optional(),
+      })
+      .strict()
+      .optional(),
+    permissions: z
+      .object({
+        autoAllow: z.boolean().optional(),
+        allow: z.array(z.string()).optional(),
+        deny: z.array(z.string()).optional(),
+      })
+      .strict()
+      .optional(),
+    projectSkills: z
+      .object({
+        enabled: z.boolean().optional(),
+        staleAfterDays: z.number().int().positive().optional(),
+        archiveAfterDays: z.number().int().positive().optional(),
+        indexCap: z.number().int().positive().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type TooluConfig = z.infer<typeof TooluConfigSchema>;
+
+/** Parse toolu.config.json; rejects unknown top-level keys. */
+export function parseTooluConfig(input: unknown): TooluConfig {
+  return TooluConfigSchema.parse(input);
+}

package/src/decision/__tests__/decision.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from "bun:test";
+import { DecisionSchema, parseDecision } from "../decision.ts";
+
+test("parseDecision accepts allow", () => {
+  expect(parseDecision({ kind: "allow" })).toEqual({ kind: "allow" });
+});
+
+test("parseDecision accepts deny with reason", () => {
+  expect(parseDecision({ kind: "deny", reason: "blocked" })).toEqual({
+    kind: "deny",
+    reason: "blocked",
+  });
+});
+
+test("parseDecision rejects unknown kind", () => {
+  expect(() => parseDecision({ kind: "maybe" })).toThrow();
+});
+
+test("parseDecision rejects deny without reason", () => {
+  expect(() => parseDecision({ kind: "deny" })).toThrow();
+});
+
+test("DecisionSchema accepts runtime_failure codes", () => {
+  const parsed = DecisionSchema.parse({
+    kind: "runtime_failure",
+    reason: "timeout",
+    code: "timeout",
+  });
+  expect(parsed.kind === "runtime_failure" && parsed.code).toBe("timeout");
+});

package/src/decision/decision.ts

@@ -0,0 +1,22 @@
+/** Discriminated decision union (portable-core #210). */
+import { z } from "zod";
+
+export const DecisionSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("allow") }),
+  z.object({ kind: z.literal("ask"), reason: z.string().min(1) }),
+  z.object({ kind: z.literal("deny"), reason: z.string().min(1) }),
+  z.object({ kind: z.literal("advisory"), message: z.string().min(1) }),
+  z.object({ kind: z.literal("post_block"), reason: z.string().min(1) }),
+  z.object({
+    kind: z.literal("runtime_failure"),
+    reason: z.string().min(1),
+    code: z.enum(["timeout", "spawn", "parse", "truncated", "cancelled", "nonzero"]),
+  }),
+]);
+
+export type Decision = z.infer<typeof DecisionSchema>;
+
+/** Parse an unknown decision envelope. */
+export function parseDecision(input: unknown): Decision {
+  return DecisionSchema.parse(input);
+}

package/src/events/__tests__/events.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import { parseNormalizedEvent } from "../events.ts";
+
+const base = {
+  sessionId: "s1",
+  cwd: "/repo",
+  projectRoot: "/repo",
+  worktree: "/repo",
+};
+
+test("parseNormalizedEvent accepts tool/pre", () => {
+  expect(
+    parseNormalizedEvent({
+      type: "tool/pre",
+      ...base,
+      toolCallId: "c1",
+      toolName: "Edit",
+      toolInput: { file_path: "/repo/a.ts" },
+    }).type,
+  ).toBe("tool/pre");
+});
+
+test("parseNormalizedEvent rejects missing sessionId", () => {
+  expect(() =>
+    parseNormalizedEvent({
+      type: "tool/pre",
+      cwd: "/repo",
+      projectRoot: "/repo",
+      worktree: "/repo",
+      toolCallId: "c1",
+      toolName: "Edit",
+    }),
+  ).toThrow();
+});
+
+test("parseNormalizedEvent accepts session/start", () => {
+  expect(parseNormalizedEvent({ type: "session/start", ...base }).type).toBe("session/start");
+});

package/src/events/events.ts

@@ -0,0 +1,65 @@
+/** Normalized host event vocabulary (portable-core #210). */
+import { z } from "zod";
+
+const SessionContextSchema = z.object({
+  sessionId: z.string().min(1),
+  cwd: z.string().min(1),
+  projectRoot: z.string().min(1),
+  worktree: z.string().min(1),
+});
+
+const ToolContextSchema = SessionContextSchema.extend({
+  toolCallId: z.string().min(1),
+  toolName: z.string().min(1),
+  toolInput: z.record(z.string(), z.unknown()).default({}),
+});
+
+export const NormalizedEventSchema = z.discriminatedUnion("type", [
+  SessionContextSchema.extend({ type: z.literal("session/start") }),
+  SessionContextSchema.extend({ type: z.literal("session/resume") }),
+  SessionContextSchema.extend({ type: z.literal("session/clear") }),
+  SessionContextSchema.extend({ type: z.literal("session/unload") }),
+  SessionContextSchema.extend({
+    type: z.literal("prompt"),
+    prompt: z.string(),
+  }),
+  SessionContextSchema.extend({ type: z.literal("pre_compact") }),
+  SessionContextSchema.extend({ type: z.literal("compaction") }),
+  SessionContextSchema.extend({
+    type: z.literal("permission/evaluate"),
+    permission: z.string().min(1),
+  }),
+  ToolContextSchema.extend({ type: z.literal("tool/pre") }),
+  ToolContextSchema.extend({
+    type: z.literal("tool/post"),
+    toolOutput: z.unknown().optional(),
+  }),
+  ToolContextSchema.extend({
+    type: z.literal("shell/pre"),
+    command: z.string().min(1),
+  }),
+]);
+
+export type NormalizedEvent = z.infer<typeof NormalizedEventSchema>;
+
+/** Bridge-facing event slug (subset used in BridgeRequest.event). */
+export const BridgeEventSchema = z.enum([
+  "tool/pre",
+  "tool/post",
+  "shell/pre",
+  "session/start",
+  "session/resume",
+  "session/clear",
+  "session/unload",
+  "prompt",
+  "pre_compact",
+  "compaction",
+  "permission/evaluate",
+]);
+
+export type BridgeEvent = z.infer<typeof BridgeEventSchema>;
+
+/** Parse a normalized event envelope. */
+export function parseNormalizedEvent(input: unknown): NormalizedEvent {
+  return NormalizedEventSchema.parse(input);
+}

package/src/policy/__tests__/policy.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "bun:test";
+import { mergeDecisions, parseClassification } from "../policy.ts";
+
+test("parseClassification accepts shell-out", () => {
+  expect(parseClassification("shell-out")).toBe("shell-out");
+});
+
+test("mergeDecisions deny beats ask beats advisory beats allow", () => {
+  expect(
+    mergeDecisions([
+      { kind: "allow" },
+      { kind: "advisory", message: "note" },
+      { kind: "ask", reason: "prompt" },
+      { kind: "deny", reason: "no" },
+    ]).kind,
+  ).toBe("deny");
+
+  expect(
+    mergeDecisions([
+      { kind: "allow" },
+      { kind: "advisory", message: "note" },
+      { kind: "ask", reason: "prompt" },
+    ]).kind,
+  ).toBe("ask");
+
+  expect(mergeDecisions([{ kind: "allow" }, { kind: "advisory", message: "note" }]).kind).toBe(
+    "advisory",
+  );
+});
+
+test("mergeDecisions empty yields allow", () => {
+  expect(mergeDecisions([])).toEqual({ kind: "allow" });
+});

package/src/policy/policy.ts

@@ -0,0 +1,42 @@
+/** Classification enum + decision precedence (#210). */
+import { z } from "zod";
+import { type Decision, DecisionSchema } from "../decision/decision.ts";
+
+export const ClassificationSchema = z.enum(["shell-out", "port-native", "port-new", "no-map"]);
+
+export type Classification = z.infer<typeof ClassificationSchema>;
+
+/** Parse a portable-core classification token. */
+export function parseClassification(input: unknown): Classification {
+  return ClassificationSchema.parse(input);
+}
+
+const MERGE_RANK: Record<Decision["kind"], number> = {
+  runtime_failure: 6,
+  deny: 5,
+  post_block: 5,
+  ask: 4,
+  advisory: 3,
+  allow: 1,
+};
+
+/** deny > ask > advisory; allow loses to any of those. */
+export function mergeDecisions(decisions: Decision[]): Decision {
+  if (decisions.length === 0) {
+    return { kind: "allow" };
+  }
+  let best = decisions[0];
+  if (best === undefined) {
+    return { kind: "allow" };
+  }
+  for (let i = 1; i < decisions.length; i++) {
+    const next = decisions[i];
+    if (next === undefined) {
+      continue;
+    }
+    if (MERGE_RANK[next.kind] > MERGE_RANK[best.kind]) {
+      best = next;
+    }
+  }
+  return DecisionSchema.parse(best);
+}

package/src/runner/__tests__/runner.test.ts

@@ -0,0 +1,83 @@
+import { expect, test } from "bun:test";
+import { mkdir, mkdtemp, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { createBunBashRunner } from "../runner.ts";
+
+const runner = createBunBashRunner();
+
+test("runner timeout yields runtime_failure-capable spawn result not ok timeout", async () => {
+  const result = await runner.run({
+    argv: ["bash", "-c", "sleep 5"],
+    cwd: process.cwd(),
+    env: {},
+    stdin: "",
+    deadlineMs: 200,
+    maxStdoutBytes: 65536,
+  });
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.code).toBe("timeout");
+  }
+});
+
+test("runner exit 2 returns ok true exitCode 2 for bridge mapping", async () => {
+  const result = await runner.run({
+    argv: ["bash", "-c", "echo blocked 1>&2; exit 2"],
+    cwd: process.cwd(),
+    env: {},
+    stdin: "",
+    deadlineMs: 5000,
+    maxStdoutBytes: 65536,
+  });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("blocked");
+  }
+});
+
+test("runner spawn failure missing binary yields spawn code", async () => {
+  const result = await runner.run({
+    argv: ["toolu-nonexistent-binary-210"],
+    cwd: process.cwd(),
+    env: {},
+    stdin: "",
+    deadlineMs: 5000,
+    maxStdoutBytes: 65536,
+  });
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.code).toBe("spawn");
+  }
+});
+
+test("runner path with spaces cwd runs echo ok", async () => {
+  const base = process.env.TMPDIR ?? "/tmp";
+  const cwd = await mkdtemp(join(base, "toolu spaces "));
+  await mkdir(cwd, { recursive: true });
+  const result = await runner.run({
+    argv: ["bash", "-c", "pwd"],
+    cwd,
+    env: {},
+    stdin: "",
+    deadlineMs: 5000,
+    maxStdoutBytes: 65536,
+  });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    // macOS exposes TMPDIR as /var/... while pwd resolves /private/var/...
+    expect(result.stdout.trim()).toBe(await realpath(cwd));
+  }
+});
+
+test("runner malformed handled at bridge not runner", async () => {
+  const result = await runner.run({
+    argv: ["bash", "-c", "echo not-json"],
+    cwd: process.cwd(),
+    env: {},
+    stdin: "",
+    deadlineMs: 5000,
+    maxStdoutBytes: 65536,
+  });
+  expect(result.ok).toBe(true);
+});

package/src/runner/runner-exec.ts

@@ -0,0 +1,212 @@
+/** Execute one argv spawn with deadline and output limits. */
+import type { Subprocess } from "bun";
+import { readLimitedStream } from "./runner-read.ts";
+import type { BashRunArgs, RawProcessResult } from "./runner-types.ts";
+
+type Spawned = {
+  proc: Subprocess<"pipe", "pipe", "pipe">;
+  sessionLeader: boolean;
+};
+
+function spawnFailure(message: string): RawProcessResult {
+  return {
+    ok: false,
+    code: "spawn",
+    message,
+    exitCode: null,
+    stdout: "",
+    stderr: message,
+    truncated: false,
+  };
+}
+
+function killSpawned(spawned: Spawned): void {
+  const { proc, sessionLeader } = spawned;
+  if (sessionLeader) {
+    try {
+      process.kill(-proc.pid, "SIGTERM");
+      return;
+    } catch {
+      /* fall through to PID kill */
+    }
+  }
+  try {
+    process.kill(proc.pid, "SIGTERM");
+  } catch {
+    /* already exited */
+  }
+}
+
+function withSession(argv: string[]): { argv: string[]; sessionLeader: boolean } {
+  if (argv[0] === "setsid") {
+    return { argv, sessionLeader: true };
+  }
+  const setsidBin = Bun.which("setsid");
+  if (setsidBin !== null) {
+    return { argv: [setsidBin, ...argv], sessionLeader: true };
+  }
+  const python = Bun.which("python3") ?? Bun.which("python");
+  if (python !== null) {
+    return {
+      argv: [
+        python,
+        "-c",
+        "import os, sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])",
+        ...argv,
+      ],
+      sessionLeader: true,
+    };
+  }
+  return { argv, sessionLeader: false };
+}
+
+function raceAbort(
+  deadlineMs: number,
+  signal: AbortSignal | undefined,
+): { promise: Promise<"timeout" | "cancelled">; clear: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<"timeout">((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), deadlineMs);
+  });
+  const cancel =
+    signal === undefined
+      ? null
+      : signal.aborted
+        ? Promise.resolve("cancelled" as const)
+        : new Promise<"cancelled">((resolve) => {
+            signal.addEventListener("abort", () => resolve("cancelled"), { once: true });
+          });
+  const racers: Promise<"timeout" | "cancelled">[] = [deadline];
+  if (cancel !== null) {
+    racers.push(cancel);
+  }
+  return {
+    promise: Promise.race(racers),
+    clear: () => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+async function collectOutputs(
+  proc: Subprocess<"pipe", "pipe", "pipe">,
+  maxStdoutBytes: number,
+): Promise<{
+  stdoutOut: Awaited<ReturnType<typeof readLimitedStream>>;
+  stderrOut: Awaited<ReturnType<typeof readLimitedStream>>;
+  exitCode: number;
+}> {
+  const [stdoutOut, stderrOut, exitCode] = await Promise.all([
+    readLimitedStream(proc.stdout, maxStdoutBytes),
+    readLimitedStream(proc.stderr, maxStdoutBytes),
+    proc.exited,
+  ]);
+  return { stdoutOut, stderrOut, exitCode };
+}
+
+async function settleMaybePromise(value: number | Promise<number> | undefined): Promise<void> {
+  if (value === undefined || typeof value === "number") {
+    return;
+  }
+  await value;
+}
+
+async function feedStdin(proc: Subprocess<"pipe", "pipe", "pipe">, stdin: string): Promise<void> {
+  try {
+    proc.stdin.write(stdin);
+    await settleMaybePromise(proc.stdin.flush());
+    await settleMaybePromise(proc.stdin.end());
+  } catch {
+    // Child already closed stdin / exited — runner still collects exit.
+  }
+}
+
+async function openSpawn(args: BashRunArgs): Promise<Spawned | RawProcessResult> {
+  const cmd = args.argv[0];
+  if (cmd === undefined || cmd.length === 0) {
+    return spawnFailure("empty argv");
+  }
+  if (!cmd.includes("/") && Bun.which(cmd) === null) {
+    return spawnFailure(`command not found: ${cmd}`);
+  }
+  const wrapped = withSession(args.argv);
+  try {
+    const proc = Bun.spawn(wrapped.argv, {
+      cwd: args.cwd,
+      env: { ...process.env, ...args.env },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await feedStdin(proc, args.stdin);
+    return { proc, sessionLeader: wrapped.sessionLeader };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return spawnFailure(message);
+  }
+}
+
+async function finishTimedOut(
+  spawned: Spawned,
+  code: "timeout" | "cancelled",
+  maxStdoutBytes: number,
+): Promise<RawProcessResult> {
+  killSpawned(spawned);
+  await spawned.proc.exited;
+  const { stdoutOut, stderrOut } = await collectOutputs(spawned.proc, maxStdoutBytes);
+  return {
+    ok: false,
+    code,
+    message: code === "cancelled" ? "process cancelled" : "process timed out",
+    exitCode: null,
+    stdout: stdoutOut.text,
+    stderr: stderrOut.text,
+    truncated: stdoutOut.truncated || stderrOut.truncated,
+  };
+}
+
+export async function execBashRun(args: BashRunArgs): Promise<RawProcessResult> {
+  const opened = await openSpawn(args);
+  if (!("proc" in opened)) {
+    return opened;
+  }
+
+  const abort = raceAbort(args.deadlineMs, args.signal);
+  // Attach both fulfill/reject so a losing racer cannot raise unhandledRejection.
+  const exitedDone = opened.proc.exited.then(
+    () => "done" as const,
+    () => "done" as const,
+  );
+  const raced = await Promise.race([exitedDone, abort.promise]);
+
+  if (raced !== "done") {
+    abort.clear();
+    return finishTimedOut(opened, raced, args.maxStdoutBytes);
+  }
+
+  abort.clear();
+  await exitedDone;
+  const { stdoutOut, stderrOut, exitCode } = await collectOutputs(opened.proc, args.maxStdoutBytes);
+
+  if (stdoutOut.truncated) {
+    return {
+      ok: false,
+      code: "truncated",
+      message: "stdout exceeded maxStdoutBytes",
+      exitCode,
+      stdout: stdoutOut.text,
+      stderr: stderrOut.text,
+      truncated: true,
+    };
+  }
+
+  return {
+    ok: true,
+    exitCode,
+    stdout: stdoutOut.text,
+    stderr: stderrOut.text,
+    truncated: false,
+  };
+}

package/src/runner/runner-read.ts

@@ -0,0 +1,46 @@
+/** Read subprocess streams with a byte ceiling. */
+
+async function readChunk(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  chunks: Uint8Array[],
+  state: { total: number; truncated: boolean },
+  maxBytes: number,
+): Promise<void> {
+  const { done, value } = await reader.read();
+  if (done) {
+    return;
+  }
+  if (value.byteLength > 0) {
+    if (state.total >= maxBytes) {
+      state.truncated = true;
+    } else {
+      const room = maxBytes - state.total;
+      if (value.byteLength <= room) {
+        chunks.push(value);
+        state.total += value.byteLength;
+      } else {
+        chunks.push(value.subarray(0, room));
+        state.total = maxBytes;
+        state.truncated = true;
+      }
+    }
+  }
+  await readChunk(reader, chunks, state, maxBytes);
+}
+
+export async function readLimitedStream(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<{ text: string; truncated: boolean }> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  const state = { total: 0, truncated: false };
+  await readChunk(reader, chunks, state, maxBytes);
+  const merged = new Uint8Array(state.total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { text: new TextDecoder().decode(merged), truncated: state.truncated };
+}

package/src/runner/runner-types.ts

@@ -0,0 +1,35 @@
+/** Shared runner result types. */
+
+export type RawProcessFailureCode = "timeout" | "spawn" | "truncated" | "cancelled" | "ok";
+
+export type RawProcessResult =
+  | {
+      ok: true;
+      exitCode: number;
+      stdout: string;
+      stderr: string;
+      truncated: boolean;
+    }
+  | {
+      ok: false;
+      code: Exclude<RawProcessFailureCode, "ok">;
+      message: string;
+      exitCode: number | null;
+      stdout: string;
+      stderr: string;
+      truncated: boolean;
+    };
+
+export type BashRunArgs = {
+  argv: string[];
+  cwd: string;
+  env: Record<string, string>;
+  stdin: string;
+  deadlineMs: number;
+  maxStdoutBytes: number;
+  signal?: AbortSignal;
+};
+
+export interface BashRunner {
+  run(args: BashRunArgs): Promise<RawProcessResult>;
+}

package/src/runner/runner.ts

@@ -0,0 +1,19 @@
+/** argv-only bash runner for the portable bridge (#210). */
+import { execBashRun } from "./runner-exec.ts";
+import type { BashRunArgs, BashRunner, RawProcessResult } from "./runner-types.ts";
+
+export type {
+  BashRunArgs,
+  BashRunner,
+  RawProcessFailureCode,
+  RawProcessResult,
+} from "./runner-types.ts";
+
+/** Bun.spawn runner: argv array only, never a shell string. */
+export function createBunBashRunner(): BashRunner {
+  return {
+    run(args: BashRunArgs): Promise<RawProcessResult> {
+      return execBashRun(args);
+    },
+  };
+}