@dreb/coding-agent 2.30.1 → 2.31.1

package/dist/core/nested-context.d.ts

@@ -0,0 +1,107 @@
+export interface LoadedContextFile {
+    /** Absolute path of the loaded context file. */
+    path: string;
+    /** File content (HTML comments already stripped by the loader). */
+    content: string;
+}
+export interface NestedContextCollection {
+    /** Context files newly loaded during this collection pass. */
+    files: LoadedContextFile[];
+    /** Whether any existing context file failed to read and should be retried later. */
+    hadReadError: boolean;
+}
+/**
+ * Extract the target of a leading `cd <dir>` from a bash command.
+ *
+ * Covers the overwhelming majority of directory-changing bash commands (analysis of
+ * real session logs: ~75% of bash calls start with `cd`, ~97% of those with an absolute
+ * path). Returns the raw, unresolved path string (with a leading `~` preserved) or
+ * `null` when the command does not begin with a simple `cd`.
+ */
+export declare function parseLeadingCd(command: string): string | null;
+/**
+ * Resolve the absolute directory a tool call is about to operate in, or `null` when the
+ * tool/argument shape does not identify a directory we should react to.
+ */
+export declare function resolveTargetDir(toolName: string, args: Record<string, unknown> | undefined, cwd: string): string | null;
+/**
+ * Predicate deciding whether a collected context file should be *suppressed* from the
+ * injected block because the triggering tool call already delivers its content (e.g. a
+ * `read` of the file itself, or a `bash` command that prints it). Suppressed files are
+ * still marked as loaded so they are never injected later — they are simply not
+ * duplicated into the result that already contains them.
+ */
+export type SuppressPredicate = (file: LoadedContextFile) => boolean;
+/**
+ * Collect nested context files for `targetDir`, walking up to the ceiling described in
+ * {@link resolveWalkDirs}. Files whose realpath is already in `alreadyLoaded` are skipped
+ * (and not re-reported). Newly collected realpaths are added to `alreadyLoaded` so the
+ * caller's per-session set stays authoritative and each file loads at most once. Also
+ * reports whether an existing context file failed to read so callers can retry later
+ * instead of negatively caching a transient failure.
+ *
+ * When `suppress` matches a newly-seen file, that file is marked loaded but excluded from
+ * the returned `files` — the triggering tool result already contains it, so re-injecting
+ * would duplicate the content and waste tokens.
+ */
+export declare function collectNestedContext(targetDir: string, cwd: string, alreadyLoaded: Set<string>, suppress?: SuppressPredicate): NestedContextCollection;
+/**
+ * Format collected context files into a single text block for injection into a tool
+ * result. Leads with *why* the load happened and headers each file with its source path.
+ * There is intentionally no size cap — oversized context files are the project's concern.
+ */
+export declare function formatNestedContextBlock(targetDir: string, files: LoadedContextFile[]): string;
+/**
+ * Resolve the absolute file path a `read` tool call delivers, or `null` when the tool is
+ * not `read` or has no usable `path`. Only `read` returns the *full* file content, so it
+ * is the only path-tool whose result fully duplicates an injected context file. (`grep`
+ * returns matched lines, `ls`/`edit`/`write` do not echo the whole file — those still
+ * benefit from injection.)
+ */
+export declare function resolveSelfReadFile(toolName: string, args: Record<string, unknown> | undefined, cwd: string): string | null;
+/**
+ * Resolve the absolute paths of files a bash command fully delivers to stdout via a
+ * full-dump command (`cat`/`bat`). Path arguments are resolved against `workingDir` (the
+ * command's effective cwd — e.g. a leading `cd` target). Conservative on purpose:
+ *
+ *  - Segments are split on `&&`, `||`, `;`. Segments that are *only* a `cd` produce no
+ *    stdout and are ignored, but there must be **exactly one** remaining output-producing
+ *    segment. The bash tool truncates its *combined* command output from the **tail**
+ *    (keeping the last {@link DEFAULT_MAX_LINES} lines / {@link DEFAULT_MAX_BYTES} bytes and
+ *    dropping the head), so any *additional* output-producing segment could evict the dumped
+ *    file from the visible window while {@link deliveredInFull} — which measures the file
+ *    alone — still reports a full delivery. Bail to the safe double-load in that case.
+ *  - That sole segment must not contain a pipe (`|`), output redirection (`>`), or input
+ *    redirection / here-doc / here-string (`<`, `<<`, `<<<`) — its output is filtered /
+ *    redirected, or its operands are stdin body words rather than dumped files.
+ *  - Its first token must be `cat`/`bat`; flags (`-…`) are ignored.
+ *  - A `bat` segment carrying a partial-range flag (`-r`/`--line-range`, any spelling) is
+ *    skipped — it emits only a fragment, like `head`/`tail`.
+ *  - It must have **exactly one** file operand. A multi-file dump (`cat A.md B.md`)
+ *    concatenates several files; under tail truncation an earlier operand can be evicted
+ *    while still appearing fully sized on disk, so it is not a provable full delivery.
+ *  - If the command chains more than one `cd`, the effective cwd is ambiguous (we only
+ *    resolved the *first* `cd`), so operands cannot be resolved reliably — return nothing.
+ *
+ * Anything we cannot confidently classify as a full delivery is omitted, so the worst case
+ * is a double-load rather than a silently dropped context file.
+ */
+export declare function resolveBashDeliveredFiles(command: string, workingDir: string): string[];
+export interface NestedContextState {
+    /** Whether auto-loading is enabled (the `context.autoLoadNested` setting). */
+    enabled: boolean;
+    /** The session's working directory. */
+    cwd: string;
+    /** Realpaths of context files already loaded this session (seeded at session start). Mutated. */
+    loaded: Set<string>;
+    /** Realpaths of directories already scanned (negative cache). Mutated. */
+    scannedDirs: Set<string>;
+}
+/**
+ * Orchestrate a single nested-context decision for a tool call: gate on the setting,
+ * resolve the target directory, skip directories already scanned (negative cache),
+ * collect not-yet-loaded context files, and format them. Returns the injection block or
+ * `null` when nothing should be injected. Mutates `state.scannedDirs` and `state.loaded`.
+ */
+export declare function computeNestedContextBlock(toolName: string, args: Record<string, unknown> | undefined, state: NestedContextState): string | null;
+//# sourceMappingURL=nested-context.d.ts.map

package/dist/core/nested-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-context.d.ts","sourceRoot":"","sources":["../../src/core/nested-context.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACvC,8DAA8D;IAC9D,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsC7D;AAgBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,GAAG,EAAE,MAAM,GACT,MAAM,GAAG,IAAI,CA6Bf;AAkGD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,QAAQ,CAAC,EAAE,iBAAiB,GAC1B,uBAAuB,CAwBzB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAc9F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,GAAG,EAAE,MAAM,GACT,MAAM,GAAG,IAAI,CAUf;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CA0CvF;AAED,MAAM,WAAW,kBAAkB;IAClC,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,iGAAiG;IACjG,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,0EAA0E;IAC1E,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAkCD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,KAAK,EAAE,kBAAkB,GACvB,MAAM,GAAG,IAAI,CAwCf","sourcesContent":["import { existsSync, readFileSync, realpathSync, statSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, isAbsolute, join, resolve, sep } from \"node:path\";\nimport { CONTEXT_FILE_CANDIDATES, loadContextFilesFromDir, type ResourceDiagnostic } from \"./resource-loader.js\";\nimport { renderTerminalOutput } from \"./tools/terminal-render.js\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from \"./tools/truncate.js\";\n\n/**\n * Auto-load of nested AGENTS.md/CLAUDE.md context files.\n *\n * Project context files are only loaded at session start by walking *upward* from\n * `cwd`. When the agent (or a subagent) operates in a subdirectory — or in an entirely\n * different repo/project — that directory's context files are never loaded. This module\n * detects the directory a tool is about to operate in, walks up to a sensible ceiling\n * collecting context files, and returns a formatted block for injection into the tool\n * result (which is cache-safe — it does not rebuild the system prompt).\n */\n\n/** A safety bound on how many directories the upward walk will visit. */\nconst MAX_WALK_DEPTH = 64;\n\n/** Tools whose `path` argument identifies the directory being operated on. */\nconst PATH_TOOLS = new Set([\"read\", \"edit\", \"write\", \"grep\", \"find\", \"ls\"]);\n\nexport interface LoadedContextFile {\n\t/** Absolute path of the loaded context file. */\n\tpath: string;\n\t/** File content (HTML comments already stripped by the loader). */\n\tcontent: string;\n}\n\nexport interface NestedContextCollection {\n\t/** Context files newly loaded during this collection pass. */\n\tfiles: LoadedContextFile[];\n\t/** Whether any existing context file failed to read and should be retried later. */\n\thadReadError: boolean;\n}\n\n/**\n * Extract the target of a leading `cd <dir>` from a bash command.\n *\n * Covers the overwhelming majority of directory-changing bash commands (analysis of\n * real session logs: ~75% of bash calls start with `cd`, ~97% of those with an absolute\n * path). Returns the raw, unresolved path string (with a leading `~` preserved) or\n * `null` when the command does not begin with a simple `cd`.\n */\nexport function parseLeadingCd(command: string): string | null {\n\tif (typeof command !== \"string\") return null;\n\n\tconst leadingCd = command.match(/^\\s*cd\\s+/);\n\tif (!leadingCd) return null;\n\n\tlet rest = command.slice(leadingCd[0].length);\n\twhile (true) {\n\t\t// Match either a quoted path or an unquoted token that stops at the first shell\n\t\t// separator (&&, ;, |, newline) or whitespace.\n\t\tconst match = rest.match(/^\\s*(?:\"([^\"]+)\"|'([^']+)'|([^\\s&;|<>]+))/);\n\t\tif (!match) return null;\n\n\t\tconst target = (match[1] ?? match[2] ?? match[3] ?? \"\").trim();\n\t\tif (!target) return null;\n\n\t\t// `cd -` means \"previous directory\" and cannot be resolved cheaply.\n\t\tif (target === \"-\") return null;\n\n\t\t// Skip leading options (`cd -P /x`, `cd -L /x`). After `--`, the next token is\n\t\t// the path even if it begins with `-`.\n\t\tif (target === \"--\") {\n\t\t\trest = rest.slice(match[0].length);\n\t\t\tconst pathMatch = rest.match(/^\\s*(?:\"([^\"]+)\"|'([^']+)'|([^\\s&;|<>]+))/);\n\t\t\tif (!pathMatch) return null;\n\t\t\tconst pathTarget = (pathMatch[1] ?? pathMatch[2] ?? pathMatch[3] ?? \"\").trim();\n\t\t\tif (!pathTarget || pathTarget.startsWith(\"$\")) return null;\n\t\t\treturn pathTarget;\n\t\t}\n\t\tif (target.startsWith(\"-\")) {\n\t\t\trest = rest.slice(match[0].length);\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Skip variable-based targets we cannot resolve cheaply.\n\t\tif (target.startsWith(\"$\")) return null;\n\t\treturn target;\n\t}\n}\n\n/**\n * Expand a leading `~` to the home directory and resolve a raw path string to an absolute\n * path against `baseDir`. Shared by every place that turns a user-supplied path token into\n * an absolute path (`resolveTargetDir`, `resolveSelfReadFile`, bash argument resolution).\n */\nfunction expandToAbsolute(rawPath: string, baseDir: string): string {\n\tif (rawPath === \"~\") {\n\t\trawPath = homedir();\n\t} else if (rawPath.startsWith(`~${sep}`) || rawPath.startsWith(\"~/\")) {\n\t\trawPath = join(homedir(), rawPath.slice(2));\n\t}\n\treturn isAbsolute(rawPath) ? rawPath : resolve(baseDir, rawPath);\n}\n\n/**\n * Resolve the absolute directory a tool call is about to operate in, or `null` when the\n * tool/argument shape does not identify a directory we should react to.\n */\nexport function resolveTargetDir(\n\ttoolName: string,\n\targs: Record<string, unknown> | undefined,\n\tcwd: string,\n): string | null {\n\tif (!args) return null;\n\n\tlet rawPath: string | null = null;\n\n\tif (toolName === \"bash\") {\n\t\trawPath = parseLeadingCd(typeof args.command === \"string\" ? args.command : \"\");\n\t} else if (PATH_TOOLS.has(toolName)) {\n\t\tconst p = args.path;\n\t\tif (typeof p === \"string\" && p.trim() !== \"\") {\n\t\t\trawPath = p;\n\t\t}\n\t}\n\n\tif (!rawPath) return null;\n\n\tconst absolute = expandToAbsolute(rawPath, cwd);\n\n\t// For path-bearing tools the argument is usually a file; for bash `cd` it is a\n\t// directory. Resolve to a directory: existing dirs are used as-is, everything else\n\t// (existing files, not-yet-created files) maps to its parent directory.\n\ttry {\n\t\tif (existsSync(absolute) && statSync(absolute).isDirectory()) {\n\t\t\treturn absolute;\n\t\t}\n\t} catch {\n\t\t// Fall through to dirname on permission/stat errors.\n\t}\n\treturn dirname(absolute);\n}\n\n/** Safe realpath that falls back to the input on error. */\nfunction safeRealpath(p: string): string {\n\ttry {\n\t\treturn realpathSync(p);\n\t} catch {\n\t\treturn p;\n\t}\n}\n\nfunction isWithin(parent: string, child: string): boolean {\n\tconst p = safeRealpath(parent);\n\tconst c = safeRealpath(child);\n\treturn c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);\n}\n\n/**\n * Build the ordered list of directories to inspect, from the target directory up to the\n * appropriate ceiling. Ordered outermost-first so the most specific (closest to the\n * target) context appears last, matching session-start precedence.\n *\n * Ceiling priority:\n *   1. `cwd` — when the target is within the cwd subtree (ancestors already loaded at start).\n *   2. The outermost git repo root in the chain (a directory containing `.git`).\n *   3. The outermost directory containing a CLAUDE.md/AGENTS.md.\n *   4. Hard stop at filesystem root, the depth bound, or a permission/stat failure.\n */\nfunction resolveWalkDirs(targetDir: string, cwd: string): string[] {\n\tconst root = resolve(\"/\");\n\n\t// Case 1: target within cwd subtree — never walk above cwd.\n\tif (isWithin(cwd, targetDir)) {\n\t\tconst dirs: string[] = [];\n\t\tlet current = targetDir;\n\t\tconst stop = safeRealpath(cwd);\n\t\tfor (let i = 0; i < MAX_WALK_DEPTH; i++) {\n\t\t\tdirs.push(current);\n\t\t\tif (safeRealpath(current) === stop) break;\n\t\t\tconst parent = resolve(current, \"..\");\n\t\t\tif (parent === current) break;\n\t\t\tcurrent = parent;\n\t\t}\n\t\treturn dirs.reverse();\n\t}\n\n\t// Case 2/3/4: target outside cwd — walk to the hard ceiling, recording git roots and\n\t// directories that hold context files, then bound to the outermost relevant ceiling.\n\tconst chain: string[] = [];\n\tlet highestGitRootIdx = -1;\n\tlet highestContextIdx = -1;\n\tlet current = targetDir;\n\tfor (let i = 0; i < MAX_WALK_DEPTH; i++) {\n\t\t// A permission/stat failure on the directory itself stops the walk.\n\t\ttry {\n\t\t\tstatSync(current);\n\t\t} catch {\n\t\t\tbreak;\n\t\t}\n\t\tchain.push(current);\n\t\tconst idx = chain.length - 1;\n\t\ttry {\n\t\t\tif (existsSync(join(current, \".git\"))) highestGitRootIdx = idx;\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\tif (dirHasContextFile(current)) highestContextIdx = idx;\n\n\t\tif (current === root) break;\n\t\tconst parent = resolve(current, \"..\");\n\t\tif (parent === current) break;\n\t\tcurrent = parent;\n\t}\n\n\tlet ceilingIdx: number;\n\tif (highestGitRootIdx >= 0) {\n\t\tceilingIdx = highestGitRootIdx;\n\t} else if (highestContextIdx >= 0) {\n\t\tceilingIdx = highestContextIdx;\n\t} else {\n\t\tceilingIdx = chain.length - 1;\n\t}\n\n\treturn chain.slice(0, ceilingIdx + 1).reverse();\n}\n\n/** Cheap check: does this directory hold any candidate context file? */\nfunction dirHasContextFile(dir: string): boolean {\n\tfor (const c of CONTEXT_FILE_CANDIDATES) {\n\t\ttry {\n\t\t\tif (existsSync(join(dir, c))) return true;\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * Predicate deciding whether a collected context file should be *suppressed* from the\n * injected block because the triggering tool call already delivers its content (e.g. a\n * `read` of the file itself, or a `bash` command that prints it). Suppressed files are\n * still marked as loaded so they are never injected later — they are simply not\n * duplicated into the result that already contains them.\n */\nexport type SuppressPredicate = (file: LoadedContextFile) => boolean;\n\n/**\n * Collect nested context files for `targetDir`, walking up to the ceiling described in\n * {@link resolveWalkDirs}. Files whose realpath is already in `alreadyLoaded` are skipped\n * (and not re-reported). Newly collected realpaths are added to `alreadyLoaded` so the\n * caller's per-session set stays authoritative and each file loads at most once. Also\n * reports whether an existing context file failed to read so callers can retry later\n * instead of negatively caching a transient failure.\n *\n * When `suppress` matches a newly-seen file, that file is marked loaded but excluded from\n * the returned `files` — the triggering tool result already contains it, so re-injecting\n * would duplicate the content and waste tokens.\n */\nexport function collectNestedContext(\n\ttargetDir: string,\n\tcwd: string,\n\talreadyLoaded: Set<string>,\n\tsuppress?: SuppressPredicate,\n): NestedContextCollection {\n\tconst dirs = resolveWalkDirs(targetDir, cwd);\n\tconst collected: LoadedContextFile[] = [];\n\tlet hadReadError = false;\n\tfor (const dir of dirs) {\n\t\tconst diagnostics: ResourceDiagnostic[] = [];\n\t\tconst files = loadContextFilesFromDir(dir, diagnostics);\n\t\tfor (const diagnostic of diagnostics) {\n\t\t\tif (diagnostic.type !== \"warning\") continue;\n\t\t\thadReadError = true;\n\t\t\tconsole.warn(\n\t\t\t\t`[nested-context] Nested context file existed but could not be read: ${diagnostic.path ?? dir} — ${diagnostic.message}`,\n\t\t\t);\n\t\t}\n\t\tfor (const file of files) {\n\t\t\tconst real = safeRealpath(file.path);\n\t\t\tif (alreadyLoaded.has(real)) continue;\n\t\t\talreadyLoaded.add(real);\n\t\t\t// Mark loaded but do not inject: the triggering tool already delivers this file.\n\t\t\tif (suppress?.(file)) continue;\n\t\t\tcollected.push(file);\n\t\t}\n\t}\n\treturn { files: collected, hadReadError };\n}\n\n/**\n * Format collected context files into a single text block for injection into a tool\n * result. Leads with *why* the load happened and headers each file with its source path.\n * There is intentionally no size cap — oversized context files are the project's concern.\n */\nexport function formatNestedContextBlock(targetDir: string, files: LoadedContextFile[]): string {\n\tconst header =\n\t\t`[dreb] Auto-loaded project context\\n\\n` +\n\t\t`A tool just operated in \\`${targetDir}\\`, whose project context had not been loaded yet. ` +\n\t\t`The file(s) below were loaded automatically to prevent missing important project context ` +\n\t\t`when working across multiple repos / projects / folders. ` +\n\t\t`(Disable with the \\`context.autoLoadNested\\` setting.)`;\n\n\tconst sections = files.map(\n\t\t(f) =>\n\t\t\t`===== BEGIN project context: ${f.path} =====\\n${f.content.trim()}\\n===== END project context: ${f.path} =====`,\n\t);\n\n\treturn `${header}\\n\\n${sections.join(\"\\n\\n\")}`;\n}\n\n/**\n * Resolve the absolute file path a `read` tool call delivers, or `null` when the tool is\n * not `read` or has no usable `path`. Only `read` returns the *full* file content, so it\n * is the only path-tool whose result fully duplicates an injected context file. (`grep`\n * returns matched lines, `ls`/`edit`/`write` do not echo the whole file — those still\n * benefit from injection.)\n */\nexport function resolveSelfReadFile(\n\ttoolName: string,\n\targs: Record<string, unknown> | undefined,\n\tcwd: string,\n): string | null {\n\tif (!args || toolName !== \"read\") return null;\n\t// A sliced read (`offset`/`limit`) delivers only a fragment of the file — the same\n\t// hazard for which bash partial viewers (`head`/`tail`) are excluded. Treating it as a\n\t// full delivery would suppress (and permanently mark loaded) a file the result only\n\t// partially contains, silently dropping the rest. Fall back to the safe double-load.\n\tif (args.offset !== undefined || args.limit !== undefined) return null;\n\tconst p = args.path;\n\tif (typeof p !== \"string\" || p.trim() === \"\") return null;\n\treturn expandToAbsolute(p, cwd);\n}\n\n/**\n * Bash commands that dump a file's *full* contents to stdout. Deliberately narrow: only\n * commands that emit the whole file qualify. Partial viewers (`head`/`tail`) and\n * interactive pagers (`less`/`more`) are excluded — they may show only a fragment, so\n * treating them as \"delivered\" could silently drop the rest of a context file. The safe\n * failure mode is a harmless double-load (we still inject), never a silent context drop.\n *\n * `bat` is included but is *not* unconditionally a full dump: its `-r`/`--line-range` flag\n * emits only a range (same hazard as `head`/`tail`). Segments carrying that flag are\n * disqualified in {@link resolveBashDeliveredFiles}.\n */\nconst FULL_DUMP_COMMANDS = new Set([\"cat\", \"bat\"]);\n\n/** `bat` flags that limit output to a partial range — disqualify the segment if present. */\nconst BAT_RANGE_FLAGS = [\"-r\", \"--line-range\"];\n\n/**\n * Whether a `bat` token requests a partial line range. Matches the space-separated form\n * (`-r`, `--line-range`), the `=`-attached long form (`--line-range=10:20`), and the\n * attached short form (`-r10:20`) — clap accepts an attached value on a short flag, so a\n * bare `startsWith` check on each known range flag covers every spelling. A partial range\n * is the same hazard as `head`/`tail`: only a fragment is emitted, so the segment must not\n * be treated as a full dump.\n */\nfunction isBatRangeFlag(token: string): boolean {\n\treturn BAT_RANGE_FLAGS.some((flag) => token.startsWith(flag));\n}\n\n/** Strip a single layer of matching surrounding quotes from a shell token. */\nfunction unquoteToken(token: string): string {\n\tif (token.length >= 2) {\n\t\tconst first = token[0];\n\t\tconst last = token[token.length - 1];\n\t\tif ((first === '\"' || first === \"'\") && first === last) {\n\t\t\treturn token.slice(1, -1);\n\t\t}\n\t}\n\treturn token;\n}\n\n/**\n * Resolve the absolute paths of files a bash command fully delivers to stdout via a\n * full-dump command (`cat`/`bat`). Path arguments are resolved against `workingDir` (the\n * command's effective cwd — e.g. a leading `cd` target). Conservative on purpose:\n *\n *  - Segments are split on `&&`, `||`, `;`. Segments that are *only* a `cd` produce no\n *    stdout and are ignored, but there must be **exactly one** remaining output-producing\n *    segment. The bash tool truncates its *combined* command output from the **tail**\n *    (keeping the last {@link DEFAULT_MAX_LINES} lines / {@link DEFAULT_MAX_BYTES} bytes and\n *    dropping the head), so any *additional* output-producing segment could evict the dumped\n *    file from the visible window while {@link deliveredInFull} — which measures the file\n *    alone — still reports a full delivery. Bail to the safe double-load in that case.\n *  - That sole segment must not contain a pipe (`|`), output redirection (`>`), or input\n *    redirection / here-doc / here-string (`<`, `<<`, `<<<`) — its output is filtered /\n *    redirected, or its operands are stdin body words rather than dumped files.\n *  - Its first token must be `cat`/`bat`; flags (`-…`) are ignored.\n *  - A `bat` segment carrying a partial-range flag (`-r`/`--line-range`, any spelling) is\n *    skipped — it emits only a fragment, like `head`/`tail`.\n *  - It must have **exactly one** file operand. A multi-file dump (`cat A.md B.md`)\n *    concatenates several files; under tail truncation an earlier operand can be evicted\n *    while still appearing fully sized on disk, so it is not a provable full delivery.\n *  - If the command chains more than one `cd`, the effective cwd is ambiguous (we only\n *    resolved the *first* `cd`), so operands cannot be resolved reliably — return nothing.\n *\n * Anything we cannot confidently classify as a full delivery is omitted, so the worst case\n * is a double-load rather than a silently dropped context file.\n */\nexport function resolveBashDeliveredFiles(command: string, workingDir: string): string[] {\n\tif (typeof command !== \"string\" || command.trim() === \"\") return [];\n\tconst segments = command.split(/&&|\\|\\||;/);\n\tconst isCdSegment = (s: string) => /^\\s*cd(\\s|$)/.test(s);\n\n\t// More than one `cd` means the effective cwd differs from the first `cd` target we\n\t// resolved as `workingDir`; resolving operands against it would suppress the wrong\n\t// (same-named) file. Bail to the safe double-load.\n\tif (segments.filter(isCdSegment).length > 1) return [];\n\n\t// Segments that are only a `cd` emit no stdout. Everything else produces output, and\n\t// because the bash tool tail-truncates the *combined* output, a context file is only\n\t// provably delivered in full when it is the command's *sole* output-producing segment.\n\tconst outputSegments = segments.filter((s) => s.trim() !== \"\" && !isCdSegment(s));\n\tif (outputSegments.length !== 1) return [];\n\n\tconst segment = outputSegments[0];\n\t// Output piped/redirected, or operands fed via input redirection / here-doc, are not raw\n\t// file dumps to stdout.\n\tif (segment.includes(\"|\") || segment.includes(\">\") || segment.includes(\"<\")) return [];\n\tconst tokens = segment.trim().split(/\\s+/).filter(Boolean);\n\tif (tokens.length === 0) return [];\n\t// Match the command verb case-sensitively: shell PATH lookup is case-sensitive on\n\t// Linux, so `CAT`/`Bat` are command-not-found and emit nothing to stdout. Lowercasing\n\t// would let them match the allowlist and falsely suppress a file they never printed —\n\t// a silent context drop. Exact matching keeps the failure mode a harmless double-load.\n\tconst cmd = tokens[0];\n\tif (!FULL_DUMP_COMMANDS.has(cmd)) return [];\n\t// `bat -r 10:20` / `bat -r10:20` / `bat --line-range=10:20` shows only a range — not a full dump.\n\tif (cmd === \"bat\" && tokens.slice(1).some(isBatRangeFlag)) return [];\n\n\tconst operands: string[] = [];\n\tfor (const token of tokens.slice(1)) {\n\t\tif (token.startsWith(\"-\")) continue; // flag, not a file argument\n\t\tconst arg = unquoteToken(token);\n\t\tif (arg === \"\") continue;\n\t\toperands.push(arg);\n\t}\n\t// A single operand is the only provable full delivery: multi-file dumps concatenate,\n\t// and tail truncation can evict an earlier file while it still looks fully sized.\n\tif (operands.length !== 1) return [];\n\treturn [expandToAbsolute(operands[0], workingDir)];\n}\n\nexport interface NestedContextState {\n\t/** Whether auto-loading is enabled (the `context.autoLoadNested` setting). */\n\tenabled: boolean;\n\t/** The session's working directory. */\n\tcwd: string;\n\t/** Realpaths of context files already loaded this session (seeded at session start). Mutated. */\n\tloaded: Set<string>;\n\t/** Realpaths of directories already scanned (negative cache). Mutated. */\n\tscannedDirs: Set<string>;\n}\n\n/**\n * Whether a tool that delivers `realPath` actually delivers its *full* content. Both `read`\n * and `bash` truncate their output at {@link DEFAULT_MAX_LINES} lines / {@link DEFAULT_MAX_BYTES}\n * bytes, while {@link formatNestedContextBlock} is uncapped. If the file exceeds either limit\n * it is delivered truncated, so suppressing (and permanently marking loaded) would silently\n * drop the remainder. Any stat/read failure also returns `false` — the safe double-load.\n *\n * `rendered` selects which delivery the measure must mirror:\n *  - `read` delivers the file's raw content unchanged (`truncateHead` with no transform), so\n *    the raw byte/line count is exact.\n *  - `bash` delivers `truncateTail(renderTerminalOutput(...))`, and terminal rendering expands\n *    tabs to 8-column stops and resolves cursor/ANSI sequences — the rendered output can be\n *    *larger* than the file on disk. A tab-dense file just under the budget on disk can render\n *    past it and be tail-truncated (its head dropped) while the raw measure still reports a\n *    full delivery. Measuring the rendered output keeps the failure mode a harmless double-load\n *    rather than a silent context drop.\n */\nfunction deliveredInFull(realPath: string, rendered: boolean): boolean {\n\ttry {\n\t\t// Cheap early-out: the raw on-disk size is a lower bound on the delivered size\n\t\t// (terminal rendering only ever grows the byte count), so a file already over the\n\t\t// byte budget on disk is certainly delivered truncated.\n\t\tif (statSync(realPath).size > DEFAULT_MAX_BYTES) return false;\n\t\tconst raw = readFileSync(realPath, \"utf8\");\n\t\tconst delivered = rendered ? renderTerminalOutput(raw) : raw;\n\t\tif (Buffer.byteLength(delivered, \"utf-8\") > DEFAULT_MAX_BYTES) return false;\n\t\treturn delivered.split(\"\\n\").length <= DEFAULT_MAX_LINES;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Orchestrate a single nested-context decision for a tool call: gate on the setting,\n * resolve the target directory, skip directories already scanned (negative cache),\n * collect not-yet-loaded context files, and format them. Returns the injection block or\n * `null` when nothing should be injected. Mutates `state.scannedDirs` and `state.loaded`.\n */\nexport function computeNestedContextBlock(\n\ttoolName: string,\n\targs: Record<string, unknown> | undefined,\n\tstate: NestedContextState,\n): string | null {\n\tif (!state.enabled) return null;\n\n\tconst targetDir = resolveTargetDir(toolName, args, state.cwd);\n\tif (!targetDir) return null;\n\n\tconst realTarget = safeRealpath(targetDir);\n\tif (state.scannedDirs.has(realTarget)) return null;\n\n\t// A context file the triggering tool already delivers should be marked loaded but not\n\t// re-injected (the result already contains it). Two cases: a `read` of the file itself,\n\t// or a `bash` command that dumps its full contents (`cat`/`bat`). Both are matched by\n\t// full resolved realpath — never by basename — so printing one file never suppresses a\n\t// same-named sibling/ancestor or a file in a different directory.\n\tconst selfReadFile = resolveSelfReadFile(toolName, args, state.cwd);\n\tconst realSelfReadFile = selfReadFile ? safeRealpath(selfReadFile) : null;\n\tconst bashCommand = toolName === \"bash\" && typeof args?.command === \"string\" ? args.command : null;\n\t// Bash file arguments resolve against the command's effective cwd, which `resolveTargetDir`\n\t// has already computed as `targetDir` (the leading `cd` destination).\n\tconst bashDelivered = bashCommand\n\t\t? new Set(resolveBashDeliveredFiles(bashCommand, targetDir).map(safeRealpath))\n\t\t: null;\n\tconst suppress: SuppressPredicate = (file) => {\n\t\tconst realFile = safeRealpath(file.path);\n\t\t// Only suppress when the file was delivered *in full*: a truncated delivery (oversized\n\t\t// file) would drop the remainder if we marked it fully loaded and skipped injection.\n\t\t// `read` delivers the file's raw content unchanged; `bash` delivers it through terminal\n\t\t// rendering (tab/ANSI expansion can grow it past the truncation budget), so each path\n\t\t// measures fullness against what it actually emits.\n\t\tif (realFile === realSelfReadFile) return deliveredInFull(realFile, false);\n\t\tif (bashDelivered?.has(realFile)) return deliveredInFull(realFile, true);\n\t\treturn false;\n\t};\n\n\tconst collected = collectNestedContext(targetDir, state.cwd, state.loaded, suppress);\n\tif (!collected.hadReadError) {\n\t\tstate.scannedDirs.add(realTarget);\n\t}\n\tif (collected.files.length === 0) return null;\n\treturn formatNestedContextBlock(targetDir, collected.files);\n}\n"]}

package/dist/core/nested-context.js

@@ -0,0 +1,485 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { CONTEXT_FILE_CANDIDATES, loadContextFilesFromDir } from "./resource-loader.js";
+import { renderTerminalOutput } from "./tools/terminal-render.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "./tools/truncate.js";
+/**
+ * Auto-load of nested AGENTS.md/CLAUDE.md context files.
+ *
+ * Project context files are only loaded at session start by walking *upward* from
+ * `cwd`. When the agent (or a subagent) operates in a subdirectory — or in an entirely
+ * different repo/project — that directory's context files are never loaded. This module
+ * detects the directory a tool is about to operate in, walks up to a sensible ceiling
+ * collecting context files, and returns a formatted block for injection into the tool
+ * result (which is cache-safe — it does not rebuild the system prompt).
+ */
+/** A safety bound on how many directories the upward walk will visit. */
+const MAX_WALK_DEPTH = 64;
+/** Tools whose `path` argument identifies the directory being operated on. */
+const PATH_TOOLS = new Set(["read", "edit", "write", "grep", "find", "ls"]);
+/**
+ * Extract the target of a leading `cd <dir>` from a bash command.
+ *
+ * Covers the overwhelming majority of directory-changing bash commands (analysis of
+ * real session logs: ~75% of bash calls start with `cd`, ~97% of those with an absolute
+ * path). Returns the raw, unresolved path string (with a leading `~` preserved) or
+ * `null` when the command does not begin with a simple `cd`.
+ */
+export function parseLeadingCd(command) {
+    if (typeof command !== "string")
+        return null;
+    const leadingCd = command.match(/^\s*cd\s+/);
+    if (!leadingCd)
+        return null;
+    let rest = command.slice(leadingCd[0].length);
+    while (true) {
+        // Match either a quoted path or an unquoted token that stops at the first shell
+        // separator (&&, ;, |, newline) or whitespace.
+        const match = rest.match(/^\s*(?:"([^"]+)"|'([^']+)'|([^\s&;|<>]+))/);
+        if (!match)
+            return null;
+        const target = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+        if (!target)
+            return null;
+        // `cd -` means "previous directory" and cannot be resolved cheaply.
+        if (target === "-")
+            return null;
+        // Skip leading options (`cd -P /x`, `cd -L /x`). After `--`, the next token is
+        // the path even if it begins with `-`.
+        if (target === "--") {
+            rest = rest.slice(match[0].length);
+            const pathMatch = rest.match(/^\s*(?:"([^"]+)"|'([^']+)'|([^\s&;|<>]+))/);
+            if (!pathMatch)
+                return null;
+            const pathTarget = (pathMatch[1] ?? pathMatch[2] ?? pathMatch[3] ?? "").trim();
+            if (!pathTarget || pathTarget.startsWith("$"))
+                return null;
+            return pathTarget;
+        }
+        if (target.startsWith("-")) {
+            rest = rest.slice(match[0].length);
+            continue;
+        }
+        // Skip variable-based targets we cannot resolve cheaply.
+        if (target.startsWith("$"))
+            return null;
+        return target;
+    }
+}
+/**
+ * Expand a leading `~` to the home directory and resolve a raw path string to an absolute
+ * path against `baseDir`. Shared by every place that turns a user-supplied path token into
+ * an absolute path (`resolveTargetDir`, `resolveSelfReadFile`, bash argument resolution).
+ */
+function expandToAbsolute(rawPath, baseDir) {
+    if (rawPath === "~") {
+        rawPath = homedir();
+    }
+    else if (rawPath.startsWith(`~${sep}`) || rawPath.startsWith("~/")) {
+        rawPath = join(homedir(), rawPath.slice(2));
+    }
+    return isAbsolute(rawPath) ? rawPath : resolve(baseDir, rawPath);
+}
+/**
+ * Resolve the absolute directory a tool call is about to operate in, or `null` when the
+ * tool/argument shape does not identify a directory we should react to.
+ */
+export function resolveTargetDir(toolName, args, cwd) {
+    if (!args)
+        return null;
+    let rawPath = null;
+    if (toolName === "bash") {
+        rawPath = parseLeadingCd(typeof args.command === "string" ? args.command : "");
+    }
+    else if (PATH_TOOLS.has(toolName)) {
+        const p = args.path;
+        if (typeof p === "string" && p.trim() !== "") {
+            rawPath = p;
+        }
+    }
+    if (!rawPath)
+        return null;
+    const absolute = expandToAbsolute(rawPath, cwd);
+    // For path-bearing tools the argument is usually a file; for bash `cd` it is a
+    // directory. Resolve to a directory: existing dirs are used as-is, everything else
+    // (existing files, not-yet-created files) maps to its parent directory.
+    try {
+        if (existsSync(absolute) && statSync(absolute).isDirectory()) {
+            return absolute;
+        }
+    }
+    catch {
+        // Fall through to dirname on permission/stat errors.
+    }
+    return dirname(absolute);
+}
+/** Safe realpath that falls back to the input on error. */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function isWithin(parent, child) {
+    const p = safeRealpath(parent);
+    const c = safeRealpath(child);
+    return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+/**
+ * Build the ordered list of directories to inspect, from the target directory up to the
+ * appropriate ceiling. Ordered outermost-first so the most specific (closest to the
+ * target) context appears last, matching session-start precedence.
+ *
+ * Ceiling priority:
+ *   1. `cwd` — when the target is within the cwd subtree (ancestors already loaded at start).
+ *   2. The outermost git repo root in the chain (a directory containing `.git`).
+ *   3. The outermost directory containing a CLAUDE.md/AGENTS.md.
+ *   4. Hard stop at filesystem root, the depth bound, or a permission/stat failure.
+ */
+function resolveWalkDirs(targetDir, cwd) {
+    const root = resolve("/");
+    // Case 1: target within cwd subtree — never walk above cwd.
+    if (isWithin(cwd, targetDir)) {
+        const dirs = [];
+        let current = targetDir;
+        const stop = safeRealpath(cwd);
+        for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+            dirs.push(current);
+            if (safeRealpath(current) === stop)
+                break;
+            const parent = resolve(current, "..");
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return dirs.reverse();
+    }
+    // Case 2/3/4: target outside cwd — walk to the hard ceiling, recording git roots and
+    // directories that hold context files, then bound to the outermost relevant ceiling.
+    const chain = [];
+    let highestGitRootIdx = -1;
+    let highestContextIdx = -1;
+    let current = targetDir;
+    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+        // A permission/stat failure on the directory itself stops the walk.
+        try {
+            statSync(current);
+        }
+        catch {
+            break;
+        }
+        chain.push(current);
+        const idx = chain.length - 1;
+        try {
+            if (existsSync(join(current, ".git")))
+                highestGitRootIdx = idx;
+        }
+        catch {
+            // ignore
+        }
+        if (dirHasContextFile(current))
+            highestContextIdx = idx;
+        if (current === root)
+            break;
+        const parent = resolve(current, "..");
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    let ceilingIdx;
+    if (highestGitRootIdx >= 0) {
+        ceilingIdx = highestGitRootIdx;
+    }
+    else if (highestContextIdx >= 0) {
+        ceilingIdx = highestContextIdx;
+    }
+    else {
+        ceilingIdx = chain.length - 1;
+    }
+    return chain.slice(0, ceilingIdx + 1).reverse();
+}
+/** Cheap check: does this directory hold any candidate context file? */
+function dirHasContextFile(dir) {
+    for (const c of CONTEXT_FILE_CANDIDATES) {
+        try {
+            if (existsSync(join(dir, c)))
+                return true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return false;
+}
+/**
+ * Collect nested context files for `targetDir`, walking up to the ceiling described in
+ * {@link resolveWalkDirs}. Files whose realpath is already in `alreadyLoaded` are skipped
+ * (and not re-reported). Newly collected realpaths are added to `alreadyLoaded` so the
+ * caller's per-session set stays authoritative and each file loads at most once. Also
+ * reports whether an existing context file failed to read so callers can retry later
+ * instead of negatively caching a transient failure.
+ *
+ * When `suppress` matches a newly-seen file, that file is marked loaded but excluded from
+ * the returned `files` — the triggering tool result already contains it, so re-injecting
+ * would duplicate the content and waste tokens.
+ */
+export function collectNestedContext(targetDir, cwd, alreadyLoaded, suppress) {
+    const dirs = resolveWalkDirs(targetDir, cwd);
+    const collected = [];
+    let hadReadError = false;
+    for (const dir of dirs) {
+        const diagnostics = [];
+        const files = loadContextFilesFromDir(dir, diagnostics);
+        for (const diagnostic of diagnostics) {
+            if (diagnostic.type !== "warning")
+                continue;
+            hadReadError = true;
+            console.warn(`[nested-context] Nested context file existed but could not be read: ${diagnostic.path ?? dir} — ${diagnostic.message}`);
+        }
+        for (const file of files) {
+            const real = safeRealpath(file.path);
+            if (alreadyLoaded.has(real))
+                continue;
+            alreadyLoaded.add(real);
+            // Mark loaded but do not inject: the triggering tool already delivers this file.
+            if (suppress?.(file))
+                continue;
+            collected.push(file);
+        }
+    }
+    return { files: collected, hadReadError };
+}
+/**
+ * Format collected context files into a single text block for injection into a tool
+ * result. Leads with *why* the load happened and headers each file with its source path.
+ * There is intentionally no size cap — oversized context files are the project's concern.
+ */
+export function formatNestedContextBlock(targetDir, files) {
+    const header = `[dreb] Auto-loaded project context\n\n` +
+        `A tool just operated in \`${targetDir}\`, whose project context had not been loaded yet. ` +
+        `The file(s) below were loaded automatically to prevent missing important project context ` +
+        `when working across multiple repos / projects / folders. ` +
+        `(Disable with the \`context.autoLoadNested\` setting.)`;
+    const sections = files.map((f) => `===== BEGIN project context: ${f.path} =====\n${f.content.trim()}\n===== END project context: ${f.path} =====`);
+    return `${header}\n\n${sections.join("\n\n")}`;
+}
+/**
+ * Resolve the absolute file path a `read` tool call delivers, or `null` when the tool is
+ * not `read` or has no usable `path`. Only `read` returns the *full* file content, so it
+ * is the only path-tool whose result fully duplicates an injected context file. (`grep`
+ * returns matched lines, `ls`/`edit`/`write` do not echo the whole file — those still
+ * benefit from injection.)
+ */
+export function resolveSelfReadFile(toolName, args, cwd) {
+    if (!args || toolName !== "read")
+        return null;
+    // A sliced read (`offset`/`limit`) delivers only a fragment of the file — the same
+    // hazard for which bash partial viewers (`head`/`tail`) are excluded. Treating it as a
+    // full delivery would suppress (and permanently mark loaded) a file the result only
+    // partially contains, silently dropping the rest. Fall back to the safe double-load.
+    if (args.offset !== undefined || args.limit !== undefined)
+        return null;
+    const p = args.path;
+    if (typeof p !== "string" || p.trim() === "")
+        return null;
+    return expandToAbsolute(p, cwd);
+}
+/**
+ * Bash commands that dump a file's *full* contents to stdout. Deliberately narrow: only
+ * commands that emit the whole file qualify. Partial viewers (`head`/`tail`) and
+ * interactive pagers (`less`/`more`) are excluded — they may show only a fragment, so
+ * treating them as "delivered" could silently drop the rest of a context file. The safe
+ * failure mode is a harmless double-load (we still inject), never a silent context drop.
+ *
+ * `bat` is included but is *not* unconditionally a full dump: its `-r`/`--line-range` flag
+ * emits only a range (same hazard as `head`/`tail`). Segments carrying that flag are
+ * disqualified in {@link resolveBashDeliveredFiles}.
+ */
+const FULL_DUMP_COMMANDS = new Set(["cat", "bat"]);
+/** `bat` flags that limit output to a partial range — disqualify the segment if present. */
+const BAT_RANGE_FLAGS = ["-r", "--line-range"];
+/**
+ * Whether a `bat` token requests a partial line range. Matches the space-separated form
+ * (`-r`, `--line-range`), the `=`-attached long form (`--line-range=10:20`), and the
+ * attached short form (`-r10:20`) — clap accepts an attached value on a short flag, so a
+ * bare `startsWith` check on each known range flag covers every spelling. A partial range
+ * is the same hazard as `head`/`tail`: only a fragment is emitted, so the segment must not
+ * be treated as a full dump.
+ */
+function isBatRangeFlag(token) {
+    return BAT_RANGE_FLAGS.some((flag) => token.startsWith(flag));
+}
+/** Strip a single layer of matching surrounding quotes from a shell token. */
+function unquoteToken(token) {
+    if (token.length >= 2) {
+        const first = token[0];
+        const last = token[token.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return token.slice(1, -1);
+        }
+    }
+    return token;
+}
+/**
+ * Resolve the absolute paths of files a bash command fully delivers to stdout via a
+ * full-dump command (`cat`/`bat`). Path arguments are resolved against `workingDir` (the
+ * command's effective cwd — e.g. a leading `cd` target). Conservative on purpose:
+ *
+ *  - Segments are split on `&&`, `||`, `;`. Segments that are *only* a `cd` produce no
+ *    stdout and are ignored, but there must be **exactly one** remaining output-producing
+ *    segment. The bash tool truncates its *combined* command output from the **tail**
+ *    (keeping the last {@link DEFAULT_MAX_LINES} lines / {@link DEFAULT_MAX_BYTES} bytes and
+ *    dropping the head), so any *additional* output-producing segment could evict the dumped
+ *    file from the visible window while {@link deliveredInFull} — which measures the file
+ *    alone — still reports a full delivery. Bail to the safe double-load in that case.
+ *  - That sole segment must not contain a pipe (`|`), output redirection (`>`), or input
+ *    redirection / here-doc / here-string (`<`, `<<`, `<<<`) — its output is filtered /
+ *    redirected, or its operands are stdin body words rather than dumped files.
+ *  - Its first token must be `cat`/`bat`; flags (`-…`) are ignored.
+ *  - A `bat` segment carrying a partial-range flag (`-r`/`--line-range`, any spelling) is
+ *    skipped — it emits only a fragment, like `head`/`tail`.
+ *  - It must have **exactly one** file operand. A multi-file dump (`cat A.md B.md`)
+ *    concatenates several files; under tail truncation an earlier operand can be evicted
+ *    while still appearing fully sized on disk, so it is not a provable full delivery.
+ *  - If the command chains more than one `cd`, the effective cwd is ambiguous (we only
+ *    resolved the *first* `cd`), so operands cannot be resolved reliably — return nothing.
+ *
+ * Anything we cannot confidently classify as a full delivery is omitted, so the worst case
+ * is a double-load rather than a silently dropped context file.
+ */
+export function resolveBashDeliveredFiles(command, workingDir) {
+    if (typeof command !== "string" || command.trim() === "")
+        return [];
+    const segments = command.split(/&&|\|\||;/);
+    const isCdSegment = (s) => /^\s*cd(\s|$)/.test(s);
+    // More than one `cd` means the effective cwd differs from the first `cd` target we
+    // resolved as `workingDir`; resolving operands against it would suppress the wrong
+    // (same-named) file. Bail to the safe double-load.
+    if (segments.filter(isCdSegment).length > 1)
+        return [];
+    // Segments that are only a `cd` emit no stdout. Everything else produces output, and
+    // because the bash tool tail-truncates the *combined* output, a context file is only
+    // provably delivered in full when it is the command's *sole* output-producing segment.
+    const outputSegments = segments.filter((s) => s.trim() !== "" && !isCdSegment(s));
+    if (outputSegments.length !== 1)
+        return [];
+    const segment = outputSegments[0];
+    // Output piped/redirected, or operands fed via input redirection / here-doc, are not raw
+    // file dumps to stdout.
+    if (segment.includes("|") || segment.includes(">") || segment.includes("<"))
+        return [];
+    const tokens = segment.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return [];
+    // Match the command verb case-sensitively: shell PATH lookup is case-sensitive on
+    // Linux, so `CAT`/`Bat` are command-not-found and emit nothing to stdout. Lowercasing
+    // would let them match the allowlist and falsely suppress a file they never printed —
+    // a silent context drop. Exact matching keeps the failure mode a harmless double-load.
+    const cmd = tokens[0];
+    if (!FULL_DUMP_COMMANDS.has(cmd))
+        return [];
+    // `bat -r 10:20` / `bat -r10:20` / `bat --line-range=10:20` shows only a range — not a full dump.
+    if (cmd === "bat" && tokens.slice(1).some(isBatRangeFlag))
+        return [];
+    const operands = [];
+    for (const token of tokens.slice(1)) {
+        if (token.startsWith("-"))
+            continue; // flag, not a file argument
+        const arg = unquoteToken(token);
+        if (arg === "")
+            continue;
+        operands.push(arg);
+    }
+    // A single operand is the only provable full delivery: multi-file dumps concatenate,
+    // and tail truncation can evict an earlier file while it still looks fully sized.
+    if (operands.length !== 1)
+        return [];
+    return [expandToAbsolute(operands[0], workingDir)];
+}
+/**
+ * Whether a tool that delivers `realPath` actually delivers its *full* content. Both `read`
+ * and `bash` truncate their output at {@link DEFAULT_MAX_LINES} lines / {@link DEFAULT_MAX_BYTES}
+ * bytes, while {@link formatNestedContextBlock} is uncapped. If the file exceeds either limit
+ * it is delivered truncated, so suppressing (and permanently marking loaded) would silently
+ * drop the remainder. Any stat/read failure also returns `false` — the safe double-load.
+ *
+ * `rendered` selects which delivery the measure must mirror:
+ *  - `read` delivers the file's raw content unchanged (`truncateHead` with no transform), so
+ *    the raw byte/line count is exact.
+ *  - `bash` delivers `truncateTail(renderTerminalOutput(...))`, and terminal rendering expands
+ *    tabs to 8-column stops and resolves cursor/ANSI sequences — the rendered output can be
+ *    *larger* than the file on disk. A tab-dense file just under the budget on disk can render
+ *    past it and be tail-truncated (its head dropped) while the raw measure still reports a
+ *    full delivery. Measuring the rendered output keeps the failure mode a harmless double-load
+ *    rather than a silent context drop.
+ */
+function deliveredInFull(realPath, rendered) {
+    try {
+        // Cheap early-out: the raw on-disk size is a lower bound on the delivered size
+        // (terminal rendering only ever grows the byte count), so a file already over the
+        // byte budget on disk is certainly delivered truncated.
+        if (statSync(realPath).size > DEFAULT_MAX_BYTES)
+            return false;
+        const raw = readFileSync(realPath, "utf8");
+        const delivered = rendered ? renderTerminalOutput(raw) : raw;
+        if (Buffer.byteLength(delivered, "utf-8") > DEFAULT_MAX_BYTES)
+            return false;
+        return delivered.split("\n").length <= DEFAULT_MAX_LINES;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Orchestrate a single nested-context decision for a tool call: gate on the setting,
+ * resolve the target directory, skip directories already scanned (negative cache),
+ * collect not-yet-loaded context files, and format them. Returns the injection block or
+ * `null` when nothing should be injected. Mutates `state.scannedDirs` and `state.loaded`.
+ */
+export function computeNestedContextBlock(toolName, args, state) {
+    if (!state.enabled)
+        return null;
+    const targetDir = resolveTargetDir(toolName, args, state.cwd);
+    if (!targetDir)
+        return null;
+    const realTarget = safeRealpath(targetDir);
+    if (state.scannedDirs.has(realTarget))
+        return null;
+    // A context file the triggering tool already delivers should be marked loaded but not
+    // re-injected (the result already contains it). Two cases: a `read` of the file itself,
+    // or a `bash` command that dumps its full contents (`cat`/`bat`). Both are matched by
+    // full resolved realpath — never by basename — so printing one file never suppresses a
+    // same-named sibling/ancestor or a file in a different directory.
+    const selfReadFile = resolveSelfReadFile(toolName, args, state.cwd);
+    const realSelfReadFile = selfReadFile ? safeRealpath(selfReadFile) : null;
+    const bashCommand = toolName === "bash" && typeof args?.command === "string" ? args.command : null;
+    // Bash file arguments resolve against the command's effective cwd, which `resolveTargetDir`
+    // has already computed as `targetDir` (the leading `cd` destination).
+    const bashDelivered = bashCommand
+        ? new Set(resolveBashDeliveredFiles(bashCommand, targetDir).map(safeRealpath))
+        : null;
+    const suppress = (file) => {
+        const realFile = safeRealpath(file.path);
+        // Only suppress when the file was delivered *in full*: a truncated delivery (oversized
+        // file) would drop the remainder if we marked it fully loaded and skipped injection.
+        // `read` delivers the file's raw content unchanged; `bash` delivers it through terminal
+        // rendering (tab/ANSI expansion can grow it past the truncation budget), so each path
+        // measures fullness against what it actually emits.
+        if (realFile === realSelfReadFile)
+            return deliveredInFull(realFile, false);
+        if (bashDelivered?.has(realFile))
+            return deliveredInFull(realFile, true);
+        return false;
+    };
+    const collected = collectNestedContext(targetDir, state.cwd, state.loaded, suppress);
+    if (!collected.hadReadError) {
+        state.scannedDirs.add(realTarget);
+    }
+    if (collected.files.length === 0)
+        return null;
+    return formatNestedContextBlock(targetDir, collected.files);
+}
+//# sourceMappingURL=nested-context.js.map