From 111b7968203482bbafe4e0287f740cd74e60475a Mon Sep 17 00:00:00 2001
From: MoerAI <friendnt@g.skku.edu>
Date: Mon, 27 Apr 2026 20:33:06 +0900
Subject: [PATCH] fix(resolve-file-uri): explain project boundary restriction
 in rejection warning (fixes #3554)

Root cause: when a file:// prompt URI resolves outside the project root, resolvePromptAppend returns the warning '[WARNING: Path rejected: $URI]' with no indication of WHY the path was rejected. Issue #3554 reports that this is confusing because the docs explicitly advertise support for absolute, home-relative, and cross-project file:// paths, yet the code intentionally restricts file:// prompt resolution to the project boundary (commit 98659783, security hardening).

Fix: extend the warning message so it now includes the resolved project root and an explicit hint that file:// prompts must reside within the project boundary. The security restriction itself is preserved unchanged.

Verification: added a regression test that asserts the rejection warning matches /outside project root/i. Test fails before the fix, passes after. Full resolve-file-uri.test.ts suite: 11 pass / 0 fail. typecheck clean.
---
 src/agents/builtin-agents/resolve-file-uri.test.ts | 12 ++++++++++++
 src/agents/builtin-agents/resolve-file-uri.ts      |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

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)) {