nolo-cli 0.1.40 → 0.1.42

package/agent-runtime/localWorkspaceTools.ts

@@ -13,14 +13,63 @@ type LocalWorkspaceToolArgs = {
   commandPrefix?: string[];
 };
 
+export type ActivityRef =
+  | { type: "file"; path: string }
+  | { type: "terminal"; id?: string; label?: string }
+  | { type: "url"; url: string; label?: string };
+
+export type ToolActivityAction = {
+  title: string;
+  kind?: string;
+  detail?: string;
+  refs?: ActivityRef[];
+};
+
+export type ToolActivityPhase = {
+  id: string;
+  title: string;
+  index?: number;
+  total?: number;
+  status?: "pending" | "running" | "success" | "failed";
+};
+
+export type ActivityPlan = {
+  title?: string;
+  phases: Array<{
+    id: string;
+    title: string;
+    index?: number;
+    status?: "pending" | "running" | "success" | "failed";
+  }>;
+};
+
+export type ToolActivity = Partial<ToolActivityAction> & {
+  phase?: ToolActivityPhase;
+  action?: ToolActivityAction;
+  plan?: ActivityPlan;
+};
+
 type WorkspaceFileArgs = {
   path?: unknown;
   content?: unknown;
   oldText?: unknown;
   newText?: unknown;
   expectedReplacements?: unknown;
+  maxDepth?: unknown;
+  entryType?: unknown;
+  startLine?: unknown;
+  endLine?: unknown;
+  maxLines?: unknown;
+  tailLines?: unknown;
   query?: unknown;
+  pattern?: unknown;
+  glob?: unknown;
+  exclude?: unknown;
+  maxResults?: unknown;
   includeIgnored?: unknown;
+  literal?: unknown;
+  caseSensitive?: unknown;
+  contextLines?: unknown;
   command?: unknown;
   cmd?: unknown;
   branch?: unknown;
@@ -36,17 +85,28 @@ type WorkspaceFileArgs = {
   screenshotPath?: unknown;
   metricsPath?: unknown;
   shell?: unknown;
+  _activity?: unknown;
 };
 
 type OpenAiCompatibleTool = Record<string, unknown> & {
   function?: Record<string, unknown> & { name?: string };
 };
 
+export type GlobFilesDescriptionVariant = "brief" | "strategy" | "workflow" | "antiShell";
+export type GlobFilesParameterVariant = "minimal" | "scoped" | "rich";
+export type SearchFilesDescriptionVariant = "brief" | "strategy" | "workflow" | "antiShell";
+export type SearchFilesParameterVariant = "minimal" | "scoped" | "rich";
+export type ReadFileDescriptionVariant = "brief" | "strategy" | "workflow" | "antiShell";
+export type ReadFileParameterVariant = "minimal" | "scoped" | "rich";
+export type ListFilesDescriptionVariant = "brief" | "strategy" | "workflow" | "antiShell";
+export type ListFilesParameterVariant = "minimal" | "scoped" | "rich";
+
 const WORKSPACE_TOOL_NAMES = [
   "listFiles",
   "readFile",
   "writeFile",
   "editFile",
+  "globFiles",
   "searchFiles",
   "startPreview",
   "getPreviewStatus",
@@ -61,6 +121,7 @@ const DEFAULT_LOCAL_CODING_TOOL_NAMES = [
   "readFile",
   "writeFile",
   "editFile",
+  "globFiles",
   "searchFiles",
 ] as const;
 
@@ -75,6 +136,199 @@ const REMOVED_WORKSPACE_TOOL_NAMES = new Set([
   "commitWorkspace",
 ]);
 
+function buildActivityProperty() {
+  const refsProperty = {
+    type: "array",
+    items: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: ["file", "terminal", "url"] },
+        path: { type: "string" },
+        id: { type: "string" },
+        label: { type: "string" },
+        url: { type: "string" },
+      },
+    },
+    description: "Referenced files, terminals, or URLs for this action.",
+  };
+  const actionProperty = {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Short human-readable action label." },
+      kind: {
+        type: "string",
+        enum: ["read", "write", "edit", "search", "terminal", "version", "test", "build", "preview", "other"],
+      },
+      detail: { type: "string", description: "Optional concise detail shown after the label." },
+      refs: refsProperty,
+    },
+    required: ["title"],
+  };
+  const planPhaseProperty = {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "Stable phase id reused by activity.phase.id." },
+      title: { type: "string", description: "Human-readable planned task phase." },
+      index: { type: "number" },
+      status: { type: "string", enum: ["pending", "running", "success", "failed"] },
+    },
+    required: ["id", "title"],
+  };
+  return {
+    type: "object",
+    description:
+      "Optional lightweight human-readable activity hint for UI display only. Prefer { plan, phase, action }. The executor ignores this for execution semantics but echoes it back in result metadata.",
+    properties: {
+      title: { type: "string", description: "Short human-readable action label." },
+      kind: {
+        type: "string",
+        enum: ["read", "write", "edit", "search", "terminal", "version", "test", "build", "preview", "other"],
+      },
+      detail: { type: "string", description: "Optional longer description shown on expand." },
+      refs: refsProperty,
+      plan: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Optional label for the visible task progress block." },
+          phases: {
+            type: "array",
+            items: planPhaseProperty,
+          },
+        },
+        required: ["phases"],
+      },
+      phase: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Stable phase id reused across related tool calls." },
+          title: { type: "string", description: "Human-readable current task phase." },
+          index: { type: "number" },
+          total: { type: "number" },
+          status: { type: "string", enum: ["pending", "running", "success", "failed"] },
+        },
+        required: ["id", "title"],
+      },
+      action: actionProperty,
+    },
+  };
+}
+
+function readTrimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function readFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function extractActivityRefs(rawRefs: unknown): ActivityRef[] | undefined {
+  if (!Array.isArray(rawRefs)) return undefined;
+  const refs = rawRefs.flatMap((entry): ActivityRef[] => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+    const ref = entry as Record<string, unknown>;
+    if (ref.type === "file") {
+      const path = readTrimmedString(ref.path);
+      return path ? [{ type: "file", path }] : [];
+    }
+    if (ref.type === "terminal") {
+      const id = readTrimmedString(ref.id);
+      const label = readTrimmedString(ref.label);
+      return id || label
+        ? [{ type: "terminal", ...(id ? { id } : {}), ...(label ? { label } : {}) }]
+        : [];
+    }
+    if (ref.type === "url") {
+      const url = readTrimmedString(ref.url);
+      const label = readTrimmedString(ref.label);
+      return url ? [{ type: "url", url, ...(label ? { label } : {}) }] : [];
+    }
+    return [];
+  });
+  return refs.length ? refs : undefined;
+}
+
+function extractActivityAction(rawAction: unknown): ToolActivityAction | undefined {
+  if (!rawAction || typeof rawAction !== "object" || Array.isArray(rawAction)) return undefined;
+  const obj = rawAction as Record<string, unknown>;
+  const title = readTrimmedString(obj.title);
+  if (!title) return undefined;
+  const kind = readTrimmedString(obj.kind);
+  const detail = readTrimmedString(obj.detail);
+  const refs = extractActivityRefs(obj.refs);
+  return {
+    title,
+    ...(kind ? { kind } : {}),
+    ...(detail ? { detail } : {}),
+    ...(refs ? { refs } : {}),
+  };
+}
+
+function extractActivityPhase(rawPhase: unknown): ToolActivityPhase | undefined {
+  if (!rawPhase || typeof rawPhase !== "object" || Array.isArray(rawPhase)) return undefined;
+  const obj = rawPhase as Record<string, unknown>;
+  const title = readTrimmedString(obj.title);
+  if (!title) return undefined;
+  const id = readTrimmedString(obj.id) || title.toLowerCase().replace(/\s+/g, "-");
+  const index = readFiniteNumber(obj.index);
+  const total = readFiniteNumber(obj.total);
+  const status =
+    obj.status === "pending" ||
+    obj.status === "running" ||
+    obj.status === "success" ||
+    obj.status === "failed"
+      ? obj.status
+      : undefined;
+  return {
+    id,
+    title,
+    ...(index !== undefined ? { index } : {}),
+    ...(total !== undefined ? { total } : {}),
+    ...(status ? { status } : {}),
+  };
+}
+
+function extractActivityPlan(rawPlan: unknown): ActivityPlan | undefined {
+  if (!rawPlan || typeof rawPlan !== "object" || Array.isArray(rawPlan)) return undefined;
+  const obj = rawPlan as Record<string, unknown>;
+  if (!Array.isArray(obj.phases)) return undefined;
+  const phases = obj.phases.flatMap((entry, index): ActivityPlan["phases"] => {
+    const phase = extractActivityPhase(entry);
+    if (!phase) return [];
+    return [{
+      id: phase.id,
+      title: phase.title,
+      index: phase.index ?? index + 1,
+      ...(phase.status ? { status: phase.status } : {}),
+    }];
+  });
+  if (phases.length === 0) return undefined;
+  const title = readTrimmedString(obj.title);
+  return {
+    ...(title ? { title } : {}),
+    phases,
+  };
+}
+
+function extractActivity(parsed: WorkspaceFileArgs): ToolActivity | undefined {
+  const raw = parsed._activity;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const obj = raw as Record<string, unknown>;
+  const nestedAction = extractActivityAction(obj.action);
+  const legacyAction = extractActivityAction(obj);
+  const action = nestedAction || legacyAction;
+  const phase = extractActivityPhase(obj.phase);
+  const plan = extractActivityPlan(obj.plan);
+  if (!action && !plan) return undefined;
+  return {
+    ...(action ? action : {}),
+    ...(phase ? { phase } : {}),
+    ...(nestedAction ? { action: nestedAction } : {}),
+    ...(plan ? { plan } : {}),
+  };
+}
+
 function buildWorkspacePathProperty() {
   return {
     type: "string",
@@ -82,36 +336,153 @@ function buildWorkspacePathProperty() {
   };
 }
 
-function buildListWorkspaceFilesTool(): OpenAiCompatibleTool {
+function buildListWorkspaceDescription(variant?: ListFilesDescriptionVariant) {
+  if (variant === "brief") {
+    return "List files and directories inside a workspace directory.";
+  }
+  if (variant === "workflow") {
+    return "List a bounded directory overview inside the workspace. Use first when you need to understand nearby structure, choose a subdirectory, or inspect a non-code project. Then use globFiles for path-pattern discovery, searchFiles for text/content discovery, and readFile only for the specific files or line ranges you need.";
+  }
+  if (variant === "antiShell") {
+    return "List a bounded directory overview inside the workspace. Do not use execShell with ls/find/tree for normal directory overviews when listFiles can show the needed depth and limit. Use globFiles for path-pattern discovery and searchFiles for content search.";
+  }
+  return "List a bounded directory overview inside the workspace. Use for scanning nearby structure, not for path-pattern discovery across the repo. Prefer globFiles for finding files by name/extension and searchFiles for text inside files.";
+}
+
+function buildListWorkspaceParameters(variant?: ListFilesParameterVariant) {
+  const path = buildWorkspacePathProperty();
+  const _activity = buildActivityProperty();
+  const maxDepth = {
+    type: "integer",
+    description: "Maximum directory depth to include. Defaults to 1 for the requested directory only.",
+  };
+  const maxResults = {
+    type: "integer",
+    description: "Maximum number of entries to return. Use a small value for large directories.",
+  };
+  const entryType = {
+    type: "string",
+    enum: ["all", "files", "directories"],
+    description: "Filter returned entries. Defaults to all.",
+  };
+  if (variant === "minimal") {
+    return {
+      type: "object",
+      properties: { path, _activity },
+    };
+  }
+  if (variant === "rich") {
+    return {
+      type: "object",
+      properties: {
+        path,
+        maxDepth,
+        maxResults,
+        entryType,
+        _activity,
+      },
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      path,
+      maxResults,
+      _activity,
+    },
+  };
+}
+
+function buildListWorkspaceFilesTool(args?: {
+  descriptionVariant?: ListFilesDescriptionVariant;
+  parameterVariant?: ListFilesParameterVariant;
+}): OpenAiCompatibleTool {
   return {
     type: "function",
     function: {
       name: "listFiles",
-      description: "List files and directories inside a workspace directory.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: buildWorkspacePathProperty(),
-        },
+      description: buildListWorkspaceDescription(args?.descriptionVariant),
+      parameters: buildListWorkspaceParameters(args?.parameterVariant),
+    },
+  };
+}
+
+function buildReadWorkspaceDescription(variant?: ReadFileDescriptionVariant) {
+  if (variant === "brief") {
+    return "Read a UTF-8 text file inside the workspace.";
+  }
+  if (variant === "workflow") {
+    return "Read a UTF-8 text file inside the workspace after listFiles, globFiles, or searchFiles has narrowed the target. Use line ranges from searchFiles matches and tailLines for logs or generated output. Read the whole file only when the task truly needs all content or exact edit context.";
+  }
+  if (variant === "antiShell") {
+    return "Read a UTF-8 text file inside the workspace. Do not use execShell with cat/sed/head/tail for normal text reads when readFile can return the needed file or line range. Use searchFiles first for content search, then readFile only the relevant lines when possible.";
+  }
+  return "Read a UTF-8 text file inside the workspace. Read before editing when you need exact text for editFile. For discovery or classification tasks, avoid batch-reading every candidate; report candidate paths first, or read only one to three representative files with maxLines or focused line ranges. Use line ranges for large code, docs, data, configs, and logs after searchFiles returns line numbers. Read the whole file only when the task truly needs all content or exact edit context.";
+}
+
+function buildReadWorkspaceParameters(variant?: ReadFileParameterVariant) {
+  const path = buildWorkspacePathProperty();
+  const _activity = buildActivityProperty();
+  const startLine = {
+    type: "integer",
+    description: "1-based first line to return. Use with endLine or maxLines after searchFiles gives a line number.",
+  };
+  const endLine = {
+    type: "integer",
+    description: "1-based last line to return, inclusive.",
+  };
+  const maxLines = {
+    type: "integer",
+    description: "Maximum number of lines to return starting at startLine, or from the start of the file when startLine is omitted. Use for lightweight previews of candidate configs, docs, data, and logs instead of reading many whole files. When the user gives a read/preview budget, each readFile preview consumes one budget slot.",
+  };
+  const tailLines = {
+    type: "integer",
+    description: "Return only the last N lines, useful for logs and generated text.",
+  };
+  if (variant === "minimal") {
+    return {
+      type: "object",
+      properties: { path, _activity },
+      required: ["path"],
+    };
+  }
+  if (variant === "rich") {
+    return {
+      type: "object",
+      properties: {
+        path,
+        startLine,
+        endLine,
+        maxLines,
+        tailLines,
+        _activity,
       },
+      required: ["path"],
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      path,
+      startLine,
+      endLine,
+      maxLines,
+      _activity,
     },
+    required: ["path"],
   };
 }
 
-function buildReadWorkspaceFileTool(): OpenAiCompatibleTool {
+function buildReadWorkspaceFileTool(args?: {
+  descriptionVariant?: ReadFileDescriptionVariant;
+  parameterVariant?: ReadFileParameterVariant;
+}): OpenAiCompatibleTool {
   return {
     type: "function",
     function: {
       name: "readFile",
-      description:
-        "Read a UTF-8 text file inside the workspace. Read before editing when you need the current content or exact text for editFile; skip unnecessary reads for trivial known writes.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: buildWorkspacePathProperty(),
-        },
-        required: ["path"],
-      },
+      description: buildReadWorkspaceDescription(args?.descriptionVariant),
+      parameters: buildReadWorkspaceParameters(args?.parameterVariant),
     },
   };
 }
@@ -131,6 +502,7 @@ function buildWriteWorkspaceFileTool(): OpenAiCompatibleTool {
             type: "string",
             description: "Full UTF-8 file content to write.",
           },
+          _activity: buildActivityProperty(),
         },
         required: ["path", "content"],
       },
@@ -161,6 +533,7 @@ function buildReplaceWorkspaceTextTool(): OpenAiCompatibleTool {
             type: "integer",
             description: "Expected replacement count. Defaults to 1.",
           },
+          _activity: buildActivityProperty(),
         },
         required: ["path", "oldText", "newText"],
       },
@@ -168,28 +541,183 @@ function buildReplaceWorkspaceTextTool(): OpenAiCompatibleTool {
   };
 }
 
-function buildSearchWorkspaceTool(): OpenAiCompatibleTool {
+function buildSearchWorkspaceDescription(variant?: SearchFilesDescriptionVariant) {
+  if (variant === "brief") {
+    return "Search workspace file contents.";
+  }
+  if (variant === "workflow") {
+    return "Search file contents inside the current workspace after listFiles or globFiles has scoped the likely area, or directly when the task names text to find. Use for code, docs, data, configs, logs, and other text files. Return line numbers, then use readFile with focused ranges for interpretation or editing.";
+  }
+  if (variant === "antiShell") {
+    return "Search text inside workspace files for code, docs, data, configs, logs, or other text-like assets. Do not use execShell for content search when searchFiles can directly find matching lines. Use globFiles instead for path-only discovery, then readFile for exact surrounding content when needed.";
+  }
+  return "Search file contents inside the current workspace using ripgrep when available. Use for grep-like text or regex search across code, docs, data, configs, logs, and other text files. Use globFiles instead when you only need to find files by name or extension before readFile.";
+}
+
+function buildSearchWorkspaceParameters(variant?: SearchFilesParameterVariant) {
+  const query = {
+    type: "string",
+    description: "Search query. Treated as a regular expression unless literal is true.",
+  };
+  const path = buildWorkspacePathProperty();
+  const includeIgnored = {
+    type: "boolean",
+    description:
+      "When true, search files ignored by .gitignore such as .tmp. Defaults to false; .git and node_modules remain excluded.",
+  };
+  const exclude = {
+    type: "array",
+    items: { type: "string" },
+    description: "Glob patterns to exclude from content search, for example ['dist/**', 'build/**', 'exports/**', '*.log'].",
+  };
+  const maxResults = {
+    type: "integer",
+    description: "Maximum number of matching output lines to return. Use a small value when you only need candidate files or examples.",
+  };
+  const literal = {
+    type: "boolean",
+    description: "When true, search for query as literal text instead of a regular expression.",
+  };
+  const caseSensitive = {
+    type: "boolean",
+    description: "When false, search case-insensitively. Defaults to true.",
+  };
+  const contextLines = {
+    type: "integer",
+    description: "Number of surrounding context lines to include around each match. Defaults to 0.",
+  };
+  if (variant === "minimal") {
+    return {
+      type: "object",
+      properties: { query, _activity: buildActivityProperty() },
+      required: ["query"],
+    };
+  }
+  if (variant === "rich") {
+    return {
+      type: "object",
+      properties: {
+        query,
+        path,
+        exclude,
+        includeIgnored,
+        maxResults,
+        literal,
+        caseSensitive,
+        contextLines,
+        _activity: buildActivityProperty(),
+      },
+      required: ["query"],
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      query,
+      path,
+      includeIgnored,
+      maxResults,
+      _activity: buildActivityProperty(),
+    },
+    required: ["query"],
+  };
+}
+
+function buildSearchWorkspaceTool(args?: {
+  descriptionVariant?: SearchFilesDescriptionVariant;
+  parameterVariant?: SearchFilesParameterVariant;
+}): OpenAiCompatibleTool {
   return {
     type: "function",
     function: {
       name: "searchFiles",
-      description: "Search text in the current workspace using ripgrep when available.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description: "Search query or regular expression.",
-          },
-          path: buildWorkspacePathProperty(),
-          includeIgnored: {
-            type: "boolean",
-            description:
-              "When true, search files ignored by .gitignore such as .tmp. Defaults to false; .git and node_modules remain excluded.",
-          },
-        },
-        required: ["query"],
+      description: buildSearchWorkspaceDescription(args?.descriptionVariant),
+      parameters: buildSearchWorkspaceParameters(args?.parameterVariant),
+    },
+  };
+}
+
+function buildGlobWorkspaceDescription(variant?: GlobFilesDescriptionVariant) {
+  if (variant === "brief") {
+    return "Find workspace files by path glob without reading file contents.";
+  }
+  if (variant === "workflow") {
+    return "Find files by glob pattern inside the current workspace without reading file contents. Use after listFiles when you know the likely area, or first when the task names a filename, extension, asset type, config, or document pattern. Then use searchFiles for text inside candidates or readFile for the specific candidate paths.";
+  }
+  if (variant === "antiShell") {
+    return "Find workspace files by path glob without reading file contents. Use for code, docs, data, images, configs, logs, or any file discovery task. Do not use execShell or listFiles for path discovery when globFiles can directly narrow candidate files. Use before opening or reading files, and use searchFiles instead for searching text inside files.";
+  }
+  return "Find files by glob pattern inside the current workspace without reading file contents. Use for code, docs, data, images, configs, logs, or any file discovery task. Use one bounded glob with brace groups before repeated narrow globs when a task names several extensions or config names, for example **/*.{png,jpg,svg}, **/{package.json,bunfig.toml,tsconfig*.json}, or src/**/*.ts. Prefer searchFiles for searching text inside files, and readFile only after candidate paths are narrow enough.";
+}
+
+function buildGlobWorkspaceParameters(variant?: GlobFilesParameterVariant) {
+  const pattern = {
+    type: "string",
+    description: "Glob pattern for files. For candidate discovery, combine related names or extensions in one brace-group pattern before making repeated narrow calls, for example '**/*.ts', 'packages/**/local*.test.ts', '**/*.{png,jpg,svg}', or '**/{package.json,bunfig.toml,tsconfig*.json}'.",
+  };
+  const path = buildWorkspacePathProperty();
+  const includeIgnored = {
+    type: "boolean",
+    description:
+      "When true, include files ignored by .gitignore. Defaults to false; .git and node_modules remain excluded.",
+  };
+  const maxResults = {
+    type: "integer",
+    description: "Maximum number of file paths to return. Use a small value when you only need candidate paths before readFile; if results are truncated, report that and narrow the pattern or path before reading.",
+  };
+  const exclude = {
+    type: "array",
+    items: { type: "string" },
+    description: "Glob patterns to exclude from results, for example ['dist/**', 'build/**', 'exports/**', '*.tmp'].",
+  };
+  if (variant === "minimal") {
+    return {
+      type: "object",
+      properties: { pattern, _activity: buildActivityProperty() },
+      required: ["pattern"],
+    };
+  }
+  if (variant === "rich") {
+    return {
+      type: "object",
+      properties: {
+        pattern,
+        path,
+        exclude,
+        includeIgnored,
+        maxResults,
+        _activity: buildActivityProperty(),
       },
+      required: ["pattern"],
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      pattern,
+      glob: {
+        type: "string",
+        description: "Alias for pattern, kept for compatibility with codeSearch-style prompts.",
+      },
+      path,
+      exclude,
+      includeIgnored,
+      maxResults,
+      _activity: buildActivityProperty(),
+    },
+  };
+}
+
+function buildGlobWorkspaceFilesTool(args?: {
+  descriptionVariant?: GlobFilesDescriptionVariant;
+  parameterVariant?: GlobFilesParameterVariant;
+}): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "globFiles",
+      description: buildGlobWorkspaceDescription(args?.descriptionVariant),
+      parameters: buildGlobWorkspaceParameters(args?.parameterVariant),
     },
   };
 }
@@ -277,6 +805,7 @@ function buildExecShellTool(toolName: string): OpenAiCompatibleTool {
             type: "string",
             description: "Shell command to run.",
           },
+          _activity: buildActivityProperty(),
         },
       },
     },
@@ -330,12 +859,27 @@ function buildWorkspaceShellCommand(args: {
     : buildBashCommand(args.command);
 }
 
-function buildWorkspaceToolDefinition(toolName: string) {
+function buildWorkspaceToolDefinition(toolName: string, args?: {
+  listFilesDescriptionVariant?: ListFilesDescriptionVariant;
+  listFilesParameterVariant?: ListFilesParameterVariant;
+  readFileDescriptionVariant?: ReadFileDescriptionVariant;
+  readFileParameterVariant?: ReadFileParameterVariant;
+  globFilesDescriptionVariant?: GlobFilesDescriptionVariant;
+  globFilesParameterVariant?: GlobFilesParameterVariant;
+  searchFilesDescriptionVariant?: SearchFilesDescriptionVariant;
+  searchFilesParameterVariant?: SearchFilesParameterVariant;
+}) {
   if (toolName === "listFiles") {
-    return buildListWorkspaceFilesTool();
+    return buildListWorkspaceFilesTool({
+      descriptionVariant: args?.listFilesDescriptionVariant,
+      parameterVariant: args?.listFilesParameterVariant,
+    });
   }
   if (toolName === "readFile") {
-    return buildReadWorkspaceFileTool();
+    return buildReadWorkspaceFileTool({
+      descriptionVariant: args?.readFileDescriptionVariant,
+      parameterVariant: args?.readFileParameterVariant,
+    });
   }
   if (toolName === "writeFile") {
     return buildWriteWorkspaceFileTool();
@@ -343,8 +887,17 @@ function buildWorkspaceToolDefinition(toolName: string) {
   if (toolName === "editFile") {
     return buildReplaceWorkspaceTextTool();
   }
+  if (toolName === "globFiles") {
+    return buildGlobWorkspaceFilesTool({
+      descriptionVariant: args?.globFilesDescriptionVariant,
+      parameterVariant: args?.globFilesParameterVariant,
+    });
+  }
   if (toolName === "searchFiles") {
-    return buildSearchWorkspaceTool();
+    return buildSearchWorkspaceTool({
+      descriptionVariant: args?.searchFilesDescriptionVariant,
+      parameterVariant: args?.searchFilesParameterVariant,
+    });
   }
   if (toolName === "startPreview" || toolName === "getPreviewStatus" || toolName === "stopPreview" || toolName === "releasePreview") {
     return buildPreviewLifecycleTool(toolName);
@@ -368,8 +921,19 @@ function filterDeclaredWorkspaceToolNames(args: {
 export function buildLocalWorkspaceToolset(args: {
   declaredToolNames?: string[];
   exposeShellTools?: boolean;
+  useDeclaredToolNamesOnly?: boolean;
 }) {
   const exposeShellTools = args.exposeShellTools === true;
+  if (args.useDeclaredToolNamesOnly) {
+    const toolNames = new Set(filterDeclaredWorkspaceToolNames({
+      toolNames: args.declaredToolNames,
+      exposeShellTools,
+    }));
+    return {
+      toolNames: [...toolNames],
+      exposeShellTools,
+    };
+  }
   const toolNames = new Set([
     ...DEFAULT_LOCAL_CODING_TOOL_NAMES,
     ...(exposeShellTools ? SHELL_TOOL_NAMES : []),
@@ -387,7 +951,14 @@ export function buildLocalWorkspaceToolset(args: {
 export function buildLocalWorkspacePolicyToolNames(args: {
   declaredToolNames?: string[];
   exposeShellTools?: boolean;
+  useDeclaredToolNamesOnly?: boolean;
 }) {
+  if (args.useDeclaredToolNamesOnly) {
+    return filterDeclaredWorkspaceToolNames({
+      toolNames: args.declaredToolNames,
+      exposeShellTools: args.exposeShellTools === true,
+    });
+  }
   return [...new Set([
     ...buildLocalWorkspaceToolset({
       exposeShellTools: args.exposeShellTools,
@@ -402,6 +973,14 @@ export function buildLocalWorkspacePolicyToolNames(args: {
 export function buildLocalWorkspaceOpenAiTools(args: {
   toolNames?: string[];
   exposeShellTools?: boolean;
+  listFilesDescriptionVariant?: ListFilesDescriptionVariant;
+  listFilesParameterVariant?: ListFilesParameterVariant;
+  readFileDescriptionVariant?: ReadFileDescriptionVariant;
+  readFileParameterVariant?: ReadFileParameterVariant;
+  globFilesDescriptionVariant?: GlobFilesDescriptionVariant;
+  globFilesParameterVariant?: GlobFilesParameterVariant;
+  searchFilesDescriptionVariant?: SearchFilesDescriptionVariant;
+  searchFilesParameterVariant?: SearchFilesParameterVariant;
 }) {
   const declaredTools = new Set(args.toolNames ?? []);
   return WORKSPACE_TOOL_NAMES
@@ -412,7 +991,16 @@ export function buildLocalWorkspaceOpenAiTools(args: {
       }
       return true;
     })
-    .map((toolName) => buildWorkspaceToolDefinition(toolName))
+    .map((toolName) => buildWorkspaceToolDefinition(toolName, {
+      listFilesDescriptionVariant: args.listFilesDescriptionVariant,
+      listFilesParameterVariant: args.listFilesParameterVariant,
+      readFileDescriptionVariant: args.readFileDescriptionVariant,
+      readFileParameterVariant: args.readFileParameterVariant,
+      globFilesDescriptionVariant: args.globFilesDescriptionVariant,
+      globFilesParameterVariant: args.globFilesParameterVariant,
+      searchFilesDescriptionVariant: args.searchFilesDescriptionVariant,
+      searchFilesParameterVariant: args.searchFilesParameterVariant,
+    }))
     .filter((tool): tool is OpenAiCompatibleTool => Boolean(tool));
 }
 
@@ -477,6 +1065,96 @@ function readExpectedReplacementCount(args: WorkspaceFileArgs) {
   return value;
 }
 
+function readPositiveIntegerArg(args: {
+  value: unknown;
+  name: string;
+  max?: number;
+}) {
+  if (args.value === undefined) return undefined;
+  const value = Number(args.value);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${args.name} must be a positive integer.`);
+  }
+  return args.max ? Math.min(value, args.max) : value;
+}
+
+function readFileSliceArgs(args: WorkspaceFileArgs) {
+  const startLine = readPositiveIntegerArg({ value: args.startLine, name: "startLine" });
+  const endLine = readPositiveIntegerArg({ value: args.endLine, name: "endLine" });
+  const maxLines = readPositiveIntegerArg({ value: args.maxLines, name: "maxLines", max: 2000 });
+  const tailLines = readPositiveIntegerArg({ value: args.tailLines, name: "tailLines", max: 2000 });
+  if (tailLines !== undefined && (startLine !== undefined || endLine !== undefined)) {
+    throw new Error("tailLines cannot be combined with startLine or endLine.");
+  }
+  if (endLine !== undefined && startLine !== undefined && endLine < startLine) {
+    throw new Error("endLine must be greater than or equal to startLine.");
+  }
+  return {
+    startLine,
+    endLine,
+    maxLines,
+    tailLines,
+  };
+}
+
+function splitTextLines(content: string) {
+  const lines = content.split(/\r?\n/);
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+function sliceReadFileContent(args: {
+  content: string;
+  startLine?: number;
+  endLine?: number;
+  maxLines?: number;
+  tailLines?: number;
+}) {
+  const lines = splitTextLines(args.content);
+  const totalLines = lines.length;
+  if (
+    args.startLine === undefined &&
+    args.endLine === undefined &&
+    args.maxLines === undefined &&
+    args.tailLines === undefined
+  ) {
+    return {
+      content: args.content,
+      startLine: 1,
+      endLine: totalLines,
+      totalLines,
+      truncated: false,
+    };
+  }
+  if (args.tailLines !== undefined) {
+    const startIndex = Math.max(0, totalLines - args.tailLines);
+    const selected = lines.slice(startIndex);
+    return {
+      content: selected.join("\n"),
+      startLine: startIndex + 1,
+      endLine: startIndex + selected.length,
+      totalLines,
+      truncated: startIndex > 0,
+    };
+  }
+  const startLine = args.startLine ?? 1;
+  let endLine = args.endLine ?? totalLines;
+  if (args.maxLines !== undefined) {
+    endLine = Math.min(endLine, startLine + args.maxLines - 1);
+  }
+  const startIndex = Math.min(Math.max(startLine - 1, 0), totalLines);
+  const endIndex = Math.min(Math.max(endLine, 0), totalLines);
+  const selected = lines.slice(startIndex, endIndex);
+  const effectiveEndLine = selected.length ? startIndex + selected.length : startIndex;
+  return {
+    content: selected.join("\n"),
+    startLine,
+    endLine: effectiveEndLine,
+    totalLines,
+    truncated: startLine > 1 || effectiveEndLine < totalLines,
+  };
+}
+
 function countExactTextOccurrences(args: {
   content: string;
   oldText: string;
@@ -494,6 +1172,64 @@ function requireWorkspaceSearchQuery(args: WorkspaceFileArgs) {
   return query;
 }
 
+function requireWorkspaceGlobPattern(args: WorkspaceFileArgs) {
+  const pattern = typeof args.pattern === "string" && args.pattern.trim()
+    ? args.pattern.trim()
+    : typeof args.glob === "string" && args.glob.trim()
+      ? args.glob.trim()
+      : "";
+  if (!pattern) throw new Error("globFiles requires a non-empty pattern.");
+  return pattern;
+}
+
+function readWorkspaceMaxResults(args: WorkspaceFileArgs) {
+  if (args.maxResults === undefined) return undefined;
+  const value = Number(args.maxResults);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("maxResults must be a positive integer.");
+  }
+  return Math.min(value, 500);
+}
+
+function readWorkspaceMaxDepth(args: WorkspaceFileArgs) {
+  if (args.maxDepth === undefined) return 1;
+  const value = Number(args.maxDepth);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("maxDepth must be a positive integer.");
+  }
+  return Math.min(value, 10);
+}
+
+function readWorkspaceEntryType(args: WorkspaceFileArgs) {
+  if (args.entryType === undefined) return "all";
+  if (args.entryType === "all" || args.entryType === "files" || args.entryType === "directories") {
+    return args.entryType;
+  }
+  throw new Error("entryType must be one of all, files, or directories.");
+}
+
+function readWorkspaceContextLines(args: WorkspaceFileArgs) {
+  if (args.contextLines === undefined) return undefined;
+  const value = Number(args.contextLines);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error("contextLines must be a non-negative integer.");
+  }
+  return Math.min(value, 20);
+}
+
+function readWorkspaceExcludeGlobs(args: WorkspaceFileArgs) {
+  if (args.exclude === undefined) return [];
+  if (typeof args.exclude === "string" && args.exclude.trim()) {
+    return [args.exclude.trim()];
+  }
+  if (!Array.isArray(args.exclude)) {
+    throw new Error("exclude must be a glob string or an array of glob strings.");
+  }
+  return args.exclude.flatMap((item) =>
+    typeof item === "string" && item.trim() ? [item.trim()] : []
+  );
+}
+
 function requireShellCommand(args: WorkspaceFileArgs, toolName: string) {
   const command = typeof args.cmd === "string"
     ? args.cmd.trim()
@@ -726,6 +1462,66 @@ async function runWorkspaceCommand(args: {
   };
 }
 
+async function runWorkspaceCommandLimitedLines(args: {
+  workspaceRoot: string;
+  command: string[];
+  maxLines: number;
+  commandPrefix?: string[];
+}) {
+  const command = [
+    ...(args.commandPrefix ?? []),
+    ...args.command,
+  ];
+  const proc = Bun.spawn(command, {
+    cwd: resolve(args.workspaceRoot),
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+    detached: false,
+  });
+  const stderrPromise = new Response(proc.stderr).text();
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  const lines: string[] = [];
+  let pending = "";
+  let limitedByMaxResults = false;
+  try {
+    while (lines.length < args.maxLines) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      pending += decoder.decode(chunk.value, { stream: true });
+      const parts = pending.split(/\r?\n/);
+      pending = parts.pop() ?? "";
+      for (const part of parts) {
+        if (!part) continue;
+        lines.push(part);
+        if (lines.length >= args.maxLines) {
+          limitedByMaxResults = true;
+          break;
+        }
+      }
+    }
+    if (!limitedByMaxResults && pending.trim()) lines.push(pending);
+  } finally {
+    reader.releaseLock();
+  }
+  if (limitedByMaxResults) {
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+      // The command may already have exited.
+    }
+  }
+  const exitCode = limitedByMaxResults ? 0 : Number(await proc.exited);
+  const stderr = await stderrPromise;
+  return {
+    stdout: lines.join("\n"),
+    stderr,
+    exitCode,
+    limitedByMaxResults,
+  };
+}
+
 export function resolveLocalWorkspaceToolPath(args: {
   workspaceRoot: string;
   requestedPath: string;
@@ -744,19 +1540,33 @@ async function readFileTool(args: {
 }): Promise<AgentRuntimeToolResult> {
   const parsed = parseWorkspaceToolArguments(args.call.arguments);
   const requestedPath = requireWorkspaceToolPath(parsed);
+  const sliceArgs = readFileSliceArgs(parsed);
   const absolutePath = resolveLocalWorkspaceToolPath({
     workspaceRoot: args.workspaceRoot,
     requestedPath,
   });
   const content = await readFile(absolutePath, "utf8");
-  return {
+  const activity = extractActivity(parsed);
+  const sliced = sliceReadFileContent({
     content,
+    ...sliceArgs,
+  });
+  return {
+    content: sliced.content,
     metadata: {
       path: normalizeWorkspaceRelativePath({
         workspaceRoot: resolve(args.workspaceRoot),
         targetPath: absolutePath,
       }),
-      bytes: Buffer.byteLength(content),
+      bytes: Buffer.byteLength(sliced.content),
+      totalBytes: Buffer.byteLength(content),
+      startLine: sliced.startLine,
+      endLine: sliced.endLine,
+      totalLines: sliced.totalLines,
+      truncated: sliced.truncated,
+      ...(sliceArgs.maxLines ? { maxLines: sliceArgs.maxLines } : {}),
+      ...(sliceArgs.tailLines ? { tailLines: sliceArgs.tailLines } : {}),
+      ...(activity ? { activity } : {}),
     },
   };
 }
@@ -783,11 +1593,13 @@ async function writeFileTool(args: {
     workspaceRoot: resolve(args.workspaceRoot),
     targetPath: absolutePath,
   });
+  const activity = extractActivity(parsed);
   return {
     content: `wrote ${relativePath}`,
     metadata: {
       path: relativePath,
       bytes: Buffer.byteLength(content),
+      ...(activity ? { activity } : {}),
     },
   };
 }
@@ -819,12 +1631,14 @@ async function editFileTool(args: {
     workspaceRoot: resolve(args.workspaceRoot),
     targetPath: absolutePath,
   });
+  const activity = extractActivity(parsed);
   return {
     content: `replaced ${replacementCount} occurrence${replacementCount === 1 ? "" : "s"} in ${relativePath}`,
     metadata: {
       path: relativePath,
       replacements: replacementCount,
       bytes: Buffer.byteLength(nextContent),
+      ...(activity ? { activity } : {}),
     },
   };
 }
@@ -843,6 +1657,58 @@ async function formatWorkspaceDirEntry(args: {
   return info.isDirectory() ? `${relativePath}/` : relativePath;
 }
 
+async function listWorkspaceEntries(args: {
+  workspaceRoot: string;
+  dirPath: string;
+  maxDepth: number;
+  entryType: "all" | "files" | "directories";
+  maxResults?: number;
+}) {
+  const entries: string[] = [];
+  let truncated = false;
+  let visitedEntries = 0;
+  let limitedByMaxDepth = false;
+  const visit = async (dirPath: string, depth: number) => {
+    if (truncated) return;
+    const names = (await readdir(dirPath)).sort((left, right) => left.localeCompare(right));
+    for (const name of names) {
+      if (truncated) break;
+      const absolutePath = resolve(dirPath, name);
+      const info = await stat(absolutePath);
+      visitedEntries += 1;
+      const relativePath = normalizeWorkspaceRelativePath({
+        workspaceRoot: resolve(args.workspaceRoot),
+        targetPath: absolutePath,
+      });
+      const isDirectory = info.isDirectory();
+      if (
+        args.entryType === "all" ||
+        (args.entryType === "files" && !isDirectory) ||
+        (args.entryType === "directories" && isDirectory)
+      ) {
+        entries.push(isDirectory ? `${relativePath}/` : relativePath);
+        if (args.maxResults && entries.length >= args.maxResults) {
+          truncated = true;
+          break;
+        }
+      }
+      if (isDirectory && depth < args.maxDepth) {
+        await visit(absolutePath, depth + 1);
+      } else if (isDirectory && depth >= args.maxDepth && !limitedByMaxDepth) {
+        const childNames = await readdir(absolutePath);
+        limitedByMaxDepth = childNames.length > 0;
+      }
+    }
+  };
+  await visit(args.dirPath, 1);
+  return {
+    entries,
+    truncated,
+    visitedEntries,
+    limitedByMaxDepth,
+  };
+}
+
 async function listFilesTool(args: {
   call: AgentRuntimeToolCallInput;
   workspaceRoot: string;
@@ -851,21 +1717,32 @@ async function listFilesTool(args: {
   const requestedPath = typeof parsed.path === "string" && parsed.path.trim()
     ? parsed.path.trim()
     : ".";
+  const maxDepth = readWorkspaceMaxDepth(parsed);
+  const maxResults = readWorkspaceMaxResults(parsed);
+  const entryType = readWorkspaceEntryType(parsed);
   const dirPath = resolveLocalWorkspaceToolPath({
     workspaceRoot: args.workspaceRoot,
     requestedPath,
   });
-  const names = (await readdir(dirPath)).sort((left, right) => left.localeCompare(right));
-  const entries = await Promise.all(names.map((name) => formatWorkspaceDirEntry({
+  const listed = await listWorkspaceEntries({
     workspaceRoot: args.workspaceRoot,
     dirPath,
-    name,
-  })));
+    maxDepth,
+    maxResults,
+    entryType,
+  });
   return {
-    content: entries.join("\n"),
+    content: listed.entries.join("\n"),
     metadata: {
       path: requestedPath,
-      count: entries.length,
+      count: listed.entries.length,
+      maxDepth,
+      entryType,
+      truncated: listed.truncated,
+      limitedByMaxResults: listed.truncated,
+      limitedByMaxDepth: listed.limitedByMaxDepth,
+      visitedEntries: listed.visitedEntries,
+      ...(maxResults ? { maxResults } : {}),
     },
   };
 }
@@ -876,6 +1753,11 @@ async function searchFilesTool(args: {
 }): Promise<AgentRuntimeToolResult> {
   const parsed = parseWorkspaceToolArguments(args.call.arguments);
   const query = requireWorkspaceSearchQuery(parsed);
+  const exclude = readWorkspaceExcludeGlobs(parsed);
+  const maxResults = readWorkspaceMaxResults(parsed);
+  const contextLines = readWorkspaceContextLines(parsed);
+  const literal = parsed.literal === true;
+  const caseSensitive = parsed.caseSensitive === false ? false : true;
   const requestedPath = typeof parsed.path === "string" && parsed.path.trim()
     ? parsed.path.trim()
     : ".";
@@ -888,47 +1770,336 @@ async function searchFilesTool(args: {
     workspaceRoot: resolve(args.workspaceRoot),
     targetPath: searchPath,
   });
+  const rgCommand = [
+    "rg",
+    "--line-number",
+    "--no-heading",
+    "--hidden",
+    ...(literal ? ["--fixed-strings"] : []),
+    ...(caseSensitive ? [] : ["--ignore-case"]),
+    ...(contextLines !== undefined ? ["--context", String(contextLines)] : []),
+    ...(includeIgnored ? ["--no-ignore"] : []),
+    "--glob",
+    "!node_modules",
+    "--glob",
+    "!.git",
+    ...exclude.flatMap((excludePattern) => ["--glob", `!${excludePattern}`]),
+    "--",
+    query,
+    relativeSearchPath,
+  ];
+  const grepCommand = [
+    "grep",
+    "-R",
+    "-n",
+    "-I",
+    ...(literal ? ["-F"] : []),
+    ...(caseSensitive ? [] : ["-i"]),
+    ...(contextLines !== undefined ? ["-C", String(contextLines)] : []),
+    "--exclude-dir=node_modules",
+    "--exclude-dir=.git",
+    ...exclude.flatMap((excludePattern) => ["--exclude", excludePattern]),
+    query,
+    relativeSearchPath,
+  ];
   const result = await (async () => {
     try {
-      return await runWorkspaceCommand({
-        workspaceRoot: args.workspaceRoot,
-        command: [
-          "rg",
-          "--line-number",
-          "--no-heading",
-          "--hidden",
-          ...(includeIgnored ? ["--no-ignore"] : []),
-          "--glob",
-          "!node_modules",
-          "--glob",
-          "!.git",
-          query,
-          relativeSearchPath,
-        ],
-      });
+      return maxResults && !contextLines
+        ? await runWorkspaceCommandLimitedLines({
+            workspaceRoot: args.workspaceRoot,
+            command: rgCommand,
+            maxLines: maxResults,
+          })
+        : await runWorkspaceCommand({
+            workspaceRoot: args.workspaceRoot,
+            command: rgCommand,
+          });
     } catch {
-      return await runWorkspaceCommand({
-        workspaceRoot: args.workspaceRoot,
-        command: [
-          "grep",
-          "-R",
-          "-n",
-          "-I",
-          "--exclude-dir=node_modules",
-          "--exclude-dir=.git",
-          query,
-          relativeSearchPath,
-        ],
-      });
+      return maxResults && !contextLines
+        ? await runWorkspaceCommandLimitedLines({
+            workspaceRoot: args.workspaceRoot,
+            command: grepCommand,
+            maxLines: maxResults,
+          })
+        : await runWorkspaceCommand({
+            workspaceRoot: args.workspaceRoot,
+            command: grepCommand,
+          });
     }
   })();
+  let outputLines = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd().replace(/^\.\//, ""))
+    .filter(Boolean);
+  let limitedByMaxResults = "limitedByMaxResults" in result && result.limitedByMaxResults === true;
+  if (outputLines.length === 0 && result.exitCode === 0 && (includeIgnored || !(await hasRootGitignore(args.workspaceRoot)))) {
+    const fallback = await scanWorkspaceTextMatches({
+      workspaceRoot: args.workspaceRoot,
+      relativeSearchPath,
+      query,
+      exclude,
+      maxResults,
+      literal,
+      caseSensitive,
+      contextLines,
+    });
+    outputLines = fallback.lines;
+    limitedByMaxResults = fallback.limitedByMaxResults;
+  }
+  if (contextLines && outputLines.length > 0) {
+    const limited = limitSearchOutputByMatches(outputLines, maxResults);
+    outputLines = limited.lines;
+    limitedByMaxResults = limitedByMaxResults || limited.truncated;
+  }
+  const matchLines = outputLines.filter((line) => /:\d+:/.test(line));
+  const matchedFiles = Array.from(new Set(matchLines.flatMap((line) => {
+    const match = line.match(/^(.*?):\d+:/);
+    return match?.[1] ? [match[1]] : [];
+  })));
   return {
-    content: result.content,
+    content: outputLines.join("\n"),
     metadata: {
       query,
       path: requestedPath,
+      searchedPath: relativeSearchPath,
+      exclude,
       includeIgnored,
+      literal,
+      caseSensitive,
+      ...(contextLines === undefined ? {} : { contextLines }),
+      count: outputLines.length,
+      matchCount: matchLines.length,
+      matchedFiles,
+      truncated: limitedByMaxResults,
+      limitedByMaxResults,
+      ...(maxResults ? { maxResults } : {}),
       exitCode: result.exitCode,
+      ...(extractActivity(parsed) ? { activity: extractActivity(parsed) } : {}),
+    },
+  };
+}
+
+async function hasRootGitignore(workspaceRoot: string) {
+  try {
+    await stat(resolve(workspaceRoot, ".gitignore"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readRootGitignorePatterns(workspaceRoot: string) {
+  try {
+    const content = await readFile(resolve(workspaceRoot, ".gitignore"), "utf8");
+    return content
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#") && !line.startsWith("!"))
+      .map((line) => {
+        const unanchored = line.replace(/^\//, "");
+        return unanchored.endsWith("/") ? `${unanchored}**` : unanchored;
+      });
+  } catch {
+    return [];
+  }
+}
+
+async function filterRootGitignoredFiles(args: {
+  workspaceRoot: string;
+  files: string[];
+  includeIgnored: boolean;
+}) {
+  if (args.includeIgnored) return args.files;
+  const patterns = await readRootGitignorePatterns(args.workspaceRoot);
+  if (patterns.length === 0) return args.files;
+  const globs = patterns.map((pattern) => new Bun.Glob(pattern));
+  return args.files.filter((file) => !globs.some((glob) => glob.match(file)));
+}
+
+function scanWorkspaceGlobFiles(args: {
+  workspaceRoot: string;
+  pattern: string;
+  relativeSearchPath: string;
+  exclude: string[];
+}) {
+  const pathPrefix = args.relativeSearchPath === "."
+    ? ""
+    : `${args.relativeSearchPath.replace(/\/+$/, "")}/`;
+  return Array.from(new Bun.Glob(args.pattern).scanSync({
+    cwd: args.workspaceRoot,
+    dot: true,
+    onlyFiles: true,
+  }))
+    .map((line) => line.trim().replace(/^\.\//, ""))
+    .filter(Boolean)
+    .filter((line) => !line.startsWith(".git/") && !line.startsWith("node_modules/"))
+    .filter((line) => !pathPrefix || line === args.relativeSearchPath || line.startsWith(pathPrefix))
+    .filter((line) => !args.exclude.some((pattern) => new Bun.Glob(pattern).match(line)))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function limitSearchOutputByMatches(lines: string[], maxResults?: number) {
+  if (!maxResults) return { lines, truncated: false };
+  const limited: string[] = [];
+  let matches = 0;
+  for (const line of lines) {
+    if (/:\d+:/.test(line)) {
+      if (matches >= maxResults) {
+        return { lines: limited, truncated: true };
+      }
+      matches += 1;
+    }
+    limited.push(line);
+  }
+  return { lines: limited, truncated: false };
+}
+
+async function scanWorkspaceTextMatches(args: {
+  workspaceRoot: string;
+  relativeSearchPath: string;
+  query: string;
+  exclude: string[];
+  maxResults?: number;
+  literal: boolean;
+  caseSensitive: boolean;
+  contextLines?: number;
+}) {
+  const files = scanWorkspaceGlobFiles({
+    workspaceRoot: args.workspaceRoot,
+    pattern: "**/*",
+    relativeSearchPath: args.relativeSearchPath,
+    exclude: args.exclude,
+  });
+  const results: string[] = [];
+  const seenContext = new Set<string>();
+  let matchCount = 0;
+  const literalQuery = args.caseSensitive ? args.query : args.query.toLowerCase();
+  const regex = args.literal
+    ? undefined
+    : new RegExp(args.query, args.caseSensitive ? "" : "i");
+  const pushLine = (file: string, lineNumber: number, text: string, isMatch: boolean) => {
+    const separator = isMatch ? ":" : "-";
+    const key = `${file}:${lineNumber}:${separator}`;
+    if (seenContext.has(key)) return;
+    seenContext.add(key);
+    results.push(`${file}${separator}${lineNumber}${separator}${text}`);
+  };
+  for (const file of files) {
+    let content = "";
+    try {
+      content = await readFile(resolve(args.workspaceRoot, file), "utf8");
+    } catch {
+      continue;
+    }
+    if (content.includes("\u0000")) continue;
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index] ?? "";
+      const haystack = args.caseSensitive ? line : line.toLowerCase();
+      const matched = args.literal
+        ? haystack.includes(literalQuery)
+        : regex?.test(line) === true;
+      if (!matched) continue;
+      matchCount += 1;
+      const contextLines = args.contextLines ?? 0;
+      const start = Math.max(0, index - contextLines);
+      const end = Math.min(lines.length - 1, index + contextLines);
+      for (let contextIndex = start; contextIndex <= end; contextIndex += 1) {
+        pushLine(file, contextIndex + 1, lines[contextIndex] ?? "", contextIndex === index);
+      }
+      if (args.maxResults && matchCount >= args.maxResults) {
+        return {
+          lines: results,
+          limitedByMaxResults: true,
+        };
+      }
+    }
+  }
+  return {
+    lines: results,
+    limitedByMaxResults: false,
+  };
+}
+
+async function globFilesTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const pattern = requireWorkspaceGlobPattern(parsed);
+  const exclude = readWorkspaceExcludeGlobs(parsed);
+  const maxResults = readWorkspaceMaxResults(parsed);
+  const requestedPath = typeof parsed.path === "string" && parsed.path.trim()
+    ? parsed.path.trim()
+    : ".";
+  const includeIgnored = parsed.includeIgnored === true;
+  const searchPath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  const relativeSearchPath = normalizeWorkspaceRelativePath({
+    workspaceRoot: resolve(args.workspaceRoot),
+    targetPath: searchPath,
+  });
+  const command = [
+      "rg",
+      "--files",
+      "--hidden",
+      ...(includeIgnored ? ["--no-ignore"] : []),
+      "--glob",
+      pattern,
+      "--glob",
+      "!node_modules",
+      "--glob",
+      "!.git",
+      ...exclude.flatMap((excludePattern) => ["--glob", `!${excludePattern}`]),
+      ...(relativeSearchPath === "." ? [] : [relativeSearchPath]),
+    ];
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command,
+  });
+  const pathPrefix = relativeSearchPath === "." ? "" : `${relativeSearchPath.replace(/\/+$/, "")}/`;
+  let files = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^\.\//, ""))
+    .filter(Boolean)
+    .filter((line) => !pathPrefix || line === relativeSearchPath || line.startsWith(pathPrefix))
+    .sort((left, right) => left.localeCompare(right));
+  files = await filterRootGitignoredFiles({
+    workspaceRoot: args.workspaceRoot,
+    files,
+    includeIgnored,
+  });
+  if (files.length === 0 && (includeIgnored || !(await hasRootGitignore(args.workspaceRoot)))) {
+    files = scanWorkspaceGlobFiles({
+      workspaceRoot: args.workspaceRoot,
+      pattern,
+      relativeSearchPath,
+      exclude,
+    });
+  }
+  const commandLimitedByMaxResults = result.limitedByMaxResults === true;
+  const totalCount = commandLimitedByMaxResults ? undefined : files.length;
+  const limitedFiles = maxResults ? files.slice(0, maxResults) : files;
+  const limitedByMaxResults = commandLimitedByMaxResults || limitedFiles.length < (totalCount ?? limitedFiles.length);
+  const activity = extractActivity(parsed);
+  return {
+    content: limitedFiles.join("\n"),
+    metadata: {
+      pattern,
+      effectivePattern: pathPrefix ? `${pathPrefix}${pattern}` : pattern,
+      path: requestedPath,
+      searchedPath: relativeSearchPath,
+      exclude,
+      includeIgnored,
+      count: limitedFiles.length,
+      ...(totalCount === undefined ? {} : { totalCount }),
+      truncated: limitedByMaxResults,
+      limitedByMaxResults,
+      ...(maxResults ? { maxResults } : {}),
+      exitCode: result.exitCode,
+      ...(activity ? { activity } : {}),
     },
   };
 }
@@ -1062,9 +2233,14 @@ async function execShellTool(args: {
     outputLimit: args.commandOutputLimit,
     commandPrefix: args.commandPrefix,
   });
+  const activity = extractActivity(parsed);
   return {
     content: result.content,
-    metadata: { exitCode: result.exitCode, timedOut: result.timedOut },
+    metadata: {
+      exitCode: result.exitCode,
+      timedOut: result.timedOut,
+      ...(activity ? { activity } : {}),
+    },
   };
 }
 
@@ -1074,6 +2250,10 @@ export function createLocalWorkspaceToolExecutors(args: LocalWorkspaceToolArgs)
       call,
       workspaceRoot: args.workspaceRoot,
     }),
+    globFiles: (call: AgentRuntimeToolCallInput) => globFilesTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
     listFiles: (call: AgentRuntimeToolCallInput) => listFilesTool({
       call,
       workspaceRoot: args.workspaceRoot,