pi-ward 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# pi-ward
+
+File access guard for [pi](https://github.com/earendil-works/pi). Declarative filesystem boundaries for the coding agent.
+
+## Installation
+
+```bash
+pi install npm:pi-ward
+```
+
+Or try without installing:
+
+```bash
+pi -e npm:pi-ward
+```
+
+## Why
+
+- Prevents the agent from reading secrets (`.env`, `.pem`, credentials)
+- Blocks writes outside the project tree
+- Stops accidental modification of `.git` internals
+- Symlink-aware — no escape via symlink tricks
+- Config-file self-protection — the agent can't weaken its own constraints
+- Fail-closed on any error — never fails open
+
+## How it works
+
+pi-ward intercepts file operations (`read`, `write`, `edit`) before they execute. It evaluates declarative rules from ward config files against the resolved real path.
+
+**Baseline policy** (no config needed):
+
+- Read/write within project root: allowed
+- Any access outside project root: denied
+
+## Config
+
+Rules are loaded from `~/.pi/agent/ward.json` (global) and `.pi/ward.json` files along the directory tree. Global rules always take precedence — inner configs can't weaken outer ones.
+
+Example `.pi/ward.json`:
+
+```json
+{
+  "rules": [
+    { "pattern": ".env*", "effect": "deny" },
+    { "pattern": "*.pem", "effect": "deny" },
+    { "pattern": ".git/", "operations": ["write"], "effect": "deny" },
+    { "pattern": ".secret/", "effect": "deny" }
+  ]
+}
+```
+
+Rules are evaluated top-to-bottom, first match wins. See [DESIGN.md](./DESIGN.md) for pattern syntax, trust scoping, and the full specification.
+
+## Design
+
+See [DESIGN.md](./DESIGN.md) for the full specification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ward",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "packageManager": "npm@11.12.1",
   "description": "File access guard for the pi coding agent — declarative filesystem boundaries.",
   "license": "MIT",
@@ -35,6 +35,9 @@
     "format": "biome format --write",
     "test": "vitest run"
   },
+  "dependencies": {
+    "typebox": "^1.1.38"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0"
   },

package/src/config.ts

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parsePattern } from "./pattern.js";
+import type { ParsedRule, Rule } from "./rules.js";
+import { ancestorDirs } from "./walk.js";
+
+export interface WardConfig {
+  rules: Rule[];
+}
+
+export interface LoadResult {
+  /** Flat list of parsed rules, global first, project last. */
+  rules: ParsedRule[];
+}
+
+/**
+ * Read and JSON-parse a config file.
+ * Returns null on ENOENT. Throws on EACCES or other read errors.
+ * Throws on invalid JSON.
+ */
+async function readConfigFile(filePath: string): Promise<WardConfig | null> {
+  let content: string;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") {
+      return null;
+    }
+    throw new Error(`Cannot read config file "${filePath}": ${(err as Error).message}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Invalid JSON in config file "${filePath}": ${(err as Error).message}`);
+  }
+
+  return validateConfig(raw, filePath);
+}
+
+/**
+ * Validate the raw parsed JSON against the expected WardConfig schema.
+ * Throws with a descriptive message (including file path) on any schema violation.
+ */
+function validateConfig(raw: unknown, filePath: string): WardConfig {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Config "${filePath}": must be a JSON object`);
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  if (!Array.isArray(obj.rules)) {
+    throw new Error(`Config "${filePath}": missing or invalid "rules" array`);
+  }
+
+  const rules = obj.rules.map((ruleRaw: unknown, i: number) => validateRule(ruleRaw, i, filePath));
+  return { rules };
+}
+
+function validateOperations(operations: unknown, index: number, filePath: string): ("read" | "write")[] {
+  if (!Array.isArray(operations)) {
+    throw new Error(`Config "${filePath}": rule[${index}].operations must be an array`);
+  }
+  for (const op of operations) {
+    if (op !== "read" && op !== "write") {
+      throw new Error(`Config "${filePath}": rule[${index}].operations contains invalid value "${String(op)}"`);
+    }
+  }
+  return operations as ("read" | "write")[];
+}
+
+function validateRule(ruleRaw: unknown, index: number, filePath: string): Rule {
+  if (typeof ruleRaw !== "object" || ruleRaw === null || Array.isArray(ruleRaw)) {
+    throw new Error(`Config "${filePath}": rule[${index}] must be an object`);
+  }
+  const r = ruleRaw as Record<string, unknown>;
+
+  if (typeof r.pattern !== "string") {
+    throw new Error(`Config "${filePath}": rule[${index}].pattern must be a string`);
+  }
+  if (r.effect !== "allow" && r.effect !== "deny") {
+    throw new Error(`Config "${filePath}": rule[${index}].effect must be "allow" or "deny"`);
+  }
+
+  let operations: ("read" | "write")[] | undefined;
+  if (r.operations !== undefined) {
+    operations = validateOperations(r.operations, index, filePath);
+  }
+
+  return {
+    pattern: r.pattern,
+    effect: r.effect,
+    ...(operations !== undefined ? { operations } : {}),
+  };
+}
+
+/**
+ * Parse validated rules into ParsedRules, attaching configDir and checking
+ * for allow rules that can structurally never match within the config's directory.
+ *
+ * Throws if:
+ * - parsePattern throws (invalid syntax)
+ * - An allow rule has an anchored pattern whose first segment is ".." (escapes config dir)
+ */
+function parseConfigRules(config: WardConfig, configDir: string, filePath: string): ParsedRule[] {
+  return config.rules.map((rule, i) => {
+    const parsedPattern = parsePattern(rule.pattern);
+
+    // Load-time trust check: an anchored allow pattern starting with ".." can never
+    // match within the config's directory.
+    if (rule.effect === "allow" && parsedPattern.anchored && parsedPattern.segments.length > 0) {
+      const firstSeg = parsedPattern.segments[0];
+      if (firstSeg.kind === "literal" && firstSeg.value === "..") {
+        throw new Error(
+          `Config "${filePath}": rule[${i}]: allow rule with pattern "${rule.pattern}" ` +
+            `can never match within the config directory "${configDir}"`,
+        );
+      }
+    }
+
+    return {
+      pattern: parsedPattern,
+      operations: rule.operations ?? ["read", "write"],
+      effect: rule.effect,
+      configDir,
+    };
+  });
+}
+
+/**
+ * Load all ward configs for a given project root.
+ *
+ * Walk order (global first, project last):
+ * 1. `~/.pi/agent/ward.json` — global config, configDir = homedir
+ * 2. `<dir>/.pi/ward.json` for each ancestor from homedir toward projectRoot
+ * 3. `projectRoot/.pi/ward.json` — project config, configDir = projectRoot
+ *
+ * If projectRoot is outside homedir, only the global config is loaded.
+ *
+ * ENOENT on any config file is silently skipped. Any other error fails closed.
+ */
+export async function loadConfig(projectRoot: string, homeDir?: string): Promise<LoadResult> {
+  const home = homeDir ?? homedir();
+  const allRules: ParsedRule[] = [];
+
+  // Step 1: global config — always attempted
+  const globalConfigPath = join(getAgentDir(), "ward.json");
+  const globalConfig = await readConfigFile(globalConfigPath);
+  if (globalConfig !== null) {
+    allRules.push(...parseConfigRules(globalConfig, home, globalConfigPath));
+  }
+
+  // Steps 2+3: walk ancestor directories from home to projectRoot (inclusive).
+  // ancestorDirs returns [] when projectRoot is outside home, so this is a no-op in that case.
+  const dirs = ancestorDirs(home, projectRoot);
+  for (const dir of dirs) {
+    const configPath = join(dir, ".pi", "ward.json");
+    const config = await readConfigFile(configPath);
+    if (config !== null) {
+      allRules.push(...parseConfigRules(config, dir, configPath));
+    }
+  }
+
+  return { rules: allRules };
+}

package/src/evaluator.ts

@@ -0,0 +1,50 @@
+import { isAbsolute } from "node:path";
+import { matches } from "./matcher.js";
+import type { Effect, Operation, ParsedRule } from "./rules.js";
+import { isDescendantOf } from "./walk.js";
+
+/**
+ * Evaluate access rules for a given operation on an absolute path.
+ *
+ * Rules are processed top-to-bottom (first-match-wins).
+ * Trust scoping: an `allow` rule only takes effect when the resolved path is
+ * at or below the rule's `configDir`.
+ *
+ * Baseline policy (when no rule matches):
+ * - Path at/below projectRoot → allow
+ * - Path outside projectRoot → deny
+ *
+ * @param rules       - Ordered list of parsed rules (global first, project last).
+ * @param operation   - The operation being attempted.
+ * @param absolutePath - The resolved absolute path being accessed.
+ * @param projectRoot - The session's working directory (resolved absolute path).
+ */
+export function evaluate(rules: ParsedRule[], operation: Operation, absolutePath: string, projectRoot: string): Effect {
+  if (!isAbsolute(absolutePath)) {
+    throw new Error(`evaluate: absolutePath must be absolute, got "${absolutePath}"`);
+  }
+  if (!isAbsolute(projectRoot)) {
+    throw new Error(`evaluate: projectRoot must be absolute, got "${projectRoot}"`);
+  }
+
+  for (const rule of rules) {
+    // 1. Operation must match.
+    if (!rule.operations.includes(operation)) continue;
+
+    // 2. Path must match the pattern.
+    if (!matches(rule.pattern, rule.configDir, absolutePath)) continue;
+
+    // 3. Trust scoping: allow rules are only effective within the config's directory.
+    if (rule.effect === "allow") {
+      if (!isDescendantOf(rule.configDir, absolutePath)) {
+        // Path is outside the config's directory — skip this allow rule.
+        continue;
+      }
+    }
+
+    return rule.effect;
+  }
+
+  // Baseline policy.
+  return isDescendantOf(projectRoot, absolutePath) ? "allow" : "deny";
+}

package/src/guard.ts

@@ -0,0 +1,48 @@
+import { evaluate } from "./evaluator.js";
+import { resolvePath } from "./resolve.js";
+import type { Operation, ParsedRule } from "./rules.js";
+import { isSelfProtected } from "./self-protect.js";
+
+/**
+ * Guard a tool call's path(s) against the configured rules.
+ *
+ * Returns `{ allowed: true }` when every path passes, or
+ * `{ allowed: false; reason: string }` with a formatted `[pi-ward] Blocked ...`
+ * message on the first path that fails.
+ */
+export async function guard(
+  toolName: string,
+  paths: string[],
+  operation: Operation,
+  rules: ParsedRule[],
+  projectRoot: string,
+  protectedPaths: string[],
+): Promise<{ allowed: true } | { allowed: false; reason: string }> {
+  for (const inputPath of paths) {
+    const resolved = await resolvePath(inputPath, projectRoot);
+
+    if (resolved.denied) {
+      return {
+        allowed: false,
+        reason: `[pi-ward] Blocked ${toolName} (${operation}) on ${inputPath}: ${resolved.denied}`,
+      };
+    }
+
+    if (operation === "write" && isSelfProtected(resolved.path, protectedPaths)) {
+      return {
+        allowed: false,
+        reason: `[pi-ward] Blocked ${toolName} (write) on ${inputPath}: ward config file is write-protected`,
+      };
+    }
+
+    const effect = evaluate(rules, operation, resolved.path, projectRoot);
+    if (effect === "deny") {
+      return {
+        allowed: false,
+        reason: `[pi-ward] Blocked ${toolName} (${operation}) on ${inputPath}: denied by policy`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}

package/src/index.ts

@@ -1,7 +1,76 @@
-import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import type { ExtensionFactory, ToolCallEvent } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "./config.js";
+import { guard } from "./guard.js";
+import type { Operation } from "./rules.js";
+import { getProtectedPaths, resolveProtectedPaths } from "./self-protect.js";
+import { createDeleteTool } from "./tools/delete.js";
 
-const factory: ExtensionFactory = async (_pi) => {
-  // TODO: load config, register file access guards
+/**
+ * Extract the guard operation and path list from a tool call event.
+ *
+ * Returns `{ operation, paths }` for tools that require access checks, or
+ * `null` for tools that should be ignored (e.g. bash).
+ */
+export function extractAccess(
+  event: ToolCallEvent,
+  projectRoot: string,
+): { operation: Operation; paths: string[] } | null {
+  if (isToolCallEventType("read", event)) {
+    return { operation: "read", paths: [event.input.path] };
+  }
+  if (isToolCallEventType("write", event)) {
+    return { operation: "write", paths: [event.input.path] };
+  }
+  if (isToolCallEventType("edit", event)) {
+    return { operation: "write", paths: [event.input.path] };
+  }
+  if (isToolCallEventType("grep", event)) {
+    return { operation: "read", paths: [event.input.path ?? projectRoot] };
+  }
+  if (isToolCallEventType("find", event)) {
+    return { operation: "read", paths: [event.input.path ?? projectRoot] };
+  }
+  if (isToolCallEventType("ls", event)) {
+    return { operation: "read", paths: [event.input.path ?? projectRoot] };
+  }
+  if (isToolCallEventType<"delete", { path: string }>("delete", event)) {
+    return { operation: "write", paths: [event.input.path] };
+  }
+  return null;
+}
+
+const factory: ExtensionFactory = async (pi) => {
+  const projectRoot = await realpath(process.cwd());
+  const homeDir = await realpath(homedir());
+  const { rules } = await loadConfig(projectRoot, homeDir);
+  const protectedPaths = await resolveProtectedPaths(getProtectedPaths(projectRoot, homeDir));
+
+  pi.registerTool(createDeleteTool(projectRoot));
+
+  pi.on("tool_call", async (event, _ctx) => {
+    try {
+      const dispatch = extractAccess(event, projectRoot);
+      if (dispatch === null) {
+        return undefined;
+      }
+
+      const { operation, paths } = dispatch;
+      const result = await guard(event.toolName, paths, operation, rules, projectRoot, protectedPaths);
+      if (!result.allowed) {
+        return { block: true, reason: result.reason };
+      }
+      return undefined;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        block: true,
+        reason: `[pi-ward] Internal error — access denied (fail-closed): ${message}`,
+      };
+    }
+  });
 };
 
 export default factory;

package/src/matcher.ts

@@ -0,0 +1,72 @@
+import { relative } from "node:path";
+import type { ParsedPattern, SegmentPattern } from "./pattern.js";
+import { isDescendantOf } from "./walk.js";
+
+function matchesSegment(pattern: SegmentPattern, segment: string): boolean {
+  const seg = segment.toLowerCase();
+  switch (pattern.kind) {
+    case "literal":
+      return seg === pattern.value.toLowerCase();
+
+    case "prefix":
+      // segment must start with prefix and have at least 1 more char (for the `*`)
+      return seg.startsWith(pattern.prefix.toLowerCase()) && seg.length > pattern.prefix.length;
+
+    case "suffix":
+      // segment must end with suffix and have at least 1 more char (for the `*`)
+      return seg.endsWith(pattern.suffix.toLowerCase()) && seg.length > pattern.suffix.length;
+
+    case "both":
+      // segment must start with prefix, end with suffix, with at least 1 char in between
+      return (
+        seg.startsWith(pattern.prefix.toLowerCase()) &&
+        seg.endsWith(pattern.suffix.toLowerCase()) &&
+        seg.length > pattern.prefix.length + pattern.suffix.length
+      );
+
+    case "wildcard":
+      // `*` matches one or more characters — any non-empty segment
+      return seg.length > 0;
+  }
+}
+
+function matchesAnchored(pattern: ParsedPattern, configDir: string, absolutePath: string): boolean {
+  const rel = relative(configDir, absolutePath);
+  if (!isDescendantOf(configDir, absolutePath)) return false;
+
+  // Segments of the relative path; empty array when absolutePath === configDir
+  const relSegments = rel === "" ? [] : rel.split(/[/\\]/).filter((s) => s !== "" && s !== ".");
+
+  if (pattern.segments.length === 0) return true;
+
+  const lengthOk = pattern.directory
+    ? relSegments.length >= pattern.segments.length
+    : relSegments.length === pattern.segments.length;
+  if (!lengthOk) return false;
+
+  return pattern.segments.every((seg, i) => matchesSegment(seg, relSegments[i]));
+}
+
+/**
+ * Determine whether an absolute path matches a parsed pattern.
+ *
+ * @param pattern   - The parsed pattern to match against.
+ * @param configDir - Absolute path to the directory the config governs
+ *                    (used for anchored patterns).
+ * @param absolutePath - The absolute path to test.
+ */
+export function matches(pattern: ParsedPattern, configDir: string, absolutePath: string): boolean {
+  if (pattern.anchored) return matchesAnchored(pattern, configDir, absolutePath);
+
+  // Unanchored: the pattern matches if ANY segment in the absolute path matches.
+  // For unanchored patterns, the `directory` flag has no additional effect at match time.
+  // Both `.secret` and `.secret/` match any path containing a segment that matches the pattern.
+  // The trailing `/` in `.secret/` is syntactic sugar indicating intent (this represents a directory),
+  // but the matching semantics are identical because segment matching inherently covers
+  // both the directory node and paths beneath it.
+  const segPattern = pattern.segments[0];
+  if (segPattern === undefined) return false;
+
+  const segments = absolutePath.split(/[/\\]/).filter((s) => s !== "");
+  return segments.some((seg) => matchesSegment(segPattern, seg));
+}

package/src/pattern.ts

@@ -0,0 +1,118 @@
+/**
+ * Describes how to match a single path segment.
+ * `*` matches one or more characters within the segment (never crosses `/`).
+ */
+export type SegmentPattern =
+  | { readonly kind: "literal"; readonly value: string }
+  | { readonly kind: "prefix"; readonly prefix: string }
+  | { readonly kind: "suffix"; readonly suffix: string }
+  | { readonly kind: "both"; readonly prefix: string; readonly suffix: string }
+  | { readonly kind: "wildcard" };
+
+/**
+ * Parsed representation of a ward pattern string.
+ */
+export interface ParsedPattern {
+  /** True if the pattern starts with "./" (anchored to the config directory). */
+  readonly anchored: boolean;
+  /** True if the pattern ends with "/" (directory match). */
+  readonly directory: boolean;
+  /**
+   * Segment patterns.
+   * - Unanchored: always one element.
+   * - Anchored with empty array: matches everything at/below the config dir (`./`).
+   * - Anchored non-empty: each element corresponds to a path segment relative to the config dir.
+   */
+  readonly segments: ReadonlyArray<SegmentPattern>;
+}
+
+function parseSegmentPattern(seg: string, rawPattern: string): SegmentPattern {
+  if (seg === "") {
+    throw new Error(`Invalid pattern: empty segment in "${rawPattern}"`);
+  }
+
+  const starCount = (seg.match(/\*/g) ?? []).length;
+
+  if (starCount === 0) {
+    return { kind: "literal", value: seg };
+  }
+
+  if (starCount === 1) {
+    if (seg === "*") return { kind: "wildcard" };
+
+    const starIdx = seg.indexOf("*");
+
+    if (starIdx === 0) {
+      // *.ext — suffix wildcard
+      return { kind: "suffix", suffix: seg.slice(1) };
+    }
+
+    if (starIdx === seg.length - 1) {
+      // foo* — prefix wildcard
+      return { kind: "prefix", prefix: seg.slice(0, -1) };
+    }
+
+    // foo*.ext — both
+    return {
+      kind: "both",
+      prefix: seg.slice(0, starIdx),
+      suffix: seg.slice(starIdx + 1),
+    };
+  }
+
+  throw new Error(`Invalid pattern: multiple wildcards in a single segment are not supported: "${rawPattern}"`);
+}
+
+function parseAnchored(body: string, directory: boolean, raw: string): ParsedPattern {
+  if (body === "") {
+    return { anchored: true, directory: true, segments: [] };
+  }
+  const segments = body.split("/").map((part) => parseSegmentPattern(part, raw));
+  return { anchored: true, directory, segments };
+}
+
+function parseUnanchored(body: string, directory: boolean, raw: string): ParsedPattern {
+  if (body === "") {
+    throw new Error(`Invalid pattern: empty pattern "${raw}"`);
+  }
+  if (body.includes("/")) {
+    throw new Error(
+      `Invalid pattern: unanchored pattern cannot contain "/": "${raw}". Use a "./" prefix for multi-segment patterns.`,
+    );
+  }
+  const segment = parseSegmentPattern(body, raw);
+  return { anchored: false, directory, segments: [segment] };
+}
+
+/**
+ * Parse a pattern string into a structured ParsedPattern.
+ *
+ * Syntax rules:
+ * - No prefix → unanchored single-segment pattern. Must not contain `/`.
+ * - `./` prefix → anchored to the config directory. May contain `/`.
+ * - Trailing `/` → directory match (the node itself and everything under it).
+ * - `*` → matches one or more characters within a segment (not `/`).
+ * - No `**`, braces, extglobs, or regex.
+ *
+ * @throws on invalid syntax.
+ */
+export function parsePattern(raw: string): ParsedPattern {
+  if (raw.includes("**")) {
+    throw new Error(`Invalid pattern: "**" is not supported: "${raw}"`);
+  }
+  if (raw.includes("{")) {
+    throw new Error(`Invalid pattern: braces are not supported: "${raw}"`);
+  }
+  if (raw.includes("}")) {
+    throw new Error(`Invalid pattern: braces are not supported: "${raw}"`);
+  }
+
+  const anchored = raw.startsWith("./");
+  const directory = raw.endsWith("/");
+
+  let inner = raw;
+  if (anchored) inner = inner.slice(2);
+  if (directory) inner = inner.slice(0, -1);
+
+  return anchored ? parseAnchored(inner, directory, raw) : parseUnanchored(inner, directory, raw);
+}

package/src/resolve.ts

@@ -0,0 +1,68 @@
+import { lstat, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+export interface ResolveResult {
+  /** Resolved absolute real path. Only meaningful when denied is not set. */
+  path: string;
+  /** If set, the path should be denied with this reason (before rule evaluation). */
+  denied?: string;
+}
+
+/**
+ * Handle the ENOENT case from realpath: distinguish a dangling symlink from a
+ * genuinely absent file (new-file write), then resolve the parent directory.
+ */
+async function resolveNewFile(normalized: string): Promise<ResolveResult> {
+  try {
+    await lstat(normalized);
+    // lstat succeeded but realpath failed — dangling/broken symlink.
+    return { path: normalized, denied: `Broken symlink at "${normalized}"` };
+  } catch (lstatErr) {
+    const lstatCode = (lstatErr as { code?: string }).code;
+    if (lstatCode !== "ENOENT") {
+      // lstat failed for a non-ENOENT reason (e.g. EACCES, ELOOP in path components).
+      return { path: normalized, denied: `Cannot resolve path "${normalized}": ${(lstatErr as Error).message}` };
+    }
+  }
+
+  // File genuinely doesn't exist — attempt to resolve the parent for new-file writes.
+  const parent = dirname(normalized);
+  const base = basename(normalized);
+  try {
+    const realParent = await realpath(parent);
+    return { path: resolve(realParent, base) };
+  } catch (parentErr) {
+    return {
+      path: normalized,
+      denied: `Cannot resolve path "${normalized}": ${(parentErr as Error).message}`,
+    };
+  }
+}
+
+/**
+ * Resolve an input path to its real absolute path.
+ *
+ * - Normalizes the path (resolves relative to projectRoot if not absolute).
+ * - Resolves symlinks via fs.realpath.
+ * - If the target doesn't exist (ENOENT):
+ *   - Checks lstat to distinguish broken symlinks from genuinely absent files.
+ *   - Broken/dangling symlink → denied.
+ *   - File doesn't exist (new file case) → tries parent directory.
+ *     - Parent resolves → returns parent + basename.
+ *     - Parent fails → denied.
+ * - Any other error → denied (fail-closed).
+ */
+export async function resolvePath(inputPath: string, projectRoot: string): Promise<ResolveResult> {
+  const normalized = isAbsolute(inputPath) ? inputPath : resolve(projectRoot, inputPath);
+
+  try {
+    const real = await realpath(normalized);
+    return { path: real };
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") {
+      return resolveNewFile(normalized);
+    }
+    return { path: normalized, denied: `Cannot resolve path "${normalized}": ${(err as Error).message}` };
+  }
+}

package/src/rules.ts

@@ -0,0 +1,19 @@
+import type { ParsedPattern } from "./pattern.js";
+
+export type Operation = "read" | "write";
+export type Effect = "allow" | "deny";
+
+export interface Rule {
+  pattern: string;
+  operations?: Operation[];
+  effect: Effect;
+}
+
+export interface ParsedRule {
+  pattern: ParsedPattern;
+  /** Always explicit — expanded from default (both) when omitted on the raw rule. */
+  operations: Operation[];
+  effect: Effect;
+  /** Absolute path to the directory this rule's config governs. */
+  configDir: string;
+}

package/src/self-protect.ts

@@ -0,0 +1,57 @@
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { ancestorDirs } from "./walk.js";
+
+/**
+ * Returns all ward config file paths that are always write-protected.
+ *
+ * Protected paths (mirrors the loadConfig walk order):
+ * - `~/.pi/agent/ward.json` (global config, always protected)
+ * - `<dir>/.pi/ward.json` for each directory from homedir to projectRoot (inclusive)
+ *
+ * If projectRoot is outside homedir, only the global config path is returned.
+ */
+export function getProtectedPaths(projectRoot: string, homeDir?: string): string[] {
+  const home = homeDir ?? homedir();
+
+  // Global config is always protected.
+  const paths = [join(getAgentDir(), "ward.json")];
+
+  // Walk ancestor directories from home to projectRoot (mirrors loadConfig walk).
+  // ancestorDirs returns [] when projectRoot is outside home, so this is a no-op in that case.
+  const dirs = ancestorDirs(home, projectRoot);
+  for (const dir of dirs) {
+    paths.push(join(dir, ".pi", "ward.json"));
+  }
+
+  return paths;
+}
+
+/**
+ * Resolves each protected path via realpath.
+ * On any error (ENOENT, EACCES, etc.), keeps the constructed path as a fallback
+ * so the path remains protected even when unresolvable.
+ */
+export async function resolveProtectedPaths(paths: string[]): Promise<string[]> {
+  const resolved: string[] = [];
+  for (const p of paths) {
+    try {
+      resolved.push(await realpath(p));
+    } catch {
+      resolved.push(p);
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Returns true if the given absolute path is a protected ward config file.
+ *
+ * Protected config files are always write-denied regardless of rules —
+ * the agent cannot modify its own access controls.
+ */
+export function isSelfProtected(absolutePath: string, protectedPaths: string[]): boolean {
+  return protectedPaths.includes(absolutePath);
+}

package/src/tools/delete.ts

@@ -0,0 +1,31 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export function createDeleteTool(projectRoot: string) {
+  return defineTool({
+    name: "delete",
+    label: "Delete",
+    description: "Delete a file or empty directory.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path to the file or empty directory to delete" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const target = resolve(projectRoot, params.path);
+      try {
+        await rm(target);
+        return {
+          content: [{ type: "text" as const, text: `Deleted: ${target}` }],
+          details: undefined,
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text" as const, text: `Error: ${message}` }],
+          details: undefined,
+        };
+      }
+    },
+  });
+}

package/src/walk.ts

@@ -0,0 +1,36 @@
+import { isAbsolute, join, relative } from "node:path";
+
+function isParentTraversal(rel: string): boolean {
+  return rel === ".." || rel.startsWith("../") || rel.startsWith("..\\");
+}
+
+/**
+ * Returns true if `target` is at or below `base` in the directory tree.
+ */
+export function isDescendantOf(base: string, target: string): boolean {
+  const rel = relative(base, target);
+  return !isAbsolute(rel) && !isParentTraversal(rel);
+}
+
+/**
+ * Compute ancestor directories from `home` toward `target`.
+ * Returns an array of directory paths in walk order (home first, target last).
+ * If target is not within home, returns an empty array.
+ */
+export function ancestorDirs(home: string, target: string): string[] {
+  if (!isDescendantOf(home, target)) {
+    return [];
+  }
+
+  const rel = relative(home, target);
+  // rel is "" when home === target, otherwise segments separated by OS sep
+  const segments = rel === "" ? [] : rel.split(/[/\\]/).filter((s) => s !== "");
+
+  const dirs: string[] = [home];
+  let current = home;
+  for (const seg of segments) {
+    current = join(current, seg);
+    dirs.push(current);
+  }
+  return dirs;
+}