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

Sub-project workspaces now look indistinguishable from a regular
single-project workspace rooted at the sub-project directory:

- The <environment> 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 <cwd> - no cd needed" form).
- AGENTS.md is concatenated parent → sub-project (parent first so
  general rules anchor before specific overrides). Each segment is
  wrapped with two markers:
    * A visible H1 heading naming the source path relative to the cwd
      (e.g. `` # `../../AGENTS.md` ``). The heading both names the
      segment's source AND bounds any scoped `## Tool:` / `## Model:`
      sections inside the segment so they can't span across the
      segment join into the next segment's narrative.
    * A markdown-invisible HTML comment with the same path injected
      after every ATX-style `## Tool:` / `## Model:` heading inside
      the segment. The H1 doesn't survive scoped extraction, so the
      inner comment carries the path provenance into per-tool/per-
      model contexts. Without this, `extractToolSection` would return
      bash bodies from both parent and sub-project with no way to
      tell which root was authored against which.
- 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).
  Depth of the relative-path heading tracks the actual sub-project
  nesting depth.
- 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 verbatim
  with no path-source heading or comment — historical behavior,
  unchanged.
- Regular non-sub-project workspaces are unaffected: no path-source
  markers are emitted (one source = no ambiguity), preserving the
  exact prompt bytes for single-project workspaces.

Also align extractModelSection's multi-match semantics with
extractToolSection: collect every matching `## Model: …` section in
source order and concatenate, instead of returning only the first
match. Without this, sub-project model overrides were silently
dropped when the parent AGENTS.md also defined a matching `## Model:`
section — only the parent's body landed in the per-model section,
and the sub-project's intended override never reached the agent.
The change is principled (parallel to how tool overrides already
compose for multi-project workspaces) and removes the now-unused
internal extractSectionByHeading helper.

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 <cwd>/<rel>/<rel> which never
existed) with an inline helper that derives both the parent root and
the relative-path hint deterministically.

Author: ammar-agent

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,

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,",

src/node/services/systemMessage.test.ts

@@ -540,4 +540,355 @@ 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 parent → sub-project with H1 path-source headings", 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. Each segment opens with an H1 heading whose body
+      // is the source path relative to the cwd (e.g. `` # `../../AGENTS.md` ``
+      // or `` # `./AGENTS.md` ``) so the agent can disambiguate which root
+      // any relative path references in each segment should resolve
+      // against. The H1 also bounds scoped `## Tool:` / `## Model:`
+      // sections inside the segment, preventing them from spanning across
+      // the segment join into the next segment's narrative.
+      //
+      // We deliberately avoid the rejected v1 framing of `# Project context
+      // (root: ...)` / `# Sub-project context (root: ...)` — the H1 here is
+      // just a path note, not a structural callout dressing the sub-project
+      // up as a special feature.
+      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");
+      // `packages/api` is two levels deep, so the parent AGENTS.md is
+      // `../../AGENTS.md` from the cwd.
+      expect(customInstructions).toContain("# `../../AGENTS.md`");
+      expect(customInstructions).toContain("# `./AGENTS.md`");
+      // Each H1 must precede its corresponding content.
+      expect(customInstructions.indexOf("# `../../AGENTS.md`")).toBeLessThan(
+        customInstructions.indexOf("PARENT_MARKER")
+      );
+      expect(customInstructions.indexOf("# `./AGENTS.md`")).toBeLessThan(
+        customInstructions.indexOf("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")
+      );
+      // Regression guard against the rejected v1 verbose framing.
+      expect(customInstructions).not.toContain("# Project context (root:");
+      expect(customInstructions).not.toContain("# Sub-project context (root:");
+    });
+
+    test("relative-path heading depth tracks the sub-project nesting depth", async () => {
+      // A single-segment sub-project (`api` instead of `packages/api`) only
+      // needs one `../` level. Verifies the depth computation rather than
+      // hard-coding the fixture's two-level structure.
+      const subProjectAbs = path.join(workspaceDir, "api");
+      await fs.mkdir(subProjectAbs, { recursive: true });
+      const metadata: WorkspaceMetadata = {
+        id: "test-workspace",
+        name: "test-workspace",
+        projectName: "test-project",
+        projectPath: workspaceDir,
+        subProjectPath: subProjectAbs,
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
+      };
+
+      await fs.writeFile(
+        path.join(workspaceDir, "AGENTS.md"),
+        "DEPTH_TEST_PARENT_MARKER: depth=1 parent.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(metadata, runtime, subProjectAbs);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).toContain("# `../AGENTS.md`");
+      expect(customInstructions).not.toContain("# `../../AGENTS.md`");
+      expect(customInstructions).toContain("DEPTH_TEST_PARENT_MARKER");
+    });
+
+    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 — and the H1 path heading lets the agent know
+      // it's reading the parent's, not its own.
+      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");
+      expect(customInstructions).toContain("# `../../AGENTS.md`");
+      expect(customInstructions).not.toContain("# `./AGENTS.md`");
+    });
+
+    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 with the matching
+      // `./AGENTS.md` heading.
+      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");
+      expect(customInstructions).toContain("# `./AGENTS.md`");
+      expect(customInstructions).not.toContain("# `../../AGENTS.md`");
+    });
+
+    test("regular non-sub-project workspaces emit no path-source heading", async () => {
+      // Non-sub-project workspaces preserve historical behavior: the cwd's
+      // AGENTS.md is loaded verbatim with no path-source heading or
+      // comment. Otherwise we'd be subtly changing the prompt for every
+      // regular project workspace.
+      const { regularMetadata, subProjectCwd } = await setupSubProjectFixture();
+      await fs.writeFile(
+        path.join(subProjectCwd, "AGENTS.md"),
+        "REGULAR_MARKER: regular project conventions.\n"
+      );
+
+      const systemMessage = await buildSystemMessage(regularMetadata, runtime, subProjectCwd);
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+
+      expect(customInstructions).toContain("REGULAR_MARKER");
+      expect(customInstructions).not.toContain("# `");
+      expect(customInstructions).not.toContain("<!--");
+    });
+
+    test("path-source comment is injected inside scoped Tool: / Model: sections so they survive extraction", async () => {
+      // Codex-flagged regression (PR #3244): `extractToolSection` /
+      // `extractModelSection` pull the body of a `## Tool: bash` /
+      // `## Model: …` section out of the segment, but the top-level
+      // `<!-- ../../AGENTS.md -->` comment lives BEFORE the section and
+      // isn't part of the extracted body. Without injecting the comment
+      // inside each scoped section, scoped tool/model instructions lose
+      // the parent-vs-subproject provenance — defeating the purpose of
+      // the comment for any path-sensitive guidance authored under a
+      // scoped heading.
+      //
+      // The injection must also play nicely with
+      // `stripScopedInstructionSections`, which deletes the entire
+      // scoped section from <custom-instructions>: the inner comment
+      // disappears with it (no leftover comment alone), while the
+      // top-level comment for the surviving narrative still anchors
+      // the segment.
+      const { subProjectMetadata, subProjectCwd, parentRoot } = await setupSubProjectFixture();
+
+      await fs.writeFile(
+        path.join(parentRoot, "AGENTS.md"),
+        `Parent narrative.
+
+## Tool: bash
+PARENT_BASH_RULE: parent's bash convention.
+
+## Model: anthropic:claude-sonnet-4-20250514
+PARENT_MODEL_RULE: parent model preference.
+`
+      );
+      await fs.writeFile(
+        path.join(subProjectCwd, "AGENTS.md"),
+        `Sub-project narrative.
+
+## Tool: bash
+SUB_BASH_RULE: sub-project's bash convention.
+
+## Model: anthropic:claude-sonnet-4-20250514
+SUB_MODEL_RULE: sub-project model override.
+`
+      );
+
+      const modelString = "anthropic:claude-sonnet-4-20250514";
+      const toolInstructions = await readToolInstructions(
+        subProjectMetadata,
+        runtime,
+        subProjectCwd,
+        modelString
+      );
+
+      const bash = toolInstructions.bash ?? "";
+      // Both bash bodies must appear in the per-tool extraction with their
+      // respective path-source comments.
+      expect(bash).toContain("PARENT_BASH_RULE");
+      expect(bash).toContain("<!-- ../../AGENTS.md -->");
+      expect(bash).toContain("SUB_BASH_RULE");
+      expect(bash).toContain("<!-- ./AGENTS.md -->");
+      // Each comment precedes its corresponding rule so the agent reads
+      // "this rule comes from this path" linearly.
+      expect(bash.indexOf("<!-- ../../AGENTS.md -->")).toBeLessThan(
+        bash.indexOf("PARENT_BASH_RULE")
+      );
+      expect(bash.indexOf("<!-- ./AGENTS.md -->")).toBeLessThan(bash.indexOf("SUB_BASH_RULE"));
+
+      const systemMessage = await buildSystemMessage(
+        subProjectMetadata,
+        runtime,
+        subProjectCwd,
+        undefined,
+        modelString
+      );
+
+      // Codex-flagged regression (PR #3244): when both parent and sub-project
+      // define matching `## Model: ...` sections, both bodies must appear in
+      // the per-model section (the previous singular `extractModelSection`
+      // returned only the parent's, silently dropping the sub-project's
+      // override). Sub-project body comes second so its rule overrides the
+      // parent's via order of presentation.
+      const sonnetSection =
+        extractTagContent(systemMessage, "model-anthropic-claude-sonnet-4-20250514") ?? "";
+      expect(sonnetSection).toContain("PARENT_MODEL_RULE");
+      expect(sonnetSection).toContain("SUB_MODEL_RULE");
+      expect(sonnetSection).toContain("<!-- ../../AGENTS.md -->");
+      expect(sonnetSection).toContain("<!-- ./AGENTS.md -->");
+      expect(sonnetSection.indexOf("PARENT_MODEL_RULE")).toBeLessThan(
+        sonnetSection.indexOf("SUB_MODEL_RULE")
+      );
+
+      // Sanity check: <custom-instructions> still strips scoped sections
+      // (including the inner comment) so the bash/model rules don't leak
+      // into the unscoped instructions block.
+      const customInstructions = extractTagContent(systemMessage, "custom-instructions") ?? "";
+      expect(customInstructions).not.toContain("PARENT_BASH_RULE");
+      expect(customInstructions).not.toContain("SUB_BASH_RULE");
+      expect(customInstructions).not.toContain("PARENT_MODEL_RULE");
+      expect(customInstructions).not.toContain("SUB_MODEL_RULE");
+      // Top-level H1 path headings survive (they're outside scoped sections,
+      // and they bound the scoped sections to their own segment so the
+      // parent's `## Model: ...` can't sweep the sub-project's narrative
+      // into its strip range).
+      expect(customInstructions).toContain("# `../../AGENTS.md`");
+      expect(customInstructions).toContain("# `./AGENTS.md`");
+      // Inner HTML comments inside scoped sections must NOT leak into the
+      // <custom-instructions> block: they're stripped along with their
+      // section.
+      expect(customInstructions).not.toContain("<!-- ../../AGENTS.md -->");
+      expect(customInstructions).not.toContain("<!-- ./AGENTS.md -->");
+    });
+
+    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 — historical behavior — with no path-source comment
+      // since there's only one source.
+      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");
+      expect(customInstructions).not.toContain("# `");
+      expect(customInstructions).not.toContain("<!--");
+    });
+  });
 });