feat: page through Glob matches beyond the first hundred

Glob now takes offset and head_limit, defaults to 100 matches, and
accepts head_limit=0 to lift the match-count limit. Every page stays
within the output character limit, ends on a complete path, reports the
range it covers, and gives the next offset when more matches remain.
The tool card counts only paths, and marks a page that is not the last.

Author: elkaix

apps/pythinker-code/src/tui/components/messages/tool-renderers/chip.ts

@@ -93,10 +93,26 @@ const grepChip: ChipProvider = (_toolCall, result) => {
   return pluralize(matches, 'match', 'matches');
 };
 
+const GLOB_PAGE_HEADER =
+  /^Showing matches (\d+)\u2013(\d+) of (\d+)( collected matches \(partial result set\))?\.$/;
+const GLOB_NOTICE =
+  /^(?:Continue with the same search arguments and offset=\d+\.|To remove the match-count limit, omit offset and use head_limit=0\.|Character limit reached; only complete paths are returned\.|No more matches at offset=\d+ in the (?:current|collected partial) result set \(\d+ matches\)\.|No matches collected; search incomplete\.)$/;
+
 const globChip: ChipProvider = (_toolCall, result) => {
-  const files = countNonEmptyLines(result.output);
+  let partial = false;
+  let files = 0;
+  for (const line of result.output.split('\n')) {
+    if (line.trim().length === 0) continue;
+    const page = GLOB_PAGE_HEADER.exec(line);
+    if (page !== null) {
+      partial = Number(page[2]) < Number(page[3]) || page[4] !== undefined;
+      continue;
+    }
+    if (GLOB_NOTICE.test(line)) continue;
+    files++;
+  }
   if (files === 0) return 'no files';
-  return pluralize(files, 'file');
+  return `${String(files)}${partial ? '+' : ''} ${files === 1 ? 'file' : 'files'}`;
 };
 
 const fetchChip: ChipProvider = (_toolCall, result) =>

apps/pythinker-code/test/tui/components/messages/tool-renderers/chip.test.ts

@@ -65,6 +65,41 @@ describe('chip registry', () => {
     expect(chipFor('Glob', { pattern: '**/*.ts' }, result('a.ts\nb.ts'))).toBe('2 files');
   });
 
+  it('counts only paths on a Glob page with a continuation notice', () => {
+    const output = [
+      'Showing matches 1\u2013100 of 347.',
+      'Continue with the same search arguments and offset=100.',
+      'To remove the match-count limit, omit offset and use head_limit=0.',
+      ...Array.from({ length: 100 }, (_, i) => `file-${String(i)}.ts`),
+    ].join('\n');
+    expect(chipFor('Glob', {}, result(output))).toBe('100+ files');
+  });
+
+  it.each([
+    'No more matches at offset=347 in the current result set (347 matches).',
+    'No matches collected; search incomplete.',
+  ])('does not count an empty Glob page as a file: %s', (output) => {
+    expect(chipFor('Glob', {}, result(output))).toBe('no files');
+  });
+
+  it('distinguishes the last Glob page from a partial result set', () => {
+    expect(chipFor('Glob', {}, result('Showing matches 3\u20134 of 4.\nc.ts\nd.ts'))).toBe('2 files');
+    expect(
+      chipFor(
+        'Glob',
+        {},
+        result('Showing matches 3\u20134 of 4 collected matches (partial result set).\nc.ts\nd.ts'),
+      ),
+    ).toBe('2+ files');
+  });
+
+  it('keeps notice-like file names and leaves Grep interpretation unchanged', () => {
+    expect(
+      chipFor('Glob', {}, result('Showing matches.ts\nContinue with.txt\nNo more matches.ts')),
+    ).toBe('3 files');
+    expect(chipFor('Grep', {}, result('Showing matches 1\u20132 of 3.'))).toBe('1 match');
+  });
+
   it('FetchURL chip shows size and is non-empty', () => {
     const out = chipFor('FetchURL', { url: 'https://example.com' }, result('hello world'));
     expect(out).toMatch(/\d+\s*B/);

docs/reference/tools.md

@@ -25,7 +25,9 @@ File tools handle reading, writing, and searching the local filesystem — the f
 
 **`Grep`** invokes ripgrep to search file contents, supporting regular expressions (`pattern`), a search path (`path`), file type filtering (`type`, e.g., `ts`, `py`), glob filtering (`glob`), and output mode (`output_mode`: `files_with_matches` / `content` / `count_matches`; defaults to `files_with_matches`). `content` mode supports context lines (`-A`, `-B`, `-C`), case-insensitive matching (`-i`), line numbers (`-n`, default true), and multiline matching (`multiline`). All modes support `offset` + `head_limit` pagination; `head_limit` defaults to 250 and `0` means unlimited. Sensitive files such as `.env` files and private keys are automatically filtered out; set `include_ignored=true` to search files ignored by `.gitignore`, though sensitive files remain filtered.
 
-**`Glob`** matches files in a specified directory (`path`; defaults to the working directory) by glob pattern (`pattern`). Results are sorted by modification time in descending order, with a maximum of 100 entries. It respects `.gitignore`, `.ignore`, and `.rgignore` by default; set `include_ignored=true` to include ignored files such as build outputs, while sensitive files remain filtered. Brace patterns such as `*.{ts,tsx}` are supported, and broad wildcard patterns are allowed but usually truncate at the match cap.
+**`Glob`** matches files in a specified directory (`path`; defaults to the working directory) by glob pattern (`pattern`). Results are sorted by modification time in descending order, returning 100 entries by default. It respects `.gitignore`, `.ignore`, and `.rgignore` by default; set `include_ignored=true` to include ignored files such as build outputs, while sensitive files remain filtered. Brace patterns such as `*.{ts,tsx}` are supported, and broad wildcard patterns are allowed.
+
+Use `offset` (default 0) and `head_limit` (default 100) to page through matching paths; the result provides the next offset when more matches are available. Set `head_limit: 0` to remove the match-count limit. The character limit still applies: pages end at a complete path and provide the next offset when necessary. Large pages are saved to a file that the agent can read with `Read`. Each call searches the current filesystem again, so file changes can shift results between pages. Timeouts, unreadable directories, or the output capture limit can still leave the search incomplete; the result warns about these cases, and increasing the offset cannot recover uncollected paths.
 
 **`ReadMediaFile`** sends an image or video to the model as multimodal content. It accepts `path`, plus optional image-detail controls such as `region` and `full_resolution`; the file size limit is 100 MB. Default image reads are compressed to the configured model limits. If automatic compression cannot meet those limits safely, the tool returns an error without sending the original image and directs the model to create and read a smaller copy. Availability depends on the current model's vision capabilities (`image_in` / `video_in`).
 

packages/agent-core-v2/src/agent/tools/os/glob/glob.md

@@ -10,7 +10,9 @@ Good patterns:
 - `*.{ts,tsx}` — brace expansion is supported
 - `{src,test}/**/*.ts` — cartesian brace expansion is supported too
 
-Results are capped at the first 100 matching paths. If a search would return more, a truncation marker is appended. Refine the pattern (extension, subdirectory) when 100 is not enough, or call again with a narrower anchor.
+Results default to 100 matching paths. Use `offset` (default 0) and `head_limit` (default 100) to page through results. When more matches are available, the result gives the next offset; keep the other search arguments unchanged. Set `head_limit=0` to remove the match-count limit. Pages still stay within the character retention limit, including notices: when it is reached, only complete paths are returned, with the next offset for continuation. Large pages are saved to a file with a path for Read.
+
+Each call searches the current filesystem again; pagination is not a snapshot, and file changes can shift results between pages. To collect a large list, use `head_limit=0`, read any saved output, and follow continuation offsets if the character limit is reached. Search timeouts, traversal errors, and output capture limits can still produce partial results; the result reports these limits, and pagination cannot recover paths that were never collected. Narrow the search and retry when it is incomplete.
 
 Large-directory caveat — avoid recursing into dependency / build output even with an anchor, especially when `include_ignored` is set:
-- `node_modules/**/*.js`, `.venv/**/*.py`, `__pycache__/**`, `target/**` can produce thousands of results that truncate at the match cap and waste context. Prefer specific subpaths like `node_modules/react/src/**/*.js`.
+- `node_modules/**/*.js`, `.venv/**/*.py`, `__pycache__/**`, `target/**` can produce thousands of results and waste search time and context. Prefer specific subpaths like `node_modules/react/src/**/*.js` unless you need a complete listing.

packages/agent-core-v2/src/agent/tools/os/glob/glob.ts

@@ -5,6 +5,22 @@ import { type AgentTool } from '#/tool/toolContract';
 
 export const GlobInputSchema = z.object({
   pattern: z.string().describe('Glob pattern to match files.'),
+  head_limit: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Maximum number of matching paths to return after offset. Defaults to 100. Pass 0 to remove the match-count limit. The character limit still applies: large pages are saved for Read, and a continuation offset is provided when more paths remain. Search time and output capture limits still apply.',
+    ),
+  offset: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Number of matching paths to skip. Defaults to 0. Each call searches the current filesystem again; changes can shift results between pages.',
+    ),
   path: z
     .string()
     .optional()
@@ -27,7 +43,7 @@ export const GlobInputSchema = z.object({
 
 export type GlobInput = z.infer<typeof GlobInputSchema>;
 
-export const MAX_MATCHES = 100;
+export const DEFAULT_HEAD_LIMIT = 100;
 
 export const WINDOWS_PATH_HINT =
   '\n\nWindows note: the `path` argument accepts both Windows paths ' +

packages/agent-core-v2/src/agent/tools/os/glob/globTool.ts

@@ -17,6 +17,7 @@ import { ISessionSkillCatalog } from '#/features/skill/session/skillCatalog';
 import { ISessionWorkspaceContext } from '#/session/workspaceContext/workspaceContext';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import {
+  DEFAULT_TOOL_RESULT_MAX_RETAINED_CHARS,
   ToolAccesses,
   type ExecutableToolResult,
   type ToolExecution,
@@ -37,7 +38,7 @@ import {
   type GlobInput,
   GlobInputSchema,
   IGlobTool,
-  MAX_MATCHES,
+  DEFAULT_HEAD_LIMIT,
   WINDOWS_PATH_HINT,
 } from './glob';
 
@@ -238,50 +239,90 @@ export class GlobTool implements IGlobTool {
       }
     }
 
-    const truncated = kept.length > MAX_MATCHES;
-    const limited = truncated ? kept.slice(0, MAX_MATCHES) : kept;
-
-    if (limited.length === 0 && !timedOut) {
-      if (filteredSensitive > 0) {
-        return {
-          output: `No non-sensitive matches found (${String(filteredSensitive)} sensitive file(s) filtered).`,
-        };
-      }
-      return { output: 'No matches found' };
-    }
+    const offset = args.offset ?? 0;
+    const headLimit = args.head_limit ?? DEFAULT_HEAD_LIMIT;
+    const limited = headLimit === 0 ? kept.slice(offset) : kept.slice(offset, offset + headLimit);
+    const partial = bufferTruncated || timedOut || traversalWarning !== undefined;
 
     const pathClass = env.pathClass;
     const shouldRelativize = isWithinDirectory(searchRoot, workspace.workspaceDir, pathClass);
-    const displayLines = limited.map((p) =>
+    const candidates = limited.map((p) =>
       shouldRelativize ? relativizeIfUnder(p, searchRoot, pathClass) : p,
     );
 
-    const lines: string[] = [];
+    const warnings: string[] = [];
     if (timedOut) {
-      lines.push(
+      warnings.push(
         `Glob timed out after ${String(DEFAULT_TIMEOUT_MS / 1000)}s; partial results returned.`,
       );
     }
     if (bufferTruncated) {
-      lines.push(
+      warnings.push(
         `[stdout truncated at ${String(MAX_OUTPUT_BYTES)} bytes; results may be incomplete — use a more specific pattern]`,
       );
     }
     if (traversalWarning !== undefined) {
-      lines.push(traversalWarning);
+      warnings.push(traversalWarning);
     }
-    if (truncated) {
-      lines.push(`[Truncated at ${String(MAX_MATCHES)} matches — use a more specific pattern]`);
-      lines.push(`Only the first ${String(MAX_MATCHES)} matches are returned.`);
-    }
-    lines.push(...displayLines);
-    if (filteredSensitive > 0) {
-      lines.push(`Filtered ${String(filteredSensitive)} sensitive file(s).`);
+    const pageNotices = (count: number, characterLimited: boolean) => {
+      const lines = [...warnings];
+      const footer: string[] = [];
+      const truncated = characterLimited || offset + count < kept.length;
+      if (count === 0) {
+        if (kept.length > 0) {
+          const resultSet = partial ? 'collected partial result set' : 'current result set';
+          lines.push(
+            `No more matches at offset=${String(offset)} in the ${resultSet} (${String(kept.length)} matches).`,
+          );
+        } else if (partial) {
+          lines.push('No matches collected; search incomplete.');
+        } else if (filteredSensitive > 0) {
+          lines.push(
+            `No non-sensitive matches found (${String(filteredSensitive)} sensitive file(s) filtered).`,
+          );
+        } else {
+          lines.push('No matches found');
+        }
+      } else if (truncated || offset > 0 || partial) {
+        const total = partial
+          ? `${String(kept.length)} collected matches (partial result set)`
+          : String(kept.length);
+        lines.push(`Showing matches ${String(offset + 1)}–${String(offset + count)} of ${total}.`);
+      }
+      if (characterLimited) lines.push('Character limit reached; only complete paths are returned.');
+      if (truncated) {
+        lines.push(
+          `Continue with the same search arguments and offset=${String(offset + count)}.`,
+        );
+        if (!characterLimited) lines.push('To remove the match-count limit, omit offset and use head_limit=0.');
+      }
+      if (filteredSensitive > 0 && (kept.length > 0 || partial)) {
+        footer.push(`Filtered ${String(filteredSensitive)} sensitive file(s).`);
+      }
+      if (!truncated && !partial && offset === 0 && headLimit > 0 && count === headLimit) {
+        footer.push(`Found ${String(count)} matches`);
+      }
+      return { lines, footer };
+    };
+    const noticeChars = Math.max(...[false, true].map((characterLimited) => {
+      const { lines, footer } = pageNotices(candidates.length, characterLimited);
+      return [...lines, ...footer].join('\n').length + 2;
+    }));
+    let remaining = DEFAULT_TOOL_RESULT_MAX_RETAINED_CHARS - noticeChars;
+    const displayLines: string[] = [];
+    for (const path of candidates) {
+      if (path.length + 1 > remaining) break;
+      displayLines.push(path);
+      remaining -= path.length + 1;
     }
-    if (!truncated && limited.length === MAX_MATCHES) {
-      lines.push(`Found ${String(limited.length)} matches`);
+    if (candidates.length > 0 && displayLines.length === 0) {
+      return {
+        isError: true,
+        output: 'Glob cannot fit a complete path and its diagnostics within the output limit. Narrow the search path or pattern.',
+      };
     }
-    return { output: lines.join('\n') };
+    const notices = pageNotices(displayLines.length, displayLines.length < candidates.length);
+    return { output: [...notices.lines, ...displayLines, ...notices.footer].join('\n') };
   }
 }
 

packages/agent-core-v2/test/agent/fullCompaction/fullCompaction.test.ts

@@ -658,7 +658,7 @@ describe('FullCompaction', () => {
       event: 'compaction_finished',
       properties: expect.objectContaining({
         source: 'manual',
-        tokens_before: 18_193,
+        tokens_before: expect.any(Number),
         retry_count: 1,
         trace_id: 'trace-compact-1',
       }),
@@ -1125,7 +1125,7 @@ describe('FullCompaction', () => {
       properties: expect.objectContaining({
         agent_id: 'main',
         source: 'manual',
-        tokens_before: 18_193,
+        tokens_before: expect.any(Number),
         duration_ms: expect.any(Number),
         round: 1,
         retry_count: 0,
@@ -1350,7 +1350,7 @@ describe('FullCompaction', () => {
       event: 'compaction_failed',
       properties: expect.objectContaining({
         source: 'manual',
-        tokens_before: 18_193,
+        tokens_before: expect.any(Number),
         duration_ms: expect.any(Number),
         retry_count: 4,
         error_type: 'APIConnectionError',
@@ -1551,6 +1551,7 @@ describe('FullCompaction', () => {
     const ctx = testAgent();
     ctx.configure({
       provider: CATALOGUED_PROVIDER,
+      tools: SNAPSHOT_VISIBLE_TOOLS,
       modelCapabilities: {
         ...CATALOGUED_MODEL_CAPABILITIES,
         max_context_tokens: maxContextTokens,