@cortexkit/aft-pi 0.48.0 → 0.49.0

package/dist/index.js

@@ -9623,14 +9623,6 @@ function coerceStringArray(value) {
   }
   return [];
 }
-function coerceAliasedStringParam(value, aliasValue) {
-  if (value !== undefined) {
-    return typeof value === "string" ? value : undefined;
-  }
-  if (typeof aliasValue !== "string")
-    return;
-  return aliasValue.trim().length > 0 ? aliasValue : undefined;
-}
 function coerceTargetParam(value) {
   if (Array.isArray(value)) {
     return value.filter((entry) => typeof entry === "string" && entry.length > 0);
@@ -10185,6 +10177,23 @@ ${reflowText}`;
   }
   return " Auto-formatted.";
 }
+// ../aft-bridge/dist/error-contract.js
+class AftToolError extends Error {
+  code;
+  response;
+  constructor(message, code, response) {
+    const cause = { code, message, response };
+    super(message, { cause });
+    this.name = "AftToolError";
+    this.code = code;
+    this.response = response;
+  }
+}
+function toolErrorFromResponse(command, response) {
+  const code = typeof response.code === "string" && response.code.length > 0 ? response.code : "unknown_error";
+  const message = typeof response.message === "string" && response.message.length > 0 ? response.message : `${command} failed`;
+  return new AftToolError(message, code, response);
+}
 // ../aft-bridge/dist/format.js
 function compressionSavingsPercent(original, compressed) {
   if (original <= 0)
@@ -11807,6 +11816,420 @@ function isProcessAlive(pid) {
     return true;
   }
 }
+// ../aft-bridge/dist/path-aliases.js
+class InvalidRequestError extends AftToolError {
+  constructor(message) {
+    super(message, "invalid_request", {
+      success: false,
+      code: "invalid_request",
+      message
+    });
+    this.name = "InvalidRequestError";
+  }
+}
+function isWellFormedUnicodeString(value) {
+  for (let index = 0;index < value.length; index++) {
+    const codeUnit = value.charCodeAt(index);
+    if (codeUnit >= 55296 && codeUnit <= 56319) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 56320 || next > 57343 || Number.isNaN(next))
+        return false;
+      index++;
+    } else if (codeUnit >= 56320 && codeUnit <= 57343) {
+      return false;
+    }
+  }
+  return true;
+}
+function hasOwn(record, key) {
+  return Object.hasOwn(record, key);
+}
+function invalidPathValue(property) {
+  throw new InvalidRequestError(`'${property}' must be a non-empty well-formed Unicode string`);
+}
+function pathValue(record, property) {
+  const value = record[property];
+  if (typeof value !== "string" || value.length === 0 || !isWellFormedUnicodeString(value)) {
+    invalidPathValue(property);
+  }
+  return value;
+}
+function normalizeAliasPair(record, canonical, legacy, required) {
+  const hasCanonical = hasOwn(record, canonical);
+  const hasLegacy = hasOwn(record, legacy);
+  if (!hasCanonical && !hasLegacy) {
+    if (required) {
+      throw new InvalidRequestError(`'${canonical}' is required`);
+    }
+    return;
+  }
+  if (hasCanonical && hasLegacy) {
+    let canonicalValue;
+    let legacyValue;
+    try {
+      canonicalValue = pathValue(record, canonical);
+      legacyValue = pathValue(record, legacy);
+    } catch {
+      throw new InvalidRequestError(`Invalid request: '${canonical}' and '${legacy}' must both be non-empty well-formed Unicode strings`);
+    }
+    if (canonicalValue !== legacyValue) {
+      throw new InvalidRequestError(`Invalid request: '${canonical}' and '${legacy}' must contain equal decoded strings`);
+    }
+    delete record[legacy];
+    return;
+  }
+  if (hasCanonical) {
+    pathValue(record, canonical);
+    return;
+  }
+  record[canonical] = pathValue(record, legacy);
+  delete record[legacy];
+}
+function validateOptionalCanonicalPath(record, property) {
+  if (hasOwn(record, property))
+    pathValue(record, property);
+}
+function normalizeZoomTargets(record) {
+  if (!hasOwn(record, "targets"))
+    return;
+  const targets = record.targets;
+  const normalizeTarget = (target, index) => {
+    if (!target || typeof target !== "object" || Array.isArray(target)) {
+      throw new InvalidRequestError(`'targets[${index}].path' must be a non-empty string`);
+    }
+    const source = target;
+    const emptyTarget = source.symbol === "" && (hasOwn(source, "path") && source.path === "" || hasOwn(source, "filePath") && source.filePath === "");
+    if (emptyTarget)
+      return { ...source };
+    const normalized = { ...source };
+    try {
+      normalizeAliasPair(normalized, "path", "filePath", true);
+    } catch (error2) {
+      if (error2 instanceof InvalidRequestError) {
+        throw new InvalidRequestError(error2.message.replace("'filePath'", `'targets[${index}].filePath'`).replace("'path'", `'targets[${index}].path'`));
+      }
+      throw error2;
+    }
+    return normalized;
+  };
+  if (Array.isArray(targets)) {
+    if (targets.length === 0)
+      return;
+    record.targets = targets.map(normalizeTarget);
+    return;
+  }
+  if (targets && typeof targets === "object") {
+    record.targets = normalizeTarget(targets, 0);
+  }
+}
+function bareToolName(toolName) {
+  const bare = toolName.startsWith("aft_") ? toolName.slice(4) : toolName;
+  if (bare === "read" || bare === "write" || bare === "edit" || bare === "zoom" || bare === "callgraph" || bare === "safety" || bare === "move" || bare === "import" || bare === "refactor" || bare === "grep" || bare === "search" || bare === "conflicts") {
+    return bare;
+  }
+  return;
+}
+function prepareCanonicalPathArguments(toolName, rawArguments) {
+  if (!rawArguments || typeof rawArguments !== "object" || Array.isArray(rawArguments)) {
+    throw new InvalidRequestError("tool arguments must be an object");
+  }
+  const tool = bareToolName(toolName);
+  const record = { ...rawArguments };
+  if (!tool)
+    return record;
+  switch (tool) {
+    case "read":
+    case "write":
+    case "edit":
+    case "move":
+    case "import":
+    case "refactor":
+      normalizeAliasPair(record, "path", "filePath", true);
+      break;
+    case "zoom":
+      normalizeAliasPair(record, "path", "filePath", false);
+      normalizeZoomTargets(record);
+      break;
+    case "callgraph":
+      normalizeAliasPair(record, "path", "filePath", true);
+      normalizeAliasPair(record, "toPath", "toFile", false);
+      break;
+    case "safety":
+      normalizeAliasPair(record, "path", "filePath", false);
+      break;
+    case "grep":
+    case "search":
+    case "conflicts":
+      validateOptionalCanonicalPath(record, "path");
+      break;
+  }
+  return record;
+}
+var EDIT_ROOT_COMPATIBILITY_KEYS = new Set([
+  "oldString",
+  "newString",
+  "replaceAll",
+  "occurrence"
+]);
+var EDIT_ROOT_CANONICAL_KEYS = new Set(["path", "appendContent", "edits", "symbol", "content"]);
+var EDIT_ITEM_KEYS = new Set([
+  "oldString",
+  "newString",
+  "replaceAll",
+  "occurrence",
+  "startLine",
+  "endLine",
+  "content"
+]);
+var ASCII_WHITESPACE = /^[\t\n\v\f\r ]+$/;
+var ASCII_TRIM = /^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g;
+var MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+function prepareCanonicalEditArguments(toolName, rawArguments) {
+  if (!rawArguments || typeof rawArguments !== "object" || Array.isArray(rawArguments)) {
+    throw new InvalidRequestError("tool arguments must be an object");
+  }
+  const raw = rawArguments;
+  const record = copyOwnProperties(raw);
+  normalizeEditPathAlias(record);
+  const suppliedLineFields = ["startLine", "endLine"].filter((key) => hasOwn(record, key));
+  if (suppliedLineFields.length > 0) {
+    throw new InvalidRequestError(`edit: top-level ${suppliedLineFields.map((key) => `'${key}'`).join(" and ")} are invalid; ` + "line-range fields are valid only inside 'edits[]'. " + "Use edits: [{ startLine, endLine, content }].");
+  }
+  const isOpenCodeRetiredBoundary = toolName === "aft_edit";
+  const retiredFields = ["file", "mode"].filter((key) => hasOwn(record, key));
+  if (retiredFields.length > 0 && isOpenCodeRetiredBoundary) {
+    throw new InvalidRequestError("aft_edit: the retired `mode`/`file` edit form is no longer supported; use `path` with " + "exactly one of `appendContent`, `edits`, or `symbol` plus `content`.");
+  }
+  const unknownRootKeys = Object.getOwnPropertyNames(record).filter((key) => !EDIT_ROOT_CANONICAL_KEYS.has(key) && !EDIT_ROOT_COMPATIBILITY_KEYS.has(key) && key !== "filePath").sort();
+  if (unknownRootKeys.length > 0) {
+    throw new InvalidRequestError(formatUnknownKeys(unknownRootKeys));
+  }
+  const modes = editModesPresent(record);
+  if (modes.length > 1) {
+    throw new InvalidRequestError(`edit: conflicting modes: ${modes.join(", ")}`);
+  }
+  if (modes.length === 0) {
+    throw new InvalidRequestError("edit: exactly one of `appendContent`, `edits`, or `symbol` plus `content` is required");
+  }
+  const mode = modes[0];
+  if (mode === "appendContent") {
+    if (typeof record.appendContent !== "string") {
+      throw new InvalidRequestError("edit: 'appendContent' must be a string");
+    }
+  } else if (mode === "edits") {
+    const parsedEdits = parseEditArray(record.edits);
+    record.edits = parsedEdits.map((item, index) => normalizeEditItem(item, index));
+  } else if (mode === "symbol/content") {
+    if (!hasOwn(record, "symbol") || typeof record.symbol !== "string") {
+      throw new InvalidRequestError("edit: 'symbol' must be a string when symbol mode is selected");
+    }
+    if (!hasOwn(record, "content") || typeof record.content !== "string") {
+      throw new InvalidRequestError("edit: symbol mode requires both 'symbol' and 'content' string properties");
+    }
+  } else {
+    const item = {};
+    for (const key of EDIT_ROOT_COMPATIBILITY_KEYS) {
+      if (hasOwn(record, key))
+        item[key] = record[key];
+    }
+    record.edits = [normalizeEditItem(item, 0)];
+    for (const key of EDIT_ROOT_COMPATIBILITY_KEYS)
+      delete record[key];
+  }
+  validateEditPath(record);
+  return record;
+}
+function normalizeEditPathAlias(record) {
+  const hasCanonical = hasOwn(record, "path");
+  const hasLegacy = hasOwn(record, "filePath");
+  if (!hasCanonical && !hasLegacy)
+    return;
+  if (hasCanonical && hasLegacy) {
+    let canonical;
+    let legacy;
+    try {
+      canonical = pathValue(record, "path");
+      legacy = pathValue(record, "filePath");
+    } catch {
+      throw new InvalidRequestError("Invalid request: 'path' and 'filePath' must both be non-empty well-formed Unicode strings");
+    }
+    if (canonical !== legacy) {
+      throw new InvalidRequestError("Invalid request: 'path' and 'filePath' must contain equal decoded strings");
+    }
+    delete record.filePath;
+    return;
+  }
+  if (!hasCanonical) {
+    record.path = pathValue(record, "filePath");
+    delete record.filePath;
+  }
+}
+function validateEditPath(record) {
+  if (!hasOwn(record, "path")) {
+    throw new InvalidRequestError("'path' is required");
+  }
+  pathValue(record, "path");
+}
+function formatUnknownKeys(keys) {
+  return `Unrecognized keys: ${keys.map((key) => `"${key}"`).join(", ")}`;
+}
+function editModesPresent(record) {
+  const modes = [];
+  if (hasOwn(record, "appendContent"))
+    modes.push("appendContent");
+  if (hasOwn(record, "edits"))
+    modes.push("edits");
+  if (hasOwn(record, "symbol") || hasOwn(record, "content"))
+    modes.push("symbol/content");
+  if (["oldString", "newString", "replaceAll", "occurrence"].some((key) => hasOwn(record, key))) {
+    modes.push("oldString/newString");
+  }
+  return modes;
+}
+function parseEditArray(value) {
+  if (typeof value === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      throw new InvalidRequestError("edit: 'edits' must contain valid JSON representing an array");
+    }
+    if (!Array.isArray(parsed)) {
+      throw new InvalidRequestError("edit: 'edits' JSON must have an array root");
+    }
+    if (parsed.length === 0) {
+      throw new InvalidRequestError("edit: 'edits' array must not be empty");
+    }
+    return parsed;
+  }
+  if (!Array.isArray(value)) {
+    throw new InvalidRequestError("edit: 'edits' must be a non-empty array");
+  }
+  if (value.length === 0) {
+    throw new InvalidRequestError("edit: 'edits' array must not be empty");
+  }
+  return value;
+}
+function normalizeEditItem(value, index) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new InvalidRequestError(`edit: edits[${index}] must be an object`);
+  }
+  const source = value;
+  const item = copyOwnProperties(source);
+  normalizeItemAlias(item, "oldString", "oldText");
+  normalizeItemAlias(item, "newString", "newText");
+  const hasFindField = ["oldString", "newString", "replaceAll", "occurrence"].some((key) => hasOwn(item, key));
+  const hasRangeField = ["startLine", "endLine", "content"].some((key) => hasOwn(item, key));
+  if (hasFindField && hasRangeField) {
+    throw new InvalidRequestError(`edit: edits[${index}] mixes find/replace and line-range fields`);
+  }
+  if (hasFindField) {
+    if (!hasOwn(item, "oldString") || typeof item.oldString !== "string") {
+      throw new InvalidRequestError(`edit: edits[${index}] requires string 'oldString'`);
+    }
+    if (hasOwn(item, "newString") && typeof item.newString !== "string") {
+      throw new InvalidRequestError(`edit: edits[${index}].newString must be a string`);
+    }
+    coerceEditScalars(item, index);
+    validateEditItemKeys(item, index);
+    return item;
+  }
+  if (hasRangeField) {
+    for (const key of ["startLine", "endLine"]) {
+      const value2 = item[key];
+      if (typeof value2 === "string" && /^[0-9]+$/.test(value2.trim())) {
+        item[key] = Number(value2.trim());
+      }
+      if (!hasOwn(item, key) || !isPositiveSafeInteger(item[key])) {
+        throw new InvalidRequestError(`edit: edits[${index}].${key} must be a positive integer`);
+      }
+    }
+    if (item.startLine > item.endLine) {
+      throw new InvalidRequestError(`edit: edits[${index}] requires startLine <= endLine`);
+    }
+    if (!hasOwn(item, "content") || typeof item.content !== "string") {
+      throw new InvalidRequestError(`edit: edits[${index}] requires string 'content'`);
+    }
+    validateEditItemKeys(item, index);
+    return item;
+  }
+  throw new InvalidRequestError(`edit: edits[${index}] must be a find/replace or line-range item`);
+}
+function normalizeItemAlias(item, canonical, legacy) {
+  if (hasOwn(item, legacy)) {
+    if (!hasOwn(item, canonical))
+      item[canonical] = item[legacy];
+    delete item[legacy];
+  }
+}
+function validateEditItemKeys(item, index) {
+  const unknown = Object.getOwnPropertyNames(item).filter((key) => !EDIT_ITEM_KEYS.has(key)).sort();
+  if (unknown.length > 0) {
+    throw new InvalidRequestError(`edit: edits[${index}] contains ${formatUnknownKeys(unknown)}`);
+  }
+}
+function coerceEditScalars(item, index) {
+  if (hasOwn(item, "replaceAll") && hasOwn(item, "occurrence")) {
+    throw new InvalidRequestError(`edit: edits[${index}] cannot contain both 'replaceAll' and 'occurrence'`);
+  }
+  if (hasOwn(item, "replaceAll"))
+    item.replaceAll = coerceEditBoolean(item.replaceAll, index);
+  if (hasOwn(item, "occurrence")) {
+    const occurrence = coerceEditOccurrence(item.occurrence, index);
+    if (occurrence === undefined)
+      delete item.occurrence;
+    else
+      item.occurrence = occurrence;
+  }
+}
+function coerceEditBoolean(value, index) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number" && Number.isFinite(value) && (value === 0 || value === 1)) {
+    return value === 1;
+  }
+  if (typeof value === "string") {
+    if (value === "1")
+      return true;
+    if (value === "0")
+      return false;
+    if (/^(?:true|false)$/i.test(value))
+      return value.toLowerCase() === "true";
+  }
+  throw new InvalidRequestError(`edit: edits[${index}].replaceAll must be a boolean, true/false string, or 0/1`);
+}
+function coerceEditOccurrence(value, index) {
+  if (value === null)
+    return;
+  if (typeof value === "string") {
+    const trimmed = value.replace(ASCII_TRIM, "");
+    if (trimmed.length === 0 || ASCII_WHITESPACE.test(trimmed))
+      return;
+    if (!/^[+]?[0-9]+$/.test(trimmed)) {
+      throw new InvalidRequestError(`edit: edits[${index}].occurrence must be a positive integer`);
+    }
+    try {
+      const parsed = BigInt(trimmed);
+      if (parsed < 1n || parsed > BigInt(MAX_SAFE_INTEGER))
+        throw new Error("out of range");
+      return Number(parsed);
+    } catch {
+      throw new InvalidRequestError(`edit: edits[${index}].occurrence must be a positive integer`);
+    }
+  }
+  if (typeof value === "number" && isPositiveSafeInteger(value))
+    return value;
+  throw new InvalidRequestError(`edit: edits[${index}].occurrence must be a positive integer`);
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+function copyOwnProperties(source) {
+  const copy = Object.create(null);
+  for (const key of Object.getOwnPropertyNames(source))
+    copy[key] = source[key];
+  return copy;
+}
 // ../aft-bridge/dist/pool.js
 import { homedir as homedir10 } from "node:os";
 
@@ -15795,7 +16218,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.48.0",
+  version: "0.49.0",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -15818,19 +16241,19 @@ var package_default = {
     "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.48.0",
+    "@cortexkit/aft-bridge": "0.49.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
     typebox: "1.1.38",
     zod: "^4.4.3"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.48.0",
-    "@cortexkit/aft-darwin-x64": "0.48.0",
-    "@cortexkit/aft-linux-arm64": "0.48.0",
-    "@cortexkit/aft-linux-x64": "0.48.0",
-    "@cortexkit/aft-win32-arm64": "0.48.0",
-    "@cortexkit/aft-win32-x64": "0.48.0"
+    "@cortexkit/aft-darwin-arm64": "0.49.0",
+    "@cortexkit/aft-darwin-x64": "0.49.0",
+    "@cortexkit/aft-linux-arm64": "0.49.0",
+    "@cortexkit/aft-linux-x64": "0.49.0",
+    "@cortexkit/aft-win32-arm64": "0.49.0",
+    "@cortexkit/aft-win32-x64": "0.49.0"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "^0.80.2",
@@ -16072,6 +16495,20 @@ import { Type } from "typebox";
 var optionalInt = (min, max, description = "(integer)") => Type.Optional(Type.Union([Type.Integer({ minimum: min, maximum: max }), Type.String()], {
   description
 }));
+function withPathAliasPreparation(tool) {
+  const existing = tool.prepareArguments;
+  const prepare = (args) => {
+    const prepared = tool.name === "edit" ? prepareCanonicalEditArguments(tool.name, args) : prepareCanonicalPathArguments(tool.name, args);
+    return existing ? existing(prepared) : prepared;
+  };
+  return {
+    ...tool,
+    prepareArguments: prepare,
+    execute(toolCallId, params, signal, onUpdate, context) {
+      return tool.execute(toolCallId, prepare(params), signal, onUpdate, context);
+    }
+  };
+}
 function bridgeFor(ctx, cwd) {
   if (!existsSync7(cwd)) {
     throw new Error(`project directory no longer exists: ${cwd} (stale restored session?)`);
@@ -32037,7 +32474,7 @@ async function ensureServerInstalled(spec, config2, fetchImpl, signal) {
             return null;
           });
           if (currentHash && currentHash !== installedMeta.sha256) {
-            error2(`[lsp] ${spec.npm}@${version2}: TOFU sha256 mismatch — refusing to use ` + `tampered binary. Recorded ${installedMeta.sha256}, current ${currentHash}. ` + `Run \`aft doctor --clear\` to re-install from scratch.`);
+            error2(`[lsp] ${spec.npm}@${version2}: TOFU sha256 mismatch — refusing to use ` + `tampered binary. Recorded ${installedMeta.sha256}, current ${currentHash}. ` + `Run \`npx @cortexkit/aft doctor --clear\` to re-install from scratch.`);
             return {
               started: false,
               reason: `TOFU sha256 mismatch on ${spec.npm}@${version2} — see plugin log`
@@ -33517,29 +33954,25 @@ async function assertExternalDirectoryPermission(extCtx, target, options = {}) {
   throw new Error(`Blocked: '${absoluteTarget}' is outside the project root and restrict_to_project_root is ` + "enabled (AFT full isolation). Not overridable per-call; set restrict_to_project_root: false " + "in aft.jsonc to allow external paths.");
 }
 var ReadParams = Type2.Object({
-  path: Type2.Optional(Type2.String({
+  path: Type2.String({
     description: "Path to the file to read (absolute or relative to project root)"
-  })),
-  filePath: Type2.Optional(Type2.String({
-    description: "Alias for `path` — provide one of the two."
-  })),
-  offset: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line number to start reading from (use with limit)"),
-  limit: optionalInt(1, Number.MAX_SAFE_INTEGER, "Maximum number of lines to return")
+  }),
+  startLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line to start reading from"),
+  endLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line to stop reading at (inclusive)"),
+  limit: optionalInt(1, Number.MAX_SAFE_INTEGER, "Maximum number of lines to return"),
+  offset: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line number to start reading from (use with limit)")
 });
 var WriteParams = Type2.Object({
-  filePath: Type2.Optional(Type2.String({
+  path: Type2.String({
     description: "Path to the file to write (absolute or relative to project root)"
-  })),
-  path: Type2.Optional(Type2.String({
-    description: "Alias for `filePath` — provide one of the two."
-  })),
+  }),
   content: Type2.String({ description: "Full file contents to write" })
 });
 var BatchEditParams = Type2.Object({
   oldString: Type2.Optional(Type2.String({ description: "Text to find for a batch find/replace edit" })),
   newString: Type2.Optional(Type2.String({ description: "Replacement text for a batch find/replace edit" })),
   replaceAll: Type2.Optional(Type2.Boolean({ description: "Replace every occurrence for this batch item" })),
-  occurrence: optionalInt(0, Number.MAX_SAFE_INTEGER, "0-based occurrence for this batch item"),
+  occurrence: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based occurrence for this batch item (1 = first match)"),
   startLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based start line for a batch line-range edit"),
   endLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based end line for a batch line-range edit"),
   content: Type2.Optional(Type2.String({
@@ -33547,21 +33980,19 @@ var BatchEditParams = Type2.Object({
   }))
 });
 var EditParams = Type2.Object({
-  filePath: Type2.Optional(Type2.String({
+  path: Type2.String({
     description: "Path to the file to edit (absolute or relative to project root)"
+  }),
+  symbol: Type2.Optional(Type2.String({ description: "Named symbol to replace (function, class, type)" })),
+  content: Type2.Optional(Type2.String({
+    description: "Replacement content for symbol mode. For whole-file writes, use the `write` tool."
   })),
-  path: Type2.Optional(Type2.String({
-    description: "Alias for `filePath` — provide one of the two."
-  })),
-  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, "0-based occurrence to replace when multiple matches exist"),
   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, edits/oldString/newString are ignored."
+    description: "Append text to the end of the file (creates the file if missing, parent dirs auto-created). When set, other edit modes are ignored."
   })),
   edits: Type2.Optional(Type2.Array(BatchEditParams, {
-    description: "Batch edits — array of { oldString, newString }, { oldString, newString, replaceAll: true }, or { startLine, endLine, content } objects applied atomically."
+    minItems: 1,
+    description: "Batch edits — non-empty array of { oldString, newString }, { oldString, newString, replaceAll: true }, or { startLine, endLine, content } objects applied atomically."
   }))
 });
 var GrepParams = Type2.Object({
@@ -33569,16 +34000,15 @@ var GrepParams = Type2.Object({
   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" }))
+  include: Type2.Optional(Type2.String({ description: "Glob filter for included files (e.g. '*.ts,*.tsx')" }))
 });
 function readPathArg(args) {
-  return coerceAliasedStringParam(args.path, args.filePath);
+  return typeof args.path === "string" ? args.path : undefined;
 }
 function mutationFilePathArg(args) {
-  return coerceAliasedStringParam(args.filePath, args.path);
+  return typeof args.path === "string" ? args.path : undefined;
 }
-function hasOwn(record2, key) {
+function hasOwn2(record2, key) {
   return Object.hasOwn(record2, key);
 }
 function validateBatchEdit(edit, index) {
@@ -33589,7 +34019,7 @@ function validateBatchEdit(edit, index) {
   if (typeof record2.oldString === "string") {
     return;
   }
-  if (hasOwn(record2, "startLine")) {
+  if (hasOwn2(record2, "startLine")) {
     if (typeof record2.startLine !== "number" || !Number.isInteger(record2.startLine) || record2.startLine < 0) {
       throw new Error(`batch: edit[${index}] 'startLine' must be a positive integer (1-based)`);
     }
@@ -33628,7 +34058,7 @@ function renderReadCall(args, theme, context) {
 }
 function registerHoistedTools(pi, ctx, surface) {
   if (surface.hoistRead) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       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. Images are returned as attachments on vision-capable models; PDFs and non-vision models are not yet supported.",
@@ -33641,6 +34071,8 @@ function registerHoistedTools(pi, ctx, surface) {
         if (typeof pathArg !== "string") {
           throw new Error("read: missing required parameter `path`");
         }
+        const startLine = coerceOptionalInt(params.startLine, "startLine", 1, Number.MAX_SAFE_INTEGER);
+        const endLine = coerceOptionalInt(params.endLine, "endLine", 1, Number.MAX_SAFE_INTEGER);
         const offset = coerceOptionalInt(params.offset, "offset", 1, Number.MAX_SAFE_INTEGER);
         const limit = coerceOptionalInt(params.limit, "limit", 1, Number.MAX_SAFE_INTEGER);
         const filePath = await resolvePathArg(extCtx.cwd, pathArg);
@@ -33649,6 +34081,10 @@ function registerHoistedTools(pi, ctx, surface) {
           serverValidatedRead: true
         });
         const rawArgs = { filePath: pathArg };
+        if (startLine !== undefined)
+          rawArgs.startLine = startLine;
+        if (endLine !== undefined)
+          rawArgs.endLine = endLine;
         if (offset !== undefined)
           rawArgs.offset = offset;
         if (limit !== undefined)
@@ -33684,21 +34120,21 @@ PDFs aren't supported on the Pi harness yet.`, response);
       renderCall(args, theme, context) {
         return renderReadCall(args, theme, context);
       }
-    });
+    }));
   }
   if (surface.hoistWrite) {
     const writeBackupText = ctx.config.backup?.enabled === false ? "Backup capture is disabled by user config." : "Existing files are backed up before overwriting (undo via aft_safety).";
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "write",
       label: "write",
-      description: `Write content to a file, creating it and parent directories automatically. ${writeBackupText} Auto-formats when the project has a formatter configured. Uses \`filePath\` (not \`path\`). For partial edits, use the \`edit\` tool.`,
-      promptSnippet: "Create or overwrite files (uses filePath; auto-formats)",
+      description: `Write content to a file, creating it and parent directories automatically. ${writeBackupText} Auto-formats when the project has a formatter configured. Uses \`path\`. For partial edits, use the \`edit\` tool.`,
+      promptSnippet: "Create or overwrite files (uses path; auto-formats)",
       promptGuidelines: ["Use write only for new files or complete rewrites."],
       parameters: WriteParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const filePathArg = mutationFilePathArg(params);
         if (typeof filePathArg !== "string") {
-          throw new Error("write: missing required parameter `filePath`");
+          throw new Error("write: missing required parameter `path`");
         }
         const filePath = await resolvePathArg(extCtx.cwd, filePathArg);
         await assertExternalDirectoryPermission(extCtx, filePath, {
@@ -33711,7 +34147,7 @@ PDFs aren't supported on the Pi harness yet.`, response);
         };
         const response = await callToolCall(bridge, "write", rawArgs, extCtx);
         if (response.success === false) {
-          throw new Error(response.text || response.message || "write failed");
+          throw toolErrorFromResponse("write", response);
         }
         return buildMutationResult(response);
       },
@@ -33721,60 +34157,45 @@ PDFs aren't supported on the Pi harness yet.`, response);
       renderResult(result, _options, theme, context) {
         return renderMutationResult(result, theme, context);
       }
-    });
+    }));
   }
   if (surface.hoistEdit) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "edit",
       label: "edit",
-      description: "Edit part of a file via `appendContent`, batch `edits[]`, or `oldString`/`newString` find-and-replace. Batch `{ oldString, newString, replaceAll: true }` replaces every match. Mode priority: appendContent > edits > oldString.",
-      promptSnippet: "Partial file edits via appendContent, edits[], or oldString/newString (mode priority: appendContent > edits > oldString).",
+      description: "Edit part of a file via `appendContent`, batch `edits[]`, or symbol plus `content`. Batch `{ oldString, newString, replaceAll: true }` replaces every match. Provide exactly one mode per call: appendContent, edits[], or symbol plus content (mixing modes is rejected).",
+      promptSnippet: "Partial file edits via appendContent, edits[], or symbol plus content (exactly one mode per call).",
       promptGuidelines: [
         "Prefer edit over write when changing part of an existing file.",
         "Use appendContent when adding text to the end of a file.",
         "Use edits[] for multiple atomic changes in one file.",
-        "Include enough surrounding context in oldString to make the match unique, or set replaceAll/occurrence explicitly."
+        "Include enough surrounding context in an edits[] find/replace item to make the match unique, or set replaceAll/occurrence explicitly."
       ],
       parameters: EditParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const argsRecord = params;
         if (argsRecord.startLine !== undefined || argsRecord.endLine !== undefined) {
-          throw new Error("edit: 'startLine'/'endLine' are not top-level parameters. " + "For line-range edits, nest them inside the `edits` array: " + '`edits: [{ startLine: N, endLine: M, content: "..." }]`. ' + "For find/replace, use `oldString`/`newString` instead.");
+          throw new Error("edit: 'startLine'/'endLine' are not top-level parameters. " + "For line-range edits, nest them inside the `edits` array: " + '`edits: [{ startLine: N, endLine: M, content: "..." }]`. ' + "For find/replace, use an item in `edits[]` instead.");
         }
         const filePathArg = mutationFilePathArg(params);
         if (typeof filePathArg !== "string") {
-          throw new Error("edit: missing required parameter `filePath`");
+          throw new Error("edit: missing required parameter `path`");
         }
-        if (params.appendContent === undefined)
+        if (params.edits !== undefined)
           validateBatchEdits(params.edits);
         const filePath = await resolvePathArg(extCtx.cwd, filePathArg);
         await assertExternalDirectoryPermission(extCtx, filePath, {
           restrictToProjectRoot: surface.restrictToProjectRoot
         });
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const rawArgs = { filePath: filePathArg };
-        for (const key of ["appendContent", "oldString", "newString"]) {
+        const rawArgs = { path: filePathArg };
+        for (const key of ["appendContent", "edits", "symbol", "content"]) {
           if (argsRecord[key] !== undefined)
             rawArgs[key] = argsRecord[key];
         }
-        if (Array.isArray(argsRecord.edits)) {
-          rawArgs.edits = argsRecord.edits.map((item) => {
-            if (!item || typeof item !== "object" || Array.isArray(item))
-              return item;
-            const batchItem = item;
-            return batchItem.replaceAll === undefined ? batchItem : { ...batchItem, replaceAll: coerceBoolean(batchItem.replaceAll) };
-          });
-        } else if (argsRecord.edits !== undefined) {
-          rawArgs.edits = argsRecord.edits;
-        }
-        if (params.replaceAll !== undefined)
-          rawArgs.replaceAll = coerceBoolean(params.replaceAll);
-        const occurrence = coerceOptionalInt(params.occurrence, "occurrence", 0, Number.MAX_SAFE_INTEGER);
-        if (occurrence !== undefined)
-          rawArgs.occurrence = occurrence;
         const response = await callToolCall(bridge, "edit", rawArgs, extCtx);
         if (response.success === false) {
-          throw new Error(response.text || response.message || "edit failed");
+          throw toolErrorFromResponse("edit", response);
         }
         return buildMutationResult(response);
       },
@@ -33784,10 +34205,10 @@ PDFs aren't supported on the Pi harness yet.`, response);
       renderResult(result, _options, theme, context) {
         return renderMutationResult(result, theme, context);
       }
-    });
+    }));
   }
   if (surface.hoistGrep) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       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.",
@@ -33809,8 +34230,6 @@ PDFs aren't supported on the Pi harness yet.`, response);
         }
         if (params.include)
           req.include = params.include;
-        if (params.caseSensitive !== undefined)
-          req.caseSensitive = params.caseSensitive;
         const response = await callToolCall(bridge, "grep", req, extCtx);
         if (response.success === false) {
           throw new Error(response.text || response.message || "grep failed");
@@ -33821,7 +34240,7 @@ PDFs aren't supported on the Pi harness yet.`, response);
         const text = appendSkippedSearchPaths(response.text ?? "", pathSplit?.missing ?? []);
         return textResult(text, response);
       }
-    });
+    }));
   }
 }
 function buildMutationResult(response) {
@@ -34165,7 +34584,7 @@ var SearchParams = Type3.Object({
   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" }))
+  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER, "Number of context lines around each match")
 });
 var ReplaceParams = Type3.Object({
   pattern: Type3.String({ description: "AST pattern with meta-variables" }),
@@ -35056,7 +35475,7 @@ function formatWaitSummary(waited, details) {
     return `Waited ${waited.elapsed_ms}ms; timeout reached without match.`;
   }
   if (waited.reason === "unavailable") {
-    return `Waited ${waited.elapsed_ms}ms; the bridge stayed busy and status couldn't be read. The task may still be running — check with bash_status({ taskId }).`;
+    return `Waited ${waited.elapsed_ms}ms; the bridge was busy, so task state is unknown. Do not poll; let the task's completion notification wake the session, or use one bash_status snapshot on the next normal tool call.`;
   }
   const exit = typeof details.exit_code === "number" ? `, exit ${details.exit_code}` : "";
   return `Waited ${waited.elapsed_ms}ms; task exited (${details.status}${exit}).`;
@@ -35197,7 +35616,7 @@ function renderConflictToolResult(result, theme, context) {
   return renderConflictResult(collectTextContent(result), theme, context);
 }
 function registerConflictsTool(pi, ctx) {
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     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.",
@@ -35224,7 +35643,7 @@ function registerConflictsTool(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderConflictToolResult(result, theme, context);
     }
-  });
+  }));
 }
 
 // src/tools/fs.ts
@@ -35239,7 +35658,7 @@ var DeleteParams = Type6.Object({
   }))
 });
 var MoveParams = Type6.Object({
-  filePath: Type6.String({
+  path: Type6.String({
     description: "Source file path to move (absolute or relative to project root)"
   }),
   destination: Type6.String({
@@ -35263,7 +35682,7 @@ function renderFsCall(toolName, args, theme, context) {
     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);
+  return renderToolCall("move", `${accentPath(theme, moveArgs.path)} ${theme.fg("muted", "→")} ${accentPath(theme, moveArgs.destination)}`, theme, context);
 }
 function renderFsResult(toolName, args, result, theme, context) {
   if (context.isError) {
@@ -35289,14 +35708,14 @@ function renderFsResult(toolName, args, result, theme, context) {
   }
   const moveArgs = args;
   return renderSections([
-    `${theme.fg("success", "✓ moved")} ${theme.fg("accent", shortenPath3(moveArgs.filePath))}`,
+    `${theme.fg("success", "✓ moved")} ${theme.fg("accent", shortenPath3(moveArgs.path ?? ""))}`,
     `${theme.fg("muted", "to")} ${theme.fg("accent", shortenPath3(moveArgs.destination))}`
   ], context);
 }
 function registerFsTools(pi, ctx, surface) {
   const backupsDisabled = ctx.config.backup?.enabled === false;
   if (surface.delete) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "aft_delete",
       label: "delete",
       description: "Delete one or more files (or directories). " + (backupsDisabled ? "Backup capture is disabled by user config, so this tool does not create undo snapshots. " : "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.",
@@ -35340,16 +35759,16 @@ function registerFsTools(pi, ctx, surface) {
       renderResult(result, _options, theme, context) {
         return renderFsResult("aft_delete", context.args, result, theme, context);
       }
-    });
+    }));
   }
   if (surface.move) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "aft_move",
       label: "move",
       description: "Move or rename a file. " + (backupsDisabled ? "Backup capture is disabled by user config. " : "Creates an undo backup before moving. ") + "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 filePath = await resolvePathArg(extCtx.cwd, params.path);
         const destination = await resolvePathArg(extCtx.cwd, params.destination);
         const checked = new Set([filePath, destination]);
         for (const file2 of checked) {
@@ -35359,7 +35778,7 @@ function registerFsTools(pi, ctx, surface) {
         }
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const response = await callToolCall(bridge, "move", {
-          filePath: params.filePath,
+          filePath: params.path,
           destination: params.destination
         }, extCtx);
         if (response.success === false) {
@@ -35373,7 +35792,7 @@ function registerFsTools(pi, ctx, surface) {
       renderResult(result, _options, theme, context) {
         return renderFsResult("aft_move", context.args, result, theme, context);
       }
-    });
+    }));
   }
 }
 
@@ -35382,7 +35801,9 @@ import { StringEnum as StringEnum2 } from "@earendil-works/pi-ai";
 import { Type as Type7 } from "typebox";
 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)" }),
+  path: 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, using native named-import text with per-name `as` aliasing where supported, e.g. ['useState'], Solidity ['ERC20', 'IERC20 as IToken']"
@@ -35412,7 +35833,7 @@ function buildImportSections(args, payload, theme) {
     const groups = asRecords2(response.groups);
     const groupText = groups.length > 0 ? groups.map((group) => `${asString2(group.name) ?? "unknown"}: ${asNumber2(group.count) ?? 0}`).join(" · ") : "No imports found";
     return [
-      `${theme.fg("success", "organized")} ${theme.fg("accent", asString2(response.file) ?? args.filePath)}`,
+      `${theme.fg("success", "organized")} ${theme.fg("accent", asString2(response.file) ?? args.path ?? "")}`,
       `${theme.fg("muted", "groups")} ${groupText}`,
       `${theme.fg("muted", "duplicates removed")} ${asNumber2(response.removed_duplicates) ?? 0}`
     ];
@@ -35422,7 +35843,7 @@ function buildImportSections(args, payload, theme) {
     const status = response.already_present === true ? theme.fg("warning", "already present") : theme.fg("success", "added");
     return [
       `${status} ${theme.fg("accent", moduleName2)}`,
-      `${theme.fg("muted", "file")} ${theme.fg("accent", asString2(response.file) ?? args.filePath)}`,
+      `${theme.fg("muted", "file")} ${theme.fg("accent", asString2(response.file) ?? args.path ?? "")}`,
       `${theme.fg("muted", "group")} ${asString2(response.group) ?? "—"}`
     ];
   }
@@ -35431,14 +35852,14 @@ function buildImportSections(args, payload, theme) {
   const removeStatus = didRemove ? `${theme.fg("success", "removed")} ${theme.fg("accent", moduleName)}` : `${theme.fg("warning", "not present")} ${theme.fg("accent", moduleName)}`;
   return [
     removeStatus,
-    `${theme.fg("muted", "file")} ${theme.fg("accent", asString2(response.file) ?? args.filePath)}`,
+    `${theme.fg("muted", "file")} ${theme.fg("accent", asString2(response.file) ?? args.path ?? "")}`,
     args.removeName ? `${theme.fg("muted", "name")} ${args.removeName}` : `${theme.fg("muted", "scope")} entire import`
   ];
 }
 function renderImportCall(args, theme, context) {
   const summary = [
     theme.fg("accent", args.op),
-    accentPath(theme, args.filePath),
+    accentPath(theme, args.path ?? ""),
     args.module ? theme.fg("toolOutput", args.module) : undefined
   ].filter(Boolean).join(" ");
   return renderToolCall("import", summary, theme, context);
@@ -35451,7 +35872,7 @@ function renderImportResult(result, args, theme, context) {
 }
 function registerImportTools(pi, ctx) {
   const organizeRecovery = ctx.config.backup?.enabled === false ? "Backup capture is disabled by user config; review broad cleanup changes before proceeding." : "Use aft_safety checkpoint/undo before broad cleanup.";
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     name: "aft_import",
     label: "import",
     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\`. ${organizeRecovery}`,
@@ -35460,7 +35881,7 @@ function registerImportTools(pi, ctx) {
       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);
+      const filePath = await resolvePathArg(extCtx.cwd, params.path);
       await assertExternalDirectoryPermission(extCtx, filePath, {
         restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
       });
@@ -35498,7 +35919,7 @@ function registerImportTools(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderImportResult(result, context.args, theme, context);
     }
-  });
+  }));
 }
 
 // src/tools/inspect.ts
@@ -35574,7 +35995,7 @@ function diagnosticsSummaryPart(summary) {
   const counts = `${errors3 ?? 0} errors/${warnings ?? 0} warnings/${info ?? 0} info/${hints ?? 0} hints`;
   const status = asString2(section.status);
   if (status === "pending") {
-    return hasCounts ? `diagnostics ${counts} so far — still pending (servers: ${diagnosticsServerSummary(section)})` : `diagnostics pending (servers: ${diagnosticsServerSummary(section)})`;
+    return hasCounts ? `diagnostics ${counts} so far — still pending (servers: ${diagnosticsServerSummary(section)}); wait for the LSP update and use the next normal aft_inspect, not repeated polling` : `diagnostics pending (servers: ${diagnosticsServerSummary(section)}); wait for the LSP update and use the next normal aft_inspect, not repeated polling`;
   }
   if (status === "incomplete") {
     return hasCounts ? `diagnostics ${counts} (incomplete — servers: ${diagnosticsServerSummary(section)})` : `diagnostics unavailable (status incomplete; servers: ${diagnosticsServerSummary(section)})`;
@@ -35727,7 +36148,7 @@ function buildInspectSections(payload, theme) {
   ].filter((part) => Boolean(part));
   const sections = [theme.fg("accent", parts.join(" · "))];
   if (stale > 0 || pending > 0) {
-    sections.push(theme.fg("warning", `scanner state: ${stale} stale · ${pending} pending`));
+    sections.push(theme.fg("warning", `scanner state: ${stale} stale · ${pending} pending. Treat stale_categories/pending_categories as stale or incomplete cache state. AFT schedules a Tier-2 refresh after its next idle or inspect-triggered background run; use one later normal aft_inspect after that refresh, not a polling loop`));
   }
   const topPreview = tier2TopPreview(summary, theme);
   if (topPreview)
@@ -35803,7 +36224,7 @@ function navigateParamsSchema() {
     op: StringEnum3(["call_tree", "callers", "trace_to", "trace_to_symbol", "impact", "trace_data"], {
       description: "Navigation operation"
     }),
-    filePath: Type9.String({
+    path: Type9.String({
       description: "Source file containing the symbol (absolute or relative to project root)"
     }),
     symbol: Type9.String({ description: "Name of the symbol to analyze" }),
@@ -35812,7 +36233,7 @@ function navigateParamsSchema() {
     toSymbol: Type9.Optional(Type9.String({
       description: "Target symbol for trace_to_symbol; the returned path ends here"
     })),
-    toFile: Type9.Optional(Type9.String({
+    toPath: Type9.Optional(Type9.String({
       description: "Optional target file for trace_to_symbol; required when toSymbol exists in multiple files"
     })),
     includeTests: Type9.Optional(Type9.Boolean({
@@ -35834,7 +36255,7 @@ function buildNavigateSections(args, payload, theme) {
 function renderNavigateCall(args, theme, context) {
   const summary = [
     theme.fg("accent", args.op),
-    accentPath(theme, args.filePath),
+    accentPath(theme, args.path),
     theme.fg("toolOutput", args.symbol),
     args.toSymbol ? theme.fg("toolOutput", `→ ${args.toSymbol}`) : undefined
   ].filter(Boolean).join(" ");
@@ -35846,14 +36267,14 @@ function renderNavigateResult(result, args, theme, context) {
   return renderSections(buildNavigateSections(args, extractStructuredPayload(result), theme), context);
 }
 function registerNavigateTool(pi, ctx) {
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     name: "aft_callgraph",
     label: "callgraph",
-    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. Use aft_zoom with `callgraph:true` for one-level forward calls-out while reading source; use aft_callgraph only for reverse callers or multi-level traces so you do not double-fetch the same relationships. 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. Markers: ~ = edge resolved by name only (may point at the wrong same-named symbol); [unresolved] = callee not resolved to a definition, so the location shown is the call site. Unmarked edges are resolved exactly. By default, unresolved external/stdlib leaf calls in call_tree are collapsed into one summary per parent; pass includeUnresolved=true to show every unresolved edge individually.",
+    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. Use aft_zoom with `callgraph:true` for one-level forward calls-out while reading source; use aft_callgraph only for reverse callers or multi-level traces so you do not double-fetch the same relationships. All ops require both `path` 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 `toPath`), `trace_data` to follow a value across assignments/params. Markers: ~ = edge resolved by name only (may point at the wrong same-named symbol); [unresolved] = callee not resolved to a definition, so the location shown is the call site. Unmarked edges are resolved exactly. By default, unresolved external/stdlib leaf calls in call_tree are collapsed into one summary per parent; pass includeUnresolved=true to show every unresolved edge individually.",
     parameters: navigateParamsSchema(),
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      if (isEmptyParam(params.filePath)) {
-        throw new Error(`op='${params.op}' requires a \`filePath\``);
+      if (isEmptyParam(params.path)) {
+        throw new Error(`op='${params.op}' requires a \`path\``);
       }
       if (isEmptyParam(params.symbol)) {
         throw new Error(`op='${params.op}' requires a \`symbol\``);
@@ -35864,8 +36285,8 @@ function registerNavigateTool(pi, ctx) {
       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 filePath = await resolvePathArg(extCtx.cwd, params.path);
+      const toFile = !isEmptyParam(params.toPath) ? await resolvePathArg(extCtx.cwd, params.toPath) : undefined;
       const checked = new Set;
       for (const target of [filePath, ...toFile !== undefined ? [toFile] : []]) {
         if (checked.has(target))
@@ -35878,7 +36299,7 @@ function registerNavigateTool(pi, ctx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const rawArgs = {
         op: params.op,
-        filePath: params.filePath,
+        filePath: params.path,
         symbol: params.symbol
       };
       const depth = coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER);
@@ -35888,8 +36309,8 @@ function registerNavigateTool(pi, ctx) {
         rawArgs.expression = params.expression;
       if (!isEmptyParam(params.toSymbol))
         rawArgs.toSymbol = params.toSymbol;
-      if (!isEmptyParam(params.toFile))
-        rawArgs.toFile = params.toFile;
+      if (!isEmptyParam(params.toPath))
+        rawArgs.toFile = params.toPath;
       if (!isEmptyParam(params.includeTests))
         rawArgs.includeTests = coerceBoolean(params.includeTests);
       if (!isEmptyParam(params.includeUnresolved))
@@ -35914,7 +36335,7 @@ function registerNavigateTool(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderNavigateResult(result, context.args, theme, context);
     }
-  });
+  }));
 }
 
 // src/tools/reading.ts
@@ -35931,21 +36352,21 @@ var OutlineParams = Type10.Object({
   }))
 });
 var ZoomTarget = Type10.Object({
-  filePath: Type10.String({ description: "Path to file (absolute or project-relative)" }),
+  path: Type10.String({ description: "Path to file (absolute or project-relative)" }),
   symbol: Type10.String({ description: "Symbol name in that file" })
 });
 var ZoomParams = Type10.Object({
-  filePath: Type10.Optional(Type10.String({ description: "Path to file (absolute or project-relative)" })),
+  path: Type10.Optional(Type10.String({ description: "Path to file (absolute or project-relative)" })),
   url: Type10.Optional(Type10.String({
     description: "HTTP/HTTPS URL of an HTML or Markdown document to fetch and zoom into"
   })),
   symbols: Type10.Optional(Type10.Union([Type10.String(), Type10.Array(Type10.String())], {
-    description: "Symbol name for code, or heading text for Markdown/HTML. Pass a string for one lookup or an array for batched lookups in the same file/URL."
+    description: "Symbol name for code, or heading text for Markdown/HTML. Pass a string or array for batched lookups in the same file/URL."
   })),
   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."
+    description: "Cross-file batch: `{ path, symbol }` or an array of them. Mutually exclusive with path/url/symbols."
   })),
-  contextLines: Type10.Optional(Type10.Number({ description: "Lines of context before/after (default: 3)" })),
+  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER, "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."
   }))
@@ -35966,7 +36387,7 @@ async function assertReadPathPermissions(extCtx, ctx, paths) {
   }
 }
 function zoomTargetLabel(args) {
-  return args.filePath ?? args.url ?? "(no target)";
+  return args.path ?? args.url ?? "(no target)";
 }
 function zoomExtraCallSites(call) {
   const extraCount = call.extra_count;
@@ -36087,7 +36508,7 @@ function renderZoomResult(result, args, theme, context) {
 }
 function registerReadingTools(pi, ctx, surface) {
   if (surface.outline) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "aft_outline",
       label: "outline",
       description: `Structural outline of source code, documentation files, or remote URLs. For code, returns symbols (functions, classes, types) with line ranges. For Markdown and HTML, returns heading hierarchy. Use this to explore structure before reading specific sections with aft_zoom. Set \`files: true\` with a directory target for a flat indexed file tree with language, symbol count, and byte metadata.
@@ -36130,7 +36551,17 @@ Pass a single \`target\`:
         if (response.success === false) {
           throw new Error(response.text || response.message || "outline failed");
         }
-        return textResult(response.text, response);
+        let text = typeof response.text === "string" ? response.text : "";
+        const trimmed = text.trim();
+        if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+          try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.text === "string") {
+              text = parsed.text;
+            }
+          } catch {}
+        }
+        return textResult(text, response);
       },
       renderCall(args, theme, context) {
         return renderOutlineCall(args, theme, context);
@@ -36138,13 +36569,13 @@ Pass a single \`target\`:
       renderResult(result, _options, theme, context) {
         return renderOutlineResult(result, theme, context);
       }
-    });
+    }));
   }
   if (surface.zoom) {
-    pi.registerTool({
+    pi.registerTool(withPathAliasPreparation({
       name: "aft_zoom",
       label: "zoom",
-      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.",
+      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: `{ path, 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: `{ path, symbol }` or an array of them.",
       parameters: ZoomParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
@@ -36154,7 +36585,7 @@ Pass a single \`target\`:
           const entryEmpty = (entry) => {
             if (!entry || typeof entry !== "object")
               return true;
-            const fp = entry.filePath;
+            const fp = entry.path;
             const sym = entry.symbol;
             const fpEmpty = typeof fp !== "string" || fp.length === 0;
             const symEmpty = typeof sym !== "string" || sym.length === 0;
@@ -36164,31 +36595,33 @@ Pass a single \`target\`:
             return !t.every(entryEmpty);
           return !entryEmpty(t);
         };
-        const hasFilePath = !isEmptyParam(params.filePath);
+        const hasPath2 = !isEmptyParam(params.path);
         const hasUrl = !isEmptyParam(params.url);
         const hasTargets = hasTargetsProvided(params.targets);
         const hasSymbols = !isEmptyParam(params.symbols);
         const wantCallgraph = coerceBoolean(params.callgraph);
         const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
         if (hasTargets) {
-          if (hasFilePath || hasUrl || hasSymbols) {
-            throw new Error("'targets' is mutually exclusive with 'filePath', 'url', and 'symbols'");
+          if (hasPath2 || hasUrl || hasSymbols) {
+            throw new Error("'targets' is mutually exclusive with 'path', 'url', and 'symbols'");
           }
           const targets = Array.isArray(params.targets) ? params.targets : [params.targets];
           if (targets.length === 0) {
             throw new Error("'targets' must be a non-empty object or array");
           }
           for (const [i, entry] of targets.entries()) {
-            if (!entry || typeof entry.filePath !== "string" || entry.filePath.length === 0) {
-              throw new Error(`targets[${i}].filePath must be a non-empty string`);
+            if (!entry || typeof entry.path !== "string" || entry.path.length === 0) {
+              throw new Error(`targets[${i}].path must be a non-empty string`);
             }
             if (typeof entry.symbol !== "string" || entry.symbol.length === 0) {
               throw new Error(`targets[${i}].symbol must be a non-empty string`);
             }
           }
-          const resolvedTargets = await Promise.all(targets.map((t) => resolvePathArg(extCtx.cwd, t.filePath)));
+          const resolvedTargets = await Promise.all(targets.map((t) => resolvePathArg(extCtx.cwd, t.path)));
           await assertReadPathPermissions(extCtx, ctx, resolvedTargets);
-          const rawArgs2 = { targets };
+          const rawArgs2 = {
+            targets: targets.map((target) => ({ filePath: target.path, symbol: target.symbol }))
+          };
           if (contextLines !== undefined)
             rawArgs2.contextLines = contextLines;
           if (wantCallgraph)
@@ -36199,17 +36632,17 @@ Pass a single \`target\`:
           }
           return textResult(response2.text, response2);
         }
-        if (!hasFilePath && !hasUrl) {
-          throw new Error("Provide exactly one of 'filePath', 'url', or 'targets'");
+        if (!hasPath2 && !hasUrl) {
+          throw new Error("Provide exactly one of 'path', 'url', or 'targets'");
         }
-        if (hasFilePath && hasUrl) {
-          throw new Error("Provide exactly ONE of 'filePath' or 'url' — not both");
+        if (hasPath2 && hasUrl) {
+          throw new Error("Provide exactly ONE of 'path' or 'url' — not both");
         }
         if (!hasUrl) {
-          const file2 = await resolvePathArg(extCtx.cwd, params.filePath);
+          const file2 = await resolvePathArg(extCtx.cwd, params.path);
           await assertReadPathPermissions(extCtx, ctx, file2);
         }
-        const rawArgs = hasUrl ? { url: params.url } : { filePath: params.filePath };
+        const rawArgs = hasUrl ? { url: params.url } : { filePath: params.path };
         if (hasSymbols)
           rawArgs.symbols = params.symbols;
         if (contextLines !== undefined)
@@ -36228,7 +36661,7 @@ Pass a single \`target\`:
       renderResult(result, _options, theme, context) {
         return renderZoomResult(result, context.args, theme, context);
       }
-    });
+    }));
   }
 }
 
@@ -36237,7 +36670,7 @@ import { StringEnum as StringEnum4 } from "@earendil-works/pi-ai";
 import { Type as Type11 } from "typebox";
 var RefactorParams = Type11.Object({
   op: StringEnum4(["move", "extract", "inline"], { description: "Refactoring operation" }),
-  filePath: Type11.String({
+  path: Type11.String({
     description: "Source file (absolute or relative to project root)"
   }),
   symbol: Type11.Optional(Type11.String({ description: "Symbol name (for move, inline)" })),
@@ -36265,14 +36698,14 @@ function buildRefactorSections(args, payload, theme) {
   if (args.op === "extract") {
     return [
       `${theme.fg("success", "extracted")} ${theme.fg("toolOutput", asString2(response.name) ?? args.name ?? "(function)")}`,
-      `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath3(asString2(response.file) ?? args.filePath))}`,
+      `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath3(asString2(response.file) ?? args.path ?? ""))}`,
       `${theme.fg("muted", "params")} ${Array.isArray(response.parameters) ? response.parameters.join(", ") || "none" : "none"}`,
       `${theme.fg("muted", "return type")} ${asString2(response.return_type) ?? "unknown"}`
     ];
   }
   return [
     `${theme.fg("success", "inlined")} ${theme.fg("toolOutput", asString2(response.symbol) ?? args.symbol ?? "(symbol)")}`,
-    `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath3(asString2(response.file) ?? args.filePath))}`,
+    `${theme.fg("muted", "file")} ${theme.fg("accent", shortenPath3(asString2(response.file) ?? args.path ?? ""))}`,
     `${theme.fg("muted", "context")} ${asString2(response.call_context) ?? "unknown"}`,
     `${theme.fg("muted", "substitutions")} ${asNumber2(response.substitutions) ?? 0}`
   ];
@@ -36280,7 +36713,7 @@ function buildRefactorSections(args, payload, theme) {
 function renderRefactorCall(args, theme, context) {
   const summary = [
     theme.fg("accent", args.op),
-    accentPath(theme, args.filePath),
+    accentPath(theme, args.path),
     args.symbol ? theme.fg("toolOutput", args.symbol) : undefined
   ].filter(Boolean).join(" ");
   return renderToolCall("refactor", summary, theme, context);
@@ -36291,7 +36724,7 @@ function renderRefactorResult(result, args, theme, context) {
   return renderSections(buildRefactorSections(args, extractStructuredPayload(result), theme), context);
 }
 function registerRefactorTool(pi, ctx) {
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     name: "aft_refactor",
     label: "refactor",
     description: "Workspace-wide refactoring that updates imports and references across files. `move` relocates a top-level symbol (not nested functions or class methods) to another file, rewriting imports workspace-wide; a checkpoint is created first. To move/rename a whole file, use aft_move. `extract` pulls a line range into a new function (TS/JS/TSX, Python). `inline` replaces a call with the function's body.",
@@ -36318,7 +36751,7 @@ function registerRefactorTool(pi, ctx) {
       if (params.op === "inline" && callSiteLine === undefined) {
         throw new Error("'callSiteLine' is required for 'inline' op");
       }
-      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+      const filePath = await resolvePathArg(extCtx.cwd, params.path);
       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;
@@ -36358,7 +36791,7 @@ function registerRefactorTool(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderRefactorResult(result, context.args, theme, context);
     }
-  });
+  }));
 }
 
 // src/tools/safety.ts
@@ -36371,7 +36804,7 @@ var SafetyParams = Type12.Object({
   op: StringEnum5(["undo", "history", "checkpoint", "restore", "list"], {
     description: "Safety operation"
   }),
-  filePath: Type12.Optional(Type12.String({
+  path: Type12.Optional(Type12.String({
     description: "File path (required for history, optional for undo). Absolute or relative to project root."
   })),
   name: Type12.Optional(Type12.String({ description: "Checkpoint name (required for checkpoint, restore)" })),
@@ -36391,14 +36824,14 @@ function buildSafetySections(args, payload, theme) {
       ];
     }
     return [
-      `${theme.fg("success", "restored")} ${theme.fg("accent", shortenPath3(asString2(response.path) ?? args.filePath ?? "(file)"))}`,
+      `${theme.fg("success", "restored")} ${theme.fg("accent", shortenPath3(asString2(response.path) ?? args.path ?? "(file)"))}`,
       `${theme.fg("muted", "backup")} ${asString2(response.backup_id) ?? "—"}`
     ];
   }
   if (args.op === "history") {
     const entries = asRecords2(response.entries);
     const sections2 = [
-      theme.fg("accent", shortenPath3(asString2(response.file) ?? args.filePath ?? "(file)"))
+      theme.fg("accent", shortenPath3(asString2(response.file) ?? args.path ?? "(file)"))
     ];
     if (entries.length === 0) {
       sections2.push(theme.fg("muted", "No history entries."));
@@ -36448,7 +36881,7 @@ ${skipped.map((entry) => `  ↳ ${shortenPath3(asString2(entry.file) ?? "(file)"
   return sections;
 }
 function renderSafetyCall(args, theme, context) {
-  const target = args.filePath ?? args.name;
+  const target = args.path ?? args.name;
   const summary = [theme.fg("accent", args.op), target ? accentPath(theme, target) : undefined].filter(Boolean).join(" ");
   return renderToolCall("safety", summary, theme, context);
 }
@@ -36458,19 +36891,19 @@ function renderSafetyResult(result, args, theme, context) {
   return renderSections(buildSafetySections(args, extractStructuredPayload(result), theme), context);
 }
 function registerSafetyTool(pi, ctx) {
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     name: "aft_safety",
     label: "safety",
-    description: "File safety and recovery operations. Ops: `undo` (omit filePath to undo the entire last tool call; pass filePath to pop latest snapshot for one file — irreversible), `history` (list snapshots for a file), `checkpoint` (save named snapshot), `restore` (restore named checkpoint), `list` (list checkpoints). Per-file undo stack is capped at 20.",
+    description: "File safety and recovery operations. Ops: `undo` (omit path to undo the entire last tool call; pass path to pop latest snapshot for one file — irreversible), `history` (list snapshots for a file), `checkpoint` (save named snapshot), `restore` (restore named checkpoint), `list` (list checkpoints). Per-file undo stack is capped at 20.",
     parameters: SafetyParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      if (params.op === "history" && !params.filePath) {
-        throw new Error(`op='${params.op}' requires 'filePath'`);
+      if (params.op === "history" && !params.path) {
+        throw new Error(`op='${params.op}' requires 'path'`);
       }
       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 filePath = params.path ? await resolvePathArg(extCtx.cwd, params.path) : undefined;
       const fileInputs = coerceStringArray(params.files);
       const files = fileInputs.length > 0 ? await Promise.all(fileInputs.map((file2) => resolvePathArg(extCtx.cwd, file2))) : undefined;
       const bridge = bridgeFor(ctx, extCtx.cwd);
@@ -36527,7 +36960,7 @@ function registerSafetyTool(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderSafetyResult(result, context.args, theme, context);
     }
-  });
+  }));
 }
 
 // src/tools/semantic.ts
@@ -36554,14 +36987,6 @@ var SearchParams2 = Type13.Object({
     default: 10,
     description: "Maximum number of results (default: 10, max: 100)"
   })),
-  hint: Type13.Optional(Type13.Union([
-    Type13.Literal("regex"),
-    Type13.Literal("literal"),
-    Type13.Literal("semantic"),
-    Type13.Literal("auto")
-  ], {
-    description: "Optional routing hint. Defaults to 'auto'."
-  })),
   includeTests: Type13.Optional(Type13.Boolean({
     default: false,
     description: "Include test files (*.test.*, *_test.rs, __tests__/, …) plus test-support, fixture, mock, snapshot, and corpus files. Defaults to false."
@@ -36653,13 +37078,11 @@ function renderSemanticResult(result, args, theme, context) {
   return renderSections(buildSemanticSections(args, extractStructuredPayload(result), theme), context);
 }
 function registerSemanticTool(pi, ctx) {
-  pi.registerTool({
+  pi.registerTool(withPathAliasPreparation({
     name: "aft_search",
     label: "search",
     description: [
-      "Search code with one tool: concepts, identifiers, error strings, regex, literals, and filenames are auto-routed to the right engine and returned ranked. For conceptual 'how does X work' queries, phrase a full natural-language sentence — the semantic lane is NL-aware and matches intent against docstrings and comments ('how does the ORM build and execute a query', 'where is rate limiting handled'), not just keywords. Exact names, strings, and regex stay terse ('^export', 'Cargo.lock').",
-      "",
-      "Set hint to 'regex', 'literal', or 'semantic' to force a lane."
+      "Search code with one tool: concepts, identifiers, error strings, regex, literals, and filenames are auto-routed to the right engine and returned ranked. For conceptual 'how does X work' queries, phrase a full natural-language sentence — the semantic lane is NL-aware and matches intent against docstrings and comments ('how does the ORM build and execute a query', 'where is rate limiting handled'), not just keywords. Exact names, strings, and regex stay terse ('^export', 'Cargo.lock')."
     ].join(`
 `),
     parameters: SearchParams2,
@@ -36671,8 +37094,6 @@ function registerSemanticTool(pi, ctx) {
       const req = { query: params.query };
       if (params.topK !== undefined)
         req.topK = params.topK;
-      if (params.hint !== undefined)
-        req.hint = params.hint;
       if (params.includeTests !== undefined)
         req.includeTests = params.includeTests;
       if (params.path !== undefined)
@@ -36689,7 +37110,98 @@ function registerSemanticTool(pi, ctx) {
     renderResult(result, _options, theme, context) {
       return renderSemanticResult(result, context.args, theme, context);
     }
-  });
+  }));
+}
+
+// src/tool-registration.ts
+var ALL_ONLY_TOOLS = new Set(["aft_callgraph", "aft_delete", "aft_move", "aft_refactor"]);
+function resolvePiToolSurface(config2) {
+  const surface = config2.tool_surface ?? "recommended";
+  const disabled = new Set(config2.disabled_tools ?? []);
+  const ok = (name) => !disabled.has(name);
+  const allOnly = (name) => ALL_ONLY_TOOLS.has(name) && ok(name);
+  const restrictToProjectRoot = config2.restrict_to_project_root ?? false;
+  if (surface === "minimal") {
+    return {
+      hoistBash: ok("bash"),
+      hoistRead: false,
+      hoistWrite: false,
+      hoistEdit: false,
+      hoistGrep: false,
+      restrictToProjectRoot,
+      outline: ok("aft_outline"),
+      zoom: ok("aft_zoom"),
+      semantic: false,
+      inspect: false,
+      navigate: false,
+      conflicts: false,
+      importTool: false,
+      safety: ok("aft_safety"),
+      delete: false,
+      move: false,
+      astSearch: false,
+      astReplace: false,
+      refactor: false
+    };
+  }
+  const base = {
+    hoistBash: ok("bash"),
+    hoistRead: ok("read"),
+    hoistWrite: ok("write"),
+    hoistEdit: ok("edit"),
+    hoistGrep: ok("grep") && config2.search_index === true,
+    restrictToProjectRoot,
+    outline: ok("aft_outline"),
+    zoom: ok("aft_zoom"),
+    semantic: ok("aft_search") && config2.semantic_search === true,
+    inspect: ok("aft_inspect") && config2.inspect?.enabled !== false,
+    navigate: false,
+    conflicts: ok("aft_conflicts"),
+    importTool: ok("aft_import"),
+    safety: ok("aft_safety"),
+    delete: false,
+    move: false,
+    astSearch: ok("ast_grep_search"),
+    astReplace: ok("ast_grep_replace"),
+    refactor: false
+  };
+  if (surface === "all") {
+    return {
+      ...base,
+      navigate: allOnly("aft_callgraph"),
+      delete: allOnly("aft_delete"),
+      move: allOnly("aft_move"),
+      refactor: allOnly("aft_refactor")
+    };
+  }
+  return base;
+}
+function registerPiToolSurface(pi, ctx, surface) {
+  if (surface.hoistBash && resolveBashConfig(ctx.config).enabled) {
+    registerBashTool(pi, ctx, surface.semantic);
+  }
+  registerHoistedTools(pi, ctx, surface);
+  if (surface.outline || surface.zoom) {
+    registerReadingTools(pi, ctx, surface);
+  }
+  if (surface.semantic)
+    registerSemanticTool(pi, ctx);
+  if (surface.inspect)
+    registerInspectTool(pi, ctx);
+  if (surface.navigate)
+    registerNavigateTool(pi, ctx);
+  if (surface.conflicts)
+    registerConflictsTool(pi, ctx);
+  if (surface.importTool)
+    registerImportTools(pi, ctx);
+  if (surface.safety && ctx.config.backup?.enabled !== false)
+    registerSafetyTool(pi, ctx);
+  if (surface.astSearch || surface.astReplace)
+    registerAstTools(pi, ctx, surface);
+  if (surface.delete || surface.move)
+    registerFsTools(pi, ctx, surface);
+  if (surface.refactor)
+    registerRefactorTool(pi, ctx);
 }
 
 // src/workflow-hints.ts
@@ -36720,18 +37232,18 @@ function buildWorkflowHints(opts) {
   }
   if (hasOutline && hasZoom && (hasGrep || hasSearch)) {
     const searchName = hasSearch ? "aft_search" : grepName;
-    const locate = hasSearch ? '`aft_search` is the primary code-search tool: one call auto-routes concepts, identifiers, regex, error strings, and literals (pass `hint: "regex"`/`"literal"`/`"semantic"` to force a lane).' : `\`${grepName}\` (the tool — indexed and ranked) locates code.`;
+    const locate = hasSearch ? "`aft_search` is the primary code-search tool: one call auto-routes concepts, identifiers, regex, error strings, and literals." : `\`${grepName}\` (the tool — indexed and ranked) locates code.`;
     const readName = opts.hoistBuiltins ? "read" : "aft_read";
     sections.push([
       `**Code exploration**: ${locate} Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s). DO NOT run \`grep\`/\`rg\`/\`find\`/\`sed\`/\`cat\` through \`bash\` to locate or read code — the bash path is unindexed, unranked, serial, and routinely surfaces the wrong hit. Keep \`bash\` for shell facts (git state, file metadata, processes). Reflex translations:`,
       `- \`grep -rn "handleAuth" src/\` in bash → \`${searchName}({ query: "handleAuth" })\``,
       `- \`find . -name "*.ts" | xargs grep watcher\` in bash → \`${searchName}({ query: "watcher invalidation" })\` (concepts work too)`,
-      `- \`sed -n '100,160p' app.ts\` / \`cat app.ts\` in bash → \`${readName}({ filePath: "app.ts", startLine: 100, endLine: 160 })\``
+      `- \`sed -n '100,160p' app.ts\` / \`cat app.ts\` in bash → \`${readName}({ path: "app.ts", startLine: 100, endLine: 160 })\``
     ].join(`
 `));
   }
   if (hasInspect) {
-    sections.push("**Codebase health & diagnostics**: AFT does not surface compile/type errors automatically after edits — pull them with `aft_inspect`. Run it after a batch of edits and before you run tests or commit, when starting in unfamiliar code, or before a refactor/review. One call summarizes diagnostics (compile/type errors), TODOs, metrics, dead code, unused exports, and duplicates; pass `sections` for focused drill-down and `scope` to actively pull diagnostics for a specific file or directory. Its diagnostics are a fast checkpoint, not the authority — a clean `tsc` / `cargo check` / `pyright` run is the real gate. Treat `stale_categories` as a genuine stale-cache signal while an async Tier 2 refresh catches up.");
+    sections.push("**Codebase health & diagnostics**: AFT does not surface compile/type errors automatically after edits — pull them with `aft_inspect`. Run it after a batch of edits and before you run tests or commit, when starting in unfamiliar code, or before a refactor/review. One call summarizes diagnostics (compile/type errors), TODOs, metrics, dead code, unused exports, and duplicates; pass `sections` for focused drill-down and `scope` to actively pull diagnostics for a specific file or directory. Its diagnostics are a fast checkpoint, not the authority — a clean `tsc` / `cargo check` / `pyright` run is the real gate. Treat stale_categories/pending_categories as stale or incomplete cache state. AFT schedules a Tier-2 refresh after its next idle or inspect-triggered background run; use one later normal aft_inspect after that refresh, not a polling loop.");
     sections.push("**AFT status bar**: tool results may end with a one-line health bar `[AFT E<errors> W<warnings> | D<dead-code> U<unused-exports> C<clone/dup-groups> | T<todos>]` — an IDE-style glance that appears when a count changes. `E`/`W` are live LSP diagnostics for files touched this session (your universal compile-error signal across every language with an LSP). A `~` before `D` means the dead-code/unused/dup counts predate your latest edit — run `aft_inspect` for current numbers and detail. When `E>0`, you likely just introduced errors; investigate before moving on.");
   }
   if (hasNavigate) {
@@ -36851,14 +37363,13 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.48.0";
+var ANNOUNCEMENT_VERSION = "0.49.0";
 var ANNOUNCEMENT_FEATURES = [
-  "New (beta, off by default): an optional native sandbox for hoisted bash. Confines commands to your project and blocks reads of your credentials (~/.ssh, ~/.aws, cloud configs). Enable with sandbox.enabled in aft.jsonc — macOS and Linux; see docs/config.md for the platform matrix.",
-  "Fixed: Windows background bash tasks could report failed with no exit code after a detach/rebind — completion is now recorded reliably.",
-  "Fixed: search no longer rebuilds its index unnecessarily for repositories with grafted history."
+  "One unified tool surface: every tool now takes `path` (old spellings keep working), `edit` has one calling shape, and `occurrence` is 1-based. Fewer ways for models to get a call wrong; prompt caches re-warm once after this upgrade.",
+  "aft_search now routes queries itself — the hint parameter is gone, and searches that find no exact match are re-ranked by their terms instead of returning nothing.",
+  "Corporate and custom certificate authorities now work: HTTPS requests verify through the OS trust store (Keychain, Windows certificate store, SSL_CERT_FILE on Linux)."
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/DSa65w8wuf";
-var ALL_ONLY_TOOLS = new Set(["aft_callgraph", "aft_delete", "aft_move", "aft_refactor"]);
 var pendingEagerWarnings = new Map;
 function isConfigureWarning(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -36939,67 +37450,6 @@ async function handleConfigureWarningsForSession(context) {
     projectRoot: context.projectRoot
   }, combinedWarnings);
 }
-function resolveToolSurface(config2) {
-  const surface = config2.tool_surface ?? "recommended";
-  const disabled = new Set(config2.disabled_tools ?? []);
-  const ok = (name) => !disabled.has(name);
-  const allOnly = (name) => ALL_ONLY_TOOLS.has(name) && ok(name);
-  const restrictToProjectRoot = config2.restrict_to_project_root ?? false;
-  if (surface === "minimal") {
-    return {
-      hoistBash: ok("bash"),
-      hoistRead: false,
-      hoistWrite: false,
-      hoistEdit: false,
-      hoistGrep: false,
-      restrictToProjectRoot,
-      outline: ok("aft_outline"),
-      zoom: ok("aft_zoom"),
-      semantic: false,
-      inspect: false,
-      navigate: false,
-      conflicts: false,
-      importTool: false,
-      safety: ok("aft_safety"),
-      delete: false,
-      move: false,
-      astSearch: false,
-      astReplace: false,
-      refactor: false
-    };
-  }
-  const base = {
-    hoistBash: ok("bash"),
-    hoistRead: ok("read"),
-    hoistWrite: ok("write"),
-    hoistEdit: ok("edit"),
-    hoistGrep: ok("grep") && config2.search_index === true,
-    restrictToProjectRoot,
-    outline: ok("aft_outline"),
-    zoom: ok("aft_zoom"),
-    semantic: ok("aft_search") && config2.semantic_search === true,
-    inspect: ok("aft_inspect") && config2.inspect?.enabled !== false,
-    navigate: false,
-    conflicts: ok("aft_conflicts"),
-    importTool: ok("aft_import"),
-    safety: ok("aft_safety"),
-    delete: false,
-    move: false,
-    astSearch: ok("ast_grep_search"),
-    astReplace: ok("ast_grep_replace"),
-    refactor: false
-  };
-  if (surface === "all") {
-    return {
-      ...base,
-      navigate: allOnly("aft_callgraph"),
-      delete: allOnly("aft_delete"),
-      move: allOnly("aft_move"),
-      refactor: allOnly("aft_refactor")
-    };
-  }
-  return base;
-}
 async function src_default(pi) {
   const deliverConfigMigrationWarnings = (messages) => {
     for (const message of messages) {
@@ -37210,7 +37660,7 @@ ${lines}
     });
   }
   pool.setConfigureOverride("harness", "pi");
-  pool.setConfigureOverride("aft_search_registered", resolveToolSurface(config2).semantic);
+  pool.setConfigureOverride("aft_search_registered", resolvePiToolSurface(config2).semantic);
   const ctx = { pool, config: config2, storageDir };
   if (onnxRuntimePromise) {
     onnxRuntimePromise.then((ortDylibDir) => {
@@ -37249,41 +37699,8 @@ ${lines}
   if (ANNOUNCEMENT_VERSION && ANNOUNCEMENT_FEATURES.length > 0) {
     sendFeatureAnnouncement(ANNOUNCEMENT_VERSION, ANNOUNCEMENT_FEATURES, ANNOUNCEMENT_FOOTER, storageDir);
   }
-  const surface = resolveToolSurface(config2);
-  if (surface.hoistBash && resolveBashConfig(config2).enabled) {
-    registerBashTool(pi, ctx, surface.semantic);
-  }
-  registerHoistedTools(pi, ctx, surface);
-  if (surface.outline || surface.zoom) {
-    registerReadingTools(pi, ctx, surface);
-  }
-  if (surface.semantic) {
-    registerSemanticTool(pi, ctx);
-  }
-  if (surface.inspect) {
-    registerInspectTool(pi, ctx);
-  }
-  if (surface.navigate) {
-    registerNavigateTool(pi, ctx);
-  }
-  if (surface.conflicts) {
-    registerConflictsTool(pi, ctx);
-  }
-  if (surface.importTool) {
-    registerImportTools(pi, ctx);
-  }
-  if (surface.safety && config2.backup?.enabled !== false) {
-    registerSafetyTool(pi, ctx);
-  }
-  if (surface.astSearch || surface.astReplace) {
-    registerAstTools(pi, ctx, surface);
-  }
-  if (surface.delete || surface.move) {
-    registerFsTools(pi, ctx, surface);
-  }
-  if (surface.refactor) {
-    registerRefactorTool(pi, ctx);
-  }
+  const surface = resolvePiToolSurface(config2);
+  registerPiToolSurface(pi, ctx, surface);
   registerWorkflowHints(pi, config2, surface);
   registerStatusCommand(pi, ctx);
   pi.on("tool_result", async (event, extCtx) => {
@@ -37349,7 +37766,7 @@ ${lines}
 var __test__2 = {
   enqueueConfigParseWarnings,
   bridgeDirectoryFromCallback,
-  resolveToolSurface,
+  resolveToolSurface: resolvePiToolSurface,
   handleConfigureWarningsForSession,
   shouldPrepareOnnxRuntime,
   createVersionMismatchHandler