@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/write.ts

@@ -0,0 +1,170 @@
+/**
+ * Write tool: create or overwrite a file on the host filesystem.
+ *
+ * Behavioral port of pi's core/tools/write for @arnilo/prism-tools/coding, adapted to Prism's
+ * `ToolDefinition` contract. Faithfully ports the create-parent-dirs → write → serialize-per-path
+ * flow. Drops pi's TUI (`renderCall`/`renderResult`, the incremental syntax-highlight cache, key hints).
+ *
+ * Deviations from pi (documented):
+ *  - **Confirmation message carries the absolute path + real byte count + line count** (pi returns the
+ *    caller-supplied path and `content.length`, which is a UTF-16 *code-unit* count mislabeled "bytes").
+ *    The plan's acceptance criteria call for absolute path + byte/line counts; this is strictly more
+ *    informative and the byte count is now UTF-8-correct.
+ *  - Abort + all fs failures return a Prism `error` result (pi throws/rejects). Abort is checked before
+ *    each filesystem operation (mkdir, writeFile); if the write completes it is reported as success
+ *    (pi would throw "Operation aborted" even after a successful write — misleading, so dropped).
+ */
+import { Buffer } from "node:buffer";
+import { mkdir as fsMkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { atomicWriteUtf8File } from "./atomic-write.js";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import type { CodingLifecycleEvent } from "./lifecycle-events.js";
+import { DEFAULT_MAX_WRITE_BYTES, HARD_MAX_WRITE_BYTES, validateCodingLimit } from "./limits.js";
+import { resolveToCwd } from "./path-utils.js";
+import { type ReadBeforeWriteOptions, refuseReadBeforeWrite } from "./read-path-set.js";
+
+/**
+ * Pluggable operations for the write tool. Override to delegate file writing to remote systems
+ * (e.g. SSH) while keeping the tool's directory-creation + per-path serialization behavior.
+ */
+export interface WriteOperations {
+  /** Write content to a file (creating or overwriting). */
+  writeFile: (absolutePath: string, content: string, options?: { maxBytes: number; signal?: AbortSignal }) => Promise<void>;
+  /** Create a directory recursively. */
+  mkdir: (dir: string, options?: { signal?: AbortSignal }) => Promise<void>;
+}
+
+export interface WriteToolOptions extends ReadBeforeWriteOptions {
+  /** Structured pre-execution policy checked before filesystem writes. */
+  executionPolicy?: ExecutionPolicy;
+  /** Custom operations backend (default: local filesystem). */
+  operations?: WriteOperations;
+  /** Maximum UTF-8 input bytes accepted before any filesystem mutation (default 8 MiB). */
+  maxInputBytes?: number;
+  /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+  onEvent?: (event: CodingLifecycleEvent) => void;
+}
+
+const defaultWriteOperations: WriteOperations = {
+  writeFile: (path, content, options) => atomicWriteUtf8File(path, content, { signal: options?.signal }),
+  mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),
+};
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "write",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  return content.split("\n").length;
+}
+
+export function createWriteTool(cwd: string, options?: WriteToolOptions): ToolDefinition {
+  const ops = options?.operations ?? defaultWriteOperations;
+  const maxInputBytes = validateCodingLimit("maxInputBytes", options?.maxInputBytes ?? DEFAULT_MAX_WRITE_BYTES, HARD_MAX_WRITE_BYTES);
+  const guard = options?.requireReadBeforeWrite === true;
+
+  return {
+    name: "write",
+    kind: "edit",
+    effect: CODING_LOCAL_EFFECT,
+    effects: ["write"],
+    description: `Create or overwrite a file (full replace). Creates parent directories. Prefer edit for targeted changes.${guard ? " Read the path first or pass force=true to override the host's read-before-write guard." : ""}`,
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file to write (relative or absolute)" },
+        content: { type: "string", description: "Content to write to the file" },
+        ...(guard
+          ? {
+              force: {
+                type: "boolean",
+                description: "Bypass the read-before-write guard for this call.",
+              },
+            }
+          : {}),
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+
+      const path = typeof args.path === "string" ? args.path : "";
+      const content = typeof args.content === "string" ? args.content : undefined;
+      const force = args.force === true;
+
+      if (path.length === 0) {
+        return errorResult(toolCallId, "path is required and must be a non-empty string.");
+      }
+      if (content === undefined) {
+        return errorResult(toolCallId, "content is required and must be a string.");
+      }
+      const bytes = Buffer.byteLength(content, "utf-8");
+      if (bytes > maxInputBytes) {
+        return errorResult(toolCallId, `Write input is ${bytes} bytes, exceeds ${maxInputBytes} byte limit.`);
+      }
+
+      try {
+        const absolutePath = resolveToCwd(path, cwd);
+
+        const policyCheck = await enforceExecutionPolicy(
+          options?.executionPolicy,
+          {
+            kind: "write",
+            operation: "write",
+            paths: [absolutePath],
+            risk: "medium",
+            metadata: { bytes, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+          },
+          toolCallId,
+          "write",
+          (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }),
+        );
+        if (!policyCheck.allowed) return policyCheck.result;
+        const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+
+        const rbwRefusal = refuseReadBeforeWrite("write", path, allowedPath, options, force);
+        if (rbwRefusal) return errorResult(toolCallId, rbwRefusal);
+
+        const dir = dirname(allowedPath);
+
+        return await withFileMutationQueue(allowedPath, async () => {
+          // Check abort before each fs op — do not start a new operation once aborted. We intentionally
+          // do NOT throw from an abort listener: that could release the mutation queue mid-operation.
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+          await ops.mkdir(dir, { signal: context.signal });
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+          await ops.writeFile(allowedPath, content, { maxBytes: maxInputBytes, signal: context.signal });
+          options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "write", toolCallId });
+
+          const lines = countLines(content);
+          return {
+            toolCallId,
+            name: "write",
+            content: [
+              {
+                type: "text",
+                text: `Successfully wrote ${bytes} bytes (${lines} lines) to ${allowedPath}`,
+              },
+            ],
+            metadata: { bytes, lines, path: allowedPath },
+          };
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult(toolCallId, message);
+      }
+    },
+  };
+}

package/coding/src/ask-user-host.ts

@@ -0,0 +1,48 @@
+/**
+ * The `ask_user_decision` host gate (plan 154 Task 5).
+ *
+ * A `tool.call` decide handler owns the ask: it calls `host.ui` `select` (options, plus a custom
+ * sentinel when `allowCustom`) and `input` (a custom answer) and returns `{ respond }` with the
+ * resulting tool result. When the host answers `unavailable` — or no UI is attached — it returns
+ * `{ ask }`; the tool's `elicitation` contract then carries the answer schema and the kernel
+ * suspends the run, so `session.resume(decisions)` delivers the answer without executing the tool.
+ * `dismissed` becomes a declined tool result and never allows a fabricated choice.
+ */
+import type { HostUi, ToolCallDecision, ToolCallHookPayload } from "@arnilo/prism";
+import {
+  ASK_USER_DECISION_TOOL_NAME,
+  askUserDecisionViaUi,
+  parseAskUserDecisionArgs,
+  resolveAskUserDecisionLimits,
+} from "./agent/ask-user-decision.js";
+
+export interface AskUserHostHookOptions {
+  /** The host UI port, when one is attached. */
+  readonly ui?: HostUi;
+}
+
+/** Build the `ask_user_decision` gate. It ignores every other tool and never throws. */
+export function createAskUserHostHook(
+  options: AskUserHostHookOptions,
+): (payload: ToolCallHookPayload) => Promise<ToolCallDecision | undefined> {
+  const limits = resolveAskUserDecisionLimits();
+  return async (payload) => {
+    if (payload.name !== ASK_USER_DECISION_TOOL_NAME) return undefined;
+    let parsed: ReturnType<typeof parseAskUserDecisionArgs>;
+    try {
+      parsed = parseAskUserDecisionArgs(payload.args, limits);
+    } catch {
+      // Malformed args: let `execute` report the parse error rather than suspend on a bad question.
+      return undefined;
+    }
+    if (options.ui === undefined) return { ask: parsed.question };
+    try {
+      const outcome = await askUserDecisionViaUi(options.ui, parsed, limits, payload.callId);
+      if (outcome.kind === "unavailable") return { ask: parsed.question };
+      return { respond: outcome.result };
+    } catch {
+      // A throwing host UI cannot answer: suspend instead of denying or fabricating a choice.
+      return { ask: parsed.question };
+    }
+  };
+}

package/coding/src/config.ts

@@ -0,0 +1,278 @@
+import type { JsonSchema } from "@arnilo/prism";
+
+import type { NamedCheckDefinition } from "./agent/checks.js";
+import type { RepositoryLimitOptions } from "./agent/repository/types.js";
+import type { CodingSandboxKind } from "./sandbox.js";
+
+/** Shell tool settings. `enabled: false` registers every other tool but not `shell`. */
+export interface ToolsCodingShellConfig {
+  /** Default `true`. When `false`, `shell` is not registered. */
+  readonly enabled?: boolean;
+  /** Default wall timeout in milliseconds. Converted to the tool's seconds option. */
+  readonly timeoutMs?: number;
+  /** Background processes from `shell({ background: true })` (plan 189 Task 9). */
+  readonly background?: ToolsCodingShellBackgroundConfig;
+}
+
+/** Background-process settings. `shell_output` reads, waits on, and kills these. */
+export interface ToolsCodingShellBackgroundConfig {
+  /** Live background processes per session. Default 4, hard 16. */
+  readonly maxProcesses?: number;
+}
+
+/** One JSON command rule. `match` is a substring or a `/pattern/` string. */
+export interface ToolsCodingCommandRule {
+  readonly match: string;
+  readonly decision: "allow" | "deny" | "requireApproval";
+  readonly reason?: string;
+}
+
+/** One egress allow entry, as `createEgressPolicy` accepts it. */
+export interface ToolsCodingEgressRule {
+  readonly host: string;
+  readonly port: number;
+  readonly protocol?: "http" | "https";
+  readonly allowPrivate?: boolean;
+}
+
+/** Egress allow-list for sandboxed shells. Validated with `createEgressPolicy`. */
+export interface ToolsCodingEgressConfig {
+  readonly allow?: readonly ToolsCodingEgressRule[];
+  readonly presets?: readonly ("npm-registry" | "github")[];
+}
+
+/** One language server. Mirrors `LanguageServerSpec`; the model never supplies `command`. */
+export interface ToolsCodingLanguageServerConfig {
+  readonly command: string;
+  readonly args?: readonly string[];
+  /** LSP language ids the server handles (`typescript`, `typescriptreact`, `python`, …). */
+  readonly languages: readonly string[];
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+/** Language servers behind the opt-in `diagnostics` tool. No servers means no tool. */
+export interface ToolsCodingLanguageConfig {
+  readonly servers?: Readonly<Record<string, ToolsCodingLanguageServerConfig>>;
+}
+
+/** Structured git tools. `enabled: false` registers no `git_*` tool. Default `{ enabled: true }`. */
+export interface ToolsCodingGitConfig {
+  readonly enabled?: boolean;
+}
+
+/** `todo_write` and its `run.end` continuation. `continueOnOpen: false` keeps the tool, drops the hook. */
+export interface ToolsCodingTodoConfig {
+  readonly enabled?: boolean;
+  readonly continueOnOpen?: boolean;
+}
+
+/** The `workspace` service: disposable git worktrees for delegated coding work (plan 165 Task 6). */
+export interface ToolsCodingWorkspaceConfig {
+  /** Default `true`. When `false`, no `workspace` service is provided. */
+  readonly enabled?: boolean;
+  /** Where worktrees are created. Default: a per-repository directory under the OS temp dir. */
+  readonly worktreeRoot?: string;
+  /** Maximum active worktrees. Default 4, hard cap 16. */
+  readonly maxWorktrees?: number;
+  /** `diff` bounds. Defaults 200 files and 1 MiB per file. */
+  readonly diff?: {
+    readonly maxFiles?: number;
+    readonly maxBytes?: number;
+  };
+}
+
+/** The principal durable-effect tools require. Opaque; governance verifies it in Phase 9. */
+export interface ToolsCodingPrincipalConfig {
+  readonly id: string;
+}
+
+/** Forge credential ref (never a literal). Resolved through `prism.credentials.resolve`. */
+export interface ToolsCodingForgeConfig {
+  /** `env:NAME` or `keyring:NAME`; a literal fails config validation. */
+  readonly token: string;
+}
+
+/** Shared repository limits for `grep` and `glob`. */
+export type ToolsCodingRepositoryConfig = RepositoryLimitOptions;
+
+/** Validated `packageConfig` for `@arnilo/prism-tools/coding`. */
+export interface ToolsCodingConfig {
+  /** The workspace root the file tools operate in. Required; checked in `setup` with a naming error. */
+  readonly root: string;
+  /** Extra roots that the `coding.targets` service (Task 4) reports alongside `root`. */
+  readonly roots?: readonly string[];
+  /** Registers only `read`, `grep`, and `glob`. Default `false`. */
+  readonly readOnly?: boolean;
+  readonly shell?: ToolsCodingShellConfig;
+  readonly repository?: ToolsCodingRepositoryConfig;
+  /** Structured git tools. Default `{ enabled: true }`. */
+  readonly git?: ToolsCodingGitConfig;
+  /** Language servers for the opt-in `diagnostics` tool. Default: none. */
+  readonly language?: ToolsCodingLanguageConfig;
+  /** Named check commands for `coding_check`. No checks means no tool. */
+  readonly checks?: Readonly<Record<string, NamedCheckDefinition>>;
+  /** `todo_write` plus the `run.end` continuation. Default `{ enabled: true, continueOnOpen: true }`. */
+  readonly todo?: ToolsCodingTodoConfig;
+  /** Principal durable-effect tools require; when absent they fail closed. */
+  readonly principal?: ToolsCodingPrincipalConfig;
+  /** Forge credential ref; resolved only through `prism.credentials.resolve`. */
+  readonly forge?: ToolsCodingForgeConfig;
+  /** Shell/file backend. Default `"none"` (local). `docker` fails closed without host wiring. */
+  readonly sandbox?: CodingSandboxKind;
+  /** Hard-deny command rules for `shell`; a `deny` decision wins over any approval. */
+  readonly commandRules?: readonly ToolsCodingCommandRule[];
+  /** Egress allow-list for sandboxed shells. */
+  readonly egress?: ToolsCodingEgressConfig;
+  /** Disposable git worktrees for delegated coding work. Default `{ enabled: true }`. */
+  readonly workspace?: ToolsCodingWorkspaceConfig;
+}
+
+const repositoryProperties: Readonly<Record<string, JsonSchema>> = {
+  maxDepth: { type: "number", minimum: 1 },
+  maxEntries: { type: "number", minimum: 1 },
+  maxFiles: { type: "number", minimum: 1 },
+  maxResults: { type: "number", minimum: 1 },
+  maxConcurrency: { type: "number", minimum: 1 },
+  maxScanBytes: { type: "number", minimum: 1 },
+  maxFileBytes: { type: "number", minimum: 1 },
+  maxMatches: { type: "number", minimum: 1 },
+  maxPatternBytes: { type: "number", minimum: 1 },
+  maxLineBytes: { type: "number", minimum: 1 },
+  maxContextLines: { type: "number", minimum: 0 },
+  maxTimeMs: { type: "number", minimum: 1 },
+  exclude: { type: "array", items: { type: "string", minLength: 1 } },
+};
+
+/**
+ * The config schema. `root` is deliberately not declared `required`: a required field with no
+ * default would fail package conformance, so `setup` checks it and names the field instead
+ * (plan 152 Task 6's config rule).
+ */
+export const toolsCodingConfigSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    root: { type: "string", minLength: 1, maxLength: 4096 },
+    roots: { type: "array", items: { type: "string", minLength: 1, maxLength: 4096 }, maxItems: 64 },
+    readOnly: { type: "boolean", default: false },
+    shell: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean", default: true },
+        timeoutMs: { type: "number", minimum: 1, maximum: 3_600_000 },
+        background: {
+          type: "object",
+          properties: {
+            maxProcesses: { type: "number", minimum: 1, maximum: 16, default: 4 },
+          },
+        },
+      },
+    },
+    language: {
+      type: "object",
+      properties: {
+        servers: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              command: { type: "string", minLength: 1, maxLength: 4096 },
+              args: { type: "array", maxItems: 64, items: { type: "string", maxLength: 4096 } },
+              languages: { type: "array", minItems: 1, maxItems: 32, items: { type: "string", minLength: 1, maxLength: 64 } },
+              env: { type: "object", additionalProperties: { type: "string", maxLength: 4096 } },
+            },
+            required: ["command", "languages"],
+          },
+        },
+      },
+    },
+    repository: { type: "object", properties: repositoryProperties },
+    git: {
+      type: "object",
+      properties: { enabled: { type: "boolean", default: true } },
+    },
+    checks: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        properties: {
+          file: { type: "string", minLength: 1, maxLength: 4096 },
+          args: { type: "array", maxItems: 256, items: { type: "string", maxLength: 4096 } },
+          cwd: { type: "string", minLength: 1, maxLength: 4096 },
+          env: { type: "object", additionalProperties: { type: "string", maxLength: 4096 } },
+          timeoutMs: { type: "number", minimum: 1, maximum: 3_600_000 },
+        },
+        required: ["file", "args"],
+      },
+    },
+    todo: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean", default: true },
+        continueOnOpen: { type: "boolean", default: true },
+      },
+    },
+    principal: {
+      type: "object",
+      properties: { id: { type: "string", minLength: 1, maxLength: 256 } },
+    },
+    forge: {
+      type: "object",
+      properties: {
+        token: {
+          type: "string",
+          minLength: 1,
+          maxLength: 4096,
+          "x-prism-secret": true,
+          description: "An `env:` or `keyring:` ref the credentials slot resolves. A literal token is rejected.",
+        },
+      },
+    },
+    sandbox: { type: "string", enum: ["none", "native", "docker", "e2b"], default: "none" },
+    workspace: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean", default: true },
+        worktreeRoot: { type: "string", minLength: 1, maxLength: 4096 },
+        maxWorktrees: { type: "number", minimum: 1, maximum: 16 },
+        diff: {
+          type: "object",
+          properties: {
+            maxFiles: { type: "number", minimum: 1, maximum: 2000 },
+            maxBytes: { type: "number", minimum: 1, maximum: 8_388_608 },
+          },
+        },
+      },
+    },
+    commandRules: {
+      type: "array",
+      maxItems: 256,
+      items: {
+        type: "object",
+        properties: {
+          match: { type: "string", minLength: 1, maxLength: 4096 },
+          decision: { type: "string", enum: ["allow", "deny", "requireApproval"] },
+          reason: { type: "string", maxLength: 512 },
+        },
+      },
+    },
+    egress: {
+      type: "object",
+      properties: {
+        allow: {
+          type: "array",
+          maxItems: 1024,
+          items: {
+            type: "object",
+            properties: {
+              host: { type: "string", minLength: 1, maxLength: 253 },
+              port: { type: "number", minimum: 1, maximum: 65_535 },
+              protocol: { type: "string", enum: ["http", "https"] },
+              allowPrivate: { type: "boolean", default: false },
+            },
+          },
+        },
+        presets: { type: "array", maxItems: 8, items: { type: "string", enum: ["npm-registry", "github"] } },
+      },
+    },
+  },
+};

package/coding/src/hard-deny.ts

@@ -0,0 +1,97 @@
+/**
+ * Hard denies for this package's own tools, through one `tool.call` decide handler.
+ *
+ * The kernel's combination rule for `tool.call` is any-deny-wins, so these holds under
+ * `approval` `auto`, under a host `allow` hook, and from a custom loop. Reasons name the root
+ * and the tool, never file contents. Tools this package did not register are ignored. For
+ * read-effect tools, `targets.roots` also carries each skill directory; mutating tools never do.
+ */
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import type { ToolCallDecision, ToolCallHookPayload } from "@arnilo/prism";
+import { type CommandRule, evaluateCommandRules } from "./security/command-rules.js";
+import { realpathNearest } from "./security/path-containment.js";
+import { CODING_TOOL_NAMES, type CodingTargetsFn } from "./targets.js";
+
+/** Tools that change state; denied when `readOnly` is set. */
+const MUTATING_TOOLS: ReadonlySet<string> = new Set(["write", "edit", "delete", "move", "shell"]);
+
+export interface HardDenyOptions {
+  readonly targets: CodingTargetsFn;
+  readonly readOnly: boolean;
+  readonly commandRules?: readonly CommandRule[];
+}
+
+function isPathInside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * A containment check that realpaths the roots once and then costs one `realpath` per path
+ * argument, with no directory walk. Fails closed when a root or the target cannot be resolved.
+ */
+function createContainmentChecker(roots: readonly string[]): (target: string) => Promise<boolean> {
+  let realRoots: Promise<readonly string[]> | undefined;
+  const loadRoots = () => {
+    realRoots ??= Promise.all(
+      roots.map(async (root) => {
+        try {
+          return await realpath(resolve(root));
+        } catch {
+          return undefined;
+        }
+      }),
+    ).then((resolved) => resolved.filter((root): root is string => root !== undefined));
+    return realRoots;
+  };
+  return async (target: string) => {
+    const resolved = await loadRoots();
+    if (resolved.length === 0) return false;
+    const to = await realpathNearest(target);
+    return to !== undefined && resolved.some((root) => isPathInside(root, to));
+  };
+}
+
+/** The `tool.call` decide handler. Returns `{ deny }` or `undefined`; never throws. */
+export function createHardDenyHook(options: HardDenyOptions) {
+  // Targets hand back the same frozen roots array while worktree and skill roots are unchanged, so
+  // the roots are realpathed once per array instead of once per decision.
+  const checkers = new WeakMap<readonly string[], (target: string) => Promise<boolean>>();
+  const checkerFor = (roots: readonly string[]) => {
+    let checker = checkers.get(roots);
+    if (checker === undefined) {
+      checker = createContainmentChecker(roots);
+      checkers.set(roots, checker);
+    }
+    return checker;
+  };
+  return async (payload: ToolCallHookPayload): Promise<ToolCallDecision | undefined> => {
+    if (!CODING_TOOL_NAMES.has(payload.name)) return undefined;
+    const targets = options.targets(payload.name, payload.args, { sessionId: payload.sessionId });
+    if (!targets) return undefined;
+
+    if (options.readOnly && MUTATING_TOOLS.has(payload.name)) {
+      return { deny: `${payload.name} denied: @arnilo/prism-tools/coding is read-only` };
+    }
+
+    if (targets.paths.length > 0) {
+      const contained = checkerFor(targets.roots);
+      for (const path of targets.paths) {
+        if (!(await contained(path))) {
+          return { deny: `${payload.name} denied: path outside coding roots (${targets.roots.join(", ")}): ${path}` };
+        }
+      }
+    }
+
+    if (payload.name === "shell") {
+      const command = typeof payload.args.command === "string" ? payload.args.command : "";
+      const evaluation = evaluateCommandRules(command, options.commandRules, { denyMetacharacters: false });
+      if (evaluation.action === "deny") {
+        return { deny: `shell denied: ${evaluation.reason ?? "command matches a deny rule"}` };
+      }
+    }
+
+    return undefined;
+  };
+}