@cortexkit/aft-pi 0.36.1 → 0.37.1

package/dist/index.js

@@ -11678,6 +11678,9 @@ function error(message, meta) {
 var CONFLICT_HINT = `
 
 [Hint] Use aft_conflicts to see all conflict regions across files in a single call.`;
+var GREP_SEARCH_AFT_SEARCH_HINT = "DO NOT search code by running grep/rg in bash — it is unindexed, unranked, and serial. Use the `aft_search` tool instead (it auto-routes concepts, identifiers, regex, and literals).";
+var GREP_SEARCH_GREP_HINT = "DO NOT search code by running grep/rg in bash — it is unindexed, unranked, and serial. Use the `grep` tool instead (indexed and ranked).";
+var GREP_SEARCH_HINT_PREFIX = "DO NOT search code by running grep/rg in bash —";
 function maybeAppendConflictsHint(output) {
   if (!output.includes("Automatic merge failed; fix conflicts"))
     return output;
@@ -11685,6 +11688,146 @@ function maybeAppendConflictsHint(output) {
     return output;
   return output + CONFLICT_HINT;
 }
+function commandLeadsWithCodeSearch(command) {
+  const trimmed = command.trim();
+  if (!trimmed)
+    return false;
+  const afterCd = peelLeadingCdAnd(trimmed);
+  if (afterCd === null)
+    return false;
+  const firstStage = firstPipelineStage(afterCd);
+  if (firstStage === null)
+    return false;
+  const firstToken = readShellToken(firstStage, skipSpaces(firstStage, 0));
+  if (firstToken === null)
+    return false;
+  return firstToken.token === "grep" || firstToken.token === "rg";
+}
+function maybeAppendGrepSearchHint(output, command, aftSearchRegistered) {
+  if (output === "")
+    return output;
+  if (!commandLeadsWithCodeSearch(command))
+    return output;
+  if (output.includes(GREP_SEARCH_HINT_PREFIX))
+    return output;
+  const hint = aftSearchRegistered ? GREP_SEARCH_AFT_SEARCH_HINT : GREP_SEARCH_GREP_HINT;
+  return `${output}
+
+${hint}`;
+}
+function peelLeadingCdAnd(command) {
+  const first = readShellToken(command, skipSpaces(command, 0));
+  if (first === null)
+    return null;
+  if (first.token !== "cd")
+    return command;
+  const dir = readShellToken(command, skipSpaces(command, first.end));
+  if (dir === null)
+    return null;
+  if (!dir.token)
+    return command;
+  const afterDir = skipSpaces(command, dir.end);
+  if (!command.startsWith("&&", afterDir))
+    return command;
+  return command.slice(afterDir + 2).trim();
+}
+function firstPipelineStage(command) {
+  let quote = "none";
+  let firstPipeIndex;
+  for (let index = 0;index < command.length; index++) {
+    const ch = command[index];
+    if (quote === "single") {
+      if (ch === "'")
+        quote = "none";
+      continue;
+    }
+    if (quote === "double") {
+      if (ch === '"') {
+        quote = "none";
+      } else if (ch === "\\") {
+        index++;
+      } else if (ch === "`") {
+        return null;
+      }
+      continue;
+    }
+    if (ch === "'") {
+      quote = "single";
+    } else if (ch === '"') {
+      quote = "double";
+    } else if (ch === "\\") {
+      index++;
+    } else if (ch === "`") {
+      return null;
+    } else if (ch === "|") {
+      if (command[index + 1] === "|") {
+        index++;
+      } else if (firstPipeIndex === undefined) {
+        firstPipeIndex = index;
+      }
+    }
+  }
+  if (quote !== "none")
+    return null;
+  return command.slice(0, firstPipeIndex ?? command.length).trim();
+}
+function readShellToken(command, start) {
+  let quote = "none";
+  let token = "";
+  let index = start;
+  for (;index < command.length; index++) {
+    const ch = command[index];
+    if (quote === "single") {
+      if (ch === "'") {
+        quote = "none";
+      } else {
+        token += ch;
+      }
+      continue;
+    }
+    if (quote === "double") {
+      if (ch === '"') {
+        quote = "none";
+      } else if (ch === "\\") {
+        index++;
+        token += command[index] ?? "\\";
+      } else if (ch === "`") {
+        return null;
+      } else {
+        token += ch;
+      }
+      continue;
+    }
+    if (/\s/.test(ch))
+      break;
+    if (isTokenBoundary(ch))
+      break;
+    if (ch === "'") {
+      quote = "single";
+    } else if (ch === '"') {
+      quote = "double";
+    } else if (ch === "\\") {
+      index++;
+      token += command[index] ?? "\\";
+    } else if (ch === "`") {
+      return null;
+    } else {
+      token += ch;
+    }
+  }
+  if (quote !== "none")
+    return null;
+  return { token, end: index };
+}
+function isTokenBoundary(ch) {
+  return ch === "|" || ch === ";" || ch === "&" || ch === "<" || ch === ">";
+}
+function skipSpaces(input, start) {
+  let index = start;
+  while (index < input.length && /\s/.test(input[index]))
+    index++;
+  return index;
+}
 // ../aft-bridge/dist/bash-timeout.js
 function resolveBashKillTimeout(modelTimeout, foregroundWaitMs) {
   if (modelTimeout !== undefined && modelTimeout >= foregroundWaitMs) {
@@ -11698,6 +11841,21 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 
+// ../aft-bridge/dist/command-timeouts.js
+var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
+  callers: 60000,
+  trace_to: 60000,
+  trace_to_symbol: 60000,
+  trace_data: 60000,
+  impact: 60000,
+  grep: 60000,
+  glob: 60000,
+  semantic_search: 60000
+};
+function timeoutForCommand(command) {
+  return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
+}
+
 // ../aft-bridge/dist/status-bar.js
 var STATUS_BAR_HEARTBEAT_CALLS = 15;
 function createStatusBarEmitState() {
@@ -11745,6 +11903,27 @@ var DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
 var BRIDGE_HANG_TIMEOUT_THRESHOLD = 2;
 var SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS = 5000;
 var MAX_STDOUT_BUFFER = 64 * 1024 * 1024;
+var STDOUT_BUFFER_COMPACT_THRESHOLD = 64 * 1024;
+var TERMINAL_BASH_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "timed_out",
+  "cancelled",
+  "timeout"
+]);
+function isTerminalBashStatus(status) {
+  return typeof status === "string" && TERMINAL_BASH_STATUSES.has(status);
+}
+function bashTaskIdFrom(response) {
+  const snakeCase = response.task_id;
+  if (typeof snakeCase === "string" && snakeCase.length > 0)
+    return snakeCase;
+  const camelCase = response.taskId;
+  if (typeof camelCase === "string" && camelCase.length > 0)
+    return camelCase;
+  return;
+}
 function tagStderrLine(line) {
   return /^\[aft(-\w+)?\] /.test(line) ? line : `[aft] ${line}`;
 }
@@ -11799,11 +11978,12 @@ function clampSemanticTimeout(configOverrides, bridgeTimeoutMs) {
   if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
     return configOverrides;
   }
-  const maxSemanticTimeoutMs = bridgeTimeoutMs > SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS ? bridgeTimeoutMs - SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS : Math.max(1, bridgeTimeoutMs - 1);
+  const semanticTransportBudgetMs = Math.max(bridgeTimeoutMs, LONG_RUNNING_COMMAND_TIMEOUT_MS.semantic_search ?? 0);
+  const maxSemanticTimeoutMs = semanticTransportBudgetMs > SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS ? semanticTransportBudgetMs - SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS : Math.max(1, semanticTransportBudgetMs - 1);
   if (timeoutMs <= maxSemanticTimeoutMs) {
     return configOverrides;
   }
-  warn(`semantic.timeout_ms=${timeoutMs} exceeds bridge timeout budget; clamping to ${maxSemanticTimeoutMs}ms (bridge timeout: ${bridgeTimeoutMs}ms)`);
+  warn(`semantic.timeout_ms=${timeoutMs} exceeds the semantic transport budget; clamping to ${maxSemanticTimeoutMs}ms (budget: ${semanticTransportBudgetMs}ms)`);
   return {
     ...configOverrides,
     semantic: {
@@ -11829,8 +12009,10 @@ class BinaryBridge {
   cwd;
   process = null;
   pending = new Map;
+  outstandingBackgroundTaskIds = new Set;
   nextId = 1;
   stdoutBuffer = "";
+  stdoutReadOffset = 0;
   stderrBuffer = "";
   stderrTail = [];
   _restartCount = 0;
@@ -11940,6 +12122,9 @@ class BinaryBridge {
   hasPendingRequests() {
     return this.pending.size > 0;
   }
+  hasOutstandingBackgroundTasks() {
+    return this.outstandingBackgroundTaskIds.size > 0;
+  }
   getCwd() {
     return this.cwd;
   }
@@ -12061,7 +12246,7 @@ class BinaryBridge {
           entry.reject(new Error(`${this.errorPrefix} Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`));
           this.handleTimeout(requestSessionId);
         }, effectiveTimeoutMs);
-        this.pending.set(id, { resolve, reject, timer, onProgress: options?.onProgress });
+        this.pending.set(id, { resolve, reject, timer, onProgress: options?.onProgress, command });
         if (!this.process?.stdin?.writable) {
           this.pending.delete(id);
           clearTimeout(timer);
@@ -12322,6 +12507,7 @@ class BinaryBridge {
     });
     this.process = child;
     this.stdoutBuffer = "";
+    this.stdoutReadOffset = 0;
     this.stderrBuffer = "";
     this.lastChildActivityAt = 0;
     this.consecutiveRequestTimeouts = 0;
@@ -12366,24 +12552,41 @@ class BinaryBridge {
   ${tail}`;
   }
   onStdoutData(data) {
+    if (this.stdoutReadOffset > STDOUT_BUFFER_COMPACT_THRESHOLD) {
+      this.compactStdoutBuffer();
+    }
     this.stdoutBuffer += data;
-    if (this.stdoutBuffer.length > MAX_STDOUT_BUFFER) {
+    if (this.stdoutBuffer.length - this.stdoutReadOffset > MAX_STDOUT_BUFFER) {
       this.handleCrash(new Error(`aft bridge stdout buffer exceeded ${MAX_STDOUT_BUFFER} bytes — killing bridge`));
       return;
     }
     let newlineIdx;
     while ((newlineIdx = this.stdoutBuffer.indexOf(`
-`)) !== -1) {
-      const line = this.stdoutBuffer.slice(0, newlineIdx).trim();
-      this.stdoutBuffer = this.stdoutBuffer.slice(newlineIdx + 1);
-      if (!line)
-        continue;
-      this.processStdoutLine(line);
+`, this.stdoutReadOffset)) !== -1) {
+      const line = this.stdoutBuffer.slice(this.stdoutReadOffset, newlineIdx).trim();
+      this.stdoutReadOffset = newlineIdx + 1;
+      if (line) {
+        this.processStdoutLine(line);
+      }
+      if (this.stdoutReadOffset > STDOUT_BUFFER_COMPACT_THRESHOLD && this.stdoutReadOffset > this.stdoutBuffer.length / 2) {
+        this.compactStdoutBuffer();
+      }
     }
+    if (this.stdoutReadOffset === this.stdoutBuffer.length) {
+      this.stdoutBuffer = "";
+      this.stdoutReadOffset = 0;
+    }
+  }
+  compactStdoutBuffer() {
+    if (this.stdoutReadOffset === 0)
+      return;
+    this.stdoutBuffer = this.stdoutBuffer.slice(this.stdoutReadOffset);
+    this.stdoutReadOffset = 0;
   }
   flushStdoutBuffer() {
-    const line = this.stdoutBuffer.trim();
+    const line = this.stdoutBuffer.slice(this.stdoutReadOffset).trim();
     this.stdoutBuffer = "";
+    this.stdoutReadOffset = 0;
     if (!line)
       return;
     this.processStdoutLine(line);
@@ -12416,6 +12619,9 @@ class BinaryBridge {
         return;
       }
       if (response.type === "bash_completed") {
+        const taskId = bashTaskIdFrom(response);
+        if (taskId)
+          this.outstandingBackgroundTaskIds.delete(taskId);
         this.onBashCompletion?.(response, this);
         return;
       }
@@ -12446,6 +12652,7 @@ class BinaryBridge {
         clearTimeout(entry.timer);
         this.consecutiveRequestTimeouts = 0;
         this.scheduleRestartCountReset();
+        this.accountForBashTaskResponse(entry.command, response);
         this.captureStatusBar(response);
         entry.resolve(response);
       } else if (typeof response.type === "string") {
@@ -12455,6 +12662,18 @@ class BinaryBridge {
       this.warnVia(`Failed to parse stdout line: ${line}`);
     }
   }
+  accountForBashTaskResponse(command, response) {
+    const taskId = bashTaskIdFrom(response);
+    if (!taskId)
+      return;
+    if (isTerminalBashStatus(response.status)) {
+      this.outstandingBackgroundTaskIds.delete(taskId);
+      return;
+    }
+    if (command === "bash" && response.success !== false) {
+      this.outstandingBackgroundTaskIds.add(taskId);
+    }
+  }
   captureStatusBar(response) {
     const parsed = parseStatusBarCounts(response.status_bar);
     if (parsed)
@@ -12466,6 +12685,7 @@ class BinaryBridge {
   handleTimeout(triggeringSessionId) {
     this.consecutiveRequestTimeouts = 0;
     this.rejectAllPending(new Error(`${this.errorPrefix} bridge killed during sibling timeout — request aborted`));
+    this.outstandingBackgroundTaskIds.clear();
     if (this.process) {
       this.process.kill("SIGKILL");
       this.process = null;
@@ -12495,6 +12715,7 @@ class BinaryBridge {
     }
     this.clearRestartResetTimer();
     this.configured = false;
+    this.outstandingBackgroundTaskIds.clear();
     const tail = this.formatStderrTail();
     if (tail) {
       this.errorVia(`Binary crashed (restarts: ${this._restartCount})${cause ? `: ${cause.message}` : ""}.${tail}`);
@@ -14220,14 +14441,27 @@ function isCompressorHandledRunner(stage) {
   if (tokens.some((token) => token === "&&" || token === "||" || token.includes(";"))) {
     return false;
   }
-  const first = runnerName(tokens[0]);
-  const second = tokens[1];
-  const third = tokens[2];
-  const rest = tokens.slice(1);
+  let tokenOffset = 0;
+  while (tokenOffset < tokens.length && isEnvAssignment(tokens[tokenOffset])) {
+    tokenOffset++;
+  }
+  const first = runnerName(tokens[tokenOffset]);
+  const runnerArgs = tokens.slice(tokenOffset + 1);
+  const second = runnerArgs[0];
+  const third = runnerArgs[1];
+  const rest = runnerArgs;
   if (!first)
     return false;
-  if (first === "bun")
-    return second === "test" || second === "run" && startsWithTest(third);
+  if (first === "bun") {
+    let args = rest;
+    if (args[0] === "--cwd")
+      args = args.slice(2);
+    else if (args[0]?.startsWith("--cwd="))
+      args = args.slice(1);
+    const sub = args[0];
+    const subNext = args[1];
+    return sub === "test" || sub === "run" && startsWithTest(subNext);
+  }
   if (first === "npm" || first === "pnpm") {
     return second === "test" || second === "run" && startsWithTest(third);
   }
@@ -14250,14 +14484,20 @@ function isCompressorHandledRunner(stage) {
     return hasBuildTask(rest, ["test", "check", "build", "assemble", "clean"]);
   }
   if (first === "mvn" || first === "mvnw") {
-    return hasBuildTask(rest, ["test", "verify", "package", "install"]);
+    return hasBuildTask(rest, ["test", "verify", "package", "install", "clean"]);
   }
   if (first === "dotnet")
     return ["test", "build"].includes(second ?? "");
   if (first === "rspec")
     return true;
-  if (first === "rake")
-    return second === "test" || second === "spec";
+  if (first === "rake") {
+    const positionals = rest.filter((a) => !a.startsWith("-"));
+    if (positionals.length === 0)
+      return false;
+    if (positionals.some((a) => a.includes("/") || a.includes(".") || a.includes("=")))
+      return false;
+    return positionals.some((a) => a === "test" || a === "spec");
+  }
   if (first === "phpunit" || first === "pest")
     return true;
   if (first === "xcodebuild")
@@ -14280,6 +14520,11 @@ function isCompressorHandledRunner(stage) {
     "nox"
   ].includes(first);
 }
+function isEnvAssignment(token) {
+  if (!token)
+    return false;
+  return /^[a-zA-Z_][a-zA-Z0-9_]*=/.test(token);
+}
 function runnerName(token) {
   if (!token)
     return "";
@@ -14536,7 +14781,7 @@ function tokenizeStage(stage) {
 // ../aft-bridge/dist/pool.js
 import { realpathSync as realpathSync2 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
-var DEFAULT_IDLE_TIMEOUT_MS = Infinity;
+var DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 var DEFAULT_MAX_POOL_SIZE = 8;
 var CLEANUP_INTERVAL_MS = 60 * 1000;
 function canonicalHomeDir() {
@@ -14631,7 +14876,7 @@ class BridgePool {
   cleanup() {
     const now = Date.now();
     for (const [dir, entry] of this.bridges) {
-      if (entry.bridge.hasPendingRequests())
+      if (entry.bridge.hasPendingRequests() || entry.bridge.hasOutstandingBackgroundTasks())
         continue;
       if (now - entry.lastUsed > this.idleTimeoutMs) {
         entry.bridge.shutdown().catch((err) => this.error("cleanup shutdown failed:", err));
@@ -14639,7 +14884,7 @@ class BridgePool {
       }
     }
     for (const bridge of this.staleBridges) {
-      if (bridge.hasPendingRequests())
+      if (bridge.hasPendingRequests() || bridge.hasOutstandingBackgroundTasks())
         continue;
       bridge.shutdown().catch((err) => this.error("stale cleanup shutdown failed:", err));
       this.staleBridges.delete(bridge);
@@ -14649,7 +14894,7 @@ class BridgePool {
     let oldestDir = null;
     let oldestTime = Infinity;
     for (const [dir, entry] of this.bridges) {
-      if (entry.bridge.hasPendingRequests())
+      if (entry.bridge.hasPendingRequests() || entry.bridge.hasOutstandingBackgroundTasks())
         continue;
       if (entry.lastUsed < oldestTime) {
         oldestTime = entry.lastUsed;
@@ -15455,7 +15700,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.36.1",
+  version: "0.37.1",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -15478,7 +15723,7 @@ var package_default = {
     "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.36.1",
+    "@cortexkit/aft-bridge": "0.37.1",
     "@xterm/headless": "^5.5.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
@@ -15486,12 +15731,12 @@ var package_default = {
     zod: "^4.1.8"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.36.1",
-    "@cortexkit/aft-darwin-x64": "0.36.1",
-    "@cortexkit/aft-linux-arm64": "0.36.1",
-    "@cortexkit/aft-linux-x64": "0.36.1",
-    "@cortexkit/aft-win32-arm64": "0.36.1",
-    "@cortexkit/aft-win32-x64": "0.36.1"
+    "@cortexkit/aft-darwin-arm64": "0.37.1",
+    "@cortexkit/aft-darwin-x64": "0.37.1",
+    "@cortexkit/aft-linux-arm64": "0.37.1",
+    "@cortexkit/aft-linux-x64": "0.37.1",
+    "@cortexkit/aft-win32-arm64": "0.37.1",
+    "@cortexkit/aft-win32-x64": "0.37.1"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "*",
@@ -15749,19 +15994,6 @@ function isEmptyParam(value) {
     return Object.keys(value).length === 0;
   return false;
 }
-var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
-  callers: 60000,
-  trace_to: 60000,
-  trace_to_symbol: 60000,
-  trace_data: 60000,
-  impact: 60000,
-  grep: 60000,
-  glob: 60000,
-  semantic_search: 60000
-};
-function timeoutForCommand(command) {
-  return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
-}
 function asPlainObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return;
@@ -32282,6 +32514,21 @@ function registerShutdownCleanup(fn) {
   };
 }
 
+// src/sync-watch-abort.ts
+var abortFlags = new Map;
+function signalSyncWatchAbort(sessionID) {
+  const key = sessionID || "__default__";
+  abortFlags.set(key, true);
+}
+function clearSyncWatchAbort(sessionID) {
+  const key = sessionID || "__default__";
+  abortFlags.delete(key);
+}
+function isSyncWatchAborted(sessionID) {
+  const key = sessionID || "__default__";
+  return abortFlags.get(key) === true;
+}
+
 // src/tools/ast.ts
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type as Type3 } from "typebox";
@@ -32399,7 +32646,6 @@ function formatDiffForPi(oldContent, newContent, contextLines = DEFAULT_CONTEXT_
 }
 
 // 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;
 }
@@ -32469,8 +32715,7 @@ var WriteParams = Type2.Object({
   filePath: Type2.String({
     description: "Path to the file to write (absolute or relative to project root)"
   }),
-  content: Type2.String({ description: "Full file contents to write" }),
-  diagnostics: Type2.Optional(Type2.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
+  content: Type2.String({ description: "Full file contents to write" })
 });
 var EditParams = Type2.Object({
   filePath: Type2.String({
@@ -32482,8 +32727,7 @@ var EditParams = Type2.Object({
   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 }))
+  }))
 });
 var GrepParams = Type2.Object({
   pattern: Type2.String({ description: "Regex pattern to search for" }),
@@ -32491,8 +32735,7 @@ var GrepParams = Type2.Object({
     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)
+  caseSensitive: Type2.Optional(Type2.Boolean({ description: "Case-sensitive matching" }))
 });
 function registerHoistedTools(pi, ctx, surface) {
   if (surface.hoistRead) {
@@ -32507,7 +32750,9 @@ function registerHoistedTools(pi, ctx, surface) {
         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 };
+        const req = {
+          file: await resolvePathArg(extCtx.cwd, params.path)
+        };
         if (offset !== undefined) {
           req.start_line = offset;
           if (limit !== undefined) {
@@ -32534,19 +32779,20 @@ function registerHoistedTools(pi, ctx, surface) {
     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)",
+      description: "Write content to a file, creating it and parent directories automatically. Existing files are backed up before overwriting (undo via aft_safety) and auto-formatted 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)",
       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", {
+        const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+        await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
           restrictToProjectRoot: surface.restrictToProjectRoot
         });
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const response = await callBridge(bridge, "write", {
-          file: params.filePath,
+          file: filePath,
           content: params.content,
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          diagnostics: diagnosticsOnEditDefault(ctx),
           include_diff_content: true
         }, extCtx);
         return buildMutationResult(response);
@@ -32563,8 +32809,8 @@ function registerHoistedTools(pi, ctx, surface) {
     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.",
+      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`.",
+      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).",
       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.",
@@ -32572,26 +32818,27 @@ function registerHoistedTools(pi, ctx, surface) {
       ],
       parameters: EditParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
+        const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+        await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
           restrictToProjectRoot: surface.restrictToProjectRoot
         });
         const bridge = bridgeFor(ctx, extCtx.cwd);
         if (typeof params.appendContent === "string") {
           const req2 = {
             op: "append",
-            file: params.filePath,
+            file: filePath,
             append_content: params.appendContent,
-            diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+            diagnostics: diagnosticsOnEditDefault(ctx),
             include_diff_content: true
           };
           const response2 = await callBridge(bridge, "edit_match", req2, extCtx);
           return buildMutationResult(response2);
         }
         const req = {
-          file: params.filePath,
+          file: filePath,
           match: params.oldString ?? "",
           replacement: params.newString ?? "",
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          diagnostics: diagnosticsOnEditDefault(ctx),
           include_diff_content: true
         };
         if (params.replaceAll === true)
@@ -32631,9 +32878,6 @@ function registerHoistedTools(pi, ctx, surface) {
           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);
@@ -33194,7 +33438,7 @@ function registerAstTools(pi, ctx, surface) {
         if (!isEmptyParam(params.globs))
           req.globs = params.globs;
         if (params.contextLines !== undefined)
-          req.context_lines = params.contextLines;
+          req.context = params.contextLines;
         const response = await callBridge(bridge, "ast_search", req, extCtx);
         return textResult(response.text ?? JSON.stringify(response));
       },
@@ -33348,22 +33592,28 @@ function getBashSpawnHook(pi) {
   }
   return api2.hooks?.bashSpawn;
 }
-function registerBashTool(pi, ctx) {
+function registerBashTool(pi, ctx, aftSearchRegistered = false) {
   const spawnHook = getBashSpawnHook(pi);
+  const searchSteer = aftSearchRegistered ? "use `aft_search` (concepts, identifiers, regex, literals), `read`, `aft_outline`, or `aft_zoom` instead" : "use the `grep` tool, `read`, `aft_outline`, or `aft_zoom` instead";
+  const bashCfg = resolveBashConfig(ctx.config);
+  const compressionSentence = bashCfg.compress ? " Output is compressed by default; pass `compressed: false` for raw output." : "";
+  const tasksSentence = bashCfg.background ? ' Pass `background: true` to run in the background and get a task_id for `bash_status`/`bash_kill`. Pass `pty: true` for interactive programs (REPLs, TUIs) and drive them with `bash_status({ output_mode: "screen" })` plus `bash_write`.' : " Commands that outlive the foreground wait window are promoted to background tasks; inspect them with `bash_status({ task_id })` or terminate with `bash_kill`.";
   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`.',
+    description: `Execute shell commands.${compressionSentence}${tasksSentence}
+
+DO NOT use bash for code search or code exploration. If you are about to run grep, rg, sed, awk, find, or cat through bash to locate or read code: STOP — ${searchSteer}.`,
     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.",
+      `DO NOT use bash for code search or exploration — ${searchSteer}.`,
       "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 bashCfg = resolveBashConfig(ctx.config);
-      const foregroundWaitMs = resolveForegroundWaitMs(bashCfg.foreground_wait_window_ms);
+      const bashCfg2 = resolveBashConfig(ctx.config);
+      const foregroundWaitMs = resolveForegroundWaitMs(bashCfg2.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);
@@ -33380,7 +33630,7 @@ function registerBashTool(pi, ctx) {
           throw new Error(`BashSpawnHook failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
         }
       }
-      const compressionEnabled = bashCfg.compress && params.compressed !== false;
+      const compressionEnabled = bashCfg2.compress && params.compressed !== false;
       const pipeStrip = maybeStripCompressorPipe(spawnContext.command, compressionEnabled);
       const bridgeCommand = pipeStrip.command;
       let streamed = "";
@@ -33425,7 +33675,7 @@ function registerBashTool(pi, ctx) {
             throw new Error(status.message ?? "bash_status failed");
           }
           if (isTerminalStatus(status.status)) {
-            return bashResult(appendPipeStripNote(withBashHints(formatForegroundResult(status)), pipeStrip.note), {
+            return bashResult(appendPipeStripNote(withBashHints(formatForegroundResult(status), bridgeCommand, aftSearchRegistered), pipeStrip.note), {
               exit_code: status.exit_code,
               duration_ms: status.duration_ms,
               truncated: status.output_truncated,
@@ -33452,7 +33702,7 @@ function registerBashTool(pi, ctx) {
         task_id: taskId
       };
       const output = response.output ?? "";
-      return bashResult(appendPipeStripNote(withBashHints(output), pipeStrip.note), details);
+      return bashResult(appendPipeStripNote(withBashHints(output, bridgeCommand, aftSearchRegistered), pipeStrip.note), details);
     },
     renderCall(args, theme, context) {
       return renderBashCall(args?.command, args?.description, theme, context);
@@ -33484,8 +33734,8 @@ function formatPromotionMessage(taskId, timeout, waitWindowMs) {
 function formatSeconds(ms) {
   return `${Number((ms / 1000).toFixed(1))}s`;
 }
-function withBashHints(output) {
-  return maybeAppendConflictsHint(output);
+function withBashHints(output, command, aftSearchRegistered) {
+  return maybeAppendGrepSearchHint(maybeAppendConflictsHint(output), command, aftSearchRegistered);
 }
 function formatForegroundResult(data) {
   const output = data.output_preview ?? "";
@@ -33567,11 +33817,41 @@ function createBashWatchTool(ctx) {
 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));
+      if (data.waited?.reason === "user_message") {
+        const convertedText = await convertToAsyncWatchOnAbort(bridge, extCtx, params.task_id, waitFor, params.once !== false);
+        return textResult(convertedText, { waited: data.waited });
+      }
       const text = await formatBashStatus(extCtx, params.task_id, data, undefined);
       return textResult(text, data);
     }
   };
 }
+async function convertToAsyncWatchOnAbort(bridge, extCtx, taskId, waitFor, once) {
+  if (!waitFor) {
+    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits; don't poll bash_status.`;
+  }
+  const notifyParams = {
+    task_id: taskId,
+    once
+  };
+  if (waitFor.kind === "regex")
+    notifyParams.regex = waitFor.source;
+  else
+    notifyParams.pattern = waitFor.value;
+  const sessionId = resolveSessionId(extCtx);
+  markExplicitControl(sessionId, taskId, false);
+  try {
+    const registered = await callBashBridge(bridge, "bash_notify", notifyParams, extCtx);
+    if (registered.success === false) {
+      unmarkExplicitControl(sessionId, taskId);
+      return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `Auto-registering an async watch failed (${String(registered.message ?? "unknown error")}). ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits.`;
+    }
+    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `The wait has been converted to an async watch (${registered.watch_id}). ` + `A notification will fire when the pattern matches or the task exits.`;
+  } catch (err) {
+    unmarkExplicitControl(sessionId, taskId);
+    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `Auto-registering an async watch failed (${err instanceof Error ? err.message : String(err)}). ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits.`;
+  }
+}
 function createBashWriteTool(ctx) {
   return {
     name: "bash_write",
@@ -33647,6 +33927,7 @@ async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFo
     transportTimeoutMs: BASH_TRANSPORT_TIMEOUT_MS
   };
   const sessionId = resolveSessionId(extCtx);
+  clearSyncWatchAbort(sessionId);
   if (waitForExit)
     markTaskWaiting(sessionId, taskId);
   let sawTerminal = false;
@@ -33685,6 +33966,9 @@ async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFo
         }
         return withWaited(data, { reason: "exited", elapsed_ms: Date.now() - startedAt });
       }
+      if (isSyncWatchAborted(sessionId)) {
+        return withWaited(data, { reason: "user_message", elapsed_ms: Date.now() - startedAt });
+      }
       if (Date.now() >= deadline) {
         return withWaited(data, { reason: "timeout", elapsed_ms: Date.now() - startedAt });
       }
@@ -33953,8 +34237,12 @@ function registerConflictsTool(pi, ctx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const reqParams = {};
       const path2 = params?.path;
-      if (typeof path2 === "string" && path2.trim() !== "")
-        reqParams.path = path2;
+      if (typeof path2 === "string" && path2.trim() !== "") {
+        await assertExternalDirectoryPermission(extCtx, path2, "inspect", {
+          restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+        });
+        reqParams.path = await resolvePathArg(extCtx.cwd, path2);
+      }
       const response = await callBridge(bridge, "git_conflicts", reqParams, extCtx);
       return textResult(response.text ?? JSON.stringify(response, null, 2));
     },
@@ -35247,7 +35535,7 @@ function registerRefactorTool(pi, ctx) {
   pi.registerTool({
     name: "aft_refactor",
     label: "refactor",
-    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.",
+    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.",
     parameters: RefactorParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
       const commandMap = {
@@ -35626,21 +35914,9 @@ function registerSemanticTool(pi, ctx) {
     name: "aft_search",
     label: "search",
     description: [
-      "Find code with unified semantic, lexical, literal, and regex search. Returns ranked symbol/file results or exact matching lines, with routing metadata.",
+      "Search code with one tool: concepts, identifiers, error strings, regex, literals, and filenames are auto-routed to the right engine and returned ranked. Use it for any code search — including when you only know what the code does, not what it's named ('where is rate limiting handled', 'retry logic', '^export', 'Cargo.lock').",
       "",
-      "When to reach for it:",
-      "- Exploring an unfamiliar area: 'where is rate limiting handled', 'how does auth flow work'",
-      "- Concept doesn't appear as a literal string: 'retry logic', 'cache invalidation', 'graceful shutdown'",
-      "- Filename-shaped concepts: 'the bridge spawn helper', 'the session detection module'",
-      "- Regex-shaped or exact text queries when you want AFT to classify and route automatically",
-      "- You know roughly what the function does but not what it's named",
-      "",
-      "When NOT to use:",
-      "- You need exhaustive literal enumeration → use grep directly",
-      "- You want the file/module structure → use aft_outline",
-      "- You're following a call chain → use aft_callgraph",
-      "",
-      "Set hint to 'regex', 'literal', 'semantic', or 'auto' to override or document routing intent."
+      "Set hint to 'regex', 'literal', or 'semantic' to force a lane."
     ].join(`
 `),
     parameters: SearchParams2,
@@ -35671,138 +35947,8 @@ ${extra}`;
   });
 }
 
-// src/tools/structure.ts
-import { StringEnum as StringEnum6 } from "@earendil-works/pi-ai";
-import { Type as Type14 } from "typebox";
-var TransformParams = Type14.Object({
-  op: StringEnum6(["add_member", "add_derive", "wrap_try_catch", "add_decorator", "add_struct_tags"], { description: "Transformation operation" }),
-  filePath: Type14.String({
-    description: "Path to the source file (absolute or relative to project root)"
-  }),
-  container: Type14.Optional(Type14.String({ description: "Class/struct/impl name for add_member" })),
-  code: Type14.Optional(Type14.String({ description: "Member code to insert (add_member)" })),
-  target: Type14.Optional(Type14.String({ description: "Target symbol name" })),
-  derives: Type14.Optional(Type14.Array(Type14.String(), { description: "Derive macro names (add_derive)" })),
-  catchBody: Type14.Optional(Type14.String({ description: "Catch block body (wrap_try_catch, default: 'throw error;')" })),
-  decorator: Type14.Optional(Type14.String({ description: "Decorator text without @ (add_decorator)" })),
-  field: Type14.Optional(Type14.String({ description: "Struct field name (add_struct_tags)" })),
-  tag: Type14.Optional(Type14.String({ description: "Tag key (add_struct_tags)" })),
-  value: Type14.Optional(Type14.String({ description: "Tag value (add_struct_tags)" })),
-  position: Type14.Optional(Type14.String({
-    description: "Position hint: 'first', 'last' (default), 'before:name', 'after:name' for add_member"
-  })),
-  validate: Type14.Optional(StringEnum6(["syntax", "full"], {
-    description: "Validation level (default: syntax)"
-  }))
-});
-function buildTransformSections(args, payload, theme) {
-  const response = asRecord2(payload);
-  if (!response)
-    return [theme.fg("muted", "No transform result.")];
-  const target = asString(response.target) ?? asString(response.scope) ?? args.target ?? args.container ?? args.field ?? args.filePath;
-  return [
-    `${theme.fg("success", "transformed")} ${theme.fg("accent", args.op)}`,
-    `${theme.fg("muted", "file")} ${theme.fg("accent", asString(response.file) ?? args.filePath)}`,
-    target ? `${theme.fg("muted", "target")} ${target}` : theme.fg("muted", "No target metadata.")
-  ];
-}
-function renderTransformCall(args, theme, context) {
-  const target = args.target ?? args.container ?? args.field;
-  const summary = [
-    theme.fg("accent", args.op),
-    accentPath(theme, args.filePath),
-    target ? theme.fg("toolOutput", target) : undefined
-  ].filter(Boolean).join(" ");
-  return renderToolCall("transform", summary, theme, context);
-}
-function renderTransformResult(result, args, theme, context) {
-  if (context.isError)
-    return renderErrorResult(result, "transform failed", theme, context);
-  return renderSections(buildTransformSections(args, extractStructuredPayload(result), theme), context);
-}
-function registerStructureTool(pi, ctx) {
-  pi.registerTool({
-    name: "aft_transform",
-    label: "transform",
-    description: "Scope-aware structural code transformations with correct indentation. Use aft_safety checkpoint/undo before risky transforms.",
-    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: filePath };
-      if (params.container !== undefined)
-        req.scope = params.container;
-      if (params.code !== undefined)
-        req.code = params.code;
-      if (params.target !== undefined)
-        req.target = params.target;
-      if (params.derives !== undefined)
-        req.derives = params.derives;
-      if (params.catchBody !== undefined)
-        req.catch_body = params.catchBody;
-      if (params.decorator !== undefined)
-        req.decorator = params.decorator;
-      if (params.field !== undefined)
-        req.field = params.field;
-      if (params.tag !== undefined)
-        req.tag = params.tag;
-      if (params.value !== undefined)
-        req.value = params.value;
-      if (params.position !== undefined)
-        req.position = params.position;
-      if (params.validate !== undefined)
-        req.validate = params.validate;
-      const response = await callBridge(bridge, params.op, req, extCtx);
-      return textResult(JSON.stringify(response, null, 2));
-    },
-    renderCall(args, theme, context) {
-      return renderTransformCall(args, theme, context);
-    },
-    renderResult(result, _options, theme, context) {
-      return renderTransformResult(result, context.args, theme, context);
-    }
-  });
-}
-function validateTransformParams(params) {
-  const op = params.op;
-  if (op === "add_member") {
-    if (isEmptyParam(params.container)) {
-      throw new Error("'container' is required for 'add_member' op");
-    }
-    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 (isEmptyParam(params.target)) {
-      throw new Error(`'target' is required for '${op}' op`);
-    }
-  }
-  if (op === "add_derive" && isEmptyParam(params.derives)) {
-    throw new Error("'derives' array is required for 'add_derive' op");
-  }
-  if (op === "add_decorator" && isEmptyParam(params.decorator)) {
-    throw new Error("'decorator' is required for 'add_decorator' op");
-  }
-  if (op === "add_struct_tags") {
-    if (isEmptyParam(params.field)) {
-      throw new Error("'field' is required for 'add_struct_tags' op");
-    }
-    if (isEmptyParam(params.tag)) {
-      throw new Error("'tag' is required for 'add_struct_tags' op");
-    }
-    if (isEmptyParam(params.value)) {
-      throw new Error("'value' is required for 'add_struct_tags' op");
-    }
-  }
-}
-
 // src/workflow-hints.ts
-var HEADING = "## Prefer AFT tools for token efficiency";
+var HEADING = "## IMPORTANT NOTICE about your tools";
 function buildWorkflowHints(opts) {
   const sections = [];
   const grepName = opts.hoistBuiltins ? "grep" : "aft_grep";
@@ -35816,14 +35962,28 @@ function buildWorkflowHints(opts) {
   const hasBash = !opts.absentTools.has(bashName);
   const hasBgBash = opts.bashBackgroundEnabled && hasBash && !opts.absentTools.has("bash_status");
   if (hasBash && opts.bashCompressionEnabled) {
-    sections.push("When AFT bash output compression is on, do NOT pipe test/build commands through grep/head/tail (e.g. `bun test | grep fail`) to summarize. The compressor already keeps failures and the summary; piping hides failures. Run the command bare.");
+    sections.push([
+      "**Test/build output**: bash output is auto-compressed — failures and the summary are always kept. DO NOT pipe test/build commands through filters to summarize; that hides failures:",
+      "- `bun test | grep fail` → run `bun test`",
+      "- `cargo test 2>&1 | tail -20` → run `cargo test`",
+      "- `npm run build | head -50` → run `npm run build`"
+    ].join(`
+`));
   }
   if (hasOutline && hasZoom) {
     sections.push(`**Web/URL access**: \`aft_outline({ target: "<url>" })\` first for structure, then \`aft_zoom({ url: "<url>", symbols: "<heading>" })\` for the specific section.`);
   }
   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.`;
-    sections.push(`**Code exploration**: fire independent lookups in ONE parallel tool-call wave — do NOT serialize them. ${locate} Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s). DO NOT run \`grep\`/\`rg\`/\`find\` through \`bash\` to locate code — the bash path is unindexed, unranked, serial, and routinely surfaces the wrong hit. Keep \`bash\` for shell facts (git state, file metadata, processes).`);
+    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 })\``
+    ].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.");
@@ -35841,13 +36001,22 @@ function buildWorkflowHints(opts) {
 `));
   }
   if (hasBgBash) {
-    sections.push(`**Long-running commands** (builds, installs, full test suites): \`${bashName}({ background: true })\` returns immediately with a \`task_id\`, then **end your turn** — a completion reminder arrives automatically when it finishes. Do not poll \`bash_status({ task_id })\`, and do not sync-wait with \`bash_watch\` for a long task: blocking freezes your turn and locks the user out until it ends. For an early non-blocking ping on a specific output line, register an async watch \`bash_watch({ task_id, pattern, background: true })\`. \`bash_watch\` synchronous mode is only for short bounded waits (seconds, e.g. a dev server printing a readiness line), never for multi-minute jobs.`);
+    sections.push([
+      `**Long-running commands** (builds, installs, full test suites): \`${bashName}({ background: true })\` returns a \`task_id\` immediately. Then do ONE of these:`,
+      "1. Keep working on something independent of the result.",
+      "2. End your turn — a completion reminder with the result arrives automatically.",
+      `3. Need to react to a specific output line early? Register \`bash_watch({ task_id, pattern, background: true })\`, then end your turn — it pings you the moment the pattern appears.`,
+      `\`bash_status({ task_id })\` is for inspecting output AFTER the reminder arrives, or one quick look at a live task — never call it repeatedly to wait: the reminder already delivers the result, and each poll wastes a turn. Sync \`bash_watch\` (without \`background: true\`) blocks your turn and locks the user out — reserve it for waits of a few seconds (a dev server printing its ready line), never for builds or test suites.`
+    ].join(`
+`));
     sections.push(`**PTY / interactive commands**: PTY mode is for interactive REPLs and terminal apps (python, node, bash itself, vim). Start with \`${bashName}({ command: "python", pty: true, background: true })\`, read the screen with \`bash_status({ task_id, output_mode: "screen" })\`, and send input with \`bash_write({ task_id, input: "..." })\`.`);
   }
   if (sections.length === 0) {
     return null;
   }
-  sections.unshift("**Parallel tool calls**: when several read-only operations are independent, emit them in ONE response instead of serializing — file reads, structure and symbol lookups, code search, diagnostics, and git status/diff/log. Sequence only when a call depends on a prior result or when a command mutates state.");
+  sections.unshift(`You are equipped with a non-standard tool set: indexed code search, symbol-level reading, structural editing, and code analysis that are faster, more precise, and far cheaper in tokens than stitching together command-line utilities in bash. Always reach for these tools first.
+
+**Parallel tool calls**: when several read-only operations are independent, emit them in ONE response instead of serializing — file reads, structure and symbol lookups, code search, diagnostics, and git status/diff/log. Sequence only when a call depends on a prior result or when a command mutates state.`);
   return `${HEADING}
 
 ${sections.join(`
@@ -35939,21 +36108,15 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.36.0";
+var ANNOUNCEMENT_VERSION = "0.37.0";
 var ANNOUNCEMENT_FEATURES = [
-  "Persisted call graph: dead-code analysis runs on large repositories again (the file-count cap is gone), `aft_callgraph` queries resolve from disk, and method-call edges are more accurate across more languages.",
-  "Bash output stops hiding failures: piping a test/build through `grep`/`head` with compression on now keeps the failures and summary instead of stripping them.",
-  "Code search steering: guidance and hints now point to `aft_search` and parallel `aft_*` tools instead of `grep`/`find` in bash.",
-  "Fixes: a small `timeout` no longer kills a foreground `bash` command (#102), and `aft_delete`/`aft_safety checkpoint` no longer crash on a mistyped `files` argument."
+  "Much lower background CPU: idle bridges shut down after 30 minutes, deleted project roots stop the watcher instead of spinning it, and background scans reuse warm caches on a bounded thread pool.",
+  "`aft_transform` removed: usage data showed agents never called it — `edit` covers everything it did, and every request now carries a smaller tool surface.",
+  "Leaner tools: `bash`, `write`, `edit`, `apply_patch`, `aft_search`, and `aft_refactor` descriptions trimmed and config-aware; system-prompt guidance rewritten around what to do instead of what to avoid.",
+  "Background bash reminders are right-sized: failures keep head + tail context, successes show a short tail, and compressors never print a success summary for a non-zero exit."
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/DSa65w8wuf";
-var ALL_ONLY_TOOLS = new Set([
-  "aft_callgraph",
-  "aft_delete",
-  "aft_move",
-  "aft_transform",
-  "aft_refactor"
-]);
+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))
@@ -36031,7 +36194,6 @@ function resolveToolSurface(config2) {
       move: false,
       astSearch: false,
       astReplace: false,
-      structure: false,
       refactor: false
     };
   }
@@ -36054,7 +36216,6 @@ function resolveToolSurface(config2) {
     move: false,
     astSearch: ok("ast_grep_search"),
     astReplace: ok("ast_grep_replace"),
-    structure: false,
     refactor: false
   };
   if (surface === "all") {
@@ -36063,7 +36224,6 @@ function resolveToolSurface(config2) {
       navigate: allOnly("aft_callgraph"),
       delete: allOnly("aft_delete"),
       move: allOnly("aft_move"),
-      structure: allOnly("aft_transform"),
       refactor: allOnly("aft_refactor")
     };
   }
@@ -36269,7 +36429,7 @@ ${lines}
   }
   const surface = resolveToolSurface(config2);
   if (surface.hoistBash && resolveBashConfig(config2).enabled) {
-    registerBashTool(pi, ctx);
+    registerBashTool(pi, ctx, surface.semantic);
   }
   registerHoistedTools(pi, ctx, surface);
   if (surface.outline || surface.zoom) {
@@ -36299,9 +36459,6 @@ ${lines}
   if (surface.delete || surface.move) {
     registerFsTools(pi, ctx, surface);
   }
-  if (surface.structure) {
-    registerStructureTool(pi, ctx);
-  }
   if (surface.refactor) {
     registerRefactorTool(pi, ctx);
   }
@@ -36328,6 +36485,9 @@ ${lines}
       runtime: pi
     });
   });
+  pi.on("input", (_event, extCtx) => {
+    signalSyncWatchAbort(resolveSessionId(extCtx));
+  });
   const unregisterShutdownCleanup = registerShutdownCleanup(async () => {
     try {
       await Promise.allSettled([abortInFlightAutoInstalls(), abortInFlightGithubInstalls()]);