@cortexkit/aft-pi 0.33.0 → 0.34.0

package/dist/index.js

@@ -13152,26 +13152,28 @@ function getManualInstallHint() {
 }
 async function ensureOnnxRuntime(storageDir) {
   const info = getPlatformInfo();
-  const ortDir = join6(storageDir, "onnxruntime", ORT_VERSION);
-  const libPath = join6(ortDir, info?.libName ?? "libonnxruntime.dylib");
+  const ortVersionDir = join6(storageDir, "onnxruntime", ORT_VERSION);
+  const libName = info?.libName ?? "libonnxruntime.dylib";
+  const resolvedOrtDir = resolveCachedOnnxRuntimeDir(ortVersionDir, libName);
+  const libPath = join6(resolvedOrtDir, libName);
   if (existsSync5(libPath)) {
-    const meta = readOnnxInstalledMeta(ortDir);
+    const meta = readOnnxInstalledMeta(ortVersionDir);
     if (meta?.sha256) {
       try {
         const currentHash = sha256File(libPath);
         if (currentHash !== meta.sha256) {
-          error(`ONNX Runtime at ${ortDir}: TOFU sha256 mismatch — refusing to use ` + `tampered binary. Recorded ${meta.sha256}, current ${currentHash}. ` + `Run \`aft doctor --clear\` to re-download from scratch.`);
+          error(`ONNX Runtime at ${resolvedOrtDir}: TOFU sha256 mismatch — refusing to use ` + `tampered binary. Recorded ${meta.sha256}, current ${currentHash}. ` + `Run \`aft doctor --clear\` to re-download from scratch.`);
         } else {
-          log(`ONNX Runtime found at ${ortDir} (TOFU verified)`);
-          return ortDir;
+          log(`ONNX Runtime found at ${resolvedOrtDir} (TOFU verified)`);
+          return resolvedOrtDir;
         }
       } catch (err) {
-        warn(`Could not verify ONNX Runtime hash at ${ortDir}: ${err}`);
-        return ortDir;
+        warn(`Could not verify ONNX Runtime hash at ${resolvedOrtDir}: ${err}`);
+        return resolvedOrtDir;
       }
     } else {
-      log(`ONNX Runtime found at ${ortDir} (no recorded hash, accepting)`);
-      return ortDir;
+      log(`ONNX Runtime found at ${resolvedOrtDir} (no recorded hash, accepting)`);
+      return resolvedOrtDir;
     }
   }
   const systemPath = findSystemOnnxRuntime(info?.libName);
@@ -13192,8 +13194,8 @@ async function ensureOnnxRuntime(storageDir) {
     return null;
   }
   try {
-    cleanupIncompleteTargetIfUnowned(ortDir);
-    return await downloadOnnxRuntime(info, ortDir);
+    cleanupIncompleteTargetIfUnowned(ortVersionDir);
+    return await downloadOnnxRuntime(info, ortVersionDir);
   } finally {
     releaseLock(lockPath);
   }
@@ -13211,11 +13213,16 @@ function cleanupAbandonedStagingDirs(onnxBaseDir) {
       let abandoned = false;
       if (Number.isFinite(pid) && pid > 0) {
         if (process.platform === "win32") {
-          try {
-            const ageMs = Date.now() - statSync2(stagingDir).mtimeMs;
-            abandoned = ageMs > STALE_LOCK_MS;
-          } catch {
+          const ownerAlive = isProcessAlive(pid);
+          if (!ownerAlive) {
             abandoned = true;
+          } else {
+            try {
+              const ageMs = Date.now() - statSync2(stagingDir).mtimeMs;
+              abandoned = ageMs > STALE_LOCK_MS;
+            } catch {
+              abandoned = true;
+            }
           }
         } else {
           abandoned = !isProcessAlive(pid);
@@ -13249,17 +13256,32 @@ var REQUIRED_ORT_MIN_MINOR = 20;
 var INVALID_ORT_VERSION = "<invalid>";
 function parseOnnxVersionFromPath(value) {
   const name = basename(value);
-  const semverish = name.match(/\.(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)(?:\.dylib)?$/);
+  const semverish = name.match(/(?:^|[._-])(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)(?:\.(?:dylib|dll))?$/);
   if (semverish)
     return semverish[1].split(/[-+]/, 1)[0];
   return /\d+\.\d+\.\d+/.test(name) ? INVALID_ORT_VERSION : null;
 }
+function parseOnnxVersionFromDirectoryPath(value) {
+  const parts = value.split(/[\\/]+/).filter(Boolean).reverse();
+  for (const part of parts) {
+    const version = parseOnnxVersionFromPath(part);
+    if (version)
+      return version;
+  }
+  return null;
+}
+function isPathInsideRoot(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || !rel.startsWith("../") && !rel.startsWith("..\\") && rel !== ".." && !isAbsolute(rel) && !win32.isAbsolute(rel);
+}
 function detectOnnxVersion(libDir, libName) {
   try {
     const entries = readdirSync(libDir);
     const barePrefix = libName.replace(/\.(so|dylib|dll)$/, "");
+    const expectedPrefix = process.platform === "win32" ? barePrefix.toLowerCase() : barePrefix;
     for (const entry of entries) {
-      if (!entry.startsWith(barePrefix))
+      const comparable = process.platform === "win32" ? entry.toLowerCase() : entry;
+      if (!comparable.startsWith(expectedPrefix))
         continue;
       const version = parseOnnxVersionFromPath(entry);
       if (version)
@@ -13269,7 +13291,7 @@ function detectOnnxVersion(libDir, libName) {
     if (existsSync5(base)) {
       try {
         const real = realpathSync(base);
-        const version = parseOnnxVersionFromPath(real);
+        const version = parseOnnxVersionFromPath(real) ?? parseOnnxVersionFromDirectoryPath(real);
         if (version)
           return version;
       } catch {}
@@ -13280,6 +13302,7 @@ function detectOnnxVersion(libDir, libName) {
           return version;
       } catch {}
     }
+    return parseOnnxVersionFromDirectoryPath(libDir);
   } catch {}
   return null;
 }
@@ -13315,6 +13338,14 @@ function directoryContainsLibrary(dir, libName) {
     return false;
   }
 }
+function resolveCachedOnnxRuntimeDir(ortVersionDir, libName) {
+  if (existsSync5(join6(ortVersionDir, libName)))
+    return ortVersionDir;
+  const libSubdir = join6(ortVersionDir, "lib");
+  if (existsSync5(join6(libSubdir, libName)))
+    return libSubdir;
+  return ortVersionDir;
+}
 function findSystemOnnxRuntime(libName) {
   if (!libName)
     return null;
@@ -13360,6 +13391,7 @@ function findSystemOnnxRuntime(libName) {
     seen.add(key);
     return true;
   });
+  const unknownVersionPaths = [];
   for (const dir of uniquePaths) {
     const libPath = join6(dir, libName);
     if (process.platform === "win32") {
@@ -13368,23 +13400,18 @@ function findSystemOnnxRuntime(libName) {
     } else if (!existsSync5(libPath)) {
       continue;
     }
-    let skipVersionCheck = false;
-    if (process.platform === "win32") {
-      const dirLower = dir.toLowerCase();
-      const isCommonPath = dirLower.includes("program files") || dirLower.includes("onnxruntime");
-      if (!isCommonPath)
-        skipVersionCheck = true;
-    }
-    if (!skipVersionCheck) {
-      const version = detectOnnxVersion(dir, libName);
-      if (version && !isOnnxVersionCompatible(version)) {
-        warn(`Skipping system ONNX Runtime at ${dir} (v${version}); AFT requires ` + `v${REQUIRED_ORT_MAJOR}.${REQUIRED_ORT_MIN_MINOR}+. Falling through to AFT-managed download.`);
-        continue;
-      }
+    const version = detectOnnxVersion(dir, libName);
+    if (!version) {
+      unknownVersionPaths.push(dir);
+      continue;
+    }
+    if (!isOnnxVersionCompatible(version)) {
+      warn(`Skipping system ONNX Runtime at ${dir} (v${version}); AFT requires ` + `v${REQUIRED_ORT_MAJOR}.${REQUIRED_ORT_MIN_MINOR}+. Falling through to AFT-managed download.`);
+      continue;
     }
     return dir;
   }
-  return null;
+  return unknownVersionPaths[0] ?? null;
 }
 async function downloadFileWithCap(url, destPath) {
   const controller = new AbortController;
@@ -13438,13 +13465,13 @@ function validateExtractedTree(stagingRoot) {
         const linkTarget = readlinkSync(fullPath);
         const resolvedTarget = resolve(dirname3(fullPath), linkTarget);
         const rel2 = relative(realRoot, resolvedTarget);
-        if (rel2.startsWith("..") || process.platform !== "win32" && rel2.startsWith("/")) {
+        if (rel2.startsWith("..") || isAbsolute(rel2) || win32.isAbsolute(rel2)) {
           throw new Error(`extracted symlink ${fullPath} points outside staging root: ${linkTarget}`);
         }
         continue;
       }
       const rel = relative(realRoot, fullPath);
-      if (rel.startsWith("..") || process.platform !== "win32" && rel.startsWith("/")) {
+      if (rel.startsWith("..") || isAbsolute(rel) || win32.isAbsolute(rel)) {
         throw new Error(`extracted entry ${fullPath} escapes staging root`);
       }
       if (lst.isDirectory()) {
@@ -13547,11 +13574,23 @@ function copyOnnxLibraries(info, extractedDir, targetDir, realFiles, symlinks, c
       log(`ORT extract: failed to copy optional ${libFile}: ${copyErr}`);
     }
   }
+  const targetRoot = realpathSync(targetDir);
   for (const link of symlinks) {
     const dst = join6(targetDir, link.name);
     try {
       unlinkSync3(dst);
     } catch {}
+    const dstForContainment = join6(targetRoot, link.name);
+    const resolvedTarget = resolve(dirname3(dstForContainment), link.target);
+    if (!isPathInsideRoot(targetRoot, resolvedTarget)) {
+      const message = `ONNX Runtime symlink ${link.name} points outside install dir: ${link.target}`;
+      if (requiredLibs.has(link.name)) {
+        rmSync2(targetDir, { recursive: true, force: true });
+        throw new Error(message);
+      }
+      log(`ORT extract: skipping optional symlink ${link.name}: ${message}`);
+      continue;
+    }
     try {
       symlinkSync(link.target, dst);
     } catch (symlinkErr) {
@@ -13654,9 +13693,8 @@ ${new Date().toISOString()}
   }
   const age = Date.now() - lockMtimeMs;
   const ageWithinFresh = Math.abs(age) < STALE_LOCK_MS;
-  const skipLiveness = process.platform === "win32";
-  const ownerAlive = !skipLiveness && owningPid !== null && isProcessAlive(owningPid);
-  if (skipLiveness ? ageWithinFresh : ownerAlive && ageWithinFresh) {
+  const ownerAlive = owningPid !== null && isProcessAlive(owningPid);
+  if (ownerAlive && ageWithinFresh) {
     return false;
   }
   log(`[onnx] reclaiming install lock (owner_pid=${owningPid ?? "unknown"}, alive=${ownerAlive}, age_ms=${age})`);
@@ -13697,7 +13735,31 @@ function releaseLock(lockPath) {
     warn(`[onnx] unexpected error releasing lock ${lockPath}: ${err}`);
   }
 }
+function tasklistPidFromCsvLine(line) {
+  const quoted = line.match(/"([^"]*)"/g);
+  if (quoted && quoted.length >= 2)
+    return quoted[1].slice(1, -1);
+  const cells = line.split(",").map((cell) => cell.trim().replace(/^"|"$/g, ""));
+  return cells[1] ?? null;
+}
+function isWindowsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    const output = execFileSync("tasklist.exe", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], {
+      encoding: "utf8",
+      timeout: 2000,
+      windowsHide: true
+    });
+    const expected = String(pid);
+    return output.split(/\r?\n/).some((line) => tasklistPidFromCsvLine(line) === expected);
+  } catch {
+    return false;
+  }
+}
 function isProcessAlive(pid) {
+  if (process.platform === "win32")
+    return isWindowsProcessAlive(pid);
   try {
     process.kill(pid, 0);
     return true;
@@ -14632,7 +14694,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.33.0",
+  version: "0.34.0",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -14651,10 +14713,11 @@ var package_default = {
     typecheck: "tsc --noEmit",
     test: "bun test src/__tests__/",
     lint: "biome check src",
-    prepublishOnly: "bun run build"
+    prepublishOnly: "bun run build",
+    "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.33.0",
+    "@cortexkit/aft-bridge": "0.34.0",
     "@xterm/headless": "^5.5.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
@@ -14662,12 +14725,12 @@ var package_default = {
     zod: "^4.1.8"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.33.0",
-    "@cortexkit/aft-darwin-x64": "0.33.0",
-    "@cortexkit/aft-linux-arm64": "0.33.0",
-    "@cortexkit/aft-linux-x64": "0.33.0",
-    "@cortexkit/aft-win32-arm64": "0.33.0",
-    "@cortexkit/aft-win32-x64": "0.33.0"
+    "@cortexkit/aft-darwin-arm64": "0.34.0",
+    "@cortexkit/aft-darwin-x64": "0.34.0",
+    "@cortexkit/aft-linux-arm64": "0.34.0",
+    "@cortexkit/aft-linux-x64": "0.34.0",
+    "@cortexkit/aft-win32-arm64": "0.34.0",
+    "@cortexkit/aft-win32-x64": "0.34.0"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "*",
@@ -28851,6 +28914,8 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // src/config.ts
+var FOREGROUND_WAIT_WINDOW_DEFAULT_MS = 8000;
+var FOREGROUND_WAIT_WINDOW_MIN_MS = 5000;
 function resolveBashConfig(config2) {
   const top = config2.bash;
   const legacy = config2.experimental?.bash;
@@ -28858,13 +28923,16 @@ function resolveBashConfig(config2) {
   const surfaceDefaultEnabled = surface !== "minimal";
   const reminderEnabled = (typeof top === "object" && top !== null ? top.long_running_reminder_enabled : undefined) ?? legacy?.long_running_reminder_enabled;
   const reminderInterval = (typeof top === "object" && top !== null ? top.long_running_reminder_interval_ms : undefined) ?? legacy?.long_running_reminder_interval_ms;
+  const rawForegroundWait = typeof top === "object" && top !== null ? top.foreground_wait_window_ms : undefined;
+  const foregroundWaitWindowMs = Math.max(FOREGROUND_WAIT_WINDOW_MIN_MS, rawForegroundWait ?? FOREGROUND_WAIT_WINDOW_DEFAULT_MS);
   const base = {
     enabled: false,
     rewrite: false,
     compress: false,
     background: false,
     long_running_reminder_enabled: reminderEnabled,
-    long_running_reminder_interval_ms: reminderInterval
+    long_running_reminder_interval_ms: reminderInterval,
+    foreground_wait_window_ms: foregroundWaitWindowMs
   };
   if (top === false)
     return base;
@@ -28918,13 +28986,15 @@ var CheckerEnum = exports_external.enum([
   "staticcheck",
   "none"
 ]);
+var ConfigureWarningsDeliveryEnum = exports_external.enum(["toast", "log", "chat"]);
 var SemanticConfigSchema = exports_external.object({
   backend: exports_external.enum(["fastembed", "openai_compatible", "ollama"]).optional(),
   model: exports_external.string().trim().min(1).optional(),
   base_url: exports_external.string().trim().min(1).optional(),
   api_key_env: exports_external.string().trim().min(1).optional(),
   timeout_ms: exports_external.number().int().positive().optional(),
-  max_batch_size: exports_external.number().int().positive().optional()
+  max_batch_size: exports_external.number().int().positive().optional(),
+  max_files: exports_external.number().int().positive().optional()
 });
 var LspExtensionSchema = exports_external.string().trim().min(1).refine((value) => value.replace(/^\.+/, "").length > 0, {
   message: "Extension must include characters other than leading dots"
@@ -28965,7 +29035,8 @@ var BashFeaturesSchema = exports_external.object({
   compress: exports_external.boolean().optional(),
   background: exports_external.boolean().optional(),
   long_running_reminder_enabled: exports_external.boolean().optional(),
-  long_running_reminder_interval_ms: exports_external.number().int().positive().optional()
+  long_running_reminder_interval_ms: exports_external.number().int().positive().optional(),
+  foreground_wait_window_ms: exports_external.number().int().positive().optional()
 });
 var BashConfigSchema = exports_external.union([exports_external.boolean(), BashFeaturesSchema]);
 var InspectConfigSchema = exports_external.object({
@@ -28993,6 +29064,7 @@ var AftConfigSchema = exports_external.object({
   validate_on_edit: exports_external.enum(["syntax", "full"]).optional(),
   formatter: exports_external.record(exports_external.string(), FormatterEnum).optional(),
   checker: exports_external.record(exports_external.string(), CheckerEnum).optional(),
+  configure_warnings_delivery: ConfigureWarningsDeliveryEnum.optional(),
   tool_surface: exports_external.enum(["minimal", "recommended", "all"]).optional(),
   disabled_tools: exports_external.array(exports_external.string()).optional(),
   restrict_to_project_root: exports_external.boolean().optional(),
@@ -29284,6 +29356,8 @@ function mergeSemanticConfig(base, override) {
     projectSafe.timeout_ms = override.timeout_ms;
   if (override?.max_batch_size !== undefined)
     projectSafe.max_batch_size = override.max_batch_size;
+  if (override?.max_files !== undefined)
+    projectSafe.max_files = override.max_files;
   const semantic = { ...base, ...projectSafe };
   if (Object.values(semantic).every((v) => v === undefined))
     return;
@@ -29381,6 +29455,7 @@ var PROJECT_SAFE_TOP_LEVEL_FIELDS = new Set([
   "tool_surface",
   "format_on_edit",
   "validate_on_edit",
+  "configure_warnings_delivery",
   "search_index",
   "semantic_search",
   "inspect",
@@ -31368,1757 +31443,1806 @@ function registerShutdownCleanup(fn) {
 
 // src/tools/ast.ts
 import { StringEnum } from "@earendil-works/pi-ai";
-import { Type as Type2 } from "typebox";
+import { Type as Type3 } from "typebox";
 
-// src/tools/render-helpers.ts
+// src/tools/hoisted.ts
+import { stat } from "node:fs/promises";
 import { homedir as homedir8 } from "node:os";
-import { renderDiff } from "@earendil-works/pi-coding-agent";
+import { isAbsolute as isAbsolute2, relative as relative3, resolve as resolve3, sep } from "node:path";
+import {
+  renderDiff
+} from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
-function reuseText(last) {
-  return last instanceof Text ? last : new Text("", 0, 0);
-}
-function reuseContainer(last) {
-  return last instanceof Container ? last : new Container;
+import { Type as Type2 } from "typebox";
+
+// src/tools/diff-format.ts
+import { diffLines } from "diff";
+var DEFAULT_CONTEXT_LINES = 4;
+function formatDiffForPi(oldContent, newContent, contextLines = DEFAULT_CONTEXT_LINES) {
+  const parts = diffLines(oldContent, newContent);
+  const output = [];
+  const oldLines = oldContent.split(`
+`);
+  const newLines = newContent.split(`
+`);
+  const maxLineNum = Math.max(oldLines.length, newLines.length);
+  const lineNumWidth = String(maxLineNum).length;
+  const pad = (n) => String(n).padStart(lineNumWidth, " ");
+  const blank = " ".repeat(lineNumWidth);
+  let oldLineNum = 1;
+  let newLineNum = 1;
+  let lastWasChange = false;
+  let firstChangedLine;
+  for (let i = 0;i < parts.length; i++) {
+    const part = parts[i];
+    const raw = part.value.split(`
+`);
+    if (raw[raw.length - 1] === "")
+      raw.pop();
+    if (part.added || part.removed) {
+      if (firstChangedLine === undefined)
+        firstChangedLine = newLineNum;
+      for (const line of raw) {
+        if (part.added) {
+          output.push(`+${pad(newLineNum)} ${line}`);
+          newLineNum++;
+        } else {
+          output.push(`-${pad(oldLineNum)} ${line}`);
+          oldLineNum++;
+        }
+      }
+      lastWasChange = true;
+      continue;
+    }
+    const nextIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+    const hasLeading = lastWasChange;
+    const hasTrailing = nextIsChange;
+    if (hasLeading && hasTrailing) {
+      if (raw.length <= contextLines * 2) {
+        for (const line of raw) {
+          output.push(` ${pad(oldLineNum)} ${line}`);
+          oldLineNum++;
+          newLineNum++;
+        }
+      } else {
+        for (const line of raw.slice(0, contextLines)) {
+          output.push(` ${pad(oldLineNum)} ${line}`);
+          oldLineNum++;
+          newLineNum++;
+        }
+        const skipped = raw.length - contextLines * 2;
+        output.push(` ${blank} ...`);
+        oldLineNum += skipped;
+        newLineNum += skipped;
+        for (const line of raw.slice(raw.length - contextLines)) {
+          output.push(` ${pad(oldLineNum)} ${line}`);
+          oldLineNum++;
+          newLineNum++;
+        }
+      }
+    } else if (hasLeading) {
+      const shown = raw.slice(0, contextLines);
+      for (const line of shown) {
+        output.push(` ${pad(oldLineNum)} ${line}`);
+        oldLineNum++;
+        newLineNum++;
+      }
+      const skipped = raw.length - shown.length;
+      if (skipped > 0) {
+        output.push(` ${blank} ...`);
+        oldLineNum += skipped;
+        newLineNum += skipped;
+      }
+    } else if (hasTrailing) {
+      const shownCount = Math.min(contextLines, raw.length);
+      const shown = raw.slice(raw.length - shownCount);
+      const skipped = raw.length - shown.length;
+      if (skipped > 0) {
+        output.push(` ${blank} ...`);
+        oldLineNum += skipped;
+        newLineNum += skipped;
+      }
+      for (const line of shown) {
+        output.push(` ${pad(oldLineNum)} ${line}`);
+        oldLineNum++;
+        newLineNum++;
+      }
+    } else {
+      oldLineNum += raw.length;
+      newLineNum += raw.length;
+    }
+    lastWasChange = false;
+  }
+  return { diff: output.join(`
+`), firstChangedLine };
 }
-function shortenPath(path2) {
-  const home = homedir8();
-  if (path2.startsWith(home))
-    return `~${path2.slice(home.length)}`;
-  return path2;
+
+// src/tools/hoisted.ts
+var DIAGNOSTICS_PARAM_DESCRIPTION = "When true, wait up to 3 seconds for fresh LSP diagnostics on the edited file and include them in the result. Defaults to the configured `lsp.diagnostics_on_edit` value (false unless configured); per-call true/false overrides. Use aft_inspect to check diagnostics across a batch of edits or before tests/commits.";
+function diagnosticsOnEditDefault(ctx) {
+  return ctx.config.lsp?.diagnostics_on_edit ?? false;
 }
-function renderToolCall(toolName, summary, theme, context) {
-  const text = reuseText(context.lastComponent);
-  const suffix = summary ? ` ${summary}` : "";
-  text.setText(`${theme.fg("toolTitle", theme.bold(toolName))}${suffix}`);
-  return text;
+function containsPath(parent, child) {
+  const rel = relative3(parent, child);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
 }
-function accentPath(theme, path2) {
-  if (!path2)
-    return theme.fg("toolOutput", "...");
-  return theme.fg("accent", shortenPath(path2));
+function expandTilde(path2) {
+  if (!path2 || !path2.startsWith("~"))
+    return path2;
+  if (path2 === "~")
+    return homedir8();
+  if (path2.startsWith(`~${sep}`) || path2.startsWith("~/")) {
+    return resolve3(homedir8(), path2.slice(2));
+  }
+  return path2;
 }
-function collectTextContent(result) {
-  return result.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join(`
-`).trim();
+function externalDirectoryPromptTimeoutMs() {
+  const raw = process.env.AFT_PI_EXTERNAL_PROMPT_TIMEOUT_MS;
+  if (raw === undefined)
+    return 30000;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30000;
 }
-function extractStructuredPayload(result) {
-  if (result.details !== undefined)
-    return result.details;
-  const text = collectTextContent(result);
-  if (!text)
+async function assertExternalDirectoryPermission(extCtx, target, action = "modify", options = {}) {
+  if (!target)
     return;
-  try {
-    return JSON.parse(text);
-  } catch {
+  const expanded = expandTilde(target);
+  const absoluteTarget = isAbsolute2(expanded) ? expanded : resolve3(extCtx.cwd, expanded);
+  if (containsPath(extCtx.cwd, absoluteTarget))
+    return;
+  if (options.restrictToProjectRoot === false)
     return;
+  const confirmFn = extCtx.ui?.confirm;
+  if (extCtx.hasUI === false || !confirmFn) {
+    throw new Error(`Permission denied: cannot prompt for ${action} outside the project (${absoluteTarget}).`);
   }
-}
-function renderErrorResult(result, fallback, theme, context) {
-  const text = reuseText(context.lastComponent);
-  const message = collectTextContent(result) || fallback;
-  text.setText(`
-${theme.fg("error", message)}`);
-  return text;
-}
-function renderSections(sections, context) {
-  const container = reuseContainer(context.lastComponent);
-  container.clear();
-  const visibleSections = sections.filter((section) => section.trim().length > 0);
-  if (visibleSections.length === 0)
-    return container;
-  container.addChild(new Spacer(1));
-  visibleSections.forEach((section, index) => {
-    if (index > 0)
-      container.addChild(new Spacer(1));
-    container.addChild(new Text(section, 0, 0));
+  const timeoutMs = externalDirectoryPromptTimeoutMs();
+  let timer;
+  const timeoutPromise = new Promise((resolve4) => {
+    timer = setTimeout(() => resolve4("timeout"), timeoutMs);
   });
-  return container;
-}
-function asRecord2(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    return;
-  return value;
-}
-function asRecords(value) {
-  return Array.isArray(value) ? value.map(asRecord2).filter(Boolean) : [];
-}
-function asString(value) {
-  return typeof value === "string" ? value : undefined;
-}
-function asNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-function asBoolean(value) {
-  return typeof value === "boolean" ? value : undefined;
-}
-function formatValue(value) {
-  if (Array.isArray(value))
-    return value.map(formatValue).join(", ");
-  if (typeof value === "string")
-    return value;
-  if (typeof value === "number" || typeof value === "boolean")
-    return String(value);
-  if (value === null || value === undefined)
-    return "—";
   try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
-function groupByFile(items, getFile) {
-  const groups = new Map;
-  items.forEach((item) => {
-    const file2 = getFile(item) ?? "(unknown file)";
-    const current = groups.get(file2) ?? [];
-    current.push(item);
-    groups.set(file2, current);
-  });
-  return groups;
-}
-function formatTimestamp(value) {
-  if (typeof value === "string" && value.length > 0)
-    return value;
-  if (typeof value !== "number" || !Number.isFinite(value))
-    return;
-  const millis = value > 1000000000000 ? value : value * 1000;
-  const date5 = new Date(millis);
-  if (Number.isNaN(date5.getTime()))
-    return String(value);
-  return date5.toISOString().replace("T", " ").replace(".000Z", "Z");
-}
-function formatUnifiedDiffForPi(unifiedDiff) {
-  if (!unifiedDiff.trim())
-    return "";
-  const entries = [];
-  const hunkHeader = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
-  let oldLine = 1;
-  let newLine = 1;
-  for (const line of unifiedDiff.split(`
-`)) {
-    if (!line)
-      continue;
-    if (line.startsWith("--- ") || line.startsWith("+++ "))
-      continue;
-    if (line.startsWith("\"))
-      continue;
-    const headerMatch = line.match(hunkHeader);
-    if (headerMatch) {
-      oldLine = Number(headerMatch[1]);
-      newLine = Number(headerMatch[2]);
-      continue;
-    }
-    if (line.startsWith("+") && !line.startsWith("+++")) {
-      entries.push({ prefix: "+", line: newLine, text: line.slice(1) });
-      newLine += 1;
-      continue;
-    }
-    if (line.startsWith("-") && !line.startsWith("---")) {
-      entries.push({ prefix: "-", line: oldLine, text: line.slice(1) });
-      oldLine += 1;
-      continue;
-    }
-    if (line.startsWith(" ")) {
-      entries.push({ prefix: " ", line: oldLine, text: line.slice(1) });
-      oldLine += 1;
-      newLine += 1;
+    const result = await Promise.race([
+      confirmFn("Allow external directory access?", `AFT wants to ${action} outside the project: ${absoluteTarget}`),
+      timeoutPromise
+    ]);
+    if (result === true)
+      return;
+    if (result === "timeout") {
+      throw new Error(`Permission denied: external directory prompt timed out after ${timeoutMs}ms.`);
     }
-  }
-  if (entries.length === 0)
-    return "";
-  const width = String(entries.reduce((max, entry) => Math.max(max, entry.line), 1)).length;
-  return entries.map((entry) => `${entry.prefix}${String(entry.line).padStart(width, " ")} ${entry.text}`).join(`
-`);
-}
-function renderUnifiedDiff(unifiedDiff) {
-  const piDiff = formatUnifiedDiffForPi(unifiedDiff);
-  if (!piDiff)
-    return "";
-  try {
-    return renderDiff(piDiff);
-  } catch {
-    return piDiff;
+    throw new Error("Permission denied: external directory access was cancelled.");
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
   }
 }
-
-// src/tools/ast.ts
-var AstLang = StringEnum(["typescript", "tsx", "javascript", "python", "rust", "go"], {
-  description: "Target language"
+var ReadParams = Type2.Object({
+  path: Type2.String({
+    description: "Path to the file to read (absolute or relative to project root)"
+  }),
+  offset: optionalInt(1, Number.MAX_SAFE_INTEGER),
+  limit: optionalInt(1, Number.MAX_SAFE_INTEGER)
 });
-var SearchParams = Type2.Object({
-  pattern: Type2.String({
-    description: "AST pattern with meta-variables (`$VAR` matches one node, `$$$` matches many). Must be a complete AST node."
+var WriteParams = Type2.Object({
+  filePath: Type2.String({
+    description: "Path to the file to write (absolute or relative to project root)"
   }),
-  lang: AstLang,
-  paths: Type2.Optional(Type2.Array(Type2.String(), { description: "Paths to search (default: ['.'])" })),
-  globs: Type2.Optional(Type2.Array(Type2.String(), { description: "Include/exclude globs (prefix `!` to exclude)" })),
-  contextLines: Type2.Optional(Type2.Number({ description: "Number of context lines around each match" }))
+  content: Type2.String({ description: "Full file contents to write" }),
+  diagnostics: Type2.Optional(Type2.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
 });
-var ReplaceParams = Type2.Object({
-  pattern: Type2.String({ description: "AST pattern with meta-variables" }),
-  rewrite: Type2.String({ description: "Replacement pattern, can reference $VAR from pattern" }),
-  lang: AstLang,
-  paths: Type2.Optional(Type2.Array(Type2.String(), { description: "Paths (default: ['.'])" })),
-  globs: Type2.Optional(Type2.Array(Type2.String(), { description: "Include/exclude globs" })),
-  dryRun: Type2.Optional(Type2.Boolean({ description: "Preview without applying (default: false)" }))
+var EditParams = Type2.Object({
+  filePath: Type2.String({
+    description: "Path to the file to edit (absolute or relative to project root)"
+  }),
+  oldString: Type2.Optional(Type2.String({ description: "Text to find (exact match, fuzzy fallback)" })),
+  newString: Type2.Optional(Type2.String({ description: "Replacement text (omit to delete match)" })),
+  replaceAll: Type2.Optional(Type2.Boolean({ description: "Replace every occurrence" })),
+  occurrence: optionalInt(0, Number.MAX_SAFE_INTEGER),
+  appendContent: Type2.Optional(Type2.String({
+    description: "Append text to the end of the file (creates the file if missing, parent dirs auto-created). When set, oldString/newString are ignored."
+  })),
+  diagnostics: Type2.Optional(Type2.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
 });
-function appendHintSection(response, sections, theme) {
-  const hint = asString(response.hint);
-  if (hint && hint.length > 0) {
-    sections.push(theme.fg("warning", hint));
-  }
-}
-function appendScopeSections(response, sections, theme) {
-  if (response.no_files_matched_scope === true) {
-    sections.push(theme.fg("warning", "No files matched the scope (paths/globs resolved to zero files)"));
-  }
-  const warnings = asRecords(response.scope_warnings);
-  const warningStrings = Array.isArray(response.scope_warnings) ? response.scope_warnings.filter((w) => typeof w === "string") : warnings.map((w) => asString(w.warning) ?? "").filter(Boolean);
-  if (warningStrings.length > 0) {
-    sections.push(`${theme.fg("muted", "Scope warnings:")}
-${warningStrings.map((w) => `  ${w}`).join(`
-`)}`);
-  }
-}
-function buildAstSearchSections(payload, theme) {
-  const response = asRecord2(payload);
-  if (!response)
-    return [theme.fg("muted", "No AST search results.")];
-  const matches = asRecords(response.matches);
-  const totalMatches = asNumber(response.total_matches) ?? matches.length;
-  const filesWithMatches = asNumber(response.files_with_matches) ?? groupByFile(matches, (match) => asString(match.file)).size;
-  const filesSearched = asNumber(response.files_searched);
-  const header = [
-    theme.fg("success", `${totalMatches} match${totalMatches === 1 ? "" : "es"}`),
-    theme.fg("accent", `${filesWithMatches} file${filesWithMatches === 1 ? "" : "s"}`),
-    filesSearched !== undefined ? theme.fg("muted", `${filesSearched} searched`) : undefined
-  ].filter(Boolean).join(" · ");
-  if (matches.length === 0) {
-    const sections2 = [header, theme.fg("muted", "No AST matches found.")];
-    appendScopeSections(response, sections2, theme);
-    appendHintSection(response, sections2, theme);
-    return sections2;
+var GrepParams = Type2.Object({
+  pattern: Type2.String({ description: "Regex pattern to search for" }),
+  path: Type2.Optional(Type2.String({
+    description: "Path scope (file or directory; absolute or relative to project root)"
+  })),
+  include: Type2.Optional(Type2.String({ description: "Glob filter for included files (e.g. '*.ts,*.tsx')" })),
+  caseSensitive: Type2.Optional(Type2.Boolean({ description: "Case-sensitive matching" })),
+  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER)
+});
+function registerHoistedTools(pi, ctx, surface) {
+  if (surface.hoistRead) {
+    pi.registerTool({
+      name: "read",
+      label: "read",
+      description: "Read file contents with line numbers. Backed by AFT's indexed Rust reader — faster than the built-in `read` on large repos and correctly handles images/PDFs as attachments.",
+      promptSnippet: "Read file contents (supports offset/limit for large files)",
+      promptGuidelines: ["Use read to examine files instead of cat or sed."],
+      parameters: ReadParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const offset = coerceOptionalInt(params.offset, "offset", 1, Number.MAX_SAFE_INTEGER);
+        const limit = coerceOptionalInt(params.limit, "limit", 1, Number.MAX_SAFE_INTEGER);
+        const req = { file: params.path };
+        if (offset !== undefined) {
+          req.start_line = offset;
+          if (limit !== undefined) {
+            req.end_line = offset + limit - 1;
+          }
+        } else if (limit !== undefined) {
+          req.end_line = limit;
+        }
+        const response = await callBridge(bridge, "read", req, extCtx);
+        if (Array.isArray(response.entries)) {
+          return textResult(response.entries.join(`
+`));
+        }
+        let text = response.content ?? "";
+        const agentSpecifiedRange = offset !== undefined || limit !== undefined;
+        const footer = formatReadFooter(agentSpecifiedRange, response);
+        if (footer)
+          text += footer;
+        return textResult(text);
+      }
+    });
   }
-  const grouped = groupByFile(matches, (match) => asString(match.file));
-  const sections = [header];
-  for (const [file2, fileMatches] of grouped.entries()) {
-    const lines = [theme.fg("accent", shortenPath(file2))];
-    fileMatches.forEach((match, index) => {
-      const line = asNumber(match.line) ?? 0;
-      const column = asNumber(match.column) ?? 0;
-      const snippet = asString(match.text)?.trim() || "(empty match)";
-      lines.push(`  ${index + 1}. ${theme.fg("muted", `${line}:${column}`)} ${snippet}`);
-      const metaVars = asRecord2(match.meta_variables);
-      if (metaVars && Object.keys(metaVars).length > 0) {
-        Object.entries(metaVars).forEach(([name, value]) => {
-          lines.push(`     ${theme.fg("muted", `${name} =`)} ${formatValue(value)}`);
+  if (surface.hoistWrite) {
+    pi.registerTool({
+      name: "write",
+      label: "write",
+      description: "Write a file atomically with per-file backup and optional auto-format. Parent directories are created automatically. Overwrites existing files. Uses `filePath` (not `path`). Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
+      promptSnippet: "Create or overwrite files (uses filePath; auto-formats; diagnostics follow lsp.diagnostics_on_edit unless overridden)",
+      promptGuidelines: ["Use write only for new files or complete rewrites."],
+      parameters: WriteParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
+          restrictToProjectRoot: surface.restrictToProjectRoot
         });
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "write", {
+          file: params.filePath,
+          content: params.content,
+          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          include_diff_content: true
+        }, extCtx);
+        return buildMutationResult(params.filePath, response);
+      },
+      renderCall(args, theme, context) {
+        return renderMutationCall("write", args?.filePath, theme, context);
+      },
+      renderResult(result, _options, theme, context) {
+        return renderMutationResult(result, theme, context);
       }
-      const context = asRecords(match.context);
-      context.forEach((ctxLine) => {
-        const ctxNumber = asNumber(ctxLine.line) ?? 0;
-        const prefix = ctxLine.is_match === true ? theme.fg("accent", ">") : theme.fg("muted", "|");
-        lines.push(`     ${prefix} ${ctxNumber}: ${asString(ctxLine.text) ?? ""}`);
-      });
     });
-    sections.push(lines.join(`
-`));
-  }
-  return sections;
-}
-function buildAstReplaceSections(payload, theme) {
-  const response = asRecord2(payload);
-  if (!response)
-    return [theme.fg("muted", "No AST replace results.")];
-  const files = asRecords(response.files);
-  const totalReplacements = asNumber(response.total_replacements) ?? 0;
-  const totalFiles = asNumber(response.total_files) ?? files.length;
-  const filesWithMatches = asNumber(response.files_with_matches);
-  const dryRun = response.dry_run === true;
-  const headerParts = [
-    dryRun ? theme.fg("warning", "[dry run]") : theme.fg("success", "[applied]"),
-    `${totalReplacements} replacement${totalReplacements === 1 ? "" : "s"}`,
-    `${totalFiles} file${totalFiles === 1 ? "" : "s"}`,
-    filesWithMatches !== undefined ? theme.fg("muted", `${filesWithMatches} matched`) : undefined
-  ];
-  const sections = [headerParts.filter(Boolean).join(" ")];
-  if (files.length === 0) {
-    sections.push(theme.fg("muted", "No files changed."));
-    appendScopeSections(response, sections, theme);
-    appendHintSection(response, sections, theme);
-    return sections;
   }
-  files.forEach((fileResult) => {
-    const file2 = shortenPath(asString(fileResult.file) ?? "(unknown file)");
-    const replacements = asNumber(fileResult.replacements) ?? 0;
-    const error50 = asString(fileResult.error);
-    const diff = asString(fileResult.diff);
-    const lines = [
-      `${theme.fg("accent", file2)} ${theme.fg("muted", `(${replacements} replacement${replacements === 1 ? "" : "s"})`)}`
-    ];
-    if (error50) {
-      lines.push(theme.fg("error", error50));
-    } else if (diff) {
-      const rendered = renderUnifiedDiff(diff);
-      lines.push(rendered || theme.fg("muted", "No diff available."));
-    } else {
-      const backupId = asString(fileResult.backup_id);
-      lines.push(backupId ? `${theme.fg("success", "saved")} ${theme.fg("muted", backupId)}` : theme.fg("success", "saved"));
-    }
-    sections.push(lines.join(`
-`));
-  });
-  return sections;
-}
-function renderAstCall(toolName, args, theme, context) {
-  const lang = theme.fg("accent", args.lang);
-  const summary = toolName === "ast_grep_replace" ? `${lang} ${theme.fg("toolOutput", `${args.pattern} → ${args.rewrite}`)}` : `${lang} ${theme.fg("toolOutput", args.pattern)}`;
-  return renderToolCall(toolName === "ast_grep_replace" ? "ast replace" : "ast search", summary, theme, context);
-}
-function renderAstResult(toolName, result, theme, context) {
-  if (context.isError) {
-    return renderErrorResult(result, `${toolName} failed`, theme, context);
-  }
-  const payload = extractStructuredPayload(result);
-  if (!payload) {
-    const text = collectTextContent(result);
-    return renderSections([text || theme.fg("muted", "No result.")], context);
-  }
-  const sections = toolName === "ast_grep_replace" ? buildAstReplaceSections(payload, theme) : buildAstSearchSections(payload, theme);
-  return renderSections(sections, context);
-}
-function registerAstTools(pi, ctx, surface) {
-  if (surface.astSearch) {
+  if (surface.hoistEdit) {
     pi.registerTool({
-      name: "ast_grep_search",
-      label: "ast search",
-      description: "Search code patterns across the filesystem using AST-aware matching. Use `$VAR` to match a single AST node, `$$$` for multiple. Pattern must be a complete, valid code fragment (include braces, params, etc.).",
-      parameters: SearchParams,
+      name: "edit",
+      label: "edit",
+      description: "Find-and-replace edit with progressive fuzzy matching (handles whitespace and Unicode drift). Uses `filePath`, `oldString`, `newString`. Errors on multiple matches — use `occurrence` to pick one, or `replaceAll: true`. Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
+      promptSnippet: "Targeted find-and-replace (uses filePath/oldString/newString; occurrence or replaceAll for disambiguation; fuzzy whitespace matching). Pass appendContent to append to a file (creates if missing). Diagnostics follow lsp.diagnostics_on_edit unless overridden.",
+      promptGuidelines: [
+        "Prefer edit over write when changing part of an existing file.",
+        "Include enough surrounding context in oldString to make the match unique, or set replaceAll/occurrence explicitly.",
+        "Use appendContent (instead of read+write) when adding text to the end of a file."
+      ],
+      parameters: EditParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
+          restrictToProjectRoot: surface.restrictToProjectRoot
+        });
         const bridge = bridgeFor(ctx, extCtx.cwd);
+        if (typeof params.appendContent === "string") {
+          const req2 = {
+            op: "append",
+            file: params.filePath,
+            append_content: params.appendContent,
+            diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+            include_diff_content: true
+          };
+          const response2 = await callBridge(bridge, "edit_match", req2, extCtx);
+          return buildMutationResult(params.filePath, response2);
+        }
         const req = {
-          pattern: params.pattern,
-          lang: params.lang
+          file: params.filePath,
+          match: params.oldString ?? "",
+          replacement: params.newString ?? "",
+          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          include_diff_content: true
         };
-        if (!isEmptyParam(params.paths))
-          req.paths = params.paths;
-        if (!isEmptyParam(params.globs))
-          req.globs = params.globs;
-        if (params.contextLines !== undefined)
-          req.context_lines = params.contextLines;
-        const response = await callBridge(bridge, "ast_search", req, extCtx);
-        return textResult(response.text ?? JSON.stringify(response));
+        if (params.replaceAll === true)
+          req.replace_all = true;
+        const occurrence = coerceOptionalInt(params.occurrence, "occurrence", 0, Number.MAX_SAFE_INTEGER);
+        if (occurrence !== undefined)
+          req.occurrence = occurrence;
+        const response = await callBridge(bridge, "edit_match", req, extCtx);
+        return buildMutationResult(params.filePath, response);
       },
       renderCall(args, theme, context) {
-        return renderAstCall("ast_grep_search", args, theme, context);
+        return renderMutationCall("edit", args?.filePath, theme, context);
       },
       renderResult(result, _options, theme, context) {
-        return renderAstResult("ast_grep_search", result, theme, context);
+        return renderMutationResult(result, theme, context);
       }
     });
   }
-  if (surface.astReplace) {
+  if (surface.hoistGrep) {
     pi.registerTool({
-      name: "ast_grep_replace",
-      label: "ast replace",
-      description: "Replace code patterns across the filesystem with AST-aware rewriting. Applies by default — pass `dryRun: true` to preview. Use meta-variables in `rewrite` to preserve captured content from the pattern.",
-      parameters: ReplaceParams,
+      name: "grep",
+      label: "grep",
+      description: "Search for a regex pattern across files. Uses AFT's trigram index inside the project root for fast repeated queries, and falls back to ripgrep for paths outside the project root.",
+      promptSnippet: "Fast regex search across files (trigram-indexed inside the project root)",
+      promptGuidelines: ["Prefer grep over bash-invoked find/rg for in-project searches."],
+      parameters: GrepParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const req = {
-          pattern: params.pattern,
-          rewrite: params.rewrite,
-          lang: params.lang
-        };
-        if (!isEmptyParam(params.paths))
-          req.paths = params.paths;
-        if (!isEmptyParam(params.globs))
-          req.globs = params.globs;
-        req.dry_run = params.dryRun === true;
-        const response = await callBridge(bridge, "ast_replace", req, extCtx);
-        return textResult(response.text ?? JSON.stringify(response));
-      },
-      renderCall(args, theme, context) {
-        return renderAstCall("ast_grep_replace", args, theme, context);
-      },
-      renderResult(result, _options, theme, context) {
-        return renderAstResult("ast_grep_replace", result, theme, context);
+        const req = { pattern: params.pattern };
+        if (params.path) {
+          await assertExternalDirectoryPermission(extCtx, params.path, "search", {
+            restrictToProjectRoot: surface.restrictToProjectRoot
+          });
+          req.path = await resolvePathArg(extCtx.cwd, params.path);
+        }
+        if (params.include)
+          req.include = splitIncludeGlobs(params.include);
+        if (params.caseSensitive !== undefined)
+          req.case_sensitive = params.caseSensitive;
+        const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
+        if (contextLines !== undefined)
+          req.context_lines = contextLines;
+        const response = await callBridge(bridge, "grep", req, extCtx);
+        const text = response.text ?? "";
+        return textResult(text);
       }
     });
   }
 }
+function buildMutationResult(filePath, response) {
+  const diffObj = response.diff;
+  const additions = diffObj?.additions ?? 0;
+  const deletions = diffObj?.deletions ?? 0;
+  const replacements = response.replacements;
+  const diagnostics = response.lsp_diagnostics;
+  const truncated = diffObj?.truncated === true;
+  const noOp = response.no_op === true;
+  const formatted = response.formatted;
+  const formatSkippedReason = response.format_skipped_reason;
+  const globFormatSkipReasons = response.format_skip_reasons;
+  let diffText;
+  let firstChangedLine;
+  if (diffObj && !truncated && typeof diffObj.before === "string" && typeof diffObj.after === "string") {
+    const piDiff = formatDiffForPi(diffObj.before, diffObj.after);
+    diffText = piDiff.diff;
+    firstChangedLine = piDiff.firstChangedLine;
+  }
+  const summaryHeader = replacements !== undefined ? `Edited ${filePath} (+${additions}/-${deletions}, ${replacements} replacement${replacements === 1 ? "" : "s"})` : `Wrote ${filePath} (+${additions}/-${deletions})`;
+  let text = summaryHeader;
+  if (noOp) {
+    text += `
 
-// src/tools/bash.ts
-import * as fs3 from "node:fs/promises";
-import { Container as Container2, Spacer as Spacer2, Text as Text2 } from "@earendil-works/pi-tui";
-import { Type as Type3 } from "typebox";
-var FOREGROUND_WAIT_WINDOW_MS = 5000;
-var FOREGROUND_POLL_INTERVAL_MS = 100;
-var BASH_WAIT_POLL_INTERVAL_MS = 100;
-var DEFAULT_BASH_STATUS_WAIT_TIMEOUT_MS = 30000;
-var MAX_BASH_STATUS_WAIT_TIMEOUT_MS = 300000;
-var BASH_TRANSPORT_TIMEOUT_MS = 30000;
-var BashParams = Type3.Object({
-  command: Type3.String({
-    description: "Shell command to execute. Supports pipes, redirections, and shell syntax."
-  }),
-  timeout: optionalInt(1, Number.MAX_SAFE_INTEGER),
-  workdir: Type3.Optional(Type3.String({
-    description: "Working directory for command execution. Relative paths resolve against the project root. Defaults to the current session's working directory."
-  })),
-  description: Type3.Optional(Type3.String({
-    description: "Human-readable description shown in UI logs. Helps users understand what the command does without reading shell syntax."
-  })),
-  background: Type3.Optional(Type3.Boolean({
-    description: "Spawn command in background and return immediately with a task_id. Use bash_status to poll completion and bash_kill to terminate. Ideal for long-running tasks like builds or dev servers."
-  })),
-  compressed: Type3.Optional(Type3.Boolean({
-    description: "Compress output by removing ANSI codes, carriage returns, and excessive blank lines. Default: true. Set to false for raw terminal output including color codes."
-  })),
-  pty: Type3.Optional(Type3.Boolean({
-    description: 'Spawn the command in a real PTY for interactive programs. Implies background: true automatically. Inspect with bash_status({ task_id, output_mode: "screen" }) and send input with bash_write.'
-  })),
-  ptyRows: optionalInt(1, 60),
-  ptyCols: optionalInt(1, 140)
-});
-var BashTaskParams = Type3.Object({
-  task_id: Type3.String({
-    description: "Background bash task id returned by bash({ background: true })."
-  })
-});
-var BashStatusParams = Type3.Object({
-  task_id: Type3.String({
-    description: "Background bash task id returned by bash({ background: true })."
-  }),
-  output_mode: Type3.Optional(Type3.Union([Type3.Literal("screen"), Type3.Literal("raw"), Type3.Literal("both")], {
-    description: "PTY output rendering mode. Defaults to screen for PTY tasks and preserves existing behavior for piped tasks when omitted."
-  }))
-});
-var BashWatchParams = Type3.Object({
-  task_id: Type3.String({
-    description: "Background bash task id returned by bash({ background: true })."
-  }),
-  pattern: Type3.Optional(Type3.Union([Type3.String(), Type3.Object({ regex: Type3.String() })])),
-  background: Type3.Optional(Type3.Boolean()),
-  timeout_ms: optionalInt(1, MAX_BASH_STATUS_WAIT_TIMEOUT_MS),
-  once: Type3.Optional(Type3.Boolean())
-});
-var BashWriteParams = Type3.Object({
-  task_id: Type3.String({
-    description: "Background PTY task id returned by bash({ pty: true, background: true })."
-  }),
-  input: Type3.Union([
-    Type3.String(),
-    Type3.Array(Type3.Union([
-      Type3.String(),
-      Type3.Object({
-        key: Type3.String({
-          description: "Named control key, e.g. 'esc', 'enter', 'up', 'ctrl-c'. Case-insensitive."
-        })
-      })
-    ]))
-  ], {
-    description: "Either a string of verbatim bytes (e.g. 'print(1)\\n') OR an array mixing strings " + "and { key: '<name>' } objects for atomic text+key sequences. " + "Example: [ 'iHello', { key: 'esc' }, ':wq', { key: 'enter' } ]. " + "Allowed key names: enter, return, tab, space, backspace, esc, escape, up, down, " + "left, right, home, end, page-up, page-down, delete, insert, f1..f12, ctrl-a..ctrl-z."
-  })
-});
-function truncateToVisualLines(text, maxLines) {
-  const lines = text.split(`
-`);
-  if (lines.length <= maxLines)
-    return text;
-  return lines.slice(-maxLines).join(`
-`);
-}
-function reuseText2(last) {
-  return last instanceof Text2 ? last : new Text2("", 0, 0);
-}
-function reuseContainer2(last) {
-  return last instanceof Container2 ? last : new Container2;
-}
-function getBashSpawnHook(pi) {
-  const api2 = pi;
-  if (typeof api2.getHook === "function") {
-    return api2.getHook("bashSpawn");
+Note: no net file change — the match was found and applied, but the file content is byte-identical to before. Likely causes: oldString and newString are identical, or a formatter normalized the change away.`;
   }
-  return api2.hooks?.bashSpawn;
+  const skipNote = formatSkipReasonNote(formatSkippedReason);
+  if (skipNote)
+    text += `
+
+${skipNote}`;
+  const globSkipNote = formatGlobSkipReasonsNote(globFormatSkipReasons);
+  if (globSkipNote)
+    text += `
+
+${globSkipNote}`;
+  if (diagnostics && diagnostics.length > 0) {
+    text += `
+
+LSP diagnostics:
+${formatDiagnosticsText(diagnostics)}`;
+  }
+  return {
+    content: [{ type: "text", text }],
+    details: {
+      diff: diffText,
+      firstChangedLine,
+      additions,
+      deletions,
+      replacements,
+      diagnostics,
+      truncated: truncated || undefined,
+      formatted,
+      formatSkippedReason,
+      noOp: noOp || undefined
+    }
+  };
 }
-function registerBashTool(pi, ctx) {
-  const spawnHook = getBashSpawnHook(pi);
-  pi.registerTool({
-    name: "bash",
-    label: "bash",
-    description: 'Execute shell commands through AFT\'s Rust bash handler. By default, output is compressed. Pass `compressed: false` for raw output. Pass `background: true` to spawn in the background and get a task_id for `bash_status`/`bash_kill`. Pass `pty: true` with `background: true` for interactive programs and drive them with `bash_status({ output_mode: "screen" })` plus `bash_write`.',
-    promptSnippet: "Run shell commands (timeout in milliseconds; supports workdir, background tasks, compressed output, PTY mode)",
-    promptGuidelines: [
-      "Use bash only when a dedicated AFT tool is not a better fit.",
-      "Set compressed: false when you need ANSI color codes in the output."
-    ],
-    parameters: BashParams,
-    async execute(_toolCallId, params, _signal, onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const timeout = coerceOptionalInt(params.timeout, "timeout", 1, Number.MAX_SAFE_INTEGER);
-      const ptyRows = coerceOptionalInt(params.ptyRows, "ptyRows", 1, 60);
-      const ptyCols = coerceOptionalInt(params.ptyCols, "ptyCols", 1, 140);
-      const effectiveBackground = params.background === true || params.pty === true;
-      let spawnContext = {
-        command: params.command,
-        cwd: params.workdir
-      };
-      if (spawnHook) {
-        try {
-          spawnContext = await spawnHook(spawnContext);
-        } catch (hookErr) {
-          throw new Error(`BashSpawnHook failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
-        }
-      }
-      let streamed = "";
-      const response = await callBridge(bridge, "bash", {
-        command: spawnContext.command,
-        timeout,
-        workdir: spawnContext.cwd ?? params.workdir,
-        env: spawnContext.env,
-        description: params.description,
-        background: effectiveBackground,
-        notify_on_completion: effectiveBackground,
-        compressed: params.compressed,
-        pty: params.pty,
-        pty_rows: ptyRows,
-        pty_cols: ptyCols
-      }, extCtx, {
-        transportTimeoutMs: BASH_TRANSPORT_TIMEOUT_MS,
-        keepBridgeOnTimeout: true,
-        onProgress: ({ text }) => {
-          streamed += text;
-          const displayText = truncateToVisualLines(streamed, 100);
-          onUpdate?.(bashResult(displayText, { streaming: true }));
-        }
-      }).catch((err) => {
-        if (err instanceof Error && err.message.includes("permission_required")) {
-          throw new Error("Permission ask reached Pi adapter — this is a bug. Pi has no permission system.");
-        }
-        throw err;
-      });
-      if (response.success === false) {
-        throw new Error(response.message ?? "bash failed");
-      }
-      const taskId = response.task_id;
-      if (response.status === "running" && taskId) {
-        if (effectiveBackground) {
-          trackBgTask(resolveSessionId(extCtx), taskId);
-          return bashResult(formatBackgroundLaunch(taskId, params.pty === true), {
-            task_id: taskId
-          });
-        }
-        const waitTimeoutMs = timeout !== undefined ? Math.min(timeout, FOREGROUND_WAIT_WINDOW_MS) : FOREGROUND_WAIT_WINDOW_MS;
-        const startedAt = Date.now();
-        while (true) {
-          const status = await callBridge(bridge, "bash_status", { task_id: taskId }, extCtx);
-          if (status.success === false) {
-            throw new Error(status.message ?? "bash_status failed");
-          }
-          if (isTerminalStatus(status.status)) {
-            return bashResult(formatForegroundResult(status), {
-              exit_code: status.exit_code,
-              duration_ms: status.duration_ms,
-              truncated: status.output_truncated,
-              output_path: status.output_path,
-              task_id: taskId
-            });
-          }
-          if (Date.now() - startedAt >= waitTimeoutMs) {
-            const promoted = await callBridge(bridge, "bash_promote", { task_id: taskId }, extCtx);
-            if (promoted.success === false) {
-              throw new Error(promoted.message ?? "bash_promote failed");
-            }
-            trackBgTask(resolveSessionId(extCtx), taskId);
-            return bashResult(formatPromotionMessage(taskId, params.timeout), {
-              task_id: taskId
-            });
-          }
-          await sleep(FOREGROUND_POLL_INTERVAL_MS);
-        }
-      }
-      const details = {
-        exit_code: response.exit_code,
-        duration_ms: response.duration_ms,
-        truncated: response.truncated,
-        output_path: response.output_path,
-        task_id: taskId
-      };
-      const output = response.output ?? "";
-      return bashResult(output, details);
-    },
-    renderCall(args, theme, context) {
-      return renderBashCall(args?.command, args?.description, theme, context);
-    },
-    renderResult(result, _options, theme, context) {
-      return renderBashResult(result, theme, context);
-    }
-  });
-  pi.registerTool(createBashStatusTool(ctx));
-  pi.registerTool(createBashWatchTool(ctx));
-  pi.registerTool(createBashWriteTool(ctx));
-  pi.registerTool(createBashKillTool(ctx));
+function formatGlobSkipReasonsNote(reasons) {
+  if (!Array.isArray(reasons))
+    return;
+  const actionable = reasons.filter((reason) => typeof reason === "string").filter((reason) => ["formatter_not_installed", "formatter_excluded_path", "timeout", "error"].includes(reason));
+  if (actionable.length === 0)
+    return;
+  return `Note: formatter skipped some glob edit result file(s): ${[...new Set(actionable)].sort().join(", ")}. See per-file format_skipped_reason values for details.`;
 }
-function formatBackgroundLaunch(taskId, isPty) {
-  if (isPty) {
-    return `PTY task started: ${taskId}. Use bash_status({ task_id: "${taskId}", output_mode: "screen" }) to see the visible terminal, bash_write({ task_id: "${taskId}", input: ... }) to send keystrokes. A completion reminder fires automatically when the task exits.`;
+function formatSkipReasonNote(reason) {
+  switch (reason) {
+    case "formatter_not_installed":
+      return "Note: formatter binary not installed; file written unformatted.";
+    case "timeout":
+      return "Note: formatter timed out; file written unformatted. Raise formatter_timeout_secs or check the formatter for hangs.";
+    case "formatter_excluded_path":
+      return "Note: formatter is configured to ignore this path (e.g. biome.json files.includes, .prettierignore). File written unformatted.";
+    case "error":
+      return "Note: formatter exited with an unrecognized error; file written unformatted.";
+    default:
+      return;
   }
-  return `Background task started: ${taskId}. A completion reminder will be delivered automatically; don't poll bash_status.`;
-}
-function formatPromotionMessage(taskId, timeout) {
-  const waited = timeout !== undefined ? Math.min(timeout, FOREGROUND_WAIT_WINDOW_MS) : FOREGROUND_WAIT_WINDOW_MS;
-  return `Foreground bash didn't finish within ${waited}ms and was promoted to background: ${taskId}. A completion reminder will be delivered automatically; use bash_status({ task_id: "${taskId}" }) to inspect output or bash_kill({ task_id: "${taskId}" }) to terminate.`;
 }
-function formatForegroundResult(data) {
-  const output = data.output_preview ?? "";
-  const outputPath = data.output_path;
-  const truncated = data.output_truncated === true;
-  const status = data.status;
-  const exit = data.exit_code;
-  let rendered = output;
-  if (truncated && outputPath) {
-    rendered += `
-[output truncated; full output at ${outputPath}]`;
+function formatDiagnosticsText(diagnostics) {
+  try {
+    return diagnostics.map((d) => {
+      if (d && typeof d === "object") {
+        const obj = d;
+        const line = obj.line ?? obj.startLine ?? "?";
+        const severity = obj.severity ?? "info";
+        const msg = obj.message ?? JSON.stringify(obj);
+        return `  [${severity}] line ${line}: ${msg}`;
+      }
+      return `  ${String(d)}`;
+    }).join(`
+`);
+  } catch {
+    return JSON.stringify(diagnostics, null, 2);
   }
-  if (status === "timed_out") {
-    rendered += `
-[command timed out]`;
+}
+function reuseText(last) {
+  return last instanceof Text ? last : new Text("", 0, 0);
+}
+function reuseContainer(last) {
+  return last instanceof Container ? last : new Container;
+}
+function renderMutationCall(toolName, filePath, theme, context) {
+  const text = reuseText(context.lastComponent);
+  const pathDisplay = filePath ? theme.fg("accent", shortenPath(filePath)) : theme.fg("toolOutput", "...");
+  text.setText(`${theme.fg("toolTitle", theme.bold(toolName))} ${pathDisplay}`);
+  return text;
+}
+function renderMutationResult(result, theme, context) {
+  if (context.isError) {
+    const errorText = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
+`).trim();
+    const text = reuseText(context.lastComponent);
+    text.setText(`
+${theme.fg("error", errorText || "edit failed")}`);
+    return text;
   }
-  if (typeof exit === "number" && exit !== 0) {
-    rendered += `
-[exit code: ${exit}]`;
+  const details = result.details;
+  const diff = typeof details?.diff === "string" ? details.diff : undefined;
+  if (!diff) {
+    const additions = details?.additions ?? 0;
+    const deletions = details?.deletions ?? 0;
+    const text = reuseText(context.lastComponent);
+    const summary = theme.fg("success", `+${additions}/-${deletions}`);
+    let suffix = "";
+    if (details?.truncated) {
+      suffix = ` ${theme.fg("muted", "(diff truncated)")}`;
+    } else if (details?.noOp) {
+      suffix = ` ${theme.fg("muted", "(no net change)")}`;
+    }
+    text.setText(`
+${summary}${suffix}`);
+    return text;
   }
-  return rendered;
+  const container = reuseContainer(context.lastComponent);
+  container.clear();
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(renderDiff(diff), 1, 0));
+  return container;
 }
-function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+function shortenPath(path2) {
+  const home = homedir8();
+  if (path2.startsWith(home))
+    return `~${path2.slice(home.length)}`;
+  return path2;
 }
-function createBashStatusTool(ctx) {
-  return {
-    name: "bash_status",
-    label: "bash_status",
-    description: "Read-only snapshot of a background bash task. Returns immediately. Never waits. Use bash_watch to block on or register for pattern matches and exit events.",
-    promptSnippet: "Inspect a background bash task by task_id",
-    parameters: BashStatusParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const data = await bashStatusSnapshot(bridge, extCtx, params.task_id, params.output_mode);
-      const details = data;
-      return bashStatusResult(await formatBashStatus(extCtx, params.task_id, details, params.output_mode), details);
+async function resolvePathArg(cwd, path2) {
+  const expanded = expandTilde(path2);
+  const abs = isAbsolute2(expanded) ? expanded : resolve3(cwd, expanded);
+  try {
+    await stat(abs);
+    return abs;
+  } catch {
+    return expanded;
+  }
+}
+function splitIncludeGlobs(include) {
+  const out = [];
+  let depth = 0;
+  let buf = "";
+  for (const ch of include) {
+    if (ch === "{") {
+      depth++;
+      buf += ch;
+      continue;
     }
-  };
+    if (ch === "}") {
+      if (depth > 0)
+        depth--;
+      buf += ch;
+      continue;
+    }
+    if (ch === "," && depth === 0) {
+      const trimmed = buf.trim();
+      if (trimmed.length > 0)
+        out.push(trimmed);
+      buf = "";
+      continue;
+    }
+    buf += ch;
+  }
+  const tail2 = buf.trim();
+  if (tail2.length > 0)
+    out.push(tail2);
+  return out;
 }
-function createBashWatchTool(ctx) {
-  return {
-    name: "bash_watch",
-    label: "bash_watch",
-    description: "Block on a background bash task until a pattern matches, it exits, or timeout elapses; or register an async pattern notification with background:true.",
-    promptSnippet: "Wait for or watch a background bash task",
-    parameters: BashWatchParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const waitFor = parseWaitPattern(params.pattern);
-      if (params.background === true) {
-        if (!waitFor) {
-          throw new Error("invalid_request: Use auto-reminder; bash_watch without pattern in async mode is redundant");
-        }
-        const notifyParams = {
-          task_id: params.task_id,
-          once: params.once !== false
-        };
-        if (waitFor.kind === "regex")
-          notifyParams.regex = waitFor.source;
-        else
-          notifyParams.pattern = waitFor.value;
-        const sessionId = resolveSessionId(extCtx);
-        markExplicitControl(sessionId, params.task_id, false);
-        let registered;
-        try {
-          registered = await callBridge(bridge, "bash_notify", notifyParams, extCtx);
-        } catch (err) {
-          unmarkExplicitControl(sessionId, params.task_id);
-          throw err;
-        }
-        if (registered.success === false) {
-          unmarkExplicitControl(sessionId, params.task_id);
-          const message = String(registered.message ?? "bash_notify failed");
-          throw new Error(`${String(registered.code ?? "invalid_request")}: ${message}`);
-        }
-        markExplicitControl(sessionId, params.task_id);
-        const watchDetails = { registered: true, watchId: registered.watch_id };
-        return textResult(`Watch registered: ${registered.watch_id} on task ${params.task_id}
-A notification will fire when the pattern matches or the task exits.`, watchDetails);
-      }
-      const data = await waitForBashStatus(ctx, bridge, extCtx, params.task_id, undefined, waitFor, true, Math.min(coerceOptionalInt(params.timeout_ms, "timeout_ms", 1, MAX_BASH_STATUS_WAIT_TIMEOUT_MS) ?? DEFAULT_BASH_STATUS_WAIT_TIMEOUT_MS, MAX_BASH_STATUS_WAIT_TIMEOUT_MS));
-      const text = await formatBashStatus(extCtx, params.task_id, data, undefined);
-      return textResult(text, data);
-    }
-  };
+function formatReadFooter(agentSpecifiedRange, data) {
+  if (agentSpecifiedRange)
+    return "";
+  if (!data.truncated)
+    return "";
+  const startLine = data.start_line;
+  const endLine = data.end_line;
+  const totalLines = data.total_lines;
+  if (startLine === undefined || endLine === undefined || totalLines === undefined) {
+    return "";
+  }
+  return `
+(Showing lines ${startLine}-${endLine} of ${totalLines}. Use offset/limit to read other sections.)`;
 }
-function createBashWriteTool(ctx) {
-  return {
-    name: "bash_write",
-    label: "bash_write",
-    description: 'Write input bytes to a running PTY bash task. PTY-only; check bash_status reports mode: "pty" first. ' + 'Input is either a string (verbatim bytes) or an array mixing strings and { key: "esc" | "enter" | "up" | "ctrl-c" | ... } objects ' + 'for atomic text+key sequences such as [ "iHello", { key: "esc" }, ":wq", { key: "enter" } ]. ' + "Named keys cover enter/return/tab/space/backspace/esc/escape, arrows, home/end/page-up/page-down/delete/insert, f1..f12, and ctrl-a..ctrl-z. " + "Maximum 1 MiB per call (post-expansion).",
-    promptSnippet: "Write keystrokes/input to a PTY bash task",
-    parameters: BashWriteParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const data = await callBridge(bridge, "bash_write", { task_id: params.task_id, input: params.input }, extCtx);
-      return textResult(JSON.stringify({ bytes_written: data.bytes_written }, null, 2), data);
-    }
-  };
+
+// src/tools/render-helpers.ts
+import { homedir as homedir9 } from "node:os";
+import { renderDiff as renderDiff2 } from "@earendil-works/pi-coding-agent";
+import { Container as Container2, Spacer as Spacer2, Text as Text2 } from "@earendil-works/pi-tui";
+function reuseText2(last) {
+  return last instanceof Text2 ? last : new Text2("", 0, 0);
 }
-function createBashKillTool(ctx) {
-  return {
-    name: "bash_kill",
-    label: "bash_kill",
-    description: "Terminate a running background bash task spawned with bash({ background: true }).",
-    promptSnippet: "Kill a background bash task by task_id",
-    parameters: BashTaskParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const data = await callBridge(bridge, "bash_kill", { task_id: params.task_id }, extCtx);
-      if (data.success === false) {
-        throw new Error(data.message ?? "bash_kill failed");
-      }
-      await disposePtyTerminal(ptyCacheKey(extCtx, params.task_id));
-      const details = data;
-      if (details.kill_signaled === true) {
-        return bashKillResult(`Task ${params.task_id}: kill_signaled`, details);
-      }
-      return bashKillResult(`Task ${params.task_id}: ${details.status}`, details);
-    }
-  };
+function reuseContainer2(last) {
+  return last instanceof Container2 ? last : new Container2;
 }
-function bashResult(output, details) {
-  return {
-    content: [{ type: "text", text: output }],
-    details: {
-      exit_code: details.exit_code,
-      duration_ms: details.duration_ms,
-      truncated: details.truncated,
-      output_path: details.output_path,
-      task_id: details.task_id,
-      bg_completions: details.bg_completions
-    }
-  };
+function shortenPath2(path2) {
+  const home = homedir9();
+  if (path2.startsWith(home))
+    return `~${path2.slice(home.length)}`;
+  return path2;
 }
-function bashStatusResult(output, details) {
-  return {
-    content: [{ type: "text", text: output }],
-    details
-  };
+function renderToolCall(toolName, summary, theme, context) {
+  const text = reuseText2(context.lastComponent);
+  const suffix = summary ? ` ${summary}` : "";
+  text.setText(`${theme.fg("toolTitle", theme.bold(toolName))}${suffix}`);
+  return text;
 }
-function bashKillResult(output, details) {
-  return {
-    content: [{ type: "text", text: output }],
-    details
-  };
+function accentPath(theme, path2) {
+  if (!path2)
+    return theme.fg("toolOutput", "...");
+  return theme.fg("accent", shortenPath2(path2));
 }
-async function bashStatusSnapshot(bridge, extCtx, taskId, outputMode, options) {
-  return await callBridge(bridge, "bash_status", { task_id: taskId, output_mode: outputMode }, extCtx, options);
+function collectTextContent(result) {
+  return result.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join(`
+`).trim();
 }
-async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFor, waitForExit, effectiveWaitMs) {
-  const startedAt = Date.now();
-  const deadline = startedAt + effectiveWaitMs;
-  let spillCursor = { output: 0, stderr: 0, combined: 0 };
-  let scanText = "";
-  let scanBaseOffset = 0;
-  const bridgeOptions = {
-    keepBridgeOnTimeout: true,
-    transportTimeoutMs: BASH_TRANSPORT_TIMEOUT_MS
-  };
-  const sessionId = resolveSessionId(extCtx);
-  if (waitForExit)
-    markTaskWaiting(sessionId, taskId);
-  let sawTerminal = false;
+function extractStructuredPayload(result) {
+  if (result.details !== undefined)
+    return result.details;
+  const text = collectTextContent(result);
+  if (!text)
+    return;
   try {
-    while (true) {
-      const data = await bashStatusSnapshot(bridge, extCtx, taskId, outputMode, bridgeOptions);
-      const terminal = isTerminalStatus(data.status);
-      if (waitFor) {
-        const scan = await readNewTaskOutput(extCtx, taskId, data, spillCursor);
-        if (scan) {
-          spillCursor = scan.nextCursor;
-          if (scanText.length === 0)
-            scanBaseOffset = scan.baseOffset;
-          scanText += scan.text;
-          const match = findWaitMatch(scanText, waitFor);
-          if (match) {
-            if (waitForExit && terminal) {
-              sawTerminal = true;
-              consumeBgCompletion(sessionId, taskId);
-              await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
-            }
-            return withWaited(data, {
-              reason: "matched",
-              elapsed_ms: Date.now() - startedAt,
-              match: match.text,
-              match_offset: scanBaseOffset + Buffer.byteLength(scanText.slice(0, match.index), "utf8")
-            });
-          }
-        }
-      }
-      if (terminal) {
-        if (waitForExit) {
-          sawTerminal = true;
-          consumeBgCompletion(sessionId, taskId);
-          await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
-        }
-        return withWaited(data, { reason: "exited", elapsed_ms: Date.now() - startedAt });
-      }
-      if (Date.now() >= deadline) {
-        return withWaited(data, { reason: "timeout", elapsed_ms: Date.now() - startedAt });
-      }
-      await sleep(Math.min(BASH_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
-    }
-  } finally {
-    if (waitForExit && !sawTerminal)
-      unmarkTaskWaiting(sessionId, taskId);
-    if (waitFor) {
-      await disposePtyTerminal(watchPtyCacheKey(extCtx, taskId));
-    }
+    return JSON.parse(text);
+  } catch {
+    return;
   }
 }
-async function readNewTaskOutput(extCtx, taskId, data, cursor) {
-  const outputPath = data.output_path;
-  if (data.mode === "pty") {
-    if (!outputPath)
-      return;
-    const { rows, cols } = ptyDimensions(data);
-    const state = await getOrCreatePtyTerminal(watchPtyCacheKey(extCtx, taskId), outputPath, rows, cols);
-    const baseOffset = state.offset;
-    const bytes = await readPtyBytes(state);
-    if (bytes.length === 0)
-      return;
-    return {
-      text: bytes.toString("utf8"),
-      baseOffset,
-      nextCursor: { output: state.offset, stderr: 0, combined: state.offset }
-    };
-  }
-  const stderrPath = data.stderr_path;
-  if (!outputPath && !stderrPath)
-    return;
-  const stdoutBytes = outputPath ? await readFileBytesFrom(outputPath, cursor.output) : Buffer.alloc(0);
-  const stderrBytes = stderrPath ? await readFileBytesFrom(stderrPath, cursor.stderr) : Buffer.alloc(0);
-  const bytesRead = stdoutBytes.length + stderrBytes.length;
-  if (bytesRead === 0)
-    return;
-  return {
-    text: Buffer.concat([stdoutBytes, stderrBytes]).toString("utf8"),
-    baseOffset: cursor.combined,
-    nextCursor: {
-      output: cursor.output + stdoutBytes.length,
-      stderr: cursor.stderr + stderrBytes.length,
-      combined: cursor.combined + bytesRead
-    }
-  };
+function renderErrorResult(result, fallback, theme, context) {
+  const text = reuseText2(context.lastComponent);
+  const message = collectTextContent(result) || fallback;
+  text.setText(`
+${theme.fg("error", message)}`);
+  return text;
 }
-async function readFileBytesFrom(outputPath, cursor) {
-  const handle = await fs3.open(outputPath, "r");
-  try {
-    const chunks = [];
-    let offset = cursor;
-    while (true) {
-      const buffer2 = Buffer.allocUnsafe(64 * 1024);
-      const { bytesRead } = await handle.read(buffer2, 0, buffer2.length, offset);
-      if (bytesRead === 0)
-        break;
-      chunks.push(Buffer.from(buffer2.subarray(0, bytesRead)));
-      offset += bytesRead;
-    }
-    return Buffer.concat(chunks);
-  } finally {
-    await handle.close().catch(() => {
-      return;
-    });
-  }
+function renderSections(sections, context) {
+  const container = reuseContainer2(context.lastComponent);
+  container.clear();
+  const visibleSections = sections.filter((section) => section.trim().length > 0);
+  if (visibleSections.length === 0)
+    return container;
+  container.addChild(new Spacer2(1));
+  visibleSections.forEach((section, index) => {
+    if (index > 0)
+      container.addChild(new Spacer2(1));
+    container.addChild(new Text2(section, 0, 0));
+  });
+  return container;
 }
-function parseWaitPattern(value) {
-  if (typeof value === "string")
-    return { kind: "substring", value };
-  if (isRegexWaitObject(value))
-    return { kind: "regex", value: new RegExp(value.regex), source: value.regex };
-  return;
+function asRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  return value;
 }
-function isRegexWaitObject(value) {
-  return typeof value === "object" && value !== null && "regex" in value && typeof value.regex === "string";
+function asRecords(value) {
+  return Array.isArray(value) ? value.map(asRecord2).filter(Boolean) : [];
 }
-function findWaitMatch(text, pattern) {
-  if (pattern.kind === "substring") {
-    const index = text.indexOf(pattern.value);
-    return index >= 0 ? { text: pattern.value, index } : undefined;
-  }
-  pattern.value.lastIndex = 0;
-  const match = pattern.value.exec(text);
-  return match ? { text: match[0], index: match.index } : undefined;
+function asString(value) {
+  return typeof value === "string" ? value : undefined;
 }
-function withWaited(data, waited) {
-  return { ...data, waited };
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
-function formatWaitSummary(waited, details) {
-  if (waited.reason === "matched") {
-    return `Waited ${waited.elapsed_ms}ms; matched ${JSON.stringify(waited.match ?? "")} at offset ${waited.match_offset ?? 0}.`;
-  }
-  if (waited.reason === "timeout") {
-    return `Waited ${waited.elapsed_ms}ms; timeout reached without match.`;
+function asBoolean(value) {
+  return typeof value === "boolean" ? value : undefined;
+}
+function formatValue(value) {
+  if (Array.isArray(value))
+    return value.map(formatValue).join(", ");
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value === null || value === undefined)
+    return "—";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
   }
-  const exit = typeof details.exit_code === "number" ? `, exit ${details.exit_code}` : "";
-  return `Waited ${waited.elapsed_ms}ms; task exited (${details.status}${exit}).`;
 }
-async function formatBashStatus(extCtx, taskId, details, requestedOutputMode) {
-  const exit = typeof details.exit_code === "number" ? ` (exit ${details.exit_code})` : "";
-  const dur = typeof details.duration_ms === "number" ? ` ${Math.round(details.duration_ms / 1000)}s` : "";
-  let text = `Task ${taskId}: ${details.status}${exit}${dur}`;
-  if (details.waited)
-    text += `
-${formatWaitSummary(details.waited, details)}`;
-  if (details.mode === "pty") {
-    text += await formatPtyStatus(extCtx, taskId, details, requestedOutputMode);
-  } else {
-    if (isTerminalStatus(details.status) && details.output_preview) {
-      text += `
-${details.output_preview.slice(0, 2000)}`;
+function groupByFile(items, getFile) {
+  const groups = new Map;
+  items.forEach((item) => {
+    const file2 = getFile(item) ?? "(unknown file)";
+    const current = groups.get(file2) ?? [];
+    current.push(item);
+    groups.set(file2, current);
+  });
+  return groups;
+}
+function formatTimestamp(value) {
+  if (typeof value === "string" && value.length > 0)
+    return value;
+  if (typeof value !== "number" || !Number.isFinite(value))
+    return;
+  const millis = value > 1000000000000 ? value : value * 1000;
+  const date5 = new Date(millis);
+  if (Number.isNaN(date5.getTime()))
+    return String(value);
+  return date5.toISOString().replace("T", " ").replace(".000Z", "Z");
+}
+function formatUnifiedDiffForPi(unifiedDiff) {
+  if (!unifiedDiff.trim())
+    return "";
+  const entries = [];
+  const hunkHeader = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+  let oldLine = 1;
+  let newLine = 1;
+  for (const line of unifiedDiff.split(`
+`)) {
+    if (!line)
+      continue;
+    if (line.startsWith("--- ") || line.startsWith("+++ "))
+      continue;
+    if (line.startsWith("\"))
+      continue;
+    const headerMatch = line.match(hunkHeader);
+    if (headerMatch) {
+      oldLine = Number(headerMatch[1]);
+      newLine = Number(headerMatch[2]);
+      continue;
     }
-    if (!isTerminalStatus(details.status)) {
-      text += `
-A completion reminder will be delivered automatically; don't poll.`;
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      entries.push({ prefix: "+", line: newLine, text: line.slice(1) });
+      newLine += 1;
+      continue;
+    }
+    if (line.startsWith("-") && !line.startsWith("---")) {
+      entries.push({ prefix: "-", line: oldLine, text: line.slice(1) });
+      oldLine += 1;
+      continue;
+    }
+    if (line.startsWith(" ")) {
+      entries.push({ prefix: " ", line: oldLine, text: line.slice(1) });
+      oldLine += 1;
+      newLine += 1;
     }
   }
-  return text;
+  if (entries.length === 0)
+    return "";
+  const width = String(entries.reduce((max, entry) => Math.max(max, entry.line), 1)).length;
+  return entries.map((entry) => `${entry.prefix}${String(entry.line).padStart(width, " ")} ${entry.text}`).join(`
+`);
 }
-async function formatPtyStatus(extCtx, taskId, details, requestedOutputMode) {
-  if (!details.output_path)
-    return `
-[PTY output path unavailable]`;
-  const key = ptyCacheKey(extCtx, taskId);
-  const { rows, cols } = ptyDimensions(details);
-  const state = await getOrCreatePtyTerminal(key, details.output_path, rows, cols);
-  const raw = await readPtyBytes(state);
-  const outputMode = requestedOutputMode ?? "screen";
-  let suffix = "";
-  if (outputMode === "raw") {
-    suffix = raw.length > 0 ? `
-${raw.toString("utf8")}` : "";
-  } else if (outputMode === "both") {
-    suffix = `
-${JSON.stringify({ screen: renderScreen(state, rows, cols), raw: raw.toString("utf8") }, null, 2)}`;
-  } else {
-    const screen = renderScreen(state, rows, cols);
-    suffix = screen ? `
-${screen}` : "";
-  }
-  if (!isTerminalStatus(details.status)) {
-    suffix += `
-PTY task is still running. Use bash_status({ task_id: "${taskId}", output_mode: "screen" }) to inspect, bash_write({ task_id: "${taskId}", input: "..." }) to send keystrokes.`;
-  } else {
-    await disposePtyTerminal(key);
+function renderUnifiedDiff(unifiedDiff) {
+  const piDiff = formatUnifiedDiffForPi(unifiedDiff);
+  if (!piDiff)
+    return "";
+  try {
+    return renderDiff2(piDiff);
+  } catch {
+    return piDiff;
   }
-  return suffix;
-}
-function ptyDimensions(data) {
-  const rows = typeof data.pty_rows === "number" ? data.pty_rows : 24;
-  const cols = typeof data.pty_cols === "number" ? data.pty_cols : 80;
-  return { rows, cols };
-}
-function ptyCacheKey(extCtx, taskId) {
-  return `${extCtx.cwd}::${resolveSessionId(extCtx) ?? "__default__"}::${taskId}`;
 }
-function watchPtyCacheKey(extCtx, taskId) {
-  return `${ptyCacheKey(extCtx, taskId)}::watch`;
+
+// src/tools/ast.ts
+var AstLang = StringEnum(["typescript", "tsx", "javascript", "python", "rust", "go"], {
+  description: "Target language"
+});
+var SearchParams = Type3.Object({
+  pattern: Type3.String({
+    description: "AST pattern with meta-variables (`$VAR` matches one node, `$$$` matches many). Must be a complete AST node."
+  }),
+  lang: AstLang,
+  paths: Type3.Optional(Type3.Array(Type3.String(), { description: "Paths to search (default: ['.'])" })),
+  globs: Type3.Optional(Type3.Array(Type3.String(), { description: "Include/exclude globs (prefix `!` to exclude)" })),
+  contextLines: Type3.Optional(Type3.Number({ description: "Number of context lines around each match" }))
+});
+var ReplaceParams = Type3.Object({
+  pattern: Type3.String({ description: "AST pattern with meta-variables" }),
+  rewrite: Type3.String({ description: "Replacement pattern, can reference $VAR from pattern" }),
+  lang: AstLang,
+  paths: Type3.Optional(Type3.Array(Type3.String(), { description: "Paths (default: ['.'])" })),
+  globs: Type3.Optional(Type3.Array(Type3.String(), { description: "Include/exclude globs" })),
+  dryRun: Type3.Optional(Type3.Boolean({ description: "Preview without applying (default: false)" }))
+});
+function appendHintSection(response, sections, theme) {
+  const hint = asString(response.hint);
+  if (hint && hint.length > 0) {
+    sections.push(theme.fg("warning", hint));
+  }
 }
-function isTerminalStatus(status) {
-  return status === "completed" || status === "failed" || status === "killed" || status === "timed_out";
+function appendScopeSections(response, sections, theme) {
+  if (response.no_files_matched_scope === true) {
+    sections.push(theme.fg("warning", "No files matched the scope (paths/globs resolved to zero files)"));
+  }
+  const warnings = asRecords(response.scope_warnings);
+  const warningStrings = Array.isArray(response.scope_warnings) ? response.scope_warnings.filter((w) => typeof w === "string") : warnings.map((w) => asString(w.warning) ?? "").filter(Boolean);
+  if (warningStrings.length > 0) {
+    sections.push(`${theme.fg("muted", "Scope warnings:")}
+${warningStrings.map((w) => `  ${w}`).join(`
+`)}`);
+  }
 }
-function renderBashCall(command, description, theme, context) {
-  const text = reuseText2(context.lastComponent);
-  const display = description ?? (command ? shortenCommand(command) : "...");
-  text.setText(`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", display)}`);
-  return text;
+async function resolveAstPaths(extCtx, paths) {
+  if (isEmptyParam(paths) || !Array.isArray(paths))
+    return;
+  return Promise.all(paths.filter((path2) => typeof path2 === "string").map((path2) => resolvePathArg(extCtx.cwd, path2)));
 }
-function renderBashResult(result, theme, context) {
-  if (context.isError) {
-    const errorText = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
-`).trim();
-    const text = reuseText2(context.lastComponent);
-    text.setText(`
-${theme.fg("error", errorText || "bash failed")}`);
-    return text;
-  }
-  const details = result.details;
-  const exitCode = details?.exit_code;
-  const bgCompletions = details?.bg_completions ?? [];
-  const container = reuseContainer2(context.lastComponent);
-  container.clear();
-  container.addChild(new Spacer2(1));
-  const rawOutput = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
-`).trim();
-  if (rawOutput) {
-    const lines = rawOutput.split(`
-`);
-    const preview = lines.length > 25 ? `... (${lines.length - 25} lines omitted)
-${lines.slice(-25).join(`
-`)}` : rawOutput;
-    container.addChild(new Text2(preview, 1, 0));
-    container.addChild(new Spacer2(1));
+async function assertAstPathsPermission(extCtx, paths, action, restrictToProjectRoot) {
+  if (paths === undefined || paths.length === 0)
+    return;
+  const checked = new Set;
+  for (const path2 of paths) {
+    if (checked.has(path2))
+      continue;
+    checked.add(path2);
+    await assertExternalDirectoryPermission(extCtx, path2, action, { restrictToProjectRoot });
   }
-  if (exitCode !== undefined) {
-    const exitColor = exitCode === 0 ? "success" : "error";
-    const exitText = theme.fg(exitColor, `exit ${exitCode}`);
-    container.addChild(new Text2(exitText, 1, 0));
-  }
-  if (bgCompletions.length > 0) {
-    container.addChild(new Spacer2(1));
-    for (const bg of bgCompletions) {
-      const cmdPreview = bg.command ? bg.command.slice(0, 60) : "unknown command";
-      const suffix = (bg.command?.length ?? 0) > 60 ? "..." : "";
-      const exitInfo = bg.exit_code !== undefined ? `exit ${bg.exit_code}` : bg.status;
-      const statusColor = bg.status === "completed" && bg.exit_code === 0 ? "success" : "warning";
-      const line = theme.fg(statusColor, `Background task ${bg.task_id} completed (${exitInfo}): ${cmdPreview}${suffix}`);
-      container.addChild(new Text2(line, 1, 0));
-    }
-  }
-  if (details?.duration_ms !== undefined) {
-    container.addChild(new Spacer2(1));
-    const durationText = theme.fg("muted", `${details.duration_ms}ms`);
-    container.addChild(new Text2(durationText, 1, 0));
+}
+function buildAstSearchSections(payload, theme) {
+  const response = asRecord2(payload);
+  if (!response)
+    return [theme.fg("muted", "No AST search results.")];
+  const matches = asRecords(response.matches);
+  const totalMatches = asNumber(response.total_matches) ?? matches.length;
+  const filesWithMatches = asNumber(response.files_with_matches) ?? groupByFile(matches, (match) => asString(match.file)).size;
+  const filesSearched = asNumber(response.files_searched);
+  const header = [
+    theme.fg("success", `${totalMatches} match${totalMatches === 1 ? "" : "es"}`),
+    theme.fg("accent", `${filesWithMatches} file${filesWithMatches === 1 ? "" : "s"}`),
+    filesSearched !== undefined ? theme.fg("muted", `${filesSearched} searched`) : undefined
+  ].filter(Boolean).join(" · ");
+  if (matches.length === 0) {
+    const sections2 = [header, theme.fg("muted", "No AST matches found.")];
+    appendScopeSections(response, sections2, theme);
+    appendHintSection(response, sections2, theme);
+    return sections2;
   }
-  if (details?.truncated) {
-    container.addChild(new Spacer2(1));
-    const truncText = theme.fg("warning", "(output truncated)");
-    container.addChild(new Text2(truncText, 1, 0));
+  const grouped = groupByFile(matches, (match) => asString(match.file));
+  const sections = [header];
+  for (const [file2, fileMatches] of grouped.entries()) {
+    const lines = [theme.fg("accent", shortenPath2(file2))];
+    fileMatches.forEach((match, index) => {
+      const line = asNumber(match.line) ?? 0;
+      const column = asNumber(match.column) ?? 0;
+      const snippet = asString(match.text)?.trim() || "(empty match)";
+      lines.push(`  ${index + 1}. ${theme.fg("muted", `${line}:${column}`)} ${snippet}`);
+      const metaVars = asRecord2(match.meta_variables);
+      if (metaVars && Object.keys(metaVars).length > 0) {
+        Object.entries(metaVars).forEach(([name, value]) => {
+          lines.push(`     ${theme.fg("muted", `${name} =`)} ${formatValue(value)}`);
+        });
+      }
+      const context = asRecords(match.context);
+      context.forEach((ctxLine) => {
+        const ctxNumber = asNumber(ctxLine.line) ?? 0;
+        const prefix = ctxLine.is_match === true ? theme.fg("accent", ">") : theme.fg("muted", "|");
+        lines.push(`     ${prefix} ${ctxNumber}: ${asString(ctxLine.text) ?? ""}`);
+      });
+    });
+    sections.push(lines.join(`
+`));
   }
-  return container;
-}
-function shortenCommand(command) {
-  if (command.length <= 60)
-    return command;
-  return `${command.slice(0, 57)}...`;
-}
-
-// src/tools/conflicts.ts
-import { Type as Type4 } from "typebox";
-var ConflictsParams = Type4.Object({});
-function renderConflictCall(theme, context) {
-  return renderToolCall("conflicts", undefined, theme, context);
+  return sections;
 }
-function buildConflictSections(text) {
-  const trimmed = text.trim();
-  if (!trimmed)
-    return ["No merge conflicts found."];
-  const [header, ...rest] = trimmed.split(/\n\n+/);
-  const match = header.match(/^(\d+)\s+files?,\s+(\d+)\s+conflicts?/i);
-  const sections = [
-    match ? `${match[1]} conflicted file${match[1] === "1" ? "" : "s"} · ${match[2]} region${match[2] === "1" ? "" : "s"}` : header
+function buildAstReplaceSections(payload, theme) {
+  const response = asRecord2(payload);
+  if (!response)
+    return [theme.fg("muted", "No AST replace results.")];
+  const files = asRecords(response.files);
+  const totalReplacements = asNumber(response.total_replacements) ?? 0;
+  const totalFiles = asNumber(response.total_files) ?? files.length;
+  const filesWithMatches = asNumber(response.files_with_matches);
+  const dryRun = response.dry_run === true;
+  const headerParts = [
+    dryRun ? theme.fg("warning", "[dry run]") : theme.fg("success", "[applied]"),
+    `${totalReplacements} replacement${totalReplacements === 1 ? "" : "s"}`,
+    `${totalFiles} file${totalFiles === 1 ? "" : "s"}`,
+    filesWithMatches !== undefined ? theme.fg("muted", `${filesWithMatches} matched`) : undefined
   ];
-  if (rest.length === 0)
+  const sections = [headerParts.filter(Boolean).join(" ")];
+  if (files.length === 0) {
+    sections.push(theme.fg("muted", "No files changed."));
+    appendScopeSections(response, sections, theme);
+    appendHintSection(response, sections, theme);
     return sections;
-  sections.push(...rest.map((section) => section.trim()).filter(Boolean));
-  return sections;
-}
-function renderConflictResult(text, theme, context) {
-  const sections = buildConflictSections(text).map((section, index) => index === 0 ? theme.fg("warning", section) : section);
-  return renderSections(sections, context);
-}
-function renderConflictToolResult(result, theme, context) {
-  if (context.isError)
-    return renderErrorResult(result, "conflicts failed", theme, context);
-  return renderConflictResult(collectTextContent(result), theme, context);
-}
-function registerConflictsTool(pi, ctx) {
-  pi.registerTool({
-    name: "aft_conflicts",
-    label: "conflicts",
-    description: "Show all git merge conflicts across the repository — returns line-numbered conflict regions with context for every conflicted file in a single call.",
-    parameters: ConflictsParams,
-    async execute(_toolCallId, _params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const response = await callBridge(bridge, "git_conflicts", {}, extCtx);
-      return textResult(response.text ?? JSON.stringify(response, null, 2));
-    },
-    renderCall(_args, theme, context) {
-      return renderConflictCall(theme, context);
-    },
-    renderResult(result, _options, theme, context) {
-      return renderConflictToolResult(result, theme, context);
+  }
+  files.forEach((fileResult) => {
+    const file2 = shortenPath2(asString(fileResult.file) ?? "(unknown file)");
+    const replacements = asNumber(fileResult.replacements) ?? 0;
+    const error50 = asString(fileResult.error);
+    const diff = asString(fileResult.diff);
+    const lines = [
+      `${theme.fg("accent", file2)} ${theme.fg("muted", `(${replacements} replacement${replacements === 1 ? "" : "s"})`)}`
+    ];
+    if (error50) {
+      lines.push(theme.fg("error", error50));
+    } else if (diff) {
+      const rendered = renderUnifiedDiff(diff);
+      lines.push(rendered || theme.fg("muted", "No diff available."));
+    } else {
+      const backupId = asString(fileResult.backup_id);
+      lines.push(backupId ? `${theme.fg("success", "saved")} ${theme.fg("muted", backupId)}` : theme.fg("success", "saved"));
     }
+    sections.push(lines.join(`
+`));
   });
+  return sections;
 }
-
-// src/tools/fs.ts
-import { Type as Type5 } from "typebox";
-var DeleteParams = Type5.Object({
-  files: Type5.Array(Type5.String(), {
-    description: "Paths to delete (one or more). May include directories when recursive=true.",
-    minItems: 1
-  }),
-  recursive: Type5.Optional(Type5.Boolean({
-    description: "Required to delete a directory and its contents. Defaults to false; passing a directory without this returns an error."
-  }))
-});
-var MoveParams = Type5.Object({
-  filePath: Type5.String({
-    description: "Source file path to move (absolute or relative to project root)"
-  }),
-  destination: Type5.String({
-    description: "Destination file path (absolute or relative to project root)"
-  })
-});
-function renderFsCall(toolName, args, theme, context) {
-  if (toolName === "aft_delete") {
-    const files = args.files;
-    const summary = files.length === 1 ? accentPath(theme, files[0]) : `${theme.fg("accent", String(files.length))} ${theme.fg("muted", "files")}`;
-    return renderToolCall("delete", summary, theme, context);
-  }
-  const moveArgs = args;
-  return renderToolCall("move", `${accentPath(theme, moveArgs.filePath)} ${theme.fg("muted", "→")} ${accentPath(theme, moveArgs.destination)}`, theme, context);
+function renderAstCall(toolName, args, theme, context) {
+  const lang = theme.fg("accent", args.lang);
+  const summary = toolName === "ast_grep_replace" ? `${lang} ${theme.fg("toolOutput", `${args.pattern} → ${args.rewrite}`)}` : `${lang} ${theme.fg("toolOutput", args.pattern)}`;
+  return renderToolCall(toolName === "ast_grep_replace" ? "ast replace" : "ast search", summary, theme, context);
 }
-function renderFsResult(toolName, args, result, theme, context) {
+function renderAstResult(toolName, result, theme, context) {
   if (context.isError) {
     return renderErrorResult(result, `${toolName} failed`, theme, context);
   }
-  if (toolName === "aft_delete") {
-    const files = args.files;
-    const data = result?.details ?? {};
-    const deletedPaths = data.deleted ?? files;
-    const skipped = data.skipped_files ?? [];
-    const lines = [];
-    for (const entry of deletedPaths) {
-      lines.push(`${theme.fg("success", "✓ deleted")} ${theme.fg("accent", shortenPath(entry))}`);
-    }
-    for (const entry of skipped) {
-      lines.push(`${theme.fg("error", "✗ skipped")} ${theme.fg("accent", shortenPath(entry.file))} ${theme.fg("muted", `(${entry.reason})`)}`);
-    }
-    if (lines.length === 0) {
-      lines.push(theme.fg("muted", "(no files deleted)"));
-    }
-    return renderSections([lines.join(`
-`)], context);
+  const payload = extractStructuredPayload(result);
+  if (!payload) {
+    const text = collectTextContent(result);
+    return renderSections([text || theme.fg("muted", "No result.")], context);
   }
-  const moveArgs = args;
-  return renderSections([
-    `${theme.fg("success", "✓ moved")} ${theme.fg("accent", shortenPath(moveArgs.filePath))}`,
-    `${theme.fg("muted", "to")} ${theme.fg("accent", shortenPath(moveArgs.destination))}`
-  ], context);
+  const sections = toolName === "ast_grep_replace" ? buildAstReplaceSections(payload, theme) : buildAstSearchSections(payload, theme);
+  return renderSections(sections, context);
 }
-function registerFsTools(pi, ctx, surface) {
-  if (surface.delete) {
+function registerAstTools(pi, ctx, surface) {
+  if (surface.astSearch) {
     pi.registerTool({
-      name: "aft_delete",
-      label: "delete",
-      description: "Delete one or more files (or directories) with backup. Each file is backed up before deletion — use `aft_safety undo` to recover any of them. " + "For directories, every file inside is individually backed up before removal. Directory deletion requires recursive: true. " + "Returns { success, complete, deleted, skipped_files }: partial success is allowed; files that fail are reported in skipped_files.",
-      parameters: DeleteParams,
+      name: "ast_grep_search",
+      label: "ast search",
+      description: "Search code patterns across the filesystem using AST-aware matching. Use `$VAR` to match a single AST node, `$$$` for multiple. Pattern must be a complete, valid code fragment (include braces, params, etc.).",
+      parameters: SearchParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const paths = await resolveAstPaths(extCtx, params.paths);
+        await assertAstPathsPermission(extCtx, paths, "search", ctx.config.restrict_to_project_root ?? false);
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const response = await callBridge(bridge, "delete_file", {
-          files: params.files,
-          recursive: params.recursive === true
-        }, extCtx);
-        const deletedEntries = response.deleted ?? [];
-        const skipped = response.skipped_files ?? [];
-        const deleted = deletedEntries.map((entry) => entry.file);
-        if (deleted.length === 0 && skipped.length > 0) {
-          throw new Error(`delete failed for all ${skipped.length} file(s):
-` + skipped.map((entry) => `  ${entry.file}: ${entry.reason}`).join(`
-`));
-        }
-        const summary = deleted.length === 1 && skipped.length === 0 ? `Deleted ${deleted[0]}` : `Deleted ${deleted.length}/${params.files.length} file(s)`;
-        return textResult(summary, {
-          success: true,
-          complete: skipped.length === 0,
-          deleted,
-          skipped_files: skipped
-        });
+        const req = {
+          pattern: params.pattern,
+          lang: params.lang
+        };
+        if (!isEmptyParam(paths))
+          req.paths = paths;
+        if (!isEmptyParam(params.globs))
+          req.globs = params.globs;
+        if (params.contextLines !== undefined)
+          req.context_lines = params.contextLines;
+        const response = await callBridge(bridge, "ast_search", req, extCtx);
+        return textResult(response.text ?? JSON.stringify(response));
       },
       renderCall(args, theme, context) {
-        return renderFsCall("aft_delete", args, theme, context);
+        return renderAstCall("ast_grep_search", args, theme, context);
       },
       renderResult(result, _options, theme, context) {
-        return renderFsResult("aft_delete", context.args, result, theme, context);
+        return renderAstResult("ast_grep_search", result, theme, context);
       }
     });
   }
-  if (surface.move) {
+  if (surface.astReplace) {
     pi.registerTool({
-      name: "aft_move",
-      label: "move",
-      description: "Move or rename a file with backup. Creates parent directories for the destination automatically. This operates on files at the OS level — to relocate a code symbol between files, use `aft_refactor` with op='move' instead.",
-      parameters: MoveParams,
+      name: "ast_grep_replace",
+      label: "ast replace",
+      description: "Replace code patterns across the filesystem with AST-aware rewriting. Applies by default — pass `dryRun: true` to preview. Use meta-variables in `rewrite` to preserve captured content from the pattern.",
+      parameters: ReplaceParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const paths = await resolveAstPaths(extCtx, params.paths);
+        await assertAstPathsPermission(extCtx, paths, params.dryRun === true ? "search" : "modify", ctx.config.restrict_to_project_root ?? false);
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const response = await callBridge(bridge, "move_file", {
-          file: params.filePath,
-          destination: params.destination
-        }, extCtx);
-        return textResult(`Moved ${params.filePath} → ${params.destination}`, response);
-      },
-      renderCall(args, theme, context) {
-        return renderFsCall("aft_move", args, theme, context);
+        const req = {
+          pattern: params.pattern,
+          rewrite: params.rewrite,
+          lang: params.lang
+        };
+        if (!isEmptyParam(paths))
+          req.paths = paths;
+        if (!isEmptyParam(params.globs))
+          req.globs = params.globs;
+        req.dry_run = params.dryRun === true;
+        const response = await callBridge(bridge, "ast_replace", req, extCtx);
+        return textResult(response.text ?? JSON.stringify(response));
+      },
+      renderCall(args, theme, context) {
+        return renderAstCall("ast_grep_replace", args, theme, context);
       },
       renderResult(result, _options, theme, context) {
-        return renderFsResult("aft_move", context.args, result, theme, context);
+        return renderAstResult("ast_grep_replace", result, theme, context);
       }
     });
   }
 }
 
-// src/tools/hoisted.ts
-import { stat } from "node:fs/promises";
-import { homedir as homedir9 } from "node:os";
-import { isAbsolute as isAbsolute2, relative as relative3, resolve as resolve3, sep } from "node:path";
-import {
-  renderDiff as renderDiff2
-} from "@earendil-works/pi-coding-agent";
+// src/tools/bash.ts
+import * as fs3 from "node:fs/promises";
 import { Container as Container3, Spacer as Spacer3, Text as Text3 } from "@earendil-works/pi-tui";
-import { Type as Type6 } from "typebox";
-
-// src/tools/diff-format.ts
-import { diffLines } from "diff";
-var DEFAULT_CONTEXT_LINES = 4;
-function formatDiffForPi(oldContent, newContent, contextLines = DEFAULT_CONTEXT_LINES) {
-  const parts = diffLines(oldContent, newContent);
-  const output = [];
-  const oldLines = oldContent.split(`
-`);
-  const newLines = newContent.split(`
+import { Type as Type4 } from "typebox";
+var FOREGROUND_POLL_INTERVAL_MS = 100;
+var BASH_WAIT_POLL_INTERVAL_MS = 100;
+var DEFAULT_BASH_STATUS_WAIT_TIMEOUT_MS = 30000;
+var MAX_BASH_STATUS_WAIT_TIMEOUT_MS = 300000;
+var BASH_TRANSPORT_TIMEOUT_MS = 30000;
+var BashParams = Type4.Object({
+  command: Type4.String({
+    description: "Shell command to execute. Supports pipes, redirections, and shell syntax."
+  }),
+  timeout: optionalInt(1, Number.MAX_SAFE_INTEGER),
+  workdir: Type4.Optional(Type4.String({
+    description: "Working directory for command execution. Relative paths resolve against the project root. Defaults to the current session's working directory."
+  })),
+  description: Type4.Optional(Type4.String({
+    description: "Human-readable description shown in UI logs. Helps users understand what the command does without reading shell syntax."
+  })),
+  background: Type4.Optional(Type4.Boolean({
+    description: "Spawn command in background and return immediately with a task_id. Use bash_status to poll completion and bash_kill to terminate. Ideal for long-running tasks like builds or dev servers."
+  })),
+  compressed: Type4.Optional(Type4.Boolean({
+    description: "Compress output by removing ANSI codes, carriage returns, and excessive blank lines. Default: true. Set to false for raw terminal output including color codes."
+  })),
+  pty: Type4.Optional(Type4.Boolean({
+    description: 'Spawn the command in a real PTY for interactive programs. Implies background: true automatically. Inspect with bash_status({ task_id, output_mode: "screen" }) and send input with bash_write.'
+  })),
+  ptyRows: optionalInt(1, 60),
+  ptyCols: optionalInt(1, 140)
+});
+var BashTaskParams = Type4.Object({
+  task_id: Type4.String({
+    description: "Background bash task id returned by bash({ background: true })."
+  })
+});
+var BashStatusParams = Type4.Object({
+  task_id: Type4.String({
+    description: "Background bash task id returned by bash({ background: true })."
+  }),
+  output_mode: Type4.Optional(Type4.Union([Type4.Literal("screen"), Type4.Literal("raw"), Type4.Literal("both")], {
+    description: "PTY output rendering mode. Defaults to screen for PTY tasks and preserves existing behavior for piped tasks when omitted."
+  }))
+});
+var BashWatchParams = Type4.Object({
+  task_id: Type4.String({
+    description: "Background bash task id returned by bash({ background: true })."
+  }),
+  pattern: Type4.Optional(Type4.Union([Type4.String(), Type4.Object({ regex: Type4.String() })])),
+  background: Type4.Optional(Type4.Boolean()),
+  timeout_ms: optionalInt(1, MAX_BASH_STATUS_WAIT_TIMEOUT_MS),
+  once: Type4.Optional(Type4.Boolean())
+});
+var BashWriteParams = Type4.Object({
+  task_id: Type4.String({
+    description: "Background PTY task id returned by bash({ pty: true, background: true })."
+  }),
+  input: Type4.Union([
+    Type4.String(),
+    Type4.Array(Type4.Union([
+      Type4.String(),
+      Type4.Object({
+        key: Type4.String({
+          description: "Named control key, e.g. 'esc', 'enter', 'up', 'ctrl-c'. Case-insensitive."
+        })
+      })
+    ]))
+  ], {
+    description: "Either a string of verbatim bytes (e.g. 'print(1)\\n') OR an array mixing strings " + "and { key: '<name>' } objects for atomic text+key sequences. " + "Example: [ 'iHello', { key: 'esc' }, ':wq', { key: 'enter' } ]. " + "Allowed key names: enter, return, tab, space, backspace, esc, escape, up, down, " + "left, right, home, end, page-up, page-down, delete, insert, f1..f12, ctrl-a..ctrl-z."
+  })
+});
+function truncateToVisualLines(text, maxLines) {
+  const lines = text.split(`
 `);
-  const maxLineNum = Math.max(oldLines.length, newLines.length);
-  const lineNumWidth = String(maxLineNum).length;
-  const pad = (n) => String(n).padStart(lineNumWidth, " ");
-  const blank = " ".repeat(lineNumWidth);
-  let oldLineNum = 1;
-  let newLineNum = 1;
-  let lastWasChange = false;
-  let firstChangedLine;
-  for (let i = 0;i < parts.length; i++) {
-    const part = parts[i];
-    const raw = part.value.split(`
+  if (lines.length <= maxLines)
+    return text;
+  return lines.slice(-maxLines).join(`
 `);
-    if (raw[raw.length - 1] === "")
-      raw.pop();
-    if (part.added || part.removed) {
-      if (firstChangedLine === undefined)
-        firstChangedLine = newLineNum;
-      for (const line of raw) {
-        if (part.added) {
-          output.push(`+${pad(newLineNum)} ${line}`);
-          newLineNum++;
-        } else {
-          output.push(`-${pad(oldLineNum)} ${line}`);
-          oldLineNum++;
+}
+function reuseText3(last) {
+  return last instanceof Text3 ? last : new Text3("", 0, 0);
+}
+function reuseContainer3(last) {
+  return last instanceof Container3 ? last : new Container3;
+}
+function getBashSpawnHook(pi) {
+  const api2 = pi;
+  if (typeof api2.getHook === "function") {
+    return api2.getHook("bashSpawn");
+  }
+  return api2.hooks?.bashSpawn;
+}
+function registerBashTool(pi, ctx) {
+  const spawnHook = getBashSpawnHook(pi);
+  pi.registerTool({
+    name: "bash",
+    label: "bash",
+    description: 'Execute shell commands through AFT\'s Rust bash handler. By default, output is compressed. Pass `compressed: false` for raw output. Pass `background: true` to spawn in the background and get a task_id for `bash_status`/`bash_kill`. Pass `pty: true` with `background: true` for interactive programs and drive them with `bash_status({ output_mode: "screen" })` plus `bash_write`.',
+    promptSnippet: "Run shell commands (timeout in milliseconds; supports workdir, background tasks, compressed output, PTY mode)",
+    promptGuidelines: [
+      "Use bash only when a dedicated AFT tool is not a better fit.",
+      "Set compressed: false when you need ANSI color codes in the output."
+    ],
+    parameters: BashParams,
+    async execute(_toolCallId, params, _signal, onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const foregroundWaitMs = resolveBashConfig(ctx.config).foreground_wait_window_ms;
+      const timeout = coerceOptionalInt(params.timeout, "timeout", 1, Number.MAX_SAFE_INTEGER);
+      const ptyRows = coerceOptionalInt(params.ptyRows, "ptyRows", 1, 60);
+      const ptyCols = coerceOptionalInt(params.ptyCols, "ptyCols", 1, 140);
+      const effectiveBackground = params.background === true || params.pty === true;
+      let spawnContext = {
+        command: params.command,
+        cwd: params.workdir
+      };
+      if (spawnHook) {
+        try {
+          spawnContext = await spawnHook(spawnContext);
+        } catch (hookErr) {
+          throw new Error(`BashSpawnHook failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
         }
       }
-      lastWasChange = true;
-      continue;
-    }
-    const nextIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
-    const hasLeading = lastWasChange;
-    const hasTrailing = nextIsChange;
-    if (hasLeading && hasTrailing) {
-      if (raw.length <= contextLines * 2) {
-        for (const line of raw) {
-          output.push(` ${pad(oldLineNum)} ${line}`);
-          oldLineNum++;
-          newLineNum++;
-        }
-      } else {
-        for (const line of raw.slice(0, contextLines)) {
-          output.push(` ${pad(oldLineNum)} ${line}`);
-          oldLineNum++;
-          newLineNum++;
+      let streamed = "";
+      const response = await callBridge(bridge, "bash", {
+        command: spawnContext.command,
+        timeout,
+        workdir: spawnContext.cwd ?? params.workdir,
+        env: spawnContext.env,
+        description: params.description,
+        background: effectiveBackground,
+        notify_on_completion: effectiveBackground,
+        compressed: params.compressed,
+        pty: params.pty,
+        pty_rows: ptyRows,
+        pty_cols: ptyCols
+      }, extCtx, {
+        transportTimeoutMs: BASH_TRANSPORT_TIMEOUT_MS,
+        keepBridgeOnTimeout: true,
+        onProgress: ({ text }) => {
+          streamed += text;
+          const displayText = truncateToVisualLines(streamed, 100);
+          onUpdate?.(bashResult(displayText, { streaming: true }));
         }
-        const skipped = raw.length - contextLines * 2;
-        output.push(` ${blank} ...`);
-        oldLineNum += skipped;
-        newLineNum += skipped;
-        for (const line of raw.slice(raw.length - contextLines)) {
-          output.push(` ${pad(oldLineNum)} ${line}`);
-          oldLineNum++;
-          newLineNum++;
+      }).catch((err) => {
+        if (err instanceof Error && err.message.includes("permission_required")) {
+          throw new Error("Permission ask reached Pi adapter — this is a bug. Pi has no permission system.");
         }
+        throw err;
+      });
+      if (response.success === false) {
+        throw new Error(response.message ?? "bash failed");
       }
-    } else if (hasLeading) {
-      const shown = raw.slice(0, contextLines);
-      for (const line of shown) {
-        output.push(` ${pad(oldLineNum)} ${line}`);
-        oldLineNum++;
-        newLineNum++;
-      }
-      const skipped = raw.length - shown.length;
-      if (skipped > 0) {
-        output.push(` ${blank} ...`);
-        oldLineNum += skipped;
-        newLineNum += skipped;
-      }
-    } else if (hasTrailing) {
-      const shownCount = Math.min(contextLines, raw.length);
-      const shown = raw.slice(raw.length - shownCount);
-      const skipped = raw.length - shown.length;
-      if (skipped > 0) {
-        output.push(` ${blank} ...`);
-        oldLineNum += skipped;
-        newLineNum += skipped;
+      const taskId = response.task_id;
+      if (response.status === "running" && taskId) {
+        if (effectiveBackground) {
+          trackBgTask(resolveSessionId(extCtx), taskId);
+          return bashResult(formatBackgroundLaunch(taskId, params.pty === true), {
+            task_id: taskId
+          });
+        }
+        const waitTimeoutMs = timeout !== undefined ? Math.min(timeout, foregroundWaitMs) : foregroundWaitMs;
+        const startedAt = Date.now();
+        while (true) {
+          const status = await callBridge(bridge, "bash_status", { task_id: taskId }, extCtx);
+          if (status.success === false) {
+            throw new Error(status.message ?? "bash_status failed");
+          }
+          if (isTerminalStatus(status.status)) {
+            return bashResult(formatForegroundResult(status), {
+              exit_code: status.exit_code,
+              duration_ms: status.duration_ms,
+              truncated: status.output_truncated,
+              output_path: status.output_path,
+              task_id: taskId
+            });
+          }
+          if (Date.now() - startedAt >= waitTimeoutMs) {
+            const promoted = await callBridge(bridge, "bash_promote", { task_id: taskId }, extCtx);
+            if (promoted.success === false) {
+              throw new Error(promoted.message ?? "bash_promote failed");
+            }
+            trackBgTask(resolveSessionId(extCtx), taskId);
+            return bashResult(formatPromotionMessage(taskId, params.timeout, foregroundWaitMs), {
+              task_id: taskId
+            });
+          }
+          await sleep(FOREGROUND_POLL_INTERVAL_MS);
+        }
       }
-      for (const line of shown) {
-        output.push(` ${pad(oldLineNum)} ${line}`);
-        oldLineNum++;
-        newLineNum++;
-      }
-    } else {
-      oldLineNum += raw.length;
-      newLineNum += raw.length;
+      const details = {
+        exit_code: response.exit_code,
+        duration_ms: response.duration_ms,
+        truncated: response.truncated,
+        output_path: response.output_path,
+        task_id: taskId
+      };
+      const output = response.output ?? "";
+      return bashResult(output, details);
+    },
+    renderCall(args, theme, context) {
+      return renderBashCall(args?.command, args?.description, theme, context);
+    },
+    renderResult(result, _options, theme, context) {
+      return renderBashResult(result, theme, context);
     }
-    lastWasChange = false;
+  });
+  pi.registerTool(createBashStatusTool(ctx));
+  pi.registerTool(createBashWatchTool(ctx));
+  pi.registerTool(createBashWriteTool(ctx));
+  pi.registerTool(createBashKillTool(ctx));
+}
+function formatBackgroundLaunch(taskId, isPty) {
+  if (isPty) {
+    return `PTY task started: ${taskId}. Use bash_status({ task_id: "${taskId}", output_mode: "screen" }) to see the visible terminal, bash_write({ task_id: "${taskId}", input: ... }) to send keystrokes. A completion reminder fires automatically when the task exits.`;
   }
-  return { diff: output.join(`
-`), firstChangedLine };
+  return `Background task started: ${taskId}. A completion reminder will be delivered automatically; don't poll bash_status.`;
 }
-
-// src/tools/hoisted.ts
-var DIAGNOSTICS_PARAM_DESCRIPTION = "When true, wait up to 3 seconds for fresh LSP diagnostics on the edited file and include them in the result. Defaults to the configured `lsp.diagnostics_on_edit` value (false unless configured); per-call true/false overrides. Use aft_inspect to check diagnostics across a batch of edits or before tests/commits.";
-function diagnosticsOnEditDefault(ctx) {
-  return ctx.config.lsp?.diagnostics_on_edit ?? false;
+function formatPromotionMessage(taskId, timeout, waitWindowMs) {
+  const waited = timeout !== undefined ? Math.min(timeout, waitWindowMs) : waitWindowMs;
+  return `Foreground bash didn't finish within ${formatSeconds(waited)} and was promoted to background: ${taskId}. A completion reminder will be delivered automatically; use bash_status({ task_id: "${taskId}" }) to inspect output or bash_kill({ task_id: "${taskId}" }) to terminate.`;
 }
-function containsPath(parent, child) {
-  const rel = relative3(parent, child);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+function formatSeconds(ms) {
+  return `${Number((ms / 1000).toFixed(1))}s`;
 }
-function expandTilde(path2) {
-  if (!path2 || !path2.startsWith("~"))
-    return path2;
-  if (path2 === "~")
-    return homedir9();
-  if (path2.startsWith(`~${sep}`) || path2.startsWith("~/")) {
-    return resolve3(homedir9(), path2.slice(2));
+function formatForegroundResult(data) {
+  const output = data.output_preview ?? "";
+  const outputPath = data.output_path;
+  const truncated = data.output_truncated === true;
+  const status = data.status;
+  const exit = data.exit_code;
+  let rendered = output;
+  if (truncated && outputPath) {
+    rendered += `
+[output truncated; full output at ${outputPath}]`;
   }
-  return path2;
+  if (status === "timed_out") {
+    rendered += `
+[command timed out]`;
+  }
+  if (typeof exit === "number" && exit !== 0) {
+    rendered += `
+[exit code: ${exit}]`;
+  }
+  return rendered;
 }
-function externalDirectoryPromptTimeoutMs() {
-  const raw = process.env.AFT_PI_EXTERNAL_PROMPT_TIMEOUT_MS;
-  if (raw === undefined)
-    return 30000;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30000;
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
-async function assertExternalDirectoryPermission(extCtx, target, action = "modify", options = {}) {
-  if (!target)
-    return;
-  const expanded = expandTilde(target);
-  const absoluteTarget = isAbsolute2(expanded) ? expanded : resolve3(extCtx.cwd, expanded);
-  if (containsPath(extCtx.cwd, absoluteTarget))
-    return;
-  if (options.restrictToProjectRoot === false)
-    return;
-  const confirmFn = extCtx.ui?.confirm;
-  if (extCtx.hasUI === false || !confirmFn) {
-    throw new Error(`Permission denied: cannot prompt for ${action} outside the project (${absoluteTarget}).`);
-  }
-  const timeoutMs = externalDirectoryPromptTimeoutMs();
-  let timer;
-  const timeoutPromise = new Promise((resolve4) => {
-    timer = setTimeout(() => resolve4("timeout"), timeoutMs);
-  });
-  try {
-    const result = await Promise.race([
-      confirmFn("Allow external directory access?", `AFT wants to ${action} outside the project: ${absoluteTarget}`),
-      timeoutPromise
-    ]);
-    if (result === true)
-      return;
-    if (result === "timeout") {
-      throw new Error(`Permission denied: external directory prompt timed out after ${timeoutMs}ms.`);
+function createBashStatusTool(ctx) {
+  return {
+    name: "bash_status",
+    label: "bash_status",
+    description: "Read-only snapshot of a background bash task. Returns immediately. Never waits. Use bash_watch to block on or register for pattern matches and exit events.",
+    promptSnippet: "Inspect a background bash task by task_id",
+    parameters: BashStatusParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const data = await bashStatusSnapshot(bridge, extCtx, params.task_id, params.output_mode);
+      const details = data;
+      return bashStatusResult(await formatBashStatus(extCtx, params.task_id, details, params.output_mode), details);
     }
-    throw new Error("Permission denied: external directory access was cancelled.");
-  } finally {
-    if (timer !== undefined)
-      clearTimeout(timer);
-  }
+  };
 }
-var ReadParams = Type6.Object({
-  path: Type6.String({
-    description: "Path to the file to read (absolute or relative to project root)"
-  }),
-  offset: optionalInt(1, Number.MAX_SAFE_INTEGER),
-  limit: optionalInt(1, Number.MAX_SAFE_INTEGER)
-});
-var WriteParams = Type6.Object({
-  filePath: Type6.String({
-    description: "Path to the file to write (absolute or relative to project root)"
-  }),
-  content: Type6.String({ description: "Full file contents to write" }),
-  diagnostics: Type6.Optional(Type6.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
-});
-var EditParams = Type6.Object({
-  filePath: Type6.String({
-    description: "Path to the file to edit (absolute or relative to project root)"
-  }),
-  oldString: Type6.Optional(Type6.String({ description: "Text to find (exact match, fuzzy fallback)" })),
-  newString: Type6.Optional(Type6.String({ description: "Replacement text (omit to delete match)" })),
-  replaceAll: Type6.Optional(Type6.Boolean({ description: "Replace every occurrence" })),
-  occurrence: optionalInt(0, Number.MAX_SAFE_INTEGER),
-  appendContent: Type6.Optional(Type6.String({
-    description: "Append text to the end of the file (creates the file if missing, parent dirs auto-created). When set, oldString/newString are ignored."
-  })),
-  diagnostics: Type6.Optional(Type6.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
-});
-var GrepParams = Type6.Object({
-  pattern: Type6.String({ description: "Regex pattern to search for" }),
-  path: Type6.Optional(Type6.String({
-    description: "Path scope (file or directory; absolute or relative to project root)"
-  })),
-  include: Type6.Optional(Type6.String({ description: "Glob filter for included files (e.g. '*.ts,*.tsx')" })),
-  caseSensitive: Type6.Optional(Type6.Boolean({ description: "Case-sensitive matching" })),
-  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER)
-});
-function registerHoistedTools(pi, ctx, surface) {
-  if (surface.hoistRead) {
-    pi.registerTool({
-      name: "read",
-      label: "read",
-      description: "Read file contents with line numbers. Backed by AFT's indexed Rust reader — faster than the built-in `read` on large repos and correctly handles images/PDFs as attachments.",
-      promptSnippet: "Read file contents (supports offset/limit for large files)",
-      promptGuidelines: ["Use read to examine files instead of cat or sed."],
-      parameters: ReadParams,
-      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        const bridge = bridgeFor(ctx, extCtx.cwd);
-        const offset = coerceOptionalInt(params.offset, "offset", 1, Number.MAX_SAFE_INTEGER);
-        const limit = coerceOptionalInt(params.limit, "limit", 1, Number.MAX_SAFE_INTEGER);
-        const req = { file: params.path };
-        if (offset !== undefined) {
-          req.start_line = offset;
-          if (limit !== undefined) {
-            req.end_line = offset + limit - 1;
-          }
-        } else if (limit !== undefined) {
-          req.end_line = limit;
+function createBashWatchTool(ctx) {
+  return {
+    name: "bash_watch",
+    label: "bash_watch",
+    description: "Block on a background bash task until a pattern matches, it exits, or timeout elapses; or register an async pattern notification with background:true.",
+    promptSnippet: "Wait for or watch a background bash task",
+    parameters: BashWatchParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const waitFor = parseWaitPattern(params.pattern);
+      if (params.background === true) {
+        if (!waitFor) {
+          throw new Error("invalid_request: Use auto-reminder; bash_watch without pattern in async mode is redundant");
         }
-        const response = await callBridge(bridge, "read", req, extCtx);
-        if (Array.isArray(response.entries)) {
-          return textResult(response.entries.join(`
-`));
+        const notifyParams = {
+          task_id: params.task_id,
+          once: params.once !== false
+        };
+        if (waitFor.kind === "regex")
+          notifyParams.regex = waitFor.source;
+        else
+          notifyParams.pattern = waitFor.value;
+        const sessionId = resolveSessionId(extCtx);
+        markExplicitControl(sessionId, params.task_id, false);
+        let registered;
+        try {
+          registered = await callBridge(bridge, "bash_notify", notifyParams, extCtx);
+        } catch (err) {
+          unmarkExplicitControl(sessionId, params.task_id);
+          throw err;
         }
-        let text = response.content ?? "";
-        const agentSpecifiedRange = offset !== undefined || limit !== undefined;
-        const footer = formatReadFooter(agentSpecifiedRange, response);
-        if (footer)
-          text += footer;
-        return textResult(text);
+        if (registered.success === false) {
+          unmarkExplicitControl(sessionId, params.task_id);
+          const message = String(registered.message ?? "bash_notify failed");
+          throw new Error(`${String(registered.code ?? "invalid_request")}: ${message}`);
+        }
+        markExplicitControl(sessionId, params.task_id);
+        const watchDetails = { registered: true, watchId: registered.watch_id };
+        return textResult(`Watch registered: ${registered.watch_id} on task ${params.task_id}
+A notification will fire when the pattern matches or the task exits.`, watchDetails);
       }
-    });
-  }
-  if (surface.hoistWrite) {
-    pi.registerTool({
-      name: "write",
-      label: "write",
-      description: "Write a file atomically with per-file backup and optional auto-format. Parent directories are created automatically. Overwrites existing files. Uses `filePath` (not `path`). Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
-      promptSnippet: "Create or overwrite files (uses filePath; auto-formats; diagnostics follow lsp.diagnostics_on_edit unless overridden)",
-      promptGuidelines: ["Use write only for new files or complete rewrites."],
-      parameters: WriteParams,
-      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
-          restrictToProjectRoot: surface.restrictToProjectRoot
-        });
-        const bridge = bridgeFor(ctx, extCtx.cwd);
-        const response = await callBridge(bridge, "write", {
-          file: params.filePath,
-          content: params.content,
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
-          include_diff_content: true
-        }, extCtx);
-        return buildMutationResult(params.filePath, response);
-      },
-      renderCall(args, theme, context) {
-        return renderMutationCall("write", args?.filePath, theme, context);
-      },
-      renderResult(result, _options, theme, context) {
-        return renderMutationResult(result, theme, context);
+      const data = await waitForBashStatus(ctx, bridge, extCtx, params.task_id, undefined, waitFor, true, Math.min(coerceOptionalInt(params.timeout_ms, "timeout_ms", 1, MAX_BASH_STATUS_WAIT_TIMEOUT_MS) ?? DEFAULT_BASH_STATUS_WAIT_TIMEOUT_MS, MAX_BASH_STATUS_WAIT_TIMEOUT_MS));
+      const text = await formatBashStatus(extCtx, params.task_id, data, undefined);
+      return textResult(text, data);
+    }
+  };
+}
+function createBashWriteTool(ctx) {
+  return {
+    name: "bash_write",
+    label: "bash_write",
+    description: 'Write input bytes to a running PTY bash task. PTY-only; check bash_status reports mode: "pty" first. ' + 'Input is either a string (verbatim bytes) or an array mixing strings and { key: "esc" | "enter" | "up" | "ctrl-c" | ... } objects ' + 'for atomic text+key sequences such as [ "iHello", { key: "esc" }, ":wq", { key: "enter" } ]. ' + "Named keys cover enter/return/tab/space/backspace/esc/escape, arrows, home/end/page-up/page-down/delete/insert, f1..f12, and ctrl-a..ctrl-z. " + "Maximum 1 MiB per call (post-expansion).",
+    promptSnippet: "Write keystrokes/input to a PTY bash task",
+    parameters: BashWriteParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const data = await callBridge(bridge, "bash_write", { task_id: params.task_id, input: params.input }, extCtx);
+      return textResult(JSON.stringify({ bytes_written: data.bytes_written }, null, 2), data);
+    }
+  };
+}
+function createBashKillTool(ctx) {
+  return {
+    name: "bash_kill",
+    label: "bash_kill",
+    description: "Terminate a running background bash task spawned with bash({ background: true }).",
+    promptSnippet: "Kill a background bash task by task_id",
+    parameters: BashTaskParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const data = await callBridge(bridge, "bash_kill", { task_id: params.task_id }, extCtx);
+      if (data.success === false) {
+        throw new Error(data.message ?? "bash_kill failed");
       }
-    });
-  }
-  if (surface.hoistEdit) {
-    pi.registerTool({
-      name: "edit",
-      label: "edit",
-      description: "Find-and-replace edit with progressive fuzzy matching (handles whitespace and Unicode drift). Uses `filePath`, `oldString`, `newString`. Errors on multiple matches — use `occurrence` to pick one, or `replaceAll: true`. Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
-      promptSnippet: "Targeted find-and-replace (uses filePath/oldString/newString; occurrence or replaceAll for disambiguation; fuzzy whitespace matching). Pass appendContent to append to a file (creates if missing). Diagnostics follow lsp.diagnostics_on_edit unless overridden.",
-      promptGuidelines: [
-        "Prefer edit over write when changing part of an existing file.",
-        "Include enough surrounding context in oldString to make the match unique, or set replaceAll/occurrence explicitly.",
-        "Use appendContent (instead of read+write) when adding text to the end of a file."
-      ],
-      parameters: EditParams,
-      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
-          restrictToProjectRoot: surface.restrictToProjectRoot
-        });
-        const bridge = bridgeFor(ctx, extCtx.cwd);
-        if (typeof params.appendContent === "string") {
-          const req2 = {
-            op: "append",
-            file: params.filePath,
-            append_content: params.appendContent,
-            diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
-            include_diff_content: true
-          };
-          const response2 = await callBridge(bridge, "edit_match", req2, extCtx);
-          return buildMutationResult(params.filePath, response2);
+      await disposePtyTerminal(ptyCacheKey(extCtx, params.task_id));
+      const details = data;
+      if (details.kill_signaled === true) {
+        return bashKillResult(`Task ${params.task_id}: kill_signaled`, details);
+      }
+      return bashKillResult(`Task ${params.task_id}: ${details.status}`, details);
+    }
+  };
+}
+function bashResult(output, details) {
+  return {
+    content: [{ type: "text", text: output }],
+    details: {
+      exit_code: details.exit_code,
+      duration_ms: details.duration_ms,
+      truncated: details.truncated,
+      output_path: details.output_path,
+      task_id: details.task_id,
+      bg_completions: details.bg_completions
+    }
+  };
+}
+function bashStatusResult(output, details) {
+  return {
+    content: [{ type: "text", text: output }],
+    details
+  };
+}
+function bashKillResult(output, details) {
+  return {
+    content: [{ type: "text", text: output }],
+    details
+  };
+}
+async function bashStatusSnapshot(bridge, extCtx, taskId, outputMode, options) {
+  return await callBridge(bridge, "bash_status", { task_id: taskId, output_mode: outputMode }, extCtx, options);
+}
+async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFor, waitForExit, effectiveWaitMs) {
+  const startedAt = Date.now();
+  const deadline = startedAt + effectiveWaitMs;
+  let spillCursor = { output: 0, stderr: 0, combined: 0 };
+  let scanText = "";
+  let scanBaseOffset = 0;
+  const bridgeOptions = {
+    keepBridgeOnTimeout: true,
+    transportTimeoutMs: BASH_TRANSPORT_TIMEOUT_MS
+  };
+  const sessionId = resolveSessionId(extCtx);
+  if (waitForExit)
+    markTaskWaiting(sessionId, taskId);
+  let sawTerminal = false;
+  try {
+    while (true) {
+      const data = await bashStatusSnapshot(bridge, extCtx, taskId, outputMode, bridgeOptions);
+      const terminal = isTerminalStatus(data.status);
+      if (waitFor) {
+        const scan = await readNewTaskOutput(extCtx, taskId, data, spillCursor);
+        if (scan) {
+          spillCursor = scan.nextCursor;
+          if (scanText.length === 0)
+            scanBaseOffset = scan.baseOffset;
+          scanText += scan.text;
+          const match = findWaitMatch(scanText, waitFor);
+          if (match) {
+            if (waitForExit && terminal) {
+              sawTerminal = true;
+              consumeBgCompletion(sessionId, taskId);
+              await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
+            }
+            return withWaited(data, {
+              reason: "matched",
+              elapsed_ms: Date.now() - startedAt,
+              match: match.text,
+              match_offset: scanBaseOffset + Buffer.byteLength(scanText.slice(0, match.index), "utf8")
+            });
+          }
         }
-        const req = {
-          file: params.filePath,
-          match: params.oldString ?? "",
-          replacement: params.newString ?? "",
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
-          include_diff_content: true
-        };
-        if (params.replaceAll === true)
-          req.replace_all = true;
-        const occurrence = coerceOptionalInt(params.occurrence, "occurrence", 0, Number.MAX_SAFE_INTEGER);
-        if (occurrence !== undefined)
-          req.occurrence = occurrence;
-        const response = await callBridge(bridge, "edit_match", req, extCtx);
-        return buildMutationResult(params.filePath, response);
-      },
-      renderCall(args, theme, context) {
-        return renderMutationCall("edit", args?.filePath, theme, context);
-      },
-      renderResult(result, _options, theme, context) {
-        return renderMutationResult(result, theme, context);
       }
-    });
-  }
-  if (surface.hoistGrep) {
-    pi.registerTool({
-      name: "grep",
-      label: "grep",
-      description: "Search for a regex pattern across files. Uses AFT's trigram index inside the project root for fast repeated queries, and falls back to ripgrep for paths outside the project root.",
-      promptSnippet: "Fast regex search across files (trigram-indexed inside the project root)",
-      promptGuidelines: ["Prefer grep over bash-invoked find/rg for in-project searches."],
-      parameters: GrepParams,
-      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        const bridge = bridgeFor(ctx, extCtx.cwd);
-        const req = { pattern: params.pattern };
-        if (params.path) {
-          await assertExternalDirectoryPermission(extCtx, params.path, "search", {
-            restrictToProjectRoot: surface.restrictToProjectRoot
-          });
-          req.path = await resolvePathArg(extCtx.cwd, params.path);
+      if (terminal) {
+        if (waitForExit) {
+          sawTerminal = true;
+          consumeBgCompletion(sessionId, taskId);
+          await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
         }
-        if (params.include)
-          req.include = splitIncludeGlobs(params.include);
-        if (params.caseSensitive !== undefined)
-          req.case_sensitive = params.caseSensitive;
-        const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
-        if (contextLines !== undefined)
-          req.context_lines = contextLines;
-        const response = await callBridge(bridge, "grep", req, extCtx);
-        const text = response.text ?? "";
-        return textResult(text);
+        return withWaited(data, { reason: "exited", elapsed_ms: Date.now() - startedAt });
+      }
+      if (Date.now() >= deadline) {
+        return withWaited(data, { reason: "timeout", elapsed_ms: Date.now() - startedAt });
       }
+      await sleep(Math.min(BASH_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+    }
+  } finally {
+    if (waitForExit && !sawTerminal)
+      unmarkTaskWaiting(sessionId, taskId);
+    if (waitFor) {
+      await disposePtyTerminal(watchPtyCacheKey(extCtx, taskId));
+    }
+  }
+}
+async function readNewTaskOutput(extCtx, taskId, data, cursor) {
+  const outputPath = data.output_path;
+  if (data.mode === "pty") {
+    if (!outputPath)
+      return;
+    const { rows, cols } = ptyDimensions(data);
+    const state = await getOrCreatePtyTerminal(watchPtyCacheKey(extCtx, taskId), outputPath, rows, cols);
+    const baseOffset = state.offset;
+    const bytes = await readPtyBytes(state);
+    if (bytes.length === 0)
+      return;
+    return {
+      text: bytes.toString("utf8"),
+      baseOffset,
+      nextCursor: { output: state.offset, stderr: 0, combined: state.offset }
+    };
+  }
+  const stderrPath = data.stderr_path;
+  if (!outputPath && !stderrPath)
+    return;
+  const stdoutBytes = outputPath ? await readFileBytesFrom(outputPath, cursor.output) : Buffer.alloc(0);
+  const stderrBytes = stderrPath ? await readFileBytesFrom(stderrPath, cursor.stderr) : Buffer.alloc(0);
+  const bytesRead = stdoutBytes.length + stderrBytes.length;
+  if (bytesRead === 0)
+    return;
+  return {
+    text: Buffer.concat([stdoutBytes, stderrBytes]).toString("utf8"),
+    baseOffset: cursor.combined,
+    nextCursor: {
+      output: cursor.output + stdoutBytes.length,
+      stderr: cursor.stderr + stderrBytes.length,
+      combined: cursor.combined + bytesRead
+    }
+  };
+}
+async function readFileBytesFrom(outputPath, cursor) {
+  const handle = await fs3.open(outputPath, "r");
+  try {
+    const chunks = [];
+    let offset = cursor;
+    while (true) {
+      const buffer2 = Buffer.allocUnsafe(64 * 1024);
+      const { bytesRead } = await handle.read(buffer2, 0, buffer2.length, offset);
+      if (bytesRead === 0)
+        break;
+      chunks.push(Buffer.from(buffer2.subarray(0, bytesRead)));
+      offset += bytesRead;
+    }
+    return Buffer.concat(chunks);
+  } finally {
+    await handle.close().catch(() => {
+      return;
     });
   }
 }
-function buildMutationResult(filePath, response) {
-  const diffObj = response.diff;
-  const additions = diffObj?.additions ?? 0;
-  const deletions = diffObj?.deletions ?? 0;
-  const replacements = response.replacements;
-  const diagnostics = response.lsp_diagnostics;
-  const truncated = diffObj?.truncated === true;
-  const noOp = response.no_op === true;
-  const formatted = response.formatted;
-  const formatSkippedReason = response.format_skipped_reason;
-  const globFormatSkipReasons = response.format_skip_reasons;
-  let diffText;
-  let firstChangedLine;
-  if (diffObj && !truncated && typeof diffObj.before === "string" && typeof diffObj.after === "string") {
-    const piDiff = formatDiffForPi(diffObj.before, diffObj.after);
-    diffText = piDiff.diff;
-    firstChangedLine = piDiff.firstChangedLine;
+function parseWaitPattern(value) {
+  if (typeof value === "string")
+    return { kind: "substring", value };
+  if (isRegexWaitObject(value))
+    return { kind: "regex", value: new RegExp(value.regex), source: value.regex };
+  return;
+}
+function isRegexWaitObject(value) {
+  return typeof value === "object" && value !== null && "regex" in value && typeof value.regex === "string";
+}
+function findWaitMatch(text, pattern) {
+  if (pattern.kind === "substring") {
+    const index = text.indexOf(pattern.value);
+    return index >= 0 ? { text: pattern.value, index } : undefined;
   }
-  const summaryHeader = replacements !== undefined ? `Edited ${filePath} (+${additions}/-${deletions}, ${replacements} replacement${replacements === 1 ? "" : "s"})` : `Wrote ${filePath} (+${additions}/-${deletions})`;
-  let text = summaryHeader;
-  if (noOp) {
-    text += `
-
-Note: no net file change — the match was found and applied, but the file content is byte-identical to before. Likely causes: oldString and newString are identical, or a formatter normalized the change away.`;
+  pattern.value.lastIndex = 0;
+  const match = pattern.value.exec(text);
+  return match ? { text: match[0], index: match.index } : undefined;
+}
+function withWaited(data, waited) {
+  return { ...data, waited };
+}
+function formatWaitSummary(waited, details) {
+  if (waited.reason === "matched") {
+    return `Waited ${waited.elapsed_ms}ms; matched ${JSON.stringify(waited.match ?? "")} at offset ${waited.match_offset ?? 0}.`;
   }
-  const skipNote = formatSkipReasonNote(formatSkippedReason);
-  if (skipNote)
-    text += `
-
-${skipNote}`;
-  const globSkipNote = formatGlobSkipReasonsNote(globFormatSkipReasons);
-  if (globSkipNote)
-    text += `
-
-${globSkipNote}`;
-  if (diagnostics && diagnostics.length > 0) {
-    text += `
-
-LSP diagnostics:
-${formatDiagnosticsText(diagnostics)}`;
+  if (waited.reason === "timeout") {
+    return `Waited ${waited.elapsed_ms}ms; timeout reached without match.`;
   }
-  return {
-    content: [{ type: "text", text }],
-    details: {
-      diff: diffText,
-      firstChangedLine,
-      additions,
-      deletions,
-      replacements,
-      diagnostics,
-      truncated: truncated || undefined,
-      formatted,
-      formatSkippedReason,
-      noOp: noOp || undefined
-    }
-  };
+  const exit = typeof details.exit_code === "number" ? `, exit ${details.exit_code}` : "";
+  return `Waited ${waited.elapsed_ms}ms; task exited (${details.status}${exit}).`;
 }
-function formatGlobSkipReasonsNote(reasons) {
-  if (!Array.isArray(reasons))
-    return;
-  const actionable = reasons.filter((reason) => typeof reason === "string").filter((reason) => ["formatter_not_installed", "formatter_excluded_path", "timeout", "error"].includes(reason));
-  if (actionable.length === 0)
-    return;
-  return `Note: formatter skipped some glob edit result file(s): ${[...new Set(actionable)].sort().join(", ")}. See per-file format_skipped_reason values for details.`;
+async function formatBashStatus(extCtx, taskId, details, requestedOutputMode) {
+  const exit = typeof details.exit_code === "number" ? ` (exit ${details.exit_code})` : "";
+  const dur = typeof details.duration_ms === "number" ? ` ${Math.round(details.duration_ms / 1000)}s` : "";
+  let text = `Task ${taskId}: ${details.status}${exit}${dur}`;
+  if (details.waited)
+    text += `
+${formatWaitSummary(details.waited, details)}`;
+  if (details.mode === "pty") {
+    text += await formatPtyStatus(extCtx, taskId, details, requestedOutputMode);
+  } else {
+    if (isTerminalStatus(details.status) && details.output_preview) {
+      text += `
+${details.output_preview.slice(0, 2000)}`;
+    }
+    if (!isTerminalStatus(details.status)) {
+      text += `
+A completion reminder will be delivered automatically; don't poll.`;
+    }
+  }
+  return text;
 }
-function formatSkipReasonNote(reason) {
-  switch (reason) {
-    case "formatter_not_installed":
-      return "Note: formatter binary not installed; file written unformatted.";
-    case "timeout":
-      return "Note: formatter timed out; file written unformatted. Raise formatter_timeout_secs or check the formatter for hangs.";
-    case "formatter_excluded_path":
-      return "Note: formatter is configured to ignore this path (e.g. biome.json files.includes, .prettierignore). File written unformatted.";
-    case "error":
-      return "Note: formatter exited with an unrecognized error; file written unformatted.";
-    default:
-      return;
+async function formatPtyStatus(extCtx, taskId, details, requestedOutputMode) {
+  if (!details.output_path)
+    return `
+[PTY output path unavailable]`;
+  const key = ptyCacheKey(extCtx, taskId);
+  const { rows, cols } = ptyDimensions(details);
+  const state = await getOrCreatePtyTerminal(key, details.output_path, rows, cols);
+  const raw = await readPtyBytes(state);
+  const outputMode = requestedOutputMode ?? "screen";
+  let suffix = "";
+  if (outputMode === "raw") {
+    suffix = raw.length > 0 ? `
+${raw.toString("utf8")}` : "";
+  } else if (outputMode === "both") {
+    suffix = `
+${JSON.stringify({ screen: renderScreen(state, rows, cols), raw: raw.toString("utf8") }, null, 2)}`;
+  } else {
+    const screen = renderScreen(state, rows, cols);
+    suffix = screen ? `
+${screen}` : "";
+  }
+  if (!isTerminalStatus(details.status)) {
+    suffix += `
+PTY task is still running. Use bash_status({ task_id: "${taskId}", output_mode: "screen" }) to inspect, bash_write({ task_id: "${taskId}", input: "..." }) to send keystrokes.`;
+  } else {
+    await disposePtyTerminal(key);
   }
+  return suffix;
 }
-function formatDiagnosticsText(diagnostics) {
-  try {
-    return diagnostics.map((d) => {
-      if (d && typeof d === "object") {
-        const obj = d;
-        const line = obj.line ?? obj.startLine ?? "?";
-        const severity = obj.severity ?? "info";
-        const msg = obj.message ?? JSON.stringify(obj);
-        return `  [${severity}] line ${line}: ${msg}`;
-      }
-      return `  ${String(d)}`;
-    }).join(`
+function ptyDimensions(data) {
+  const rows = typeof data.pty_rows === "number" ? data.pty_rows : 24;
+  const cols = typeof data.pty_cols === "number" ? data.pty_cols : 80;
+  return { rows, cols };
+}
+function ptyCacheKey(extCtx, taskId) {
+  return `${extCtx.cwd}::${resolveSessionId(extCtx) ?? "__default__"}::${taskId}`;
+}
+function watchPtyCacheKey(extCtx, taskId) {
+  return `${ptyCacheKey(extCtx, taskId)}::watch`;
+}
+function isTerminalStatus(status) {
+  return status === "completed" || status === "failed" || status === "killed" || status === "timed_out";
+}
+function renderBashCall(command, description, theme, context) {
+  const text = reuseText3(context.lastComponent);
+  const display = description ?? (command ? shortenCommand(command) : "...");
+  text.setText(`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", display)}`);
+  return text;
+}
+function renderBashResult(result, theme, context) {
+  if (context.isError) {
+    const errorText = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
+`).trim();
+    const text = reuseText3(context.lastComponent);
+    text.setText(`
+${theme.fg("error", errorText || "bash failed")}`);
+    return text;
+  }
+  const details = result.details;
+  const exitCode = details?.exit_code;
+  const bgCompletions = details?.bg_completions ?? [];
+  const container = reuseContainer3(context.lastComponent);
+  container.clear();
+  container.addChild(new Spacer3(1));
+  const rawOutput = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
+`).trim();
+  if (rawOutput) {
+    const lines = rawOutput.split(`
 `);
-  } catch {
-    return JSON.stringify(diagnostics, null, 2);
+    const preview = lines.length > 25 ? `... (${lines.length - 25} lines omitted)
+${lines.slice(-25).join(`
+`)}` : rawOutput;
+    container.addChild(new Text3(preview, 1, 0));
+    container.addChild(new Spacer3(1));
+  }
+  if (exitCode !== undefined) {
+    const exitColor = exitCode === 0 ? "success" : "error";
+    const exitText = theme.fg(exitColor, `exit ${exitCode}`);
+    container.addChild(new Text3(exitText, 1, 0));
+  }
+  if (bgCompletions.length > 0) {
+    container.addChild(new Spacer3(1));
+    for (const bg of bgCompletions) {
+      const cmdPreview = bg.command ? bg.command.slice(0, 60) : "unknown command";
+      const suffix = (bg.command?.length ?? 0) > 60 ? "..." : "";
+      const exitInfo = bg.exit_code !== undefined ? `exit ${bg.exit_code}` : bg.status;
+      const statusColor = bg.status === "completed" && bg.exit_code === 0 ? "success" : "warning";
+      const line = theme.fg(statusColor, `Background task ${bg.task_id} completed (${exitInfo}): ${cmdPreview}${suffix}`);
+      container.addChild(new Text3(line, 1, 0));
+    }
+  }
+  if (details?.duration_ms !== undefined) {
+    container.addChild(new Spacer3(1));
+    const durationText = theme.fg("muted", `${details.duration_ms}ms`);
+    container.addChild(new Text3(durationText, 1, 0));
   }
+  if (details?.truncated) {
+    container.addChild(new Spacer3(1));
+    const truncText = theme.fg("warning", "(output truncated)");
+    container.addChild(new Text3(truncText, 1, 0));
+  }
+  return container;
 }
-function reuseText3(last) {
-  return last instanceof Text3 ? last : new Text3("", 0, 0);
+function shortenCommand(command) {
+  if (command.length <= 60)
+    return command;
+  return `${command.slice(0, 57)}...`;
+}
+
+// src/tools/conflicts.ts
+import { Type as Type5 } from "typebox";
+var ConflictsParams = Type5.Object({
+  path: Type5.Optional(Type5.String({
+    description: "Optional path inside the git repository or worktree to inspect (absolute or relative to project root). Conflicts are discovered from that repository's top level. Defaults to the session project root."
+  }))
+});
+function renderConflictCall(theme, context) {
+  return renderToolCall("conflicts", undefined, theme, context);
+}
+function buildConflictSections(text) {
+  const trimmed = text.trim();
+  if (!trimmed)
+    return ["No merge conflicts found."];
+  const [header, ...rest] = trimmed.split(/\n\n+/);
+  const match = header.match(/^(\d+)\s+files?,\s+(\d+)\s+conflicts?/i);
+  const sections = [
+    match ? `${match[1]} conflicted file${match[1] === "1" ? "" : "s"} · ${match[2]} region${match[2] === "1" ? "" : "s"}` : header
+  ];
+  if (rest.length === 0)
+    return sections;
+  sections.push(...rest.map((section) => section.trim()).filter(Boolean));
+  return sections;
 }
-function reuseContainer3(last) {
-  return last instanceof Container3 ? last : new Container3;
+function renderConflictResult(text, theme, context) {
+  const sections = buildConflictSections(text).map((section, index) => index === 0 ? theme.fg("warning", section) : section);
+  return renderSections(sections, context);
 }
-function renderMutationCall(toolName, filePath, theme, context) {
-  const text = reuseText3(context.lastComponent);
-  const pathDisplay = filePath ? theme.fg("accent", shortenPath2(filePath)) : theme.fg("toolOutput", "...");
-  text.setText(`${theme.fg("toolTitle", theme.bold(toolName))} ${pathDisplay}`);
-  return text;
+function renderConflictToolResult(result, theme, context) {
+  if (context.isError)
+    return renderErrorResult(result, "conflicts failed", theme, context);
+  return renderConflictResult(collectTextContent(result), theme, context);
 }
-function renderMutationResult(result, theme, context) {
-  if (context.isError) {
-    const errorText = result.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join(`
-`).trim();
-    const text = reuseText3(context.lastComponent);
-    text.setText(`
-${theme.fg("error", errorText || "edit failed")}`);
-    return text;
-  }
-  const details = result.details;
-  const diff = typeof details?.diff === "string" ? details.diff : undefined;
-  if (!diff) {
-    const additions = details?.additions ?? 0;
-    const deletions = details?.deletions ?? 0;
-    const text = reuseText3(context.lastComponent);
-    const summary = theme.fg("success", `+${additions}/-${deletions}`);
-    let suffix = "";
-    if (details?.truncated) {
-      suffix = ` ${theme.fg("muted", "(diff truncated)")}`;
-    } else if (details?.noOp) {
-      suffix = ` ${theme.fg("muted", "(no net change)")}`;
+function registerConflictsTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_conflicts",
+    label: "conflicts",
+    description: "Show all git merge conflicts across the repository — returns line-numbered conflict regions with context for every conflicted file in a single call.",
+    parameters: ConflictsParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const reqParams = {};
+      const path2 = params?.path;
+      if (typeof path2 === "string" && path2.trim() !== "")
+        reqParams.path = path2;
+      const response = await callBridge(bridge, "git_conflicts", reqParams, extCtx);
+      return textResult(response.text ?? JSON.stringify(response, null, 2));
+    },
+    renderCall(_args, theme, context) {
+      return renderConflictCall(theme, context);
+    },
+    renderResult(result, _options, theme, context) {
+      return renderConflictToolResult(result, theme, context);
     }
-    text.setText(`
-${summary}${suffix}`);
-    return text;
-  }
-  const container = reuseContainer3(context.lastComponent);
-  container.clear();
-  container.addChild(new Spacer3(1));
-  container.addChild(new Text3(renderDiff2(diff), 1, 0));
-  return container;
-}
-function shortenPath2(path2) {
-  const home = homedir9();
-  if (path2.startsWith(home))
-    return `~${path2.slice(home.length)}`;
-  return path2;
+  });
 }
-async function resolvePathArg(cwd, path2) {
-  const expanded = expandTilde(path2);
-  const abs = isAbsolute2(expanded) ? expanded : resolve3(cwd, expanded);
-  try {
-    await stat(abs);
-    return abs;
-  } catch {
-    return expanded;
+
+// src/tools/fs.ts
+import { Type as Type6 } from "typebox";
+var DeleteParams = Type6.Object({
+  files: Type6.Array(Type6.String(), {
+    description: "Paths to delete (one or more). May include directories when recursive=true.",
+    minItems: 1
+  }),
+  recursive: Type6.Optional(Type6.Boolean({
+    description: "Required to delete a directory and its contents. Defaults to false; passing a directory without this returns an error."
+  }))
+});
+var MoveParams = Type6.Object({
+  filePath: Type6.String({
+    description: "Source file path to move (absolute or relative to project root)"
+  }),
+  destination: Type6.String({
+    description: "Destination file path (absolute or relative to project root)"
+  })
+});
+function renderFsCall(toolName, args, theme, context) {
+  if (toolName === "aft_delete") {
+    const files = args.files;
+    const summary = files.length === 1 ? accentPath(theme, files[0]) : `${theme.fg("accent", String(files.length))} ${theme.fg("muted", "files")}`;
+    return renderToolCall("delete", summary, theme, context);
   }
+  const moveArgs = args;
+  return renderToolCall("move", `${accentPath(theme, moveArgs.filePath)} ${theme.fg("muted", "→")} ${accentPath(theme, moveArgs.destination)}`, theme, context);
 }
-function splitIncludeGlobs(include) {
-  const out = [];
-  let depth = 0;
-  let buf = "";
-  for (const ch of include) {
-    if (ch === "{") {
-      depth++;
-      buf += ch;
-      continue;
+function renderFsResult(toolName, args, result, theme, context) {
+  if (context.isError) {
+    return renderErrorResult(result, `${toolName} failed`, theme, context);
+  }
+  if (toolName === "aft_delete") {
+    const files = args.files;
+    const data = result?.details ?? {};
+    const deletedPaths = data.deleted ?? files;
+    const skipped = data.skipped_files ?? [];
+    const lines = [];
+    for (const entry of deletedPaths) {
+      lines.push(`${theme.fg("success", "✓ deleted")} ${theme.fg("accent", shortenPath2(entry))}`);
     }
-    if (ch === "}") {
-      if (depth > 0)
-        depth--;
-      buf += ch;
-      continue;
+    for (const entry of skipped) {
+      lines.push(`${theme.fg("error", "✗ skipped")} ${theme.fg("accent", shortenPath2(entry.file))} ${theme.fg("muted", `(${entry.reason})`)}`);
     }
-    if (ch === "," && depth === 0) {
-      const trimmed = buf.trim();
-      if (trimmed.length > 0)
-        out.push(trimmed);
-      buf = "";
-      continue;
+    if (lines.length === 0) {
+      lines.push(theme.fg("muted", "(no files deleted)"));
     }
-    buf += ch;
+    return renderSections([lines.join(`
+`)], context);
   }
-  const tail2 = buf.trim();
-  if (tail2.length > 0)
-    out.push(tail2);
-  return out;
+  const moveArgs = args;
+  return renderSections([
+    `${theme.fg("success", "✓ moved")} ${theme.fg("accent", shortenPath2(moveArgs.filePath))}`,
+    `${theme.fg("muted", "to")} ${theme.fg("accent", shortenPath2(moveArgs.destination))}`
+  ], context);
 }
-function formatReadFooter(agentSpecifiedRange, data) {
-  if (agentSpecifiedRange)
-    return "";
-  if (!data.truncated)
-    return "";
-  const startLine = data.start_line;
-  const endLine = data.end_line;
-  const totalLines = data.total_lines;
-  if (startLine === undefined || endLine === undefined || totalLines === undefined) {
-    return "";
+function registerFsTools(pi, ctx, surface) {
+  if (surface.delete) {
+    pi.registerTool({
+      name: "aft_delete",
+      label: "delete",
+      description: "Delete one or more files (or directories) with backup. Each file is backed up before deletion — use `aft_safety undo` to recover any of them. " + "For directories, every file inside is individually backed up before removal. Directory deletion requires recursive: true. " + "Returns { success, complete, deleted, skipped_files }: partial success is allowed; files that fail are reported in skipped_files.",
+      parameters: DeleteParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const files = await Promise.all(params.files.map((file2) => resolvePathArg(extCtx.cwd, file2)));
+        const checked = new Set;
+        for (const file2 of files) {
+          if (checked.has(file2))
+            continue;
+          checked.add(file2);
+          await assertExternalDirectoryPermission(extCtx, file2, "modify", {
+            restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+          });
+        }
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "delete_file", {
+          files,
+          recursive: params.recursive === true
+        }, extCtx);
+        const deletedEntries = response.deleted ?? [];
+        const skipped = response.skipped_files ?? [];
+        const deleted = deletedEntries.map((entry) => entry.file);
+        if (deleted.length === 0 && skipped.length > 0) {
+          throw new Error(`delete failed for all ${skipped.length} file(s):
+` + skipped.map((entry) => `  ${entry.file}: ${entry.reason}`).join(`
+`));
+        }
+        const summary = deleted.length === 1 && skipped.length === 0 ? `Deleted ${deleted[0]}` : `Deleted ${deleted.length}/${params.files.length} file(s)`;
+        return textResult(summary, {
+          success: true,
+          complete: skipped.length === 0,
+          deleted,
+          skipped_files: skipped
+        });
+      },
+      renderCall(args, theme, context) {
+        return renderFsCall("aft_delete", args, theme, context);
+      },
+      renderResult(result, _options, theme, context) {
+        return renderFsResult("aft_delete", context.args, result, theme, context);
+      }
+    });
+  }
+  if (surface.move) {
+    pi.registerTool({
+      name: "aft_move",
+      label: "move",
+      description: "Move or rename a file with backup. Creates parent directories for the destination automatically. This operates on files at the OS level — to relocate a code symbol between files, use `aft_refactor` with op='move' instead.",
+      parameters: MoveParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+        const destination = await resolvePathArg(extCtx.cwd, params.destination);
+        const checked = new Set([filePath, destination]);
+        for (const file2 of checked) {
+          await assertExternalDirectoryPermission(extCtx, file2, "modify", {
+            restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+          });
+        }
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "move_file", {
+          file: filePath,
+          destination
+        }, extCtx);
+        return textResult(`Moved ${params.filePath} → ${params.destination}`, response);
+      },
+      renderCall(args, theme, context) {
+        return renderFsCall("aft_move", args, theme, context);
+      },
+      renderResult(result, _options, theme, context) {
+        return renderFsResult("aft_move", context.args, result, theme, context);
+      }
+    });
   }
-  return `
-(Showing lines ${startLine}-${endLine} of ${totalLines}. Use offset/limit to read other sections.)`;
 }
 
 // src/tools/imports.ts
@@ -33128,8 +33252,20 @@ var ImportParams = Type7.Object({
   op: StringEnum2(["add", "remove", "organize"], { description: "Import operation" }),
   filePath: Type7.String({ description: "Path to the file (absolute or relative to project root)" }),
   module: Type7.Optional(Type7.String({ description: "Module path (required for add/remove), e.g. 'react', './utils'" })),
-  names: Type7.Optional(Type7.Array(Type7.String(), { description: "Named imports to add, e.g. ['useState']" })),
-  defaultImport: Type7.Optional(Type7.String({ description: "Default import name (e.g. 'React')" })),
+  names: Type7.Optional(Type7.Array(Type7.String(), {
+    description: "Named imports to add, using native named-import text with per-name `as` aliasing where supported, e.g. ['useState'], Solidity ['ERC20', 'IERC20 as IToken']"
+  })),
+  defaultImport: Type7.Optional(Type7.String({ description: "Default import name, ES only (e.g. 'React')" })),
+  namespace: Type7.Optional(Type7.String({
+    description: "Namespace binding: `import * as ns from 'mod'` (ES), `* as N from \"./X.sol\"` (Solidity)"
+  })),
+  alias: Type7.Optional(Type7.String({ description: 'Whole-module alias. Solidity: `import "./X.sol" as X`' })),
+  modifiers: Type7.Optional(Type7.Array(Type7.String(), {
+    description: "Statement-level modifiers, language-validated: Java/C# 'static', C# 'global'/'unsafe', Java/Kotlin/Scala 'wildcard', Swift '@testable'"
+  })),
+  importKind: Type7.Optional(Type7.String({
+    description: "Symbol-kind import: PHP 'function'/'const', Swift 'struct'/'class'/'enum', Scala 'given'"
+  })),
   removeName: Type7.Optional(Type7.String({ description: "Named import to remove; omit to remove entire import" })),
   typeOnly: Type7.Optional(Type7.Boolean({ description: "Type-only import (TS only)" })),
   validate: Type7.Optional(StringEnum2(["syntax", "full"], {
@@ -33150,16 +33286,19 @@ function buildImportSections(args, payload, theme) {
     ];
   }
   if (args.op === "add") {
-    const moduleName = asString(response.module) ?? args.module ?? "(module)";
+    const moduleName2 = asString(response.module) ?? args.module ?? "(module)";
     const status = response.already_present === true ? theme.fg("warning", "already present") : theme.fg("success", "added");
     return [
-      `${status} ${theme.fg("accent", moduleName)}`,
+      `${status} ${theme.fg("accent", moduleName2)}`,
       `${theme.fg("muted", "file")} ${theme.fg("accent", asString(response.file) ?? args.filePath)}`,
       `${theme.fg("muted", "group")} ${asString(response.group) ?? "—"}`
     ];
   }
+  const moduleName = asString(response.module) ?? args.module ?? "(module)";
+  const didRemove = response.removed !== false;
+  const removeStatus = didRemove ? `${theme.fg("success", "removed")} ${theme.fg("accent", moduleName)}` : `${theme.fg("warning", "not present")} ${theme.fg("accent", moduleName)}`;
   return [
-    `${theme.fg("success", "removed")} ${theme.fg("accent", asString(response.module) ?? args.module ?? "(module)")}`,
+    removeStatus,
     `${theme.fg("muted", "file")} ${theme.fg("accent", asString(response.file) ?? args.filePath)}`,
     args.removeName ? `${theme.fg("muted", "name")} ${args.removeName}` : `${theme.fg("muted", "scope")} entire import`
   ];
@@ -33182,25 +33321,37 @@ function registerImportTools(pi, ctx) {
   pi.registerTool({
     name: "aft_import",
     label: "import",
-    description: "Language-aware import management. Supports TS, JS, TSX, Python, Rust, Go. Ops: `add`, `remove`, `organize`. Use aft_safety checkpoint/undo before broad cleanup.",
+    description: "Language-aware import management. Supports TS, JS, TSX, Python, Rust, Go, Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, C, C++, Perl, Vue. Ops: `add`, `remove`, `organize`. Use aft_safety checkpoint/undo before broad cleanup.",
     parameters: ImportParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      if ((params.op === "add" || params.op === "remove") && !params.module) {
+      if ((params.op === "add" || params.op === "remove") && isEmptyParam(params.module)) {
         throw new Error(`op='${params.op}' requires 'module'`);
       }
+      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+      await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
+        restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+      });
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const commandMap = {
         add: "add_import",
         remove: "remove_import",
         organize: "organize_imports"
       };
-      const req = { file: params.filePath };
+      const req = { file: filePath };
       if (params.module !== undefined)
         req.module = params.module;
       if (params.names !== undefined)
         req.names = params.names;
       if (params.defaultImport !== undefined)
         req.default_import = params.defaultImport;
+      if (params.namespace !== undefined)
+        req.namespace = params.namespace;
+      if (params.alias !== undefined)
+        req.alias = params.alias;
+      if (params.modifiers !== undefined)
+        req.modifiers = params.modifiers;
+      if (params.importKind !== undefined)
+        req.import_kind = params.importKind;
       if (params.removeName !== undefined)
         req.name = params.removeName;
       if (params.typeOnly !== undefined)
@@ -33243,6 +33394,22 @@ var lastTier2TriggerAtByBridge = new WeakMap;
 function normalizeStringOrArray(value) {
   return isEmptyParam(value) ? undefined : value;
 }
+async function resolveAndGateScope(extCtx, ctx, scope) {
+  if (scope === undefined)
+    return;
+  const values = Array.isArray(scope) ? scope : [scope];
+  const resolved = await Promise.all(values.filter((value) => typeof value === "string" && value.length > 0).map((value) => resolvePathArg(extCtx.cwd, value)));
+  const checked = new Set;
+  for (const target of resolved) {
+    if (checked.has(target))
+      continue;
+    checked.add(target);
+    await assertExternalDirectoryPermission(extCtx, target, "read", {
+      restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+    });
+  }
+  return Array.isArray(scope) ? resolved : resolved[0];
+}
 function validateOptionalTopK(value) {
   if (value === undefined || value === null || value === "")
     return;
@@ -33426,7 +33593,7 @@ function registerInspectTool(pi, ctx) {
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const sections = normalizeStringOrArray(params.sections);
-      const scope = normalizeStringOrArray(params.scope);
+      const scope = await resolveAndGateScope(extCtx, ctx, normalizeStringOrArray(params.scope));
       const topK = validateOptionalTopK(params.topK);
       const response = await callBridge(bridge, "inspect", { sections, scope, topK }, extCtx);
       runPendingTier2Categories(bridge, tier2RefreshCategories(response), extCtx);
@@ -33468,7 +33635,7 @@ function treeLine(depth, text) {
 }
 function renderCallTreeNode(node, depth, lines) {
   const name = asString(node.name) ?? "(unknown)";
-  const file2 = shortenPath(asString(node.file) ?? "(unknown file)");
+  const file2 = shortenPath2(asString(node.file) ?? "(unknown file)");
   const line = asNumber(node.line);
   lines.push(treeLine(depth, `${name} ${line !== undefined ? `[${file2}:${line}]` : `[${file2}]`}`));
   asRecords(node.children).forEach((child) => {
@@ -33487,7 +33654,7 @@ function renderTracePath(path2, index, lines) {
   lines.push(`Path ${index + 1}`);
   asRecords(path2.hops).forEach((hop, hopIndex) => {
     const symbol2 = asString(hop.symbol) ?? "(unknown)";
-    const file2 = shortenPath(asString(hop.file) ?? "(unknown file)");
+    const file2 = shortenPath2(asString(hop.file) ?? "(unknown file)");
     const line = asNumber(hop.line);
     const entry = hop.is_entry_point === true ? " [entry]" : "";
     lines.push(treeLine(hopIndex + 1, `${symbol2}${entry} ${line !== undefined ? `[${file2}:${line}]` : `[${file2}]`}`));
@@ -33512,7 +33679,7 @@ function buildNavigateSections(args, payload, theme) {
       `${theme.fg("success", `${asNumber(response.total_callers) ?? 0} caller${(asNumber(response.total_callers) ?? 0) === 1 ? "" : "s"}`)} ${theme.fg("muted", `${groups.length} file group${groups.length === 1 ? "" : "s"}`)} ${warning}`.trim()
     ];
     groups.forEach((group) => {
-      const file2 = shortenPath(asString(group.file) ?? "(unknown file)");
+      const file2 = shortenPath2(asString(group.file) ?? "(unknown file)");
       const lines = [theme.fg("accent", file2)];
       asRecords(group.callers).forEach((caller) => {
         lines.push(`  ↳ ${asString(caller.symbol) ?? "(unknown)"} ${theme.fg("muted", `line ${asNumber(caller.line) ?? "?"}`)}`);
@@ -33533,7 +33700,7 @@ function buildNavigateSections(args, payload, theme) {
     const lines = [theme.fg("success", `${path2.length} hop${path2.length === 1 ? "" : "s"}`)];
     path2.forEach((hop, index) => {
       const symbol2 = asString(hop.symbol) ?? "(unknown)";
-      const file2 = shortenPath(asString(hop.file) ?? "(unknown file)");
+      const file2 = shortenPath2(asString(hop.file) ?? "(unknown file)");
       const line = asNumber(hop.line);
       lines.push(treeLine(index + 1, `${symbol2} ${line !== undefined ? `[${file2}:${line}]` : `[${file2}]`}`));
     });
@@ -33564,7 +33731,7 @@ function buildNavigateSections(args, payload, theme) {
     if (callers.length === 0)
       sections2.push(theme.fg("muted", "No impacted callers found."));
     callers.forEach((caller) => {
-      const file2 = shortenPath(asString(caller.caller_file) ?? "(unknown file)");
+      const file2 = shortenPath2(asString(caller.caller_file) ?? "(unknown file)");
       const symbol2 = asString(caller.caller_symbol) ?? "(unknown)";
       const line = asNumber(caller.line) ?? 0;
       const entry = caller.is_entry_point === true ? ` ${theme.fg("warning", "[entry]")}` : "";
@@ -33587,7 +33754,7 @@ function buildNavigateSections(args, payload, theme) {
   if (hops.length === 0)
     sections.push(theme.fg("muted", "No data-flow hops found."));
   hops.forEach((hop, index) => {
-    const file2 = shortenPath(asString(hop.file) ?? "(unknown file)");
+    const file2 = shortenPath2(asString(hop.file) ?? "(unknown file)");
     const symbol2 = asString(hop.symbol) ?? "(unknown)";
     const variable = asString(hop.variable) ?? "(unknown)";
     const line = asNumber(hop.line) ?? 0;
@@ -33617,27 +33784,44 @@ function registerNavigateTool(pi, ctx) {
     description: "Answer code-relationship questions from a real call graph — instead of grep + read chains. Reach for this whenever the question is about how symbols connect. All ops require both `filePath` and `symbol`. Use `callers` for call sites (before renaming/signature changes), `impact` for blast radius (what breaks if a symbol changes), `call_tree` for what a function calls, `trace_to` for how execution reaches a symbol from entry points, `trace_to_symbol` for the shortest path from one symbol to another (requires `toSymbol`; if ambiguous, the error returns candidate files — retry with `toFile`), `trace_data` to follow a value across assignments/params.",
     parameters: navigateParamsSchema(),
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      if (params.op === "trace_data" && !params.expression) {
+      if (isEmptyParam(params.filePath)) {
+        throw new Error(`op='${params.op}' requires a \`filePath\``);
+      }
+      if (isEmptyParam(params.symbol)) {
+        throw new Error(`op='${params.op}' requires a \`symbol\``);
+      }
+      if (params.op === "trace_data" && isEmptyParam(params.expression)) {
         throw new Error("op='trace_data' requires an `expression`");
       }
-      if (params.op === "trace_to_symbol" && !params.toSymbol) {
+      if (params.op === "trace_to_symbol" && isEmptyParam(params.toSymbol)) {
         throw new Error("op='trace_to_symbol' requires a `toSymbol`");
       }
+      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+      const toFile = !isEmptyParam(params.toFile) ? await resolvePathArg(extCtx.cwd, params.toFile) : undefined;
+      const checked = new Set;
+      for (const target of [filePath, ...toFile !== undefined ? [toFile] : []]) {
+        if (checked.has(target))
+          continue;
+        checked.add(target);
+        await assertExternalDirectoryPermission(extCtx, target, "read", {
+          restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+        });
+      }
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const req = {
         op: params.op,
-        file: params.filePath,
+        file: filePath,
         symbol: params.symbol
       };
       const depth = coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER);
       if (depth !== undefined)
         req.depth = depth;
-      if (params.expression !== undefined)
+      if (!isEmptyParam(params.expression))
         req.expression = params.expression;
-      if (params.toSymbol !== undefined)
+      if (!isEmptyParam(params.toSymbol))
         req.toSymbol = params.toSymbol;
-      if (params.toFile !== undefined)
-        req.toFile = params.toFile;
+      if (toFile !== undefined)
+        req.toFile = toFile;
       const response = await callBridge(bridge, params.op, req, extCtx);
       return textResult(JSON.stringify(response, null, 2));
     },
@@ -33652,7 +33836,6 @@ function registerNavigateTool(pi, ctx) {
 
 // src/tools/reading.ts
 import { stat as stat2 } from "node:fs/promises";
-import { resolve as resolve4 } from "node:path";
 import { Type as Type10 } from "typebox";
 var OutlineParams = Type10.Object({
   target: Type10.Union([Type10.String(), Type10.Array(Type10.String())], {
@@ -33677,11 +33860,26 @@ var ZoomParams = Type10.Object({
   targets: Type10.Optional(Type10.Union([ZoomTarget, Type10.Array(ZoomTarget)], {
     description: "Cross-file batch: `{ filePath, symbol }` or an array of them. Mutually exclusive with filePath/url/symbols."
   })),
-  contextLines: Type10.Optional(Type10.Number({ description: "Lines of context before/after (default: 3)" }))
+  contextLines: Type10.Optional(Type10.Number({ description: "Lines of context before/after (default: 3)" })),
+  callgraph: Type10.Optional(Type10.Boolean({
+    description: "Include call-graph annotations (calls-out / called-by within the same file). Default false; off keeps zoom output minimal."
+  }))
 });
 function isUrl(s) {
   return s.startsWith("http://") || s.startsWith("https://");
 }
+async function assertReadPathPermissions(extCtx, ctx, paths) {
+  const targets = Array.isArray(paths) ? paths : [paths];
+  const checked = new Set;
+  for (const target of targets) {
+    if (!target || checked.has(target))
+      continue;
+    checked.add(target);
+    await assertExternalDirectoryPermission(extCtx, target, "read", {
+      restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+    });
+  }
+}
 function zoomTargetLabel(args) {
   return args.filePath ?? args.url ?? "(no target)";
 }
@@ -33698,22 +33896,24 @@ function buildOutlineSections(text, theme) {
 }
 function buildZoomSections(args, payload, theme) {
   const batch = asRecord2(payload);
-  if (Array.isArray(batch?.symbols)) {
-    const header = batch.complete === false ? [theme.fg("warning", "Incomplete zoom results")] : [];
-    const items2 = batch.symbols;
+  const batchItems = Array.isArray(batch?.symbols) ? batch.symbols : Array.isArray(batch?.entries) ? batch.entries : null;
+  if (batchItems) {
+    const header = batch?.complete === false ? [theme.fg("warning", "Incomplete zoom results")] : [];
     return [
       ...header,
-      ...items2.map((item) => {
+      ...batchItems.map((item) => {
         const record2 = asRecord2(item);
         if (!record2)
           return theme.fg("muted", "No zoom result available.");
         const name = asString(record2.name) ?? "(unknown symbol)";
+        const itemTargetLabel = asString(record2.targetLabel) ?? zoomTargetLabel(args);
         if (record2.success === false) {
-          return theme.fg("error", `Symbol "${name}" not found: ${asString(record2.error) ?? "zoom failed"}`);
+          const location = record2.targetLabel ? ` in ${shortenPath2(itemTargetLabel)}` : "";
+          return theme.fg("error", `Symbol "${name}" not found${location}: ${asString(record2.error) ?? "zoom failed"}`);
         }
         const content = asString(record2.content);
         return [
-          `${theme.fg("accent", name)} ${theme.fg("muted", shortenPath(zoomTargetLabel(args)))}`,
+          `${theme.fg("accent", name)} ${theme.fg("muted", shortenPath2(itemTargetLabel))}`,
           content
         ].filter(Boolean).join(`
 `);
@@ -33733,7 +33933,7 @@ function buildZoomSections(args, payload, theme) {
     const startLine = range && typeof range.start_line === "number" ? range.start_line : undefined;
     const endLine = range && typeof range.end_line === "number" ? range.end_line : undefined;
     const targetLabel = zoomTargetLabel(args);
-    const location = startLine !== undefined ? `${shortenPath(targetLabel)}:${startLine}${endLine && endLine !== startLine ? `-${endLine}` : ""}` : shortenPath(targetLabel);
+    const location = startLine !== undefined ? `${shortenPath2(targetLabel)}:${startLine}${endLine && endLine !== startLine ? `-${endLine}` : ""}` : shortenPath2(targetLabel);
     const lines = [`${theme.fg("accent", name)} ${theme.fg("muted", `[${kind}] ${location}`)}`];
     const content = asString(record2.content);
     if (content) {
@@ -33810,7 +34010,9 @@ Pass a single \`target\`:
             if (target.length === 0) {
               throw new Error("'target' must be a non-empty string or array of strings");
             }
-            const response3 = await callBridge(bridge, "outline", { target, files: true }, extCtx);
+            const resolvedTargets = await Promise.all(target.map((entry) => resolvePathArg(extCtx.cwd, entry)));
+            await assertReadPathPermissions(extCtx, ctx, resolvedTargets);
+            const response3 = await callBridge(bridge, "outline", { target: resolvedTargets, files: true }, extCtx);
             if (response3.success === false) {
               throw new Error(response3.message || "outline failed");
             }
@@ -33819,13 +34021,14 @@ Pass a single \`target\`:
           if (typeof target !== "string" || target.length === 0) {
             throw new Error("'target' must be a non-empty string or array of strings");
           }
+          const resolvedTarget2 = await resolvePathArg(extCtx.cwd, target);
           let isDirectory2 = false;
           try {
-            const resolved = resolve4(extCtx.cwd, target);
-            const st = await stat2(resolved);
+            const st = await stat2(resolvedTarget2);
             isDirectory2 = st.isDirectory();
           } catch {}
-          const request = isDirectory2 ? { directory: resolve4(extCtx.cwd, target), files: true } : { file: target, files: true };
+          await assertReadPathPermissions(extCtx, ctx, resolvedTarget2);
+          const request = isDirectory2 ? { directory: resolvedTarget2, files: true } : { file: resolvedTarget2, files: true };
           const response2 = await callBridge(bridge, "outline", request, extCtx);
           if (response2.success === false) {
             throw new Error(response2.message || "outline failed");
@@ -33840,24 +34043,26 @@ Pass a single \`target\`:
           return textResult(formatOutlineText(response2));
         }
         if (isArray) {
-          const response2 = await callBridge(bridge, "outline", { files: target }, extCtx);
+          const resolvedTargets = await Promise.all(target.map((entry) => resolvePathArg(extCtx.cwd, entry)));
+          await assertReadPathPermissions(extCtx, ctx, resolvedTargets);
+          const response2 = await callBridge(bridge, "outline", { files: resolvedTargets }, extCtx);
           return textResult(formatOutlineText(response2));
         }
         if (typeof target !== "string" || target.length === 0) {
           throw new Error("'target' must be a non-empty string or array of strings");
         }
+        const resolvedTarget = await resolvePathArg(extCtx.cwd, target);
         let isDirectory = false;
         try {
-          const resolved = resolve4(extCtx.cwd, target);
-          const st = await stat2(resolved);
+          const st = await stat2(resolvedTarget);
           isDirectory = st.isDirectory();
         } catch {}
+        await assertReadPathPermissions(extCtx, ctx, resolvedTarget);
         if (isDirectory) {
-          const dirPath = resolve4(extCtx.cwd, target);
-          const response2 = await callBridge(bridge, "outline", { directory: dirPath }, extCtx);
+          const response2 = await callBridge(bridge, "outline", { directory: resolvedTarget }, extCtx);
           return textResult(JSON.stringify(response2, null, 2), response2);
         }
-        const response = await callBridge(bridge, "outline", { file: target }, extCtx);
+        const response = await callBridge(bridge, "outline", { file: resolvedTarget }, extCtx);
         return textResult(formatOutlineText(response));
       },
       renderCall(args, theme, context) {
@@ -33872,7 +34077,7 @@ Pass a single \`target\`:
     pi.registerTool({
       name: "aft_zoom",
       label: "zoom",
-      description: "Inspect code symbols or documentation sections. For code, returns the full source of a symbol with call-graph annotations (calls/called-by). For Markdown and HTML, returns the section content under the given heading.\n\nUse exactly ONE mode: `{ filePath, symbols }`, `{ url, symbols }`, or `{ targets }`. `symbols` can be a string or array (one or many lookups in the same file/URL). Use `targets` for cross-file batches: `{ filePath, symbol }` or an array of them.",
+      description: "Inspect code symbols or documentation sections. For code, returns the full source of a symbol. Pass `callgraph: true` to also include call-graph annotations (calls-out / called-by within the same file). For Markdown and HTML, returns the section content under the given heading.\n\nUse exactly ONE mode: `{ filePath, symbols }`, `{ url, symbols }`, or `{ targets }`. `symbols` can be a string or array (one or many lookups in the same file/URL). Use `targets` for cross-file batches: `{ filePath, symbol }` or an array of them.",
       parameters: ZoomParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
@@ -33896,6 +34101,7 @@ Pass a single \`target\`:
         const hasUrl = !isEmptyParam(params.url);
         const hasTargets = hasTargetsProvided(params.targets);
         const hasSymbols = !isEmptyParam(params.symbols);
+        const wantCallgraph = params.callgraph === true;
         if (hasTargets) {
           if (hasFilePath || hasUrl || hasSymbols) {
             throw new Error("'targets' is mutually exclusive with 'filePath', 'url', and 'symbols'");
@@ -33912,10 +34118,17 @@ Pass a single \`target\`:
               throw new Error(`targets[${i}].symbol must be a non-empty string`);
             }
           }
-          const responses = await Promise.all(targets.map((t) => {
-            const req2 = { file: t.filePath, symbol: t.symbol };
+          const resolvedTargets = await Promise.all(targets.map((t) => resolvePathArg(extCtx.cwd, t.filePath)));
+          await assertReadPathPermissions(extCtx, ctx, resolvedTargets);
+          const responses = await Promise.all(targets.map((t, index) => {
+            const req2 = {
+              file: resolvedTargets[index],
+              symbol: t.symbol
+            };
             if (params.contextLines !== undefined)
               req2.context_lines = params.contextLines;
+            if (wantCallgraph)
+              req2.callgraph = true;
             return callBridge(bridge, "zoom", req2, extCtx).catch((err) => ({
               success: false,
               message: err instanceof Error ? err.message : String(err)
@@ -33935,7 +34148,9 @@ Pass a single \`target\`:
         if (hasFilePath && hasUrl) {
           throw new Error("Provide exactly ONE of 'filePath' or 'url' — not both");
         }
-        const file2 = hasUrl ? params.url : params.filePath;
+        const file2 = hasUrl ? params.url : await resolvePathArg(extCtx.cwd, params.filePath);
+        if (!hasUrl)
+          await assertReadPathPermissions(extCtx, ctx, file2);
         const targetLabel = (hasUrl ? params.url : params.filePath) ?? file2;
         const symbolsArray = hasSymbols ? typeof params.symbols === "string" ? [params.symbols] : params.symbols : undefined;
         if (symbolsArray) {
@@ -33943,6 +34158,8 @@ Pass a single \`target\`:
             const req2 = { file: file2, symbol: sym };
             if (params.contextLines !== undefined)
               req2.context_lines = params.contextLines;
+            if (wantCallgraph)
+              req2.callgraph = true;
             return callBridge(bridge, "zoom", req2, extCtx).catch((err) => ({
               success: false,
               message: err instanceof Error ? err.message : String(err)
@@ -33961,6 +34178,8 @@ Pass a single \`target\`:
         const req = { file: file2 };
         if (params.contextLines !== undefined)
           req.context_lines = params.contextLines;
+        if (wantCallgraph)
+          req.callgraph = true;
         const response = await callBridge(bridge, "zoom", req, extCtx);
         if (response.success === false) {
           throw new Error(response.message || "zoom failed");
@@ -34073,21 +34292,21 @@ function buildRefactorSections(args, payload, theme) {
       `${theme.fg("success", "moved symbol")} ${theme.fg("toolOutput", args.symbol ?? "(symbol)")}`,
       `${theme.fg("muted", "files modified")} ${asNumber(response.files_modified) ?? results.length}`,
       `${theme.fg("muted", "consumers updated")} ${asNumber(response.consumers_updated) ?? 0}`,
-      results.length > 0 ? results.map((entry) => `  ↳ ${shortenPath(asString(entry.file) ?? "(unknown file)")}`).join(`
+      results.length > 0 ? results.map((entry) => `  ↳ ${shortenPath2(asString(entry.file) ?? "(unknown file)")}`).join(`
 `) : theme.fg("muted", "No files reported.")
     ];
   }
   if (args.op === "extract") {
     return [
       `${theme.fg("success", "extracted")} ${theme.fg("toolOutput", asString(response.name) ?? args.name ?? "(function)")}`,
-      `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath(asString(response.file) ?? args.filePath))}`,
+      `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath2(asString(response.file) ?? args.filePath))}`,
       `${theme.fg("muted", "params")} ${Array.isArray(response.parameters) ? response.parameters.join(", ") || "none" : "none"}`,
       `${theme.fg("muted", "return type")} ${asString(response.return_type) ?? "unknown"}`
     ];
   }
   return [
     `${theme.fg("success", "inlined")} ${theme.fg("toolOutput", asString(response.symbol) ?? args.symbol ?? "(symbol)")}`,
-    `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath(asString(response.file) ?? args.filePath))}`,
+    `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath2(asString(response.file) ?? args.filePath))}`,
     `${theme.fg("muted", "context")} ${asString(response.call_context) ?? "unknown"}`,
     `${theme.fg("muted", "substitutions")} ${asNumber(response.substitutions) ?? 0}`
   ];
@@ -34112,7 +34331,6 @@ function registerRefactorTool(pi, ctx) {
     description: "Workspace-wide refactoring that updates imports and references across files. `move` relocates a top-level symbol; `extract` pulls a line range into a new function; `inline` replaces a call site. Use aft_safety checkpoint/undo before risky refactors.",
     parameters: RefactorParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const bridge = bridgeFor(ctx, extCtx.cwd);
       const commandMap = {
         move: "move_symbol",
         extract: "extract_function",
@@ -34127,18 +34345,40 @@ function registerRefactorTool(pi, ctx) {
       if (params.op === "extract" && isEmptyParam(params.name)) {
         throw new Error("'name' is required for 'extract' op");
       }
-      const req = { file: params.filePath };
+      const startLine = coerceOptionalInt(params.startLine, "startLine", 1, Number.MAX_SAFE_INTEGER);
+      const endLine = coerceOptionalInt(params.endLine, "endLine", 1, Number.MAX_SAFE_INTEGER);
+      const callSiteLine = coerceOptionalInt(params.callSiteLine, "callSiteLine", 1, Number.MAX_SAFE_INTEGER);
+      if (params.op === "extract") {
+        if (startLine === undefined)
+          throw new Error("'startLine' is required for 'extract' op");
+        if (endLine === undefined)
+          throw new Error("'endLine' is required for 'extract' op");
+      }
+      if (params.op === "inline" && callSiteLine === undefined) {
+        throw new Error("'callSiteLine' is required for 'inline' op");
+      }
+      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+      const destination = !isEmptyParam(params.destination) ? await resolvePathArg(extCtx.cwd, params.destination) : undefined;
+      const permissionTargets = params.op === "move" && destination !== undefined ? [filePath, destination] : [filePath];
+      const checked = new Set;
+      for (const target of permissionTargets) {
+        if (checked.has(target))
+          continue;
+        checked.add(target);
+        await assertExternalDirectoryPermission(extCtx, target, "modify", {
+          restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+        });
+      }
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const req = { file: filePath };
       if (!isEmptyParam(params.symbol))
         req.symbol = params.symbol;
-      if (!isEmptyParam(params.destination))
-        req.destination = params.destination;
+      if (destination !== undefined)
+        req.destination = destination;
       if (!isEmptyParam(params.scope))
         req.scope = params.scope;
       if (!isEmptyParam(params.name))
         req.name = params.name;
-      const startLine = coerceOptionalInt(params.startLine, "startLine", 1, Number.MAX_SAFE_INTEGER);
-      const endLine = coerceOptionalInt(params.endLine, "endLine", 1, Number.MAX_SAFE_INTEGER);
-      const callSiteLine = coerceOptionalInt(params.callSiteLine, "callSiteLine", 1, Number.MAX_SAFE_INTEGER);
       if (startLine !== undefined)
         req.start_line = startLine;
       if (endLine !== undefined) {
@@ -34161,6 +34401,9 @@ function registerRefactorTool(pi, ctx) {
 // src/tools/safety.ts
 import { StringEnum as StringEnum5 } from "@earendil-works/pi-ai";
 import { Type as Type12 } from "typebox";
+function responsePaths(response) {
+  return Array.isArray(response.paths) ? response.paths.filter((path2) => typeof path2 === "string" && path2.length > 0) : [];
+}
 var SafetyParams = Type12.Object({
   op: StringEnum5(["undo", "history", "checkpoint", "restore", "list"], {
     description: "Safety operation"
@@ -34185,14 +34428,14 @@ function buildSafetySections(args, payload, theme) {
       ];
     }
     return [
-      `${theme.fg("success", "restored")} ${theme.fg("accent", shortenPath(asString(response.path) ?? args.filePath ?? "(file)"))}`,
+      `${theme.fg("success", "restored")} ${theme.fg("accent", shortenPath2(asString(response.path) ?? args.filePath ?? "(file)"))}`,
       `${theme.fg("muted", "backup")} ${asString(response.backup_id) ?? "—"}`
     ];
   }
   if (args.op === "history") {
     const entries = asRecords(response.entries);
     const sections2 = [
-      theme.fg("accent", shortenPath(asString(response.file) ?? args.filePath ?? "(file)"))
+      theme.fg("accent", shortenPath2(asString(response.file) ?? args.filePath ?? "(file)"))
     ];
     if (entries.length === 0) {
       sections2.push(theme.fg("muted", "No history entries."));
@@ -34214,7 +34457,7 @@ function buildSafetySections(args, payload, theme) {
       `${theme.fg("success", "checkpoint created")} ${theme.fg("accent", asString(response.name) ?? args.name ?? "(checkpoint)")}`,
       `${theme.fg("muted", "files")} ${asNumber(response.file_count) ?? 0}`,
       skipped.length > 0 ? `${theme.fg("warning", "skipped")}
-${skipped.map((entry) => `  ↳ ${shortenPath(asString(entry.file) ?? "(file)")}: ${asString(entry.error) ?? "unknown error"}`).join(`
+${skipped.map((entry) => `  ↳ ${shortenPath2(asString(entry.file) ?? "(file)")}: ${asString(entry.error) ?? "unknown error"}`).join(`
 `)}` : theme.fg("muted", "No skipped files.")
     ];
   }
@@ -34264,7 +34507,43 @@ function registerSafetyTool(pi, ctx) {
       if ((params.op === "checkpoint" || params.op === "restore") && !params.name) {
         throw new Error(`op='${params.op}' requires 'name'`);
       }
+      const filePath = params.filePath ? await resolvePathArg(extCtx.cwd, params.filePath) : undefined;
+      const files = params.files ? await Promise.all(params.files.map((file2) => resolvePathArg(extCtx.cwd, file2))) : undefined;
       const bridge = bridgeFor(ctx, extCtx.cwd);
+      const restrictToProjectRoot = ctx.config.restrict_to_project_root ?? false;
+      if (params.op === "undo") {
+        const previewReq = {};
+        if (filePath)
+          previewReq.file = filePath;
+        const preview = await callBridge(bridge, "undo_preview", previewReq, extCtx);
+        for (const file2 of new Set(responsePaths(preview))) {
+          await assertExternalDirectoryPermission(extCtx, file2, "modify", {
+            restrictToProjectRoot
+          });
+        }
+      }
+      if (params.op === "checkpoint") {
+        const checkpointFiles = files ?? (filePath ? [filePath] : undefined);
+        if (Array.isArray(checkpointFiles)) {
+          const checked = new Set;
+          for (const file2 of checkpointFiles) {
+            if (checked.has(file2))
+              continue;
+            checked.add(file2);
+            await assertExternalDirectoryPermission(extCtx, file2, "modify", {
+              restrictToProjectRoot
+            });
+          }
+        }
+      }
+      if (params.op === "restore" && params.name) {
+        const preview = await callBridge(bridge, "checkpoint_paths", { name: params.name }, extCtx);
+        for (const file2 of new Set(responsePaths(preview))) {
+          await assertExternalDirectoryPermission(extCtx, file2, "modify", {
+            restrictToProjectRoot
+          });
+        }
+      }
       const commandMap = {
         undo: "undo",
         history: "edit_history",
@@ -34276,16 +34555,16 @@ function registerSafetyTool(pi, ctx) {
       if (params.name)
         req.name = params.name;
       if (params.op === "checkpoint") {
-        if (params.files) {
-          req.files = params.files;
-        } else if (params.filePath) {
-          req.files = [params.filePath];
+        if (files) {
+          req.files = files;
+        } else if (filePath) {
+          req.files = [filePath];
         }
       } else {
-        if (params.filePath)
-          req.file = params.filePath;
-        if (params.files)
-          req.files = params.files;
+        if (filePath)
+          req.file = filePath;
+        if (files)
+          req.files = files;
       }
       const response = await callBridge(bridge, commandMap[params.op], req, extCtx);
       return textResult(JSON.stringify(response, null, 2));
@@ -34362,7 +34641,7 @@ function buildSemanticSections(args, payload, theme) {
   }
   const grouped = groupByFile(results, (result) => asString(result.file));
   for (const [file2, fileResults] of grouped.entries()) {
-    const lines = [theme.fg("accent", shortenPath(file2))];
+    const lines = [theme.fg("accent", shortenPath2(file2))];
     fileResults.forEach((result) => {
       if (asString(result.kind) === "GrepLine") {
         const line = asNumber(result.line);
@@ -34516,8 +34795,12 @@ function registerStructureTool(pi, ctx) {
     parameters: TransformParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
       validateTransformParams(params);
+      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+      await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
+        restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+      });
       const bridge = bridgeFor(ctx, extCtx.cwd);
-      const req = { file: params.filePath };
+      const req = { file: filePath };
       if (params.container !== undefined)
         req.scope = params.container;
       if (params.code !== undefined)
@@ -34554,32 +34837,32 @@ function registerStructureTool(pi, ctx) {
 function validateTransformParams(params) {
   const op = params.op;
   if (op === "add_member") {
-    if (typeof params.container !== "string") {
+    if (isEmptyParam(params.container)) {
       throw new Error("'container' is required for 'add_member' op");
     }
-    if (typeof params.code !== "string") {
+    if (isEmptyParam(params.code)) {
       throw new Error("'code' is required for 'add_member' op");
     }
   }
   if (op === "add_derive" || op === "wrap_try_catch" || op === "add_decorator" || op === "add_struct_tags") {
-    if (typeof params.target !== "string") {
+    if (isEmptyParam(params.target)) {
       throw new Error(`'target' is required for '${op}' op`);
     }
   }
-  if (op === "add_derive" && !Array.isArray(params.derives)) {
+  if (op === "add_derive" && isEmptyParam(params.derives)) {
     throw new Error("'derives' array is required for 'add_derive' op");
   }
-  if (op === "add_decorator" && typeof params.decorator !== "string") {
+  if (op === "add_decorator" && isEmptyParam(params.decorator)) {
     throw new Error("'decorator' is required for 'add_decorator' op");
   }
   if (op === "add_struct_tags") {
-    if (typeof params.field !== "string") {
+    if (isEmptyParam(params.field)) {
       throw new Error("'field' is required for 'add_struct_tags' op");
     }
-    if (typeof params.tag !== "string") {
+    if (isEmptyParam(params.tag)) {
       throw new Error("'tag' is required for 'add_struct_tags' op");
     }
-    if (typeof params.value !== "string") {
+    if (isEmptyParam(params.value)) {
       throw new Error("'value' is required for 'add_struct_tags' op");
     }
   }
@@ -34720,15 +35003,15 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.33.0";
+var ANNOUNCEMENT_VERSION = "0.34.0";
 var ANNOUNCEMENT_FEATURES = [
-  "New `aft_inspect` — one call for codebase health: diagnostics, metrics, TODOs, dead code, unused exports, and duplicates.",
-  "Diagnostics now flow through `aft_inspect` (run it after a batch of edits) instead of arriving automatically on every edit.",
-  "`aft_navigate` is renamed to `aft_callgraph`; the Rust call graph now resolves cross-file callers.",
-  "Edits no longer echo the whole file back to the agent — much lower token cost per edit.",
-  "Batch of `aft_search` correctness fixes and undo-history/SSRF/Windows hardening."
+  "`aft_import` now supports 12 more languages (Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, Perl, C/C++, Vue) — 17 total.",
+  "New YAML + Kubernetes/CRD support across outline, zoom, search, and ast_grep.",
+  "`aft_conflicts` takes an optional `path` to inspect any repo or git worktree, and names the repository it checked.",
+  "`.aftignore` (layered on `.gitignore`) plus ripgrep-style `grep` that searches an explicitly-named file even when ignored.",
+  "`aft_zoom` call-graph annotations are now opt-in (`callgraph: true`); `semantic.max_files` and `bash.foreground_wait_window_ms` are configurable."
 ];
-var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/F2uWxjGnU";
+var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/DSa65w8wuf";
 var ALL_ONLY_TOOLS = new Set([
   "aft_callgraph",
   "aft_delete",
@@ -35033,7 +35316,7 @@ ${lines}
       if (onnxRuntimePromise) {
         await Promise.race([
           onnxRuntimePromise,
-          new Promise((resolve5) => setTimeout(() => resolve5(null), 60000))
+          new Promise((resolve4) => setTimeout(() => resolve4(null), 60000))
         ]);
       }
       const bridge = pool.getBridge(cwd);