@toolu/opencode 6.8.0

package/plugins/ts-quality/hooks/register.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# SessionStart registry sync for the ts-quality plugin.
+#
+# Assembles hooks/concerns/[0-9][0-9]-*.sh (ordered preamble → concern partials
+# → finalize) into ONE runtime module in the toolu registry
+# (${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/toolu/post-tools.d/) under the
+# namespaced filename ts-quality@toolu__ts-quality.sh. The fragments are
+# partials of a single script; concatenating them in numeric order rebuilds the
+# original monolith so one process does one gate write (preserving
+# byte-identical behavior). Prunes any stale entry bearing OUR prefix, and
+# clears our own crashed tmp residue. Other plugins' entries are never touched.
+#
+# Silent on success (SessionStart stdout becomes context); errors are
+# non-fatal — a failed sync means the registry copy is stale, not broken.
+
+SPEC="ts-quality@toolu"
+OUT="ts-quality.sh"
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC_DIR="$SELF_DIR/concerns"
+if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+  CONFIG_ROOT="$TOOLU_CONFIG_DIR"
+elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+  CONFIG_ROOT="${CODEX_HOME:-$HOME/.codex}"
+else
+  CONFIG_ROOT="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+fi
+REG_DIR="$CONFIG_ROOT/toolu/post-tools.d"
+
+# Consume stdin so Claude Code's hook IPC never stalls.
+cat > /dev/null 2>&1 || true
+
+[ -d "$SRC_DIR" ] || exit 0
+mkdir -p "$REG_DIR" 2>/dev/null || exit 0
+
+# Clear OUR orphaned atomic-write residue from prior crashed runs. Age-gated
+# so a concurrent SessionStart's in-flight tmp (seconds old) is never clobbered.
+find "$REG_DIR" -maxdepth 1 -name "${SPEC}__*.sh.tmp.*" -mmin +1 -delete 2>/dev/null
+
+# Assemble: concatenate the numeric-prefixed fragments in lexical order into one
+# module. A newline guard between fragments keeps a fragment that lacks a
+# trailing newline from running into the next. __tests__/ and any non-prefixed
+# .sh are skipped by the glob.
+dst="$REG_DIR/${SPEC}__${OUT}"
+tmp="${dst}.tmp.$$"
+: > "$tmp"
+for src in "$SRC_DIR"/[0-9][0-9]-*.sh; do
+  [ -f "$src" ] || continue
+  cat "$src" >> "$tmp" 2>/dev/null || { rm -f "$tmp"; exit 0; }
+  printf '\n' >> "$tmp" 2>/dev/null || { rm -f "$tmp"; exit 0; }
+done
+if [ -s "$tmp" ] && { [ ! -f "$dst" ] || ! cmp -s "$tmp" "$dst"; }; then
+  mv "$tmp" "$dst" 2>/dev/null || rm -f "$tmp"
+else
+  rm -f "$tmp"
+fi
+
+# Prune: remove any entry bearing OUR prefix that is not the current assembled
+# module (e.g. per-concern files left by an older version). Never glob outside
+# our own spec prefix.
+for old in "$REG_DIR/${SPEC}__"*.sh; do
+  [ -f "$old" ] || continue
+  [ "$(basename "$old")" = "${SPEC}__${OUT}" ] || rm -f "$old"
+done
+
+exit 0

package/src/adapter/__tests__/evaluate.test.ts

@@ -0,0 +1,82 @@
+import { expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createPermissionEvaluateHandler } from "../evaluate.ts";
+import type { PermissionEvaluationEvent } from "../permission-map.ts";
+
+const tmpBase = process.env.TMPDIR ?? "/tmp";
+
+function repoRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "../../../../..");
+}
+
+async function protectedEnvProject(): Promise<{ projectRoot: string; envPath: string }> {
+  const projectRoot = await mkdtemp(join(tmpBase, "toolu-oc-eval-"));
+  const envPath = join(projectRoot, ".env");
+  await writeFile(envPath, "SECRET=1\n", "utf8");
+  await mkdir(join(projectRoot, ".opencode"), { recursive: true });
+  await writeFile(
+    join(projectRoot, ".opencode/toolu.config.json"),
+    JSON.stringify({
+      version: 1,
+      gates: { protectedFiles: { mode: "block" } },
+    }),
+    "utf8",
+  );
+  return { projectRoot, envPath };
+}
+
+function editEvent(envPath: string): PermissionEvaluationEvent {
+  return {
+    sessionID: "sess_eval_1",
+    action: "edit",
+    resources: [envPath],
+    effect: "allow",
+    metadata: { toolCallId: "call_eval_1" },
+  };
+}
+
+test("AC-2: evaluate handler + real bridge on protected .env yields deny", async () => {
+  const root = repoRoot();
+  const { projectRoot, envPath } = await protectedEnvProject();
+  const handler = createPermissionEvaluateHandler({
+    repoRoot: root,
+    bridgeContext: {
+      cwd: projectRoot,
+      projectRoot,
+      worktree: projectRoot,
+      host: "opencode",
+    },
+    env: {
+      TOOLU_SETTINGS_DIR: join(root, "plugins/toolu/settings"),
+      TOOLU_HOST_OVERRIDE: "opencode",
+      TOOLU_PROJECT_CONFIG_DIRNAME: ".opencode",
+    },
+  });
+
+  const event = editEvent(envPath);
+  await handler(event);
+
+  expect(event.effect).toBe("deny");
+});
+
+test("AC-3: runtime_failure from bad repoRoot maps to deny", async () => {
+  const { projectRoot, envPath } = await protectedEnvProject();
+  const handler = createPermissionEvaluateHandler({
+    repoRoot: join(tmpBase, "toolu-nonexistent-repo-root"),
+    bridgeContext: {
+      cwd: projectRoot,
+      projectRoot,
+      worktree: projectRoot,
+      host: "opencode",
+    },
+  });
+
+  const event = editEvent(envPath);
+  await handler(event);
+
+  expect(event.effect).toBe("deny");
+  expect(typeof event.message).toBe("string");
+  expect(event.message && event.message.length > 0).toBe(true);
+});

package/src/adapter/__tests__/permission-map.test.ts

@@ -0,0 +1,91 @@
+import { expect, test } from "bun:test";
+import type { Decision } from "@toolu/core/decision";
+import {
+  applyDecisionToPermission,
+  mapPermissionEventToBridge,
+  type PermissionEvaluationEvent,
+} from "../permission-map.ts";
+
+const ctx = {
+  cwd: "/proj",
+  projectRoot: "/proj",
+  worktree: "/proj",
+  host: "opencode",
+};
+
+function event(overrides: Partial<PermissionEvaluationEvent> = {}): PermissionEvaluationEvent {
+  return {
+    sessionID: "sess_1",
+    action: "edit",
+    resources: ["/proj/.env"],
+    effect: "allow",
+    ...overrides,
+  };
+}
+
+test("AC-4: mapPermissionEventToBridge maps edit to Edit tool/pre", () => {
+  const mapping = mapPermissionEventToBridge(event(), ctx);
+  expect(mapping.kind).toBe("request");
+  if (mapping.kind !== "request") {
+    return;
+  }
+  expect(mapping.request.protocolVersion).toBe(1);
+  expect(mapping.request.event).toBe("tool/pre");
+  expect(mapping.request.toolName).toBe("Edit");
+  expect(mapping.request.toolInput).toEqual({ file_path: "/proj/.env" });
+  expect(mapping.request.host).toBe("opencode");
+});
+
+test("AC-4: mapPermissionEventToBridge skips unknown actions", () => {
+  expect(mapPermissionEventToBridge(event({ action: "read" }), ctx).kind).toBe("skip");
+});
+
+test("AC-4: gated write without path fails closed in mapper", () => {
+  const mapping = mapPermissionEventToBridge(event({ action: "write", resources: [] }), ctx);
+  expect(mapping.kind).toBe("deny");
+});
+
+test("AC-4: bash maps command from metadata", () => {
+  const mapping = mapPermissionEventToBridge(
+    event({
+      action: "bash",
+      resources: [],
+      metadata: { command: "rm -rf /" },
+    }),
+    ctx,
+  );
+  expect(mapping.kind).toBe("request");
+  if (mapping.kind !== "request") {
+    return;
+  }
+  expect(mapping.request.toolName).toBe("Bash");
+  expect(mapping.request.toolInput).toEqual({ command: "rm -rf /" });
+});
+
+const decisionCases: Array<{
+  decision: Decision;
+  effect: PermissionEvaluationEvent["effect"];
+  message?: string;
+}> = [
+  { decision: { kind: "deny", reason: "blocked" }, effect: "deny", message: "blocked" },
+  { decision: { kind: "ask", reason: "confirm" }, effect: "ask", message: "confirm" },
+  { decision: { kind: "allow" }, effect: "allow" },
+  { decision: { kind: "advisory", message: "hint" }, effect: "allow", message: "hint" },
+  { decision: { kind: "post_block", reason: "post" }, effect: "deny", message: "post" },
+  {
+    decision: { kind: "runtime_failure", reason: "fail", code: "parse" },
+    effect: "deny",
+    message: "fail",
+  },
+];
+
+for (const { decision, effect, message } of decisionCases) {
+  test(`AC-4: applyDecisionToPermission ${decision.kind}`, () => {
+    const ev = event();
+    applyDecisionToPermission(decision, ev);
+    expect(ev.effect).toBe(effect);
+    if (message !== undefined) {
+      expect(ev.message).toBe(message);
+    }
+  });
+}

package/src/adapter/evaluate.ts

@@ -0,0 +1,54 @@
+/** permission.hook("evaluate") handler backed by runPreToolBridge (#204). */
+import { runPreToolBridge } from "@toolu/core/bridge";
+import type { BashRunner } from "@toolu/core/runner";
+import {
+  applyDecisionToPermission,
+  mapPermissionEventToBridge,
+  type PermissionBridgeContext,
+  type PermissionEvaluationEvent,
+} from "./permission-map.ts";
+
+export type PermissionEvaluateHandlerOptions = {
+  repoRoot: string;
+  bridgeContext: PermissionBridgeContext;
+  runner?: BashRunner;
+  env?: Record<string, string>;
+};
+
+function runtimeFailureDeny(event: PermissionEvaluationEvent, reason: string): void {
+  applyDecisionToPermission({ kind: "runtime_failure", reason, code: "parse" }, event);
+}
+
+/** Handler for OpenCode permission.evaluate — real bash bridge, fail closed on errors. */
+export function createPermissionEvaluateHandler(
+  opts: PermissionEvaluateHandlerOptions,
+): (event: PermissionEvaluationEvent) => Promise<void> {
+  return async (event: PermissionEvaluationEvent): Promise<void> => {
+    const mapping = mapPermissionEventToBridge(event, opts.bridgeContext);
+    if (mapping.kind === "skip") {
+      return;
+    }
+    if (mapping.kind === "deny") {
+      applyDecisionToPermission({ kind: "deny", reason: mapping.reason }, event);
+      return;
+    }
+
+    const response = await runPreToolBridge(mapping.request, {
+      repoRoot: opts.repoRoot,
+      ...(opts.runner !== undefined ? { runner: opts.runner } : {}),
+      ...(opts.env !== undefined ? { env: opts.env } : {}),
+    });
+
+    applyDecisionToPermission(response.decision, event);
+  };
+}
+
+/** Fail-closed evaluate handler when bootstrap/preflight is NotReady. */
+export function createDenyAllPermissionHandler(
+  reason: string,
+): (event: PermissionEvaluationEvent) => Promise<void> {
+  return (event: PermissionEvaluationEvent): Promise<void> => {
+    runtimeFailureDeny(event, reason);
+    return Promise.resolve();
+  };
+}

package/src/adapter/permission-map.ts

@@ -0,0 +1,177 @@
+/** OpenCode permission.evaluate ↔ portable bridge (#204). */
+import type { BridgeRequest } from "@toolu/core/bridge";
+import type { Decision } from "@toolu/core/decision";
+
+export type PermissionEffect = "allow" | "ask" | "deny";
+
+/** OpenCode-shaped permission evaluation event (mutable effect for hook handlers). */
+export type PermissionEvaluationEvent = {
+  readonly sessionID: string;
+  readonly agent?: string;
+  readonly action: string;
+  readonly resources: ReadonlyArray<string>;
+  readonly metadata?: Record<string, unknown>;
+  effect: PermissionEffect;
+  message?: string;
+};
+
+export type PermissionBridgeContext = {
+  cwd: string;
+  projectRoot: string;
+  worktree: string;
+  host: string;
+  deadlineMs?: number;
+  maxStdoutBytes?: number;
+};
+
+export type PermissionBridgeMapping =
+  | { kind: "skip" }
+  | { kind: "request"; request: BridgeRequest }
+  | { kind: "deny"; reason: string };
+
+type GatedAction = {
+  toolName: string;
+  inputKind: "file" | "shell";
+};
+
+const GATED: Record<string, GatedAction> = {
+  edit: { toolName: "Edit", inputKind: "file" },
+  write: { toolName: "Write", inputKind: "file" },
+  bash: { toolName: "Bash", inputKind: "shell" },
+  shell: { toolName: "Shell", inputKind: "shell" },
+};
+
+const DEFAULT_DEADLINE_MS = 15_000;
+const DEFAULT_MAX_STDOUT_BYTES = 1_048_576;
+
+function normalizeAction(action: string): string {
+  return action.trim().toLowerCase();
+}
+
+function readString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  if (!meta) {
+    return undefined;
+  }
+  const value = meta[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function filePathFromEvent(event: PermissionEvaluationEvent): string | undefined {
+  const fromResource = event.resources[0];
+  if (typeof fromResource === "string" && fromResource.length > 0) {
+    return fromResource;
+  }
+  const meta = event.metadata;
+  return readString(meta, "file_path") ?? readString(meta, "filePath") ?? readString(meta, "path");
+}
+
+function commandFromEvent(event: PermissionEvaluationEvent): string | undefined {
+  const fromMeta = readString(event.metadata, "command");
+  if (fromMeta) {
+    return fromMeta;
+  }
+  const fromResource = event.resources[0];
+  return typeof fromResource === "string" && fromResource.length > 0 ? fromResource : undefined;
+}
+
+function toolCallId(event: PermissionEvaluationEvent): string {
+  const meta = event.metadata;
+  const fromMeta = readString(meta, "toolCallId") ?? readString(meta, "tool_call_id");
+  if (fromMeta) {
+    return fromMeta;
+  }
+  const source = meta?.source;
+  if (typeof source === "object" && source !== null && !Array.isArray(source)) {
+    const sourceRecord: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(source)) {
+      sourceRecord[key] = value;
+    }
+    const fromSource = readString(sourceRecord, "id");
+    if (fromSource) {
+      return fromSource;
+    }
+  }
+  return `perm_${event.sessionID}`;
+}
+
+/** Map a permission.evaluate payload to a bridge tool/pre request, or skip/deny when incomplete. */
+export function mapPermissionEventToBridge(
+  event: PermissionEvaluationEvent,
+  ctx: PermissionBridgeContext,
+): PermissionBridgeMapping {
+  const gated = GATED[normalizeAction(event.action)];
+  if (!gated) {
+    return { kind: "skip" };
+  }
+
+  let toolInput: Record<string, unknown>;
+  if (gated.inputKind === "file") {
+    const filePath = filePathFromEvent(event);
+    if (!filePath) {
+      return {
+        kind: "deny",
+        reason: `toolu: ${event.action} permission missing file path (resources or metadata)`,
+      };
+    }
+    toolInput = { file_path: filePath };
+  } else {
+    const command = commandFromEvent(event);
+    if (!command) {
+      return {
+        kind: "deny",
+        reason: `toolu: ${event.action} permission missing shell command (metadata.command or resources)`,
+      };
+    }
+    toolInput = { command };
+  }
+
+  const request: BridgeRequest = {
+    protocolVersion: 1,
+    event: "tool/pre",
+    sessionId: event.sessionID,
+    toolCallId: toolCallId(event),
+    cwd: ctx.cwd,
+    projectRoot: ctx.projectRoot,
+    worktree: ctx.worktree,
+    toolName: gated.toolName,
+    toolInput,
+    host: ctx.host,
+    deadlineMs: ctx.deadlineMs ?? DEFAULT_DEADLINE_MS,
+    maxStdoutBytes: ctx.maxStdoutBytes ?? DEFAULT_MAX_STDOUT_BYTES,
+  };
+
+  return { kind: "request", request };
+}
+
+/** Apply a portable Decision onto an OpenCode permission evaluation (mutates event). */
+export function applyDecisionToPermission(
+  decision: Decision,
+  event: PermissionEvaluationEvent,
+): void {
+  switch (decision.kind) {
+    case "deny":
+      event.effect = "deny";
+      event.message = decision.reason;
+      return;
+    case "ask":
+      event.effect = "ask";
+      event.message = decision.reason;
+      return;
+    case "allow":
+      event.effect = "allow";
+      delete event.message;
+      return;
+    case "advisory":
+      event.effect = "allow";
+      event.message = decision.message;
+      return;
+    case "post_block":
+      event.effect = "deny";
+      event.message = decision.reason;
+      return;
+    case "runtime_failure":
+      event.effect = "deny";
+      event.message = decision.reason;
+      return;
+  }
+}

package/src/bootstrap/__tests__/bootstrap.test.ts

@@ -0,0 +1,148 @@
+import { expect, test } from "bun:test";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bootstrapRuntime } from "../runtime.ts";
+import { bootstrapWithNoOpRunner } from "../test-helpers.ts";
+import { listPluginManifests } from "../../inventory/scan.ts";
+import { selectPluginsWithDependencies } from "../../select/resolve.ts";
+import { opencodePluginSelectionPath } from "../../host/roots.ts";
+const tmpBase = process.env.TMPDIR ?? "/tmp";
+
+function repoRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "../../../../..");
+}
+
+function isolatedHome(): string {
+  return mkdtempSync(join(tmpBase, "toolu-oc-home-"));
+}
+
+test("AC-4: exit 0 without output artifacts is NotReady", async () => {
+  const project = mkdtempSync(join(tmpBase, "toolu-bs-nr-"));
+  const dataRoot = mkdtempSync(join(tmpBase, "toolu-bs-nr-data-"));
+  const pluginsRoot = join(repoRoot(), "plugins");
+  const manifests = listPluginManifests(pluginsRoot);
+  const toolu = manifests?.find((m) => m.name === "toolu");
+  expect(toolu).toBeDefined();
+  if (!toolu) {
+    return;
+  }
+  const result = await bootstrapWithNoOpRunner({
+    repoRoot: repoRoot(),
+    projectRoot: project,
+    dataRoot,
+    plugins: [toolu],
+    isolatedHome: isolatedHome(),
+  });
+  expect(result.status).toBe("not-ready");
+});
+
+test("AC-3: two project roots do not share bootstrap state", async () => {
+  const root = repoRoot();
+  const pluginsRoot = join(root, "plugins");
+  const projectA = mkdtempSync(join(tmpBase, "toolu-bs-a-"));
+  const projectB = mkdtempSync(join(tmpBase, "toolu-bs-b-"));
+  mkdirSync(join(projectA, ".opencode", "toolu"), { recursive: true });
+  mkdirSync(join(projectB, ".opencode", "toolu"), { recursive: true });
+  writeFileSync(
+    opencodePluginSelectionPath(projectA),
+    JSON.stringify({ version: 1, enabled: ["ts-quality"] }),
+  );
+  writeFileSync(
+    opencodePluginSelectionPath(projectB),
+    JSON.stringify({ version: 1, enabled: ["ts-quality"] }),
+  );
+  const selectA = selectPluginsWithDependencies(pluginsRoot, projectA);
+  const selectB = selectPluginsWithDependencies(pluginsRoot, projectB);
+  expect(selectA.ok && selectB.ok).toBe(true);
+  if (!selectA.ok || !selectB.ok) {
+    return;
+  }
+
+  const dataA = join(projectA, ".opencode", "toolu", "state");
+  const dataB = join(projectB, ".opencode", "toolu", "state");
+  const homeA = isolatedHome();
+  const homeB = isolatedHome();
+
+  const resultA = await bootstrapRuntime({
+    repoRoot: root,
+    projectRoot: projectA,
+    dataRoot: dataA,
+    plugins: selectA.plugins,
+    isolatedHome: homeA,
+  });
+  const resultB = await bootstrapRuntime({
+    repoRoot: root,
+    projectRoot: projectB,
+    dataRoot: dataB,
+    plugins: selectB.plugins,
+    isolatedHome: homeB,
+  });
+  expect(resultA.status).toBe("ready");
+  expect(resultB.status).toBe("ready");
+  if (resultA.status !== "ready" || resultB.status !== "ready") {
+    return;
+  }
+  const postA = resultA.artifacts.find((a) => /\/post-tools\.d\/[^/]+\.sh$/.test(a));
+  const postB = resultB.artifacts.find((a) => /\/post-tools\.d\/[^/]+\.sh$/.test(a));
+  expect(postA).toBeDefined();
+  expect(postB).toBeDefined();
+  if (!postA || !postB) {
+    return;
+  }
+  expect(postA.startsWith(dataA + "/")).toBe(true);
+  expect(postB.startsWith(dataB + "/")).toBe(true);
+  expect(postA).not.toBe(postB);
+  expect(readFileSync(postA, "utf8").length).toBeGreaterThan(0);
+  expect(existsSync(join(dataA, "toolu"))).toBe(true);
+  expect(existsSync(join(dataB, "toolu"))).toBe(true);
+});
+
+test("AC-1: core-only session-start and core+quality register bootstrap", async () => {
+  const root = repoRoot();
+  const pluginsRoot = join(root, "plugins");
+  const projectCore = mkdtempSync(join(tmpBase, "toolu-bs-core-"));
+  mkdirSync(join(projectCore, ".opencode", "toolu"), { recursive: true });
+  writeFileSync(
+    opencodePluginSelectionPath(projectCore),
+    JSON.stringify({ version: 1, enabled: ["toolu"] }),
+  );
+  const coreSelect = selectPluginsWithDependencies(pluginsRoot, projectCore);
+  expect(coreSelect.ok).toBe(true);
+  if (!coreSelect.ok) {
+    return;
+  }
+  const coreData = mkdtempSync(join(tmpBase, "toolu-bs-core-data-"));
+  const coreResult = await bootstrapRuntime({
+    repoRoot: root,
+    projectRoot: projectCore,
+    dataRoot: coreData,
+    plugins: coreSelect.plugins,
+    isolatedHome: isolatedHome(),
+  });
+  expect(coreResult.status).toBe("ready");
+
+  const projectBoth = mkdtempSync(join(tmpBase, "toolu-bs-both-"));
+  mkdirSync(join(projectBoth, ".opencode", "toolu"), { recursive: true });
+  writeFileSync(
+    opencodePluginSelectionPath(projectBoth),
+    JSON.stringify({ version: 1, enabled: ["toolu", "ts-quality"] }),
+  );
+  const bothSelect = selectPluginsWithDependencies(pluginsRoot, projectBoth);
+  expect(bothSelect.ok).toBe(true);
+  if (!bothSelect.ok) {
+    return;
+  }
+  const bothData = mkdtempSync(join(tmpBase, "toolu-bs-both-data-"));
+  const bothResult = await bootstrapRuntime({
+    repoRoot: root,
+    projectRoot: projectBoth,
+    dataRoot: bothData,
+    plugins: bothSelect.plugins,
+    isolatedHome: isolatedHome(),
+  });
+  expect(bothResult.status).toBe("ready");
+  if (bothResult.status === "ready") {
+    expect(bothResult.artifacts.some((a) => /\/post-tools\.d\/[^/]+\.sh$/.test(a))).toBe(true);
+  }
+});

package/src/bootstrap/entrypoint.ts

@@ -0,0 +1,18 @@
+/** Discover SessionStart / register entrypoints per plugin (#211).
+ * Prefer hooks/register.sh; fall back to toolu's hooks/session-start.sh.
+ * Missing both → null (caller skips; not every plugin registers).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function pluginBootstrapScript(pluginDir: string): string | null {
+  const register = join(pluginDir, "hooks", "register.sh");
+  if (existsSync(register)) {
+    return register;
+  }
+  const sessionStart = join(pluginDir, "hooks", "session-start.sh");
+  if (existsSync(sessionStart)) {
+    return sessionStart;
+  }
+  return null;
+}

package/src/bootstrap/index.ts

@@ -0,0 +1,5 @@
+export { bootstrapRuntime } from "./runtime.ts";
+export type { BootstrapRuntimeOptions } from "./runtime.ts";
+export { collectBootstrapArtifacts, evaluateBootstrapReadiness } from "./readiness.ts";
+export { pluginBootstrapScript } from "./entrypoint.ts";
+export { bootstrapWithNoOpRunner, createNoOpRunner } from "./test-helpers.ts";