diff --git a/src/agents/builtin-agents/resolve-file-uri.test.ts b/src/agents/builtin-agents/resolve-file-uri.test.ts
index 6f05f61b6..9fb5c9550 100644
--- a/src/agents/builtin-agents/resolve-file-uri.test.ts
+++ b/src/agents/builtin-agents/resolve-file-uri.test.ts
@@ -161,4 +161,16 @@ describe("resolvePromptAppend", () => {
     expect(resolved).toContain("[WARNING: Path rejected:")
     expect(resolved).not.toContain("absolute-content")
   })
+
+  test("rejection warning explains the project boundary restriction (issue #3554)", () => {
+    //#given
+    const input = `file://${absoluteFilePath}`
+
+    //#when
+    const resolved = resolvePromptAppend(input, configDir)
+
+    //#then
+    expect(resolved).toContain("[WARNING: Path rejected:")
+    expect(resolved).toMatch(/outside project root/i)
+  })
 })
diff --git a/src/agents/builtin-agents/resolve-file-uri.ts b/src/agents/builtin-agents/resolve-file-uri.ts
index 46e7f154f..8bb5fec0d 100644
--- a/src/agents/builtin-agents/resolve-file-uri.ts
+++ b/src/agents/builtin-agents/resolve-file-uri.ts
@@ -27,7 +27,7 @@ export function resolvePromptAppend(promptAppend: string, configDir?: string): s
       filePath,
       projectRoot,
     })
-    return `[WARNING: Path rejected: ${promptAppend}]`
+    return `[WARNING: Path rejected: ${promptAppend} (resolved outside project root ${projectRoot}; file:// prompts must reside within the project boundary)]`
   }
 
   if (!existsSync(filePath)) {