@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -21,31 +21,155 @@
  * signature, so the identical-args streak never trips, while allowing
  * tool-heavy turns that are making file-mutation progress. Whichever guard
  * trips first blocks.
+ *
+ * Thresholds, exempt tools, and enable flags are user-tunable (#1198) via the
+ * `tool_call_loop_guard` key in `.gsd/PREFERENCES.md` and `GSD_TOOL_LOOP_*`
+ * environment variables, applied through {@link configureToolCallLoopGuard}.
+ * Defaults preserve the original hardcoded behavior.
  */
 
 import { createHash } from "node:crypto";
 import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 
-const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+/** Built-in defaults. Preserved when preferences/env do not override them. */
+const DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+const DEFAULT_PER_TOOL_DEFAULT_CAP = 6;
+const DEFAULT_PER_TOOL_REPEATABLE_CAP = 15;
+const DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS = ["find", "glob", "grep", "ls", "read", "search_and_read"] as const;
 
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
 
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+
 /**
- * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ * User-tunable configuration shape for the loop guard (#1198).
  *
- * General-purpose execution tools are routinely called many times per turn
- * (touching multiple files, running several commands), so they get a higher
- * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
- * and any non-allowlisted tool — gets the default cap. The default is generous
- * enough to absorb legitimate retries but catches the reported improvisation
- * loop (~51 calls) well before a cost spike.
+ * Mirrors the `tool_call_loop_guard` key in `.gsd/PREFERENCES.md`. All fields
+ * are optional; anything omitted falls back to the built-in defaults so that
+ * existing installs keep their current behavior.
  */
-const PER_TOOL_DEFAULT_CAP = 6;
-const PER_TOOL_REPEATABLE_CAP = 15;
-const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
-const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+export interface ToolCallLoopGuardConfig {
+  enabled?: boolean;
+  identical_args?: {
+    enabled?: boolean;
+    max_consecutive_calls?: number;
+  };
+  repeated_tool?: {
+    enabled?: boolean;
+    default_cap?: number;
+    repeatable_cap?: number;
+    exempt_tools?: string[];
+  };
+}
+
+/**
+ * Active, resolved configuration. Set by {@link configureToolCallLoopGuard}
+ * from preferences + environment overrides, and deliberately NOT touched by
+ * {@link resetToolCallLoopGuard} so a session's tuning survives turn
+ * boundaries.
+ */
+interface ResolvedGuardConfig {
+  /** Master switch for both guards. */
+  guardEnabled: boolean;
+  identicalEnabled: boolean;
+  maxConsecutiveIdentical: number;
+  repeatedEnabled: boolean;
+  perToolDefaultCap: number;
+  perToolRepeatableCap: number;
+  /** Tool names exempt from Guard 2 (per-tool-name cap). */
+  perToolExempt: Set<string>;
+}
+
+function defaultGuardConfig(): ResolvedGuardConfig {
+  return {
+    guardEnabled: true,
+    identicalEnabled: true,
+    maxConsecutiveIdentical: DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS,
+    repeatedEnabled: true,
+    perToolDefaultCap: DEFAULT_PER_TOOL_DEFAULT_CAP,
+    perToolRepeatableCap: DEFAULT_PER_TOOL_REPEATABLE_CAP,
+    perToolExempt: new Set<string>(DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS),
+  };
+}
+
+let config: ResolvedGuardConfig = defaultGuardConfig();
+
+/** Parse a positive-integer env var, returning undefined when unset/invalid. */
+function envPositiveInt(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+
+/** Parse a boolean env var (`true`/`1` vs `false`/`0`), undefined when unset. */
+function envBool(name: string): boolean | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const v = raw.trim().toLowerCase();
+  if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+  if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+  return undefined;
+}
+
+/** Parse a comma-separated tool-name list env var. */
+function envToolList(name: string): string[] {
+  const raw = process.env[name];
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Resolve preferences + environment overrides into the active configuration.
+ * Environment variables win over preferences; preferences win over built-in
+ * defaults. User-supplied exempt tools are additive to the built-in exempt
+ * set so defaults are always preserved.
+ *
+ * Applied to both interactive sessions and `/gsd auto` (called from the
+ * session_start / session_switch hooks).
+ */
+export function configureToolCallLoopGuard(prefs?: ToolCallLoopGuardConfig | null): void {
+  const next = defaultGuardConfig();
+
+  if (prefs) {
+    if (typeof prefs.enabled === "boolean") next.guardEnabled = prefs.enabled;
+    if (prefs.identical_args) {
+      if (typeof prefs.identical_args.enabled === "boolean") next.identicalEnabled = prefs.identical_args.enabled;
+      if (typeof prefs.identical_args.max_consecutive_calls === "number" && prefs.identical_args.max_consecutive_calls >= 1) {
+        next.maxConsecutiveIdentical = Math.floor(prefs.identical_args.max_consecutive_calls);
+      }
+    }
+    if (prefs.repeated_tool) {
+      if (typeof prefs.repeated_tool.enabled === "boolean") next.repeatedEnabled = prefs.repeated_tool.enabled;
+      if (typeof prefs.repeated_tool.default_cap === "number" && prefs.repeated_tool.default_cap >= 1) {
+        next.perToolDefaultCap = Math.floor(prefs.repeated_tool.default_cap);
+      }
+      if (typeof prefs.repeated_tool.repeatable_cap === "number" && prefs.repeated_tool.repeatable_cap >= 1) {
+        next.perToolRepeatableCap = Math.floor(prefs.repeated_tool.repeatable_cap);
+      }
+      for (const tool of prefs.repeated_tool.exempt_tools ?? []) {
+        if (typeof tool === "string" && tool.trim()) next.perToolExempt.add(tool.trim());
+      }
+    }
+  }
+
+  // Environment overrides (win over preferences).
+  const envEnabled = envBool("GSD_TOOL_LOOP_GUARD_ENABLED");
+  if (envEnabled !== undefined) next.guardEnabled = envEnabled;
+  const envIdenticalMax = envPositiveInt("GSD_TOOL_LOOP_IDENTICAL_MAX");
+  if (envIdenticalMax !== undefined) next.maxConsecutiveIdentical = envIdenticalMax;
+  const envDefaultCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP");
+  if (envDefaultCap !== undefined) next.perToolDefaultCap = envDefaultCap;
+  const envRepeatableCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_REPEATABLE_CAP");
+  if (envRepeatableCap !== undefined) next.perToolRepeatableCap = envRepeatableCap;
+  for (const tool of envToolList("GSD_TOOL_LOOP_EXEMPT_TOOLS")) next.perToolExempt.add(tool);
+
+  config = next;
+}
 
 let consecutiveCount = 0;
 let lastSignature = "";
@@ -80,17 +204,20 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
  *
  * Two independent guards run; whichever trips first blocks:
- *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *  1. Identical-signature streak (config.maxConsecutiveIdentical, strict for
  *     ask_user_questions).
- *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *  2. Per-tool-name cap (config.perToolDefaultCap / config.perToolRepeatableCap),
  *     independent of args, reset after file-mutation progress — catches
  *     improvisation loops (#783).
+ *
+ * Both guards, their thresholds, and the per-tool exempt set are user-tunable
+ * via {@link configureToolCallLoopGuard} (#1198).
  */
 export function checkToolCallLoop(
   toolName: string,
   args: Record<string, unknown>,
 ): { block: boolean; reason?: string; count?: number } {
-  if (!enabled) return { block: false, count: 0 };
+  if (!enabled || !config.guardEnabled) return { block: false, count: 0 };
 
   const sig = hashToolCall(toolName, args);
 
@@ -105,14 +232,16 @@ export function checkToolCallLoop(
   // ── Guard 1: identical-signature streak ──
   const threshold = STRICT_LOOP_TOOLS.has(toolName)
     ? MAX_CONSECUTIVE_STRICT
-    : MAX_CONSECUTIVE_IDENTICAL_CALLS;
+    : config.maxConsecutiveIdentical;
 
-  if (consecutiveCount > threshold) {
+  if (config.identicalEnabled && consecutiveCount > threshold) {
     return {
       block: true,
       reason:
         `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
-        `with identical arguments. Blocking to prevent infinite loop. ` +
+        `with identical arguments (max ${threshold}). Blocking to prevent infinite loop. ` +
+        `Raise tool_call_loop_guard.identical_args.max_consecutive_calls in .gsd/PREFERENCES.md ` +
+        `(or GSD_TOOL_LOOP_IDENTICAL_MAX) if this is expected. ` +
         `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
@@ -130,14 +259,23 @@ export function checkToolCallLoop(
   perToolLastMutationEpoch.set(toolName, mutationEpoch);
 
   // Read-only navigation tools are normal context gathering; Guard 1 still
-  // catches true reread loops with identical arguments.
-  if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+  // catches true reread loops with identical arguments. Browser Automation
+  // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+  // many distinct-arg calls (read a message, count edits, inspect a card, …),
+  // so the arg-independent per-tool cap misfires on legitimate verification;
+  // Guard 1's identical-signature streak still catches a genuinely stuck
+  // browser loop.
+  if (
+    !config.repeatedEnabled ||
+    config.perToolExempt.has(toolName) ||
+    hasBrowserContractPrefix(canonicalToolName(toolName))
+  ) {
     return { block: false, count: consecutiveCount };
   }
 
   const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
-    ? PER_TOOL_REPEATABLE_CAP
-    : PER_TOOL_DEFAULT_CAP;
+    ? config.perToolRepeatableCap
+    : config.perToolDefaultCap;
 
   if (perToolCount > perToolCap) {
     return {
@@ -146,6 +284,9 @@ export function checkToolCallLoop(
         `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
         `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
         `The tool may be unavailable or failing repeatedly. ` +
+        `Raise tool_call_loop_guard.repeated_tool.default_cap/repeatable_cap or add "${toolName}" ` +
+        `to tool_call_loop_guard.repeated_tool.exempt_tools in .gsd/PREFERENCES.md ` +
+        `(or GSD_TOOL_LOOP_REPEATED_* / GSD_TOOL_LOOP_EXEMPT_TOOLS) if this is expected. ` +
         `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
       count: perToolCount,
     };

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1169,7 +1169,7 @@ function allowsControlledSubagentDispatch(
   policy: ToolsPolicy,
 ): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
   return (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
   );
 }
@@ -1199,6 +1199,7 @@ function warnMissingControlledDispatchAgentClasses(unitType: string, mode: strin
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
+  "memory_query",
   "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
   "search_and_read",
 ]);
@@ -1265,6 +1266,9 @@ type PlanningUnitBlockResult = {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1354,6 +1358,24 @@ export function shouldBlockPlanningUnit(
     return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
+  if (policy.mode === "workflow-only") {
+    if (tool === "bash") {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`,
+      );
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`,
+      );
+    }
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+  }
+
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -10,10 +10,15 @@
 
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname, extname } from "node:path";
+import { join, dirname, extname, relative, sep } from "node:path";
 
 import { execSync } from "node:child_process";
 import { gsdRoot } from "./paths.js";
+import {
+  createRepositoryRegistryFromPreferences,
+  type RepositoryRegistry,
+} from "./repository-registry.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -28,6 +33,8 @@ export interface CodebaseMapMetadata {
   fingerprint: string;
   fileCount: number;
   truncated: boolean;
+  /** Repo ids whose files appear in a workspace-aware map (parent mode only). */
+  repositories?: string[];
 }
 
 export interface EnsureCodebaseMapOptions {
@@ -48,12 +55,16 @@ export interface EnsureCodebaseMapResult {
 interface FileEntry {
   path: string;
   description: string;
+  /** Declaring repo id for workspace-aware maps (parent mode); undefined otherwise. */
+  repo?: string;
 }
 
 interface DirectoryGroup {
   path: string;
   files: FileEntry[];
   collapsed: boolean;
+  /** Repo id this group belongs to for workspace-aware maps; undefined otherwise. */
+  repo?: string;
 }
 
 interface ResolvedCodebaseMapOptions {
@@ -66,6 +77,8 @@ interface ResolvedCodebaseMapOptions {
 interface EnumeratedFiles {
   files: string[];
   truncated: boolean;
+  /** Per-file repo labels aligned with `files` (workspace-aware maps only). */
+  repos?: string[];
 }
 
 // ─── Defaults ────────────────────────────────────────────────────────────────
@@ -209,13 +222,99 @@ function lsFiles(basePath: string): string[] {
  * Enumerate tracked files, applying exclusions and the maxFiles cap.
  * Returns both the file list and whether truncation occurred.
  */
-function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): { files: string[]; truncated: boolean } {
+function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): EnumeratedFiles {
   const allFiles = lsFiles(basePath);
   const filtered = allFiles.filter((f) => !shouldExclude(f, excludes));
   const truncated = filtered.length > maxFiles;
   return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
 
+/**
+ * Build a workspace-aware registry for parent mode, or null when the project is
+ * single-repo (no declared child repositories). Returns null so the caller falls
+ * back to the legacy single-root enumeration and produces byte-identical output.
+ */
+function loadWorkspaceRegistry(basePath: string): RepositoryRegistry | null {
+  const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+  const workspace = preferences?.workspace;
+  const mode = workspace?.mode ?? "project";
+  // Parent mode is only meaningful with at least one declared child repo; the
+  // implicit "project" repo is always present, so require a declared non-project id.
+  const hasDeclaredChildRepo = workspace?.repositories
+    ? Object.keys(workspace.repositories).some((id) => id !== "project")
+    : false;
+  if (mode !== "parent" || !hasDeclaredChildRepo) {
+    return null;
+  }
+  return createRepositoryRegistryFromPreferences(basePath, preferences);
+}
+
+/** Stable key fragment for workspace-aware enumeration inputs (mode + declared repos). */
+function workspaceEnumerationSignature(basePath: string): string {
+  const registry = loadWorkspaceRegistry(basePath);
+  if (!registry) return "single-root";
+  return JSON.stringify({
+    mode: registry.mode,
+    repositories: registry.repositories
+      .map((repo) => ({ id: repo.id, root: repo.root }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+  });
+}
+
+/**
+ * Enumerate tracked files across every declared repository in a parent workspace.
+ * Child-repo paths are rewritten to be workspace-relative (e.g. `frontend/src/x`)
+ * and tagged with their declaring repo id so the map can render repo-labelled
+ * sections. The maxFiles cap is applied across the union of all repositories.
+ */
+function enumerateWorkspaceFiles(
+  registry: RepositoryRegistry,
+  excludes: string[],
+  maxFiles: number,
+): EnumeratedFiles {
+  type WorkspaceEntry = { workspacePath: string; repoId: string };
+  const perRepo: WorkspaceEntry[][] = [];
+  const seen = new Set<string>();
+  let totalEligible = 0;
+
+  for (const repo of registry.repositories) {
+    const rawFiles = lsFiles(repo.root);
+    const repoPrefix = relative(registry.projectRoot, repo.root).split(sep).join("/");
+    const repoEntries: WorkspaceEntry[] = [];
+
+    for (const file of rawFiles) {
+      // Rewrite before exclusion so workspace-relative patterns (e.g. frontend/…) apply.
+      const workspacePath = repoPrefix ? `${repoPrefix}/${file}` : file;
+      if (shouldExclude(workspacePath, excludes)) continue;
+      if (seen.has(workspacePath)) continue;
+      seen.add(workspacePath);
+      totalEligible++;
+      repoEntries.push({ workspacePath, repoId: repo.id });
+    }
+    perRepo.push(repoEntries);
+  }
+
+  const files: string[] = [];
+  const repos: string[] = [];
+  const indices = new Array(perRepo.length).fill(0);
+
+  while (files.length < maxFiles) {
+    let progressed = false;
+    for (let i = 0; i < perRepo.length; i++) {
+      if (indices[i] < perRepo[i].length) {
+        const entry = perRepo[i][indices[i]++];
+        files.push(entry.workspacePath);
+        repos.push(entry.repoId);
+        progressed = true;
+        if (files.length >= maxFiles) break;
+      }
+    }
+    if (!progressed) break;
+  }
+
+  return { files, repos, truncated: totalEligible > files.length };
+}
+
 function resolveGeneratorOptions(options?: CodebaseMapOptions): ResolvedCodebaseMapOptions {
   const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
   const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
@@ -236,10 +335,12 @@ function computeCodebaseFingerprint(
   files: string[],
   resolved: ResolvedCodebaseMapOptions,
   truncated: boolean,
+  repos?: string[],
 ): string {
   return createHash("sha1")
     .update(JSON.stringify({
       files,
+      ...(repos ? { repos } : {}),
       truncated,
       optionSignature: resolved.optionSignature,
     }))
@@ -252,32 +353,61 @@ function groupByDirectory(
   files: string[],
   descriptions: Map<string, string>,
   collapseThreshold: number,
+  repos?: string[],
 ): DirectoryGroup[] {
   const dirMap = new Map<string, FileEntry[]>();
 
-  for (const file of files) {
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
     const dir = dirname(file);
-    const dirKey = dir === "." ? "" : dir;
-    if (!dirMap.has(dirKey)) {
-      dirMap.set(dirKey, []);
+    const dirPath = dir === "." ? "" : dir;
+    const repoId = repos?.[i];
+    const groupKey = repoId !== undefined ? `${repoId}\0${dirPath}` : dirPath;
+    if (!dirMap.has(groupKey)) {
+      dirMap.set(groupKey, []);
     }
-    dirMap.get(dirKey)!.push({
+    dirMap.get(groupKey)!.push({
       path: file,
       description: descriptions.get(file) ?? "",
+      repo: repoId,
     });
   }
 
   const groups: DirectoryGroup[] = [];
-  const sortedDirs = [...dirMap.keys()].sort();
+  const repoOrder = new Map<string, number>();
+  if (repos) {
+    for (let i = 0; i < repos.length; i++) {
+      if (!repoOrder.has(repos[i])) {
+        repoOrder.set(repos[i], repoOrder.size);
+      }
+    }
+  }
+  const sortedDirs = [...dirMap.keys()].sort((a, b) => {
+    // Single-repo (project) mode must stay byte-identical to the pre-workspace
+    // output, which ordered directories with a bare `.sort()` (UTF-16 code-unit
+    // order, so uppercase sorts before lowercase). localeCompare would diverge
+    // for mixed-case names (e.g. "Zoo" before "apple" flips), so preserve
+    // code-unit ordering here; only the repo-partitioning key is added on top.
+    if (!repos) return a < b ? -1 : a > b ? 1 : 0;
+    const repoA = dirMap.get(a)![0]?.repo ?? "";
+    const repoB = dirMap.get(b)![0]?.repo ?? "";
+    const orderA = repoOrder.get(repoA) ?? 0;
+    const orderB = repoOrder.get(repoB) ?? 0;
+    if (orderA !== orderB) return orderA - orderB;
+    return a.localeCompare(b);
+  });
 
-  for (const dir of sortedDirs) {
-    const dirFiles = dirMap.get(dir)!;
+  for (const groupKey of sortedDirs) {
+    const dirFiles = dirMap.get(groupKey)!;
     dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+    const dirPath = repos ? groupKey.slice(groupKey.indexOf("\0") + 1) : groupKey;
 
     groups.push({
-      path: dir,
+      path: dirPath,
       files: dirFiles,
       collapsed: dirFiles.length > collapseThreshold,
+      // Each group is scoped to one repo in workspace-aware mode.
+      repo: dirFiles[0]?.repo,
     });
   }
 
@@ -304,7 +434,19 @@ function renderCodebaseMap(
   }
   lines.push("");
 
+  let emittedRepo: string | undefined;
   for (const group of groups) {
+    // In a workspace-aware map, partition directories under their declaring
+    // repository. `## [repo-id]` headings are used (not `###`) so they never
+    // collide with the per-directory `### <dir>/` headings or the
+    // `parseCodebaseMap` list-item regexes. Groups are sorted by declaring
+    // repo (enumeration order) then directory path so each repo is contiguous.
+    if (group.repo && group.repo !== emittedRepo) {
+      emittedRepo = group.repo;
+      lines.push(`## [${group.repo}]`);
+      lines.push("");
+    }
+
     const heading = group.path || "(root)";
     lines.push(`### ${heading}/`);
 
@@ -361,13 +503,15 @@ function buildCodebaseMap(
 } {
   const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
   const descriptions = existingDescriptions ?? new Map<string, string>();
-  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold, listed.repos);
   const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+  const repoIds = listed.repos ? Array.from(new Set(listed.repos)) : undefined;
   const metadata: CodebaseMapMetadata = {
     generatedAt,
-    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos),
     fileCount: listed.files.length,
     truncated: listed.truncated,
+    ...(repoIds ? { repositories: repoIds } : {}),
   };
   const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
 
@@ -387,13 +531,28 @@ function buildCodebaseMap(
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
+/**
+ * Resolve workspace-aware enumeration for parent mode, or undefined to fall
+ * back to the legacy single-root enumeration. Centralized so all three public
+ * entry points (generate/update/ensure) share one discovery path.
+ */
+function resolveWorkspaceEnumeration(
+  basePath: string,
+  resolved: ResolvedCodebaseMapOptions,
+): EnumeratedFiles | undefined {
+  const registry = loadWorkspaceRegistry(basePath);
+  if (!registry) return undefined;
+  return enumerateWorkspaceFiles(registry, resolved.excludes, resolved.maxFiles);
+}
+
 export function generateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
   existingDescriptions?: Map<string, string>,
 ): { content: string; fileCount: number; truncated: boolean; files: string[]; fingerprint: string; generatedAt: string } {
   const resolved = resolveGeneratorOptions(options);
-  return buildCodebaseMap(basePath, resolved, existingDescriptions);
+  const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+  return buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
 }
 
 /**
@@ -427,7 +586,8 @@ export function updateCodebaseMap(
 
   // Generate new map preserving descriptions — reuse the returned file list
   // to avoid a second enumeration (prevents race between content and stats).
-  const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
+  const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+  const result = buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
   const currentSet = new Set(result.files);
 
   // Count changes
@@ -467,7 +627,7 @@ export function ensureCodebaseMapFresh(
   ensureOptions?: EnsureCodebaseMapOptions,
 ): EnsureCodebaseMapResult {
   const resolved = resolveGeneratorOptions(options);
-  const cacheKey = `${basePath}::${resolved.optionSignature}`;
+  const cacheKey = `${basePath}::${resolved.optionSignature}::${workspaceEnumerationSignature(basePath)}`;
   const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
   const force = ensureOptions?.force === true;
   const now = Date.now();
@@ -481,8 +641,9 @@ export function ensureCodebaseMapFresh(
   }
 
   const existing = readCodebaseMap(basePath);
-  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
-  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+  const listed = resolveWorkspaceEnumeration(basePath, resolved)
+    ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos);
 
   const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
     freshnessCache.set(cacheKey, { checkedAt: now, result });