🤖 fix: present sub-projects to the agent as regular projects

ammar-agent · ammar-agent · commit f0de68eb7c69 · 2026-05-07T10:53:30.000-05:00
Sub-project workspaces now look indistinguishable from a regular
single-project workspace rooted at the sub-project directory:

- The &lt;environment&gt; block uses the same per-runtime description and
  guardrails it would use for any project at that cwd. No "the X
  sub-project of the Y at Z" framing, no relative-paths preamble.
- Bash tool description is unchanged from the regular single-project
  case (same "Runs in &lt;cwd&gt; - no cd needed" form).
- AGENTS.md is concatenated parent → sub-project (parent first so
  general rules anchor before specific overrides) but with no segment
  headings — the agent perceives a single AGENTS.md, exactly like a
  regular project's. The parent root is derived by stripping the
  recorded sub-project relative segment off the cwd, so worktree/SSH
  /Docker workspaces read the parent's AGENTS.md from their own
  branch's checkout (not from the user's local checkout, which may
  be on a different commit).
- Stale-metadata fallback: if the recorded subProjectPath isn't a
  descendant of projectPath, or the cwd doesn't end with the expected
  suffix, we degrade to reading just the cwd's AGENTS.md instead of
  guessing at a parent root.

Replaces the earlier doubled-path lookup in
readSingleProjectContextInstructions (which always read the
sub-project's AGENTS.md as if it were the parent's, and tried to read
the sub-project's AGENTS.md from &lt;cwd&gt;/&lt;rel&gt;/&lt;rel&gt; which never
existed) with a single inline helper that derives the parent root
deterministically.
diff --git a/docs/agents/system-prompt.mdx b/docs/agents/system-prompt.mdx
@@ -71,8 +71,16 @@ Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Mu
 
 /**
  * Build environment context XML block describing the workspace.
- * @param workspacePath - Workspace directory path
+ *
+ * Sub-project workspaces are framed identically to regular projects: the cwd
+ * (already the sub-project directory thanks to resolveWorkspaceExecutionPath)
+ * is presented as "the project" with no parent-repo callout. The agent does
+ * not need to know about the parent's existence to do work — it just sees a
+ * project rooted at this directory.
+ *
+ * @param workspacePath - Workspace directory path (cwd; for sub-projects this is already the sub-project path)
  * @param runtimeType - Runtime type (local, worktree, ssh, docker)
+ * @param bestOf - Best-of grouping metadata for sibling sub-agent batches
  */
 function buildEnvironmentContext(
   workspacePath: string,
diff --git a/src/node/services/agentSkills/builtInSkillContent.generated.ts b/src/node/services/agentSkills/builtInSkillContent.generated.ts
@@ -1585,8 +1585,16 @@ export const BUILTIN_SKILL_FILES: Record<string, Record<string, string>> = {
       "",
       "/**",
       " * Build environment context XML block describing the workspace.",
-      " * @param workspacePath - Workspace directory path",
+      " *",
+      " * Sub-project workspaces are framed identically to regular projects: the cwd",
+      " * (already the sub-project directory thanks to resolveWorkspaceExecutionPath)",
+      ' * is presented as "the project" with no parent-repo callout. The agent does',
+      " * not need to know about the parent's existence to do work — it just sees a",
+      " * project rooted at this directory.",
+      " *",
+      " * @param workspacePath - Workspace directory path (cwd; for sub-projects this is already the sub-project path)",
       " * @param runtimeType - Runtime type (local, worktree, ssh, docker)",
+      " * @param bestOf - Best-of grouping metadata for sibling sub-agent batches",
       " */",
       "function buildEnvironmentContext(",
       "  workspacePath: string,",
diff --git a/src/node/services/systemMessage.test.ts b/src/node/services/systemMessage.test.ts
@@ -540,4 +540,172 @@ OpenAI-only instructions.
       });
     }
   });
+
+  describe("sub-project workspaces look like regular projects", () => {
+    // Sub-project workspaces share the parent project's checkout but cwd into
+    // a descendant directory. From the agent's perspective they should be
+    // indistinguishable from a single-project workspace rooted at that cwd:
+    // no parent-repo callout in the prompt, no inherited parent AGENTS.md,
+    // no special "sub-project" framing in tool descriptions.
+    async function setupSubProjectFixture(): Promise<{
+      subProjectMetadata: WorkspaceMetadata;
+      regularMetadata: WorkspaceMetadata;
+      subProjectCwd: string;
+      parentRoot: string;
+    }> {
+      const subProjectAbs = path.join(workspaceDir, "packages", "api");
+      await fs.mkdir(subProjectAbs, { recursive: true });
+
+      const subProjectMetadata: WorkspaceMetadata = {
+        id: "test-workspace",
+        name: "test-workspace",
+        projectName: "test-project",
+        projectPath: workspaceDir,
+        subProjectPath: subProjectAbs,
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
+      };
+
+      // Regular single-project workspace whose project path IS the sub-project
+      // directory. Used as the reference oracle: the sub-project workspace's
+      // prompt at the same cwd must match this byte-for-byte in <environment>.
+      const regularMetadata: WorkspaceMetadata = {
+        id: "test-workspace",
+        name: "test-workspace",
+        projectName: "test-project",
+        projectPath: subProjectAbs,
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
+      };
+
+      return {
+        subProjectMetadata,
+        regularMetadata,
+        subProjectCwd: subProjectAbs,
+        parentRoot: workspaceDir,
+      };
+    }
+
+    test("environment block is identical to a regular single-project workspace at the same cwd", async () => {
+      // Core invariant: presence of `subProjectPath` in metadata must not
+      // change the <environment> block. The agent sees the same description
+      // and lines whether the workspace is configured as a sub-project or as
+      // a regular project rooted at that directory.
+      const { subProjectMetadata, regularMetadata, subProjectCwd } = await setupSubProjectFixture();
+
+      const subProjectMessage = await buildSystemMessage(
+        subProjectMetadata,
+        runtime,
+        subProjectCwd
+      );
+      const regularMessage = await buildSystemMessage(regularMetadata, runtime, subProjectCwd);
+
+      const subEnvironment = extractTagContent(subProjectMessage, "environment");
+      const regularEnvironment = extractTagContent(regularMessage, "environment");
+      expect(subEnvironment).toBe(regularEnvironment);
+    });
+
+    test("environment block does not mention sub-project framing or relative-path nudges", async () => {
+      // Regression guard against the rejected direction (PR #3244 v1) where
+      // the prompt called out "the `packages/api` sub-project of the X at Y"
+      // and added a relative-paths preamble. The agent should see the cwd as
+      // a regular project root with no parent-repo context. (The parentRoot
+      // is a path prefix of subProjectCwd, so checking for it directly is
+      // ambiguous — the byte-equality test above already proves the env
+      // block contains no parent-specific framing.)
+      const { subProjectMetadata, subProjectCwd } = await setupSubProjectFixture();
+
+      const systemMessage = await buildSystemMessage(subProjectMetadata, runtime, subProjectCwd);
+      const environment = extractTagContent(systemMessage, "environment") ?? "";
+
+      expect(environment).not.toContain("sub-project");
+      expect(environment).not.toMatch(/Prefer paths relative to/);
+    });
+
+    test("AGENTS.md is concatenated from parent then sub-project with no segment tagging", async () => {
+      // Sub-projects inherit parent conventions: parent AGENTS.md is glued
+      // before the sub-project's own AGENTS.md so the agent sees a single
+      // combined block. No segment headings (`# Project context (root: ...)`,
+      // `# Sub-project context (root: ...)`) are added — that would reveal
+      // the sub-project structure to the agent, contradicting the
+      // "regular project" framing the rest of the prompt commits to.
+      const { subProjectMetadata, subProjectCwd, parentRoot } = await setupSubProjectFixture();
+
+      await fs.writeFile(
+        path.join(parentRoot, "AGENTS.md"),
+        "PARENT_MARKER: parent project conventions.\n"
+      );
+      await fs.writeFile(
+        path.join(subProjectCwd, "AGENTS.md"),
+        "SUB_MARKER: sub-project specific conventions.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(subProjectMetadata, runtime, subProjectCwd);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).toContain("PARENT_MARKER");
+      expect(customInstructions).toContain("SUB_MARKER");
+      // Parent first so general rules anchor before the more specific
+      // sub-project overrides.
+      expect(customInstructions.indexOf("PARENT_MARKER")).toBeLessThan(
+        customInstructions.indexOf("SUB_MARKER")
+      );
+      // No segment headings — the agent should see a single AGENTS.md.
+      expect(customInstructions).not.toContain("# Project context (root:");
+      expect(customInstructions).not.toContain("# Sub-project context (root:");
+    });
+
+    test("only-parent AGENTS.md is loaded when sub-project has none", async () => {
+      // If only the parent has AGENTS.md, sub-project workspaces should
+      // still inherit it.
+      const { subProjectMetadata, subProjectCwd, parentRoot } = await setupSubProjectFixture();
+      await fs.writeFile(
+        path.join(parentRoot, "AGENTS.md"),
+        "PARENT_ONLY_MARKER: only parent conventions.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(subProjectMetadata, runtime, subProjectCwd);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).toContain("PARENT_ONLY_MARKER");
+    });
+
+    test("only-sub-project AGENTS.md is loaded when parent has none", async () => {
+      // Symmetric: a sub-project with its own AGENTS.md but no parent
+      // AGENTS.md should still load the sub-project's own.
+      const { subProjectMetadata, subProjectCwd } = await setupSubProjectFixture();
+      await fs.writeFile(
+        path.join(subProjectCwd, "AGENTS.md"),
+        "SUB_ONLY_MARKER: only sub-project conventions.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(subProjectMetadata, runtime, subProjectCwd);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).toContain("SUB_ONLY_MARKER");
+    });
+
+    test("falls back to cwd-only AGENTS.md when sub-project metadata is stale", async () => {
+      // If subProjectPath doesn't sit under projectPath (corrupted persisted
+      // state, or a cwd that doesn't end with the expected suffix), we
+      // can't safely derive the parent root. Degrade to reading just the
+      // cwd's AGENTS.md instead of guessing at a parent root that might
+      // pull in unrelated guidance.
+      const { subProjectMetadata, subProjectCwd, parentRoot } = await setupSubProjectFixture();
+      const stale = { ...subProjectMetadata, subProjectPath: "/elsewhere/api" };
+
+      await fs.writeFile(
+        path.join(parentRoot, "AGENTS.md"),
+        "PARENT_MARKER: should not be inherited from stale metadata.\n"
+      );
+      await fs.writeFile(
+        path.join(subProjectCwd, "AGENTS.md"),
+        "SUB_MARKER: should still appear.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(stale, runtime, subProjectCwd);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).not.toContain("PARENT_MARKER");
+      expect(customInstructions).toContain("SUB_MARKER");
+    });
+  });
 });
diff --git a/src/node/services/systemMessage.ts b/src/node/services/systemMessage.ts
@@ -97,8 +97,16 @@ Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Mu
 
 /**
  * Build environment context XML block describing the workspace.
- * @param workspacePath - Workspace directory path
+ *
+ * Sub-project workspaces are framed identically to regular projects: the cwd
+ * (already the sub-project directory thanks to resolveWorkspaceExecutionPath)
+ * is presented as "the project" with no parent-repo callout. The agent does
+ * not need to know about the parent's existence to do work — it just sees a
+ * project rooted at this directory.
+ *
+ * @param workspacePath - Workspace directory path (cwd; for sub-projects this is already the sub-project path)
  * @param runtimeType - Runtime type (local, worktree, ssh, docker)
+ * @param bestOf - Best-of grouping metadata for sibling sub-agent batches
  */
 function buildEnvironmentContext(
   workspacePath: string,
@@ -334,50 +342,75 @@ async function readSingleProjectContextInstructions(
   runtime: Runtime,
   workspacePath: string
 ): Promise<string | null> {
-  // Read parent + sub-project AGENTS.md from the workspace's *own* checkout
-  // (via the runtime). For worktree/SSH/Docker flows the parent project's host
-  // path is a different checkout than the workspace branch — mixing the two
-  // would inject contradictory or stale guidance and prevent workspace-branch
-  // edits from overriding parent guidance. The workspace root is by
-  // construction the parent project's checkout, and any registered
-  // sub-project's relative path is stable across checkouts of the same repo.
-  const subProjectRelativePath = metadata.subProjectPath
-    ? deriveSubProjectRelativePath(metadata.projectPath, metadata.subProjectPath)
-    : null;
-
-  // path.relative emits host-native separators (e.g., "packages\\api" on Windows),
-  // but SSH/Docker/devcontainer runtimes read files via POSIX paths. Normalize to
-  // forward slashes and let the runtime joiner produce a runtime-correct path.
-  const subProjectInstructionsDir = subProjectRelativePath
-    ? runtime.normalizePath(subProjectRelativePath.replace(/\\/g, "/"), workspacePath)
-    : null;
-
-  const [parentInstructions, subProjectInstructions] = await Promise.all([
-    readInstructionSetFromRuntime(runtime, workspacePath),
-    subProjectInstructionsDir
-      ? readInstructionSetFromRuntime(runtime, subProjectInstructionsDir)
-      : Promise.resolve(null),
-  ]);
+  // The agent's view of a sub-project workspace is identical to a regular
+  // project rooted at the sub-project cwd — same <environment> block, same
+  // tool descriptions — but AGENTS.md is concatenated from parent then
+  // sub-project so the agent inherits parent conventions transparently. The
+  // concatenation is plain (no segment headings, no "Project context" /
+  // "Sub-project context" tags) so the agent perceives a single AGENTS.md
+  // just like any regular project's.
+  //
+  // Parent first, sub-project second: general rules anchor before more
+  // specific sub-project overrides.
+  //
+  // For non-sub-project workspaces (or stale metadata that doesn't resolve
+  // cleanly) this collapses to reading just the cwd — historical behavior.
+  //
+  // We always read the parent AGENTS.md from the workspace's *own* checkout
+  // (i.e. derived from workspacePath, not from metadata.projectPath) so that
+  // worktree/SSH/Docker workspaces see the parent guidance from their own
+  // branch, not from the user's local checkout which may be on a different
+  // commit.
+  const parentRoot = deriveSubProjectParentRoot(metadata, workspacePath);
+
+  const segmentDirs: string[] = [];
+  if (parentRoot && parentRoot !== workspacePath) {
+    segmentDirs.push(parentRoot);
+  }
+  segmentDirs.push(workspacePath);
 
-  const contextSegments = [parentInstructions, subProjectInstructions].filter(
+  const segments = await Promise.all(
+    segmentDirs.map((dir) => readInstructionSetFromRuntime(runtime, dir))
+  );
+  const filtered = segments.filter(
     (segment): segment is string => segment != null && segment.trim().length > 0
   );
-  return contextSegments.length > 0 ? contextSegments.join("\n\n") : null;
+  return filtered.length > 0 ? filtered.join("\n\n") : null;
 }
 
 /**
- * Compute the path of `subProjectPath` relative to `projectPath` for use under
- * the workspace's own checkout. Returns `null` if the recorded sub-project
- * path is not actually a descendant of the parent project (stale persisted
- * state) — callers should treat that as "no sub-project segment" and fall
- * back to parent-only instructions rather than failing.
+ * Derive the parent project root for a sub-project workspace by stripping
+ * the recorded sub-project relative segment off the cwd. Returns null when:
+ *
+ * - The workspace is not configured as a sub-project (no `subProjectPath`).
+ * - The recorded sub-project path is not a descendant of the parent project
+ *   (stale metadata) — `path.relative` would emit `..` or an absolute path.
+ * - The cwd doesn't end with the expected sub-project suffix — some other
+ *   resolution path produced the cwd, and we don't want to guess.
+ *
+ * Separator handling: local Windows runtimes produce backslash-separated
+ * cwds (`C:\repo\packages\api`) while SSH/Docker/devcontainer runtimes use
+ * forward slashes. We compare the suffix against a forward-slash
+ * normalization of both sides so Windows cwds still match, then slice the
+ * original `workspacePath` by length (segment counts and byte length match
+ * between the two separator styles) so the returned parent root retains
+ * the runtime-native separator style used everywhere else.
  */
-function deriveSubProjectRelativePath(projectPath: string, subProjectPath: string): string | null {
-  const relative = path.relative(projectPath, subProjectPath);
+function deriveSubProjectParentRoot(
+  metadata: WorkspaceMetadata,
+  workspacePath: string
+): string | null {
+  const subProjectPath = metadata.subProjectPath?.trim();
+  if (!subProjectPath) return null;
+  const relative = path.relative(metadata.projectPath, subProjectPath);
   if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
     return null;
   }
-  return relative;
+  const posixRelative = relative.replace(/\\/g, "/");
+  const suffix = `/${posixRelative}`;
+  const normalizedWorkspace = workspacePath.replace(/\\/g, "/");
+  if (!normalizedWorkspace.endsWith(suffix)) return null;
+  return workspacePath.slice(0, workspacePath.length - suffix.length) || "/";
 }
 
 /**
