@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/index.ts

@@ -0,0 +1,318 @@
+/**
+ * `@arnilo/prism-tools/coding` — the first-party coding tools as a package.
+ *
+ * The default export registers the file, search, and shell tools (`read`, `write`, `edit`, `grep`,
+ * `glob`, `shell` with `shell_output`, plus `delete`/`move` when the shell is unavailable, or the
+ * read subset with `readOnly: true`), the
+ * structured git tools, `coding_check` when checks are configured, `todo_write` with its `run.end`
+ * continuation, and `ask_user_decision` over `host.ui`.
+ *
+ * Root escapes, read-only violations, and configured `commandRules` denies are hard-denied through
+ * one `tool.call` decide handler, so they hold under any approval mode or host `allow` hook. A
+ * durable-effect tool fails closed without a host principal. The `coding.targets` service reports the
+ * paths and roots of each own-tool call for approval.
+ *
+ * ```ts
+ * import toolsCoding from "@arnilo/prism-tools/coding";
+ * import { createAgent } from "@arnilo/prism";
+ *
+ * const agent = await createAgent({ model, packages: [toolsCoding({ root: process.cwd() })] });
+ * ```
+ */
+
+import { resolve } from "node:path";
+import { definePackage, type PackageInstance, type ToolDefinition } from "@arnilo/prism";
+import manifest from "../../package.json" with { type: "json" };
+import { createAskUserDecisionTool } from "./agent/ask-user-decision.js";
+import { createCodingCheckTool } from "./agent/checks.js";
+import { createDiagnosticsTool, type DiagnosticsToolHandle } from "./agent/diagnostics-tool.js";
+import type { ForgeCredentialResolverSource } from "./agent/forge/index.js";
+import { createGitTools } from "./agent/git-tools.js";
+import { createCodingTools, createReadOnlyTools, type ProcessSandboxBackend, type ToolsOptions } from "./agent/index.js";
+import { getShellConfig } from "./agent/shell.js";
+import { createBackgroundProcesses } from "./agent/shell-background.js";
+import { createTodoContinuationDecision, createTodoWriteTool } from "./agent/todo.js";
+import { createAskUserHostHook } from "./ask-user-host.js";
+import { type ToolsCodingCommandRule, type ToolsCodingConfig, toolsCodingConfigSchema } from "./config.js";
+import { createHardDenyHook } from "./hard-deny.js";
+import { withDurablePrincipal } from "./principal-guard.js";
+import { type CodingSandboxKind, selectCodingSandbox } from "./sandbox.js";
+import { type CommandRule } from "./security/command-rules.js";
+import { createEgressPolicy } from "./security/egress/index.js";
+import { createCodingTargets } from "./targets.js";
+import { createWorkspaceService, createWorktreeRouting, type WorkspaceService, WorkspaceServiceError } from "./workspace/index.js";
+
+// The moved agent and security surfaces keep their names, now behind one entry point.
+export * from "./agent/index.js";
+export { type AskUserHostHookOptions, createAskUserHostHook } from "./ask-user-host.js";
+export type {
+  ToolsCodingCommandRule,
+  ToolsCodingConfig,
+  ToolsCodingEgressConfig,
+  ToolsCodingEgressRule,
+  ToolsCodingForgeConfig,
+  ToolsCodingGitConfig,
+  ToolsCodingLanguageConfig,
+  ToolsCodingLanguageServerConfig,
+  ToolsCodingPrincipalConfig,
+  ToolsCodingRepositoryConfig,
+  ToolsCodingShellConfig,
+  ToolsCodingTodoConfig,
+  ToolsCodingWorkspaceConfig,
+} from "./config.js";
+export { toolsCodingConfigSchema } from "./config.js";
+export { createHardDenyHook, type HardDenyOptions } from "./hard-deny.js";
+export {
+  durablePrincipalError,
+  ERR_PRISM_CODING_PRINCIPAL_MISMATCH,
+  ERR_PRISM_CODING_PRINCIPAL_REQUIRED,
+  isDurableCall,
+  withDurablePrincipal,
+} from "./principal-guard.js";
+export { type CodingSandboxKind, type SelectedCodingSandbox, selectCodingSandbox } from "./sandbox.js";
+export * from "./security/index.js";
+export { CODING_TOOL_NAMES, type CodingTargets, type CodingTargetsFn, createCodingTargets } from "./targets.js";
+export * from "./workspace/index.js";
+
+function toCommandRules(rules: readonly ToolsCodingCommandRule[] | undefined): readonly CommandRule[] {
+  return (rules ?? []).map((rule) => ({
+    pattern: rule.match,
+    action: rule.decision,
+    ...(rule.reason !== undefined ? { reason: rule.reason } : {}),
+  }));
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** The `coding.forge` service: a ref-only credential source a forge adapter resolves per call. */
+export interface CodingForgeService {
+  readonly name: string;
+  readonly resolver: ForgeCredentialResolverSource["resolver"];
+}
+
+const definition = definePackage<ToolsCodingConfig>({
+  name: "@arnilo/prism-tools/coding",
+  version: manifest.version,
+  description:
+    "File, search, shell, git, check, todo, and ask-user coding tools with declared effects, in-tool containment, and tool.call hard denies.",
+  requires: { api: 1 },
+  capabilities: ["host-ui", "credentials"],
+  config: toolsCodingConfigSchema,
+  setup: async (prism) => {
+    const root = prism.config.root;
+    if (typeof root !== "string" || root.length === 0) {
+      throw new Error("prism-tools-coding: config needs root (the workspace root the file tools operate in)");
+    }
+    const readOnly = prism.config.readOnly === true;
+    const commandRules = toCommandRules(prism.config.commandRules);
+    const sandbox: CodingSandboxKind = prism.config.sandbox ?? "none";
+    const principalId = prism.config.principal?.id;
+
+    if (prism.config.egress !== undefined) {
+      try {
+        createEgressPolicy({
+          allow: prism.config.egress.allow?.map((rule) => ({
+            host: rule.host,
+            port: rule.port,
+            protocol: rule.protocol ?? "https",
+            ...(rule.allowPrivate !== undefined ? { allowPrivate: rule.allowPrivate } : {}),
+          })),
+          presets: prism.config.egress.presets,
+        });
+      } catch (error) {
+        throw new Error(`prism-tools-coding: invalid egress config: ${errorMessage(error)}`);
+      }
+      if (sandbox === "none") {
+        prism.status.note("warn", "egress config has no effect without a sandbox backend");
+      }
+    }
+
+    const options: ToolsOptions = {};
+    if (prism.config.repository !== undefined) options.repository = prism.config.repository;
+    if (prism.config.shell?.timeoutMs !== undefined) options.shell = { timeout: prism.config.shell.timeoutMs / 1000 };
+
+    let toolRoot = resolve(root);
+    let shellAvailable = prism.config.shell?.enabled !== false;
+    let sandboxTools: readonly ToolDefinition[] | undefined;
+    let processBackend: ProcessSandboxBackend | undefined;
+
+    if (sandbox !== "none") {
+      const selected = await selectCodingSandbox(sandbox, { root, repository: prism.config.repository, readOnly });
+      if (selected.tools !== undefined) {
+        sandboxTools = selected.tools;
+        toolRoot = selected.toolRoot;
+        processBackend = selected.processes;
+      } else {
+        for (const warning of selected.warnings) prism.status.note("warn", warning);
+        shellAvailable = false;
+      }
+    }
+
+    // `delete`/`move` are the no-shell substitutes (plan 189 Task 8), so the set depends on this.
+    options.shellAvailable = shellAvailable;
+
+    // Background processes (plan 189 Task 9): one lazy runtime shared by every worktree's tool set.
+    // Nothing is constructed in the process library until the first background call.
+    const background =
+      shellAvailable && !readOnly && (sandbox === "none" || processBackend !== undefined)
+        ? createBackgroundProcesses({
+            maxProcesses: prism.config.shell?.background?.maxProcesses,
+            shell: getShellConfig(),
+            ...(processBackend !== undefined ? { sandbox: processBackend } : {}),
+          })
+        : undefined;
+    if (background !== undefined) options.shell = { ...(options.shell ?? {}), background };
+
+    // `diagnostics` (plan 189 Task 10): opt-in, one language workspace per cwd, servers start on the
+    // first call. Handles stay in the map so a disposed tool can start its servers again.
+    const languageServers = prism.config.language?.servers;
+    const diagnosticsEnabled = languageServers !== undefined && Object.keys(languageServers).length > 0;
+    if (diagnosticsEnabled && sandbox !== "none") {
+      prism.status.note("warn", "language servers run on the host, outside the sandbox");
+    }
+    const diagnosticsByCwd = new Map<string, DiagnosticsToolHandle>();
+    const diagnosticsTool = (cwd: string): ToolDefinition => {
+      let handle = diagnosticsByCwd.get(cwd);
+      if (handle === undefined) {
+        handle = createDiagnosticsTool(cwd, {
+          servers: languageServers ?? {},
+          onServerFailure: (server, message) => prism.status.note("warn", `language server ${server}: ${message}`),
+        });
+        diagnosticsByCwd.set(cwd, handle);
+      }
+      return handle.tool;
+    };
+
+    /**
+     * The cwd-taking tools for one directory: `toolRoot` at setup, and once per worktree for a
+     * session bound to one (plan 165 Task 7). A sandbox backend's own set is not per-cwd.
+     */
+    const cwdTools = (cwd: string): readonly ToolDefinition[] => {
+      if (sandboxTools !== undefined) {
+        return diagnosticsEnabled ? [...sandboxTools, diagnosticsTool(cwd)] : sandboxTools;
+      }
+      let set = readOnly ? createReadOnlyTools(cwd, options) : createCodingTools(cwd, options);
+      // Git and checks can mutate, so read-only mode keeps exactly the four read tools.
+      if (!readOnly) {
+        if (prism.config.git?.enabled !== false) set = [...set, ...createGitTools(cwd, options)];
+        if (prism.config.checks !== undefined && Object.keys(prism.config.checks).length > 0) {
+          set = [...set, createCodingCheckTool(cwd, { checks: prism.config.checks })];
+        }
+      }
+      if (!shellAvailable) set = set.filter((tool) => tool.name !== "shell");
+      return diagnosticsEnabled ? [...set, diagnosticsTool(cwd)] : set;
+    };
+
+    let tools = cwdTools(toolRoot);
+
+    // Todo and ask_user take no cwd, so they are registered once rather than once per worktree.
+    if (!readOnly) {
+      const todoEnabled = prism.config.todo?.enabled !== false;
+      if (todoEnabled) tools = [...tools, createTodoWriteTool()];
+      if (todoEnabled && prism.config.todo?.continueOnOpen !== false) {
+        prism.hooks.on(
+          "run.end",
+          createTodoContinuationDecision({
+            onNoProgressStop: (info) =>
+              prism.events.emit("todo.no-progress-stop", { open: info.openTodos.length, noProgress: info.noProgress }),
+          }),
+          { id: "todo" },
+        );
+      }
+      const ui = prism.host.ui;
+      tools = [...tools, createAskUserDecisionTool({ ui })];
+      prism.hooks.on("tool.call", createAskUserHostHook({ ui }), { id: "ask-user" });
+    }
+
+    let workspaceService: WorkspaceService | undefined;
+    if (prism.config.workspace?.enabled !== false) {
+      try {
+        const workspace = await createWorkspaceService({
+          root: toolRoot,
+          sandboxed: sandbox !== "none",
+          ...(prism.config.workspace?.worktreeRoot !== undefined ? { worktreeRoot: prism.config.workspace.worktreeRoot } : {}),
+          ...(prism.config.workspace?.maxWorktrees !== undefined ? { maxWorktrees: prism.config.workspace.maxWorktrees } : {}),
+          ...(prism.config.workspace?.diff !== undefined ? { diff: prism.config.workspace.diff } : {}),
+        });
+        workspaceService = workspace;
+        prism.services.provide("workspace", workspace);
+      } catch (error) {
+        // Outside a git repository there is no worktree to hand out; say so and serve no service.
+        if (error instanceof WorkspaceServiceError && error.code === "workspace_not_git") {
+          prism.status.note("info", `workspace service unavailable: ${error.message}`);
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    // Approval and the hard-deny hook follow the session's worktree, when it has one.
+    const targets = createCodingTargets(toolRoot, prism.config.roots ?? [], workspaceService, () => prism.skills.list());
+    prism.services.provide("coding.targets", targets);
+    prism.hooks.on("tool.call", createHardDenyHook({ targets, readOnly, commandRules }), { id: "hard-deny" });
+
+    // One routing wrapper at registration: a bound session's tools run in its worktree.
+    const routing =
+      workspaceService !== undefined && sandboxTools === undefined
+        ? createWorktreeRouting({ base: tools, create: cwdTools, workspace: workspaceService })
+        : undefined;
+    if (routing !== undefined) {
+      prism.hooks.on("session.closed", (event) => routing.forget(event.sessionId), { id: "workspace-routing" });
+    }
+
+    if (prism.config.forge !== undefined) {
+      const ref = prism.config.forge.token;
+      const service: CodingForgeService = {
+        name: "github",
+        resolver: {
+          resolve: async () => await prism.credentials.resolve(ref),
+        },
+      };
+      prism.services.provide("coding.forge", service);
+    }
+
+    if (diagnosticsEnabled) {
+      const open = new Set<string>();
+      prism.hooks.on(
+        "session.opened",
+        (event) => {
+          open.add(event.sessionId);
+        },
+        { id: "language-open" },
+      );
+      prism.hooks.on(
+        "session.closed",
+        (event) => {
+          open.delete(event.sessionId);
+          if (open.size > 0) return;
+          for (const handle of diagnosticsByCwd.values()) void handle.dispose();
+        },
+        { id: "language-servers" },
+      );
+    }
+
+    let shellRegistered = false;
+    for (const tool of routing?.tools ?? tools) {
+      if (!shellAvailable && tool.name === "shell") continue;
+      if (tool.name === "shell") shellRegistered = true;
+      prism.tools.register(withDurablePrincipal(tool, principalId));
+    }
+    if (background !== undefined && shellRegistered) {
+      // `shell_output` itself is part of the shell tool set; this is only the kill switch.
+      prism.hooks.on("session.closed", (event) => background.killSession(event.sessionId), { id: "shell-background" });
+    }
+    if (sandbox === "none" && shellRegistered) {
+      prism.status.note("warn", "shell runs on the host without a sandbox; pair it with @arnilo/prism-extensions/approval or set sandbox");
+    }
+  },
+});
+
+/** The package definition. Pass config through `packageConfig` or use {@link toolsCoding}. */
+export default definition;
+
+/** The package with config baked in, for `packages: [toolsCoding({ root })]`. */
+export function toolsCoding(config: ToolsCodingConfig): PackageInstance {
+  return definition(config);
+}

package/coding/src/principal-guard.ts

@@ -0,0 +1,84 @@
+/**
+ * Durable-effect principal guard (plan 154 Task 5, decision (f)).
+ *
+ * A tool whose declared effect is not `none` mutates local or external state. Without a host
+ * principal there is no identity to attribute the mutation to, so the call fails closed with
+ * `ERR_PRISM_CODING_PRINCIPAL_REQUIRED`. When the package config pins `principal.id`, a call
+ * whose `ctx.principal.id` differs fails with `ERR_PRISM_CODING_PRINCIPAL_MISMATCH`. Read-only
+ * calls (and the read-only git actions, whose classifier returns `none`) need no principal.
+ *
+ * Verification of the principal stays with `governance` (Phase 9); this only refuses an
+ * unattributable or misattributed durable mutation.
+ */
+import type { JsonObject, ToolDefinition, ToolEffectDeclaration, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+
+/** A tool with a durable effect ran on an agent that has no host principal; pass `principal` to `createAgent`. */
+export const ERR_PRISM_CODING_PRINCIPAL_REQUIRED = "ERR_PRISM_CODING_PRINCIPAL_REQUIRED" as const;
+/** The call's principal id differs from the `principal.id` the package config pins. */
+export const ERR_PRISM_CODING_PRINCIPAL_MISMATCH = "ERR_PRISM_CODING_PRINCIPAL_MISMATCH" as const;
+
+/** Whether one call's declared effect is durable. A classifier that throws fails closed. */
+export function isDurableCall(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): boolean {
+  const effect = tool.effect;
+  if (effect === undefined) return false;
+  if (typeof effect === "function") {
+    try {
+      return effect(args, context).kind !== "none";
+    } catch {
+      return true;
+    }
+  }
+  return (effect as ToolEffectDeclaration).kind !== "none";
+}
+
+function principalError(toolCallId: string, toolName: string, code: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: toolName,
+    content: [{ type: "text", text: message }],
+    error: { code, message },
+  };
+}
+
+/**
+ * The error result for a durable call without a matching principal, or `undefined` when the call
+ * may proceed. `expectedId` is the package-configured `principal.id`, when set.
+ */
+export function durablePrincipalError(
+  tool: ToolDefinition,
+  args: JsonObject,
+  context: ToolExecutionContext,
+  expectedId?: string,
+): ToolResult | undefined {
+  if (!isDurableCall(tool, args, context)) return undefined;
+  const principal = context.principal;
+  if (principal === undefined || typeof principal.id !== "string" || principal.id.length === 0) {
+    return principalError(
+      context.toolCallId,
+      tool.name,
+      ERR_PRISM_CODING_PRINCIPAL_REQUIRED,
+      `${tool.name} has a durable effect and requires a principal`,
+    );
+  }
+  if (expectedId !== undefined && principal.id !== expectedId) {
+    return principalError(
+      context.toolCallId,
+      tool.name,
+      ERR_PRISM_CODING_PRINCIPAL_MISMATCH,
+      `${tool.name} principal does not match the configured principal`,
+    );
+  }
+  return undefined;
+}
+
+/** Wrap a tool so a durable call fails closed before it executes. Non-durable calls pass through. */
+export function withDurablePrincipal(tool: ToolDefinition, expectedId?: string): ToolDefinition {
+  return {
+    ...tool,
+    async execute(args, context): Promise<ToolResult> {
+      const error = durablePrincipalError(tool, args, context, expectedId);
+      if (error !== undefined) return error;
+      return await tool.execute(args, context);
+    },
+  };
+}

package/coding/src/sandbox.ts

@@ -0,0 +1,92 @@
+/**
+ * Config-selected sandbox backend for the shell and file operations.
+ *
+ * `none` (default) runs locally. `native` builds the in-repo `unshare` backend. `e2b` is reached
+ * only through `createE2BSandbox`, which imports the optional `e2b` peer dynamically. `docker`
+ * needs a host-provided digest-pinned image and runner, which a JSON config cannot carry, so it
+ * fails closed. Any backend that cannot be built yields a warning and no `shell` registration —
+ * never a throw and never a silent unsandboxed shell.
+ */
+import { resolve } from "node:path";
+import type { ToolDefinition } from "@arnilo/prism";
+import type { ProcessSandboxBackend } from "./agent/process/types.js";
+import type { RepositoryLimitOptions } from "./agent/repository/types.js";
+import { createE2BSandbox } from "./security/e2b-sandbox.js";
+import { createNativeSandbox } from "./security/native-sandbox.js";
+import type { SandboxAdapter } from "./security/sandbox.js";
+import { createSandboxCodingComposition, createSandboxReadOnlyComposition } from "./security/sandbox-coding-operations.js";
+
+export type CodingSandboxKind = "none" | "native" | "docker" | "e2b";
+
+export interface SelectCodingSandboxOptions {
+  readonly root: string;
+  readonly repository?: RepositoryLimitOptions;
+  readonly readOnly: boolean;
+}
+
+export interface SelectedCodingSandbox {
+  /** Sandbox-backed tools, or absent when the backend could not be built. */
+  readonly tools?: readonly ToolDefinition[];
+  /** The cwd the tools operate in (`/workspace` for container backends, the host root for native). */
+  readonly toolRoot: string;
+  /**
+   * The same adapter when it can start a long-running process (plan 189 Task 9). Absent means
+   * `background` stays out of the `shell` schema and `shell_output` is not registered — the
+   * native backend implements one-shot exec only.
+   */
+  readonly processes?: ProcessSandboxBackend;
+  readonly warnings: readonly string[];
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function buildAdapter(kind: Exclude<CodingSandboxKind, "none">, root: string): Promise<SandboxAdapter> {
+  if (kind === "native") return createNativeSandbox({ root: resolve(root) });
+  if (kind === "e2b") return createE2BSandbox({});
+  throw new Error('sandbox "docker" needs a host-provided digest-pinned image and docker runner');
+}
+
+/** Build the selected backend. Never throws: a failure becomes a warning and no tools. */
+export async function selectCodingSandbox(
+  kind: Exclude<CodingSandboxKind, "none">,
+  options: SelectCodingSandboxOptions,
+): Promise<SelectedCodingSandbox> {
+  let adapter: SandboxAdapter;
+  try {
+    adapter = await buildAdapter(kind, options.root);
+  } catch (error) {
+    return { toolRoot: resolve(options.root), warnings: [`sandbox "${kind}" unavailable: ${message(error)}; shell is not registered`] };
+  }
+  // Native's sandbox root IS the host workspace; container backends observe `/workspace`.
+  const workspaceRoot = kind === "native" ? resolve(options.root) : undefined;
+  try {
+    const composition = options.readOnly
+      ? createSandboxReadOnlyComposition(options.root, {
+          workspaceMode: "sandbox",
+          sandbox: adapter,
+          ...(workspaceRoot ? { workspaceRoot } : {}),
+          repository: options.repository,
+        })
+      : createSandboxCodingComposition(options.root, {
+          workspaceMode: "sandbox",
+          sandbox: adapter,
+          ...(workspaceRoot ? { workspaceRoot } : {}),
+          repository: options.repository,
+        });
+    const processes =
+      typeof (adapter as ProcessSandboxBackend).startProcess === "function" ? (adapter as ProcessSandboxBackend) : undefined;
+    return {
+      tools: composition.tools,
+      toolRoot: workspaceRoot ?? "/workspace",
+      ...(processes !== undefined ? { processes } : {}),
+      warnings: [...composition.composition.warnings],
+    };
+  } catch (error) {
+    return {
+      toolRoot: resolve(options.root),
+      warnings: [`sandbox "${kind}" could not be wired: ${message(error)}; shell is not registered`],
+    };
+  }
+}

package/coding/src/security/approval.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import type { ExecutionAction, ExecutionDecision, ExecutionPolicy } from "../agent/execution-policy.js";
+import { type CommandRule, evaluateCommandRules } from "./command-rules.js";
+import { assertPathInsideRoots } from "./path-containment.js";
+
+export interface CodingApprovalRequest {
+  readonly action: ExecutionAction;
+  readonly signal?: AbortSignal;
+}
+
+export type CodingApprovalFn = (request: CodingApprovalRequest) => boolean | Promise<boolean>;
+
+export type ApprovalCacheScope = "session" | "run" | "none";
+
+export interface CodingApprovalPolicyOptions {
+  readonly roots: readonly string[];
+  readonly approve?: CodingApprovalFn;
+  readonly readOnly?: boolean;
+  readonly commandRules?: readonly CommandRule[];
+  readonly approvalCacheScope?: ApprovalCacheScope;
+  readonly approvalTimeoutMs?: number;
+  /** When true (default), shell metacharacters require approval. */
+  readonly denyMetacharacters?: boolean;
+}
+
+const MAX_APPROVAL_CACHE_ENTRIES = 1_000;
+
+function isMutatingKind(kind: string): boolean {
+  return kind === "shell" || kind === "write" || kind === "edit" || kind === "delete" || kind === "move";
+}
+
+function approvalCacheKey(action: ExecutionAction, scope: Exclude<ApprovalCacheScope, "none">): string | undefined {
+  const identity = action.metadata?.[scope === "run" ? "runId" : "sessionId"];
+  if (typeof identity !== "string" || identity.length === 0) return undefined;
+  return createHash("sha256")
+    .update(JSON.stringify([scope, identity, action.kind, action.operation, action.paths ?? [], action.command ?? ""]))
+    .digest("hex");
+}
+
+function cacheApproval(cache: Map<string, boolean>, key: string, approved: boolean): void {
+  if (!cache.has(key) && cache.size >= MAX_APPROVAL_CACHE_ENTRIES) {
+    cache.delete(cache.keys().next().value!);
+  }
+  cache.set(key, approved);
+}
+
+function readAbortSignal(action: ExecutionAction): AbortSignal | undefined {
+  const signal = action.metadata?.signal;
+  return signal instanceof AbortSignal ? signal : undefined;
+}
+
+async function waitForApproval(approve: CodingApprovalFn, request: CodingApprovalRequest, timeoutMs: number | undefined): Promise<boolean> {
+  if (request.signal?.aborted) return false;
+
+  const approvePromise = Promise.resolve(approve(request));
+  if (!timeoutMs || timeoutMs <= 0) return approvePromise;
+
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    const finish = (value: boolean) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    const onAbort = () => finish(false);
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      request.signal?.removeEventListener("abort", onAbort);
+    };
+    request.signal?.addEventListener("abort", onAbort, { once: true });
+    approvePromise.then(finish, () => finish(false));
+  });
+}
+
+export function createCodingApprovalPolicy(options: CodingApprovalPolicyOptions): ExecutionPolicy {
+  const scope = options.approvalCacheScope ?? "none";
+  const cache = scope === "none" ? undefined : new Map<string, boolean>();
+
+  return {
+    async check(action: ExecutionAction): Promise<ExecutionDecision> {
+      if (options.roots.length === 0) {
+        return { allowed: false, reason: "no trusted roots configured" };
+      }
+
+      if (options.readOnly && action.kind !== "read") {
+        return { allowed: false, reason: "read-only mode" };
+      }
+
+      for (const path of action.paths ?? []) {
+        if (!(await assertPathInsideRoots(options.roots, path))) {
+          return { allowed: false, reason: `path outside trusted roots: ${path}` };
+        }
+      }
+
+      let needsApproval = isMutatingKind(action.kind);
+
+      if (action.kind === "shell" && action.command) {
+        const evaluation = evaluateCommandRules(action.command, options.commandRules, {
+          denyMetacharacters: options.denyMetacharacters,
+        });
+        if (evaluation.action === "deny") {
+          return {
+            allowed: false,
+            reason: evaluation.reason ?? "command denied by policy",
+          };
+        }
+        if (evaluation.action === "requireApproval") {
+          needsApproval = true;
+        }
+      }
+
+      if (needsApproval) {
+        if (!options.approve) {
+          return { allowed: false, reason: "approval required" };
+        }
+
+        const key = scope === "none" ? undefined : approvalCacheKey(action, scope);
+        if (key !== undefined && cache?.has(key)) {
+          const cached = cache.get(key);
+          if (!cached) {
+            return { allowed: false, reason: "approval denied (cached)" };
+          }
+        } else {
+          const approved = await waitForApproval(
+            options.approve,
+            { action, signal: readAbortSignal(action) },
+            options.approvalTimeoutMs ?? 30_000,
+          );
+          if (key !== undefined && cache) cacheApproval(cache, key, approved);
+          if (!approved) {
+            return { allowed: false, reason: "approval denied" };
+          }
+        }
+      }
+
+      return {
+        allowed: true,
+        exclusive: action.kind === "shell",
+      };
+    },
+  };
+}