Resolve symlinks in Glob/Grep paths and plan file for cross-platform correctness

- glob.py/grep.py: use realpath instead of abspath so git pathspecs
  are computed from the canonical path (macOS /var -> /private/var);
  previously git rejected symlinked repo paths as "outside repository"
- planmode.py: store the plan file as realpath so the plan-mode write
  guard matches tool targets (plan file was blocked on macOS)
- Add deterministic regression tests for symlinked search paths and
  symlinked plan temp dirs (fail on the old code)

Author: beacoder

python_agent_harness/planmode.py

@@ -64,8 +64,11 @@ def ensure_plan_file(self) -> str:
         os.makedirs(os.path.dirname(path), exist_ok=True)
         if not os.path.exists(path):
             Path(path).write_text("", encoding="utf-8")
-        self.plan_file = path
-        return path
+        # Store the canonical path so the plan-mode write guard (which
+        # compares against realpath'd tool targets) matches — on macOS
+        # TMPDIR (/var) is a symlink to /private/var.
+        self.plan_file = os.path.realpath(path)
+        return self.plan_file
 
     def cleanup_plan_file(self) -> None:
         if not self.plan_file:

python_agent_harness/tools/glob.py

@@ -70,7 +70,10 @@ def run(self, args: dict, ctx: ToolContext) -> str:
                 return f"Error: path {path} is not readable"
         else:
             path = ctx.cwd
-        base = os.path.abspath(path)  # directory-file-name + expand-file-name
+        # realpath (not abspath): _git_root resolves symlinks (macOS /var ->
+        # /private/var), so the base must be canonical or relpath produces a
+        # pathspec git rejects as "outside repository".
+        base = os.path.realpath(path)
         depth = args.get("depth")
 
         git_root = _git_root(base)

python_agent_harness/tools/grep.py

@@ -41,7 +41,7 @@ class Grep(Tool):
 
     def run(self, args: dict, ctx: ToolContext) -> str:
         regex = args["regex"]
-        path = os.path.abspath(args["path"])
+        path = os.path.realpath(args["path"])
         if not os.path.isdir(path) and not os.path.isfile(path):
             return f"Error: path {args['path']} is not readable"
         glob = args.get("glob")

tests/test_agents_md.py

@@ -46,7 +46,7 @@ def test_finds_agents_md_in_project_root(self):
         with tempfile.TemporaryDirectory() as d:
             (Path(d) / "AGENTS.md").write_text("# Rules\n", encoding="utf-8")
             result = find_agents_md_files(d)
-            self.assertEqual([Path(p) for p in result], [Path(d) / "AGENTS.md"])
+            self.assertEqual([Path(p) for p in result], [(Path(d) / "AGENTS.md").resolve()])
 
     @unittest.skipUnless(shutil.which("git"), "git not available")
     def test_finds_agents_md_in_ancestor(self):
@@ -57,7 +57,7 @@ def test_finds_agents_md_in_ancestor(self):
             sub.mkdir(parents=True)
             (Path(d) / "AGENTS.md").write_text("# Root rules\n", encoding="utf-8")
             result = find_agents_md_files(str(sub))
-            self.assertEqual([Path(p) for p in result], [Path(d) / "AGENTS.md"])
+            self.assertEqual([Path(p) for p in result], [(Path(d) / "AGENTS.md").resolve()])
 
     @unittest.skipUnless(shutil.which("git"), "git not available")
     def test_stacks_every_ancestor_nearest_first(self):
@@ -76,7 +76,7 @@ def test_stacks_every_ancestor_nearest_first(self):
             result = find_agents_md_files(str(sub))
             self.assertEqual(
                 [Path(p) for p in result],
-                [pkg / "AGENTS.md", Path(d) / "AGENTS.md"],
+                [(pkg / "AGENTS.md").resolve(), (Path(d) / "AGENTS.md").resolve()],
             )
 
     @unittest.skipUnless(shutil.which("git"), "git not available")
@@ -92,7 +92,7 @@ def test_stops_at_git_root(self):
             # above the git root: must NOT be picked up
             (Path(outer) / "AGENTS.md").write_text("# Outer rules\n", encoding="utf-8")
             result = find_agents_md_files(str(sub))
-            self.assertEqual([Path(p) for p in result], [repo / "AGENTS.md"])
+            self.assertEqual([Path(p) for p in result], [(repo / "AGENTS.md").resolve()])
 
     def test_non_git_dir_is_its_own_bound(self):
         """Outside a repo the search is bounded by the project dir."""
@@ -147,7 +147,7 @@ def test_rendered_as_context_block(self):
             result = load_context_files(None, extra_files=find_agents_md_files(d))
             self.assertEqual(
                 result,
-                f"Request context:\n\nIn file `{agents}`:\n\n# Project Rules\nUse 4 spaces.",
+                f"Request context:\n\nIn file `{agents.resolve()}`:\n\n# Project Rules\nUse 4 spaces.",
             )
 
     def test_empty_file_yields_no_context(self):

tests/test_filesystem.py

@@ -512,11 +512,11 @@ def test_glob_tree_fallback_lists_files_and_depth(self):
         self._mkdir("proj", "sub")
         open(os.path.join(d, "sub", "b.py"), "w").close()
         out = GlobTool().run({"pattern": "*.py", "path": d}, self.ctx)
-        self.assertIn(os.path.join(d, "a.py"), out)
-        self.assertIn(os.path.join(d, "sub", "b.py"), out)
+        self.assertIn(os.path.realpath(os.path.join(d, "a.py")), out)
+        self.assertIn(os.path.realpath(os.path.join(d, "sub", "b.py")), out)
         out1 = GlobTool().run({"pattern": "*.py", "path": d, "depth": 1}, self.ctx)
-        self.assertIn(os.path.join(d, "a.py"), out1)
-        self.assertNotIn(os.path.join(d, "sub", "b.py"), out1)
+        self.assertIn(os.path.realpath(os.path.join(d, "a.py")), out1)
+        self.assertNotIn(os.path.realpath(os.path.join(d, "sub", "b.py")), out1)
 
     @unittest.skipUnless(shutil.which("git"), "git not available")
     def test_glob_and_grep_use_git_backend_in_repo(self):
@@ -527,8 +527,8 @@ def test_glob_and_grep_use_git_backend_in_repo(self):
                 f.write(content)
         subprocess.run(["git", "add", "."], cwd=repo, check=True)
         out = GlobTool().run({"pattern": "*", "path": repo}, self.ctx)
-        self.assertIn(os.path.join(repo, "a.py"), out)
-        self.assertIn(os.path.join(repo, "b.txt"), out)
+        self.assertIn(os.path.realpath(os.path.join(repo, "a.py")), out)
+        self.assertIn(os.path.realpath(os.path.join(repo, "b.txt")), out)
         out = Grep().run({"regex": "hello", "path": repo}, self.ctx)
         self.assertIn("a.py", out)
         self.assertIn("hello", out)
@@ -537,6 +537,27 @@ def test_glob_and_grep_use_git_backend_in_repo(self):
         self.assertIn("a.py", out)
         self.assertIn("hello", out)
 
+    @unittest.skipUnless(shutil.which("git"), "git not available")
+    def test_glob_and_grep_work_through_symlinked_path(self):
+        """Regression: a search path that goes through a symlink (macOS
+        /var -> /private/var) must be resolved before the git backend
+        computes relpaths, or git rejects the pathspec as outside the
+        repository."""
+        real = self._mkdir("real")
+        link = os.path.join(self.tmp.name, "link")
+        os.symlink(real, link)
+        subprocess.run(["git", "init", "-q", real], check=True)
+        with open(os.path.join(real, "a.py"), "w") as f:
+            f.write("hello world\n")
+        subprocess.run(["git", "add", "."], cwd=real, check=True)
+        out = GlobTool().run({"pattern": "*", "path": link}, self.ctx)
+        self.assertNotIn("outside repository", out)
+        self.assertNotIn("Glob failed", out)
+        self.assertIn(os.path.realpath(os.path.join(real, "a.py")), out)
+        out = Grep().run({"regex": "hello", "path": link}, self.ctx)
+        self.assertIn("a.py", out)
+        self.assertIn("hello", out)
+
     def test_glob_nonexistent_path_errors(self):
         out = GlobTool().run(
             {"pattern": "*", "path": os.path.join(self.tmp.name, "nope")}, self.ctx

tests/test_invariants.py

@@ -780,6 +780,32 @@ def test_plan_file_itself_stays_writable_in_plan_mode(self):
             with open(plan_file) as f:
                 self.assertEqual(f.read(), "via link")
 
+    def test_plan_file_writable_when_temp_dir_is_symlinked(self):
+        """Regression: when the plan dir goes through a symlink (macOS
+        TMPDIR /var -> /private/var), the plan file must still be
+        recognized as the plan file and stay writable in plan mode."""
+        with tempfile.TemporaryDirectory(prefix="pah-prop-plan-") as tmpdir:
+            real = os.path.join(tmpdir, "real")
+            os.makedirs(real)
+            link = os.path.join(tmpdir, "link")
+            os.symlink(real, link)
+            with mock.patch(
+                "python_agent_harness.planmode._plan_temp_dir",
+                return_value=link,
+            ):
+                session = self.make_plan_session(tmpdir)
+            plan_file = session.plan_mode.plan_file
+            self.assertTrue(os.path.isfile(plan_file))
+            dirname, basename = os.path.split(plan_file)
+            r = session.execute_tool(
+                "Write",
+                {"path": dirname, "filename": basename, "content": "# plan\n"},
+                call_id="w1",
+            )
+            self.assertNotIn("blocked by plan mode", r)
+            with open(plan_file) as f:
+                self.assertEqual(f.read(), "# plan\n")
+
     def test_read_only_tools_pass_through_plan_mode(self):
         with tempfile.TemporaryDirectory(prefix="pah-prop-plan-") as tmpdir:
             session = self.make_plan_session(tmpdir)

tests/test_prompts.py

@@ -200,7 +200,7 @@ def test_index_keyed_by_frontmatter_name(self):
                 encoding="utf-8",
             )
             index = index_skills(d)
-            self.assertEqual(index, {"天气预报助手": (str(skill), "does things")})
+            self.assertEqual(index, {"天气预报助手": (os.path.realpath(skill), "does things")})
 
     def test_no_frontmatter_name_skipped(self):
         with tempfile.TemporaryDirectory() as d:
@@ -219,7 +219,7 @@ def test_symlinked_skill_dir_indexed(self):
             skill = sub / "SKILL.md"
             skill.write_text("---\nname: linked-skill\n---\nbody", encoding="utf-8")
             os.symlink(sub, Path(d) / "linked")
-            self.assertEqual(index_skills(d)["linked-skill"][0], str(skill))
+            self.assertEqual(index_skills(d)["linked-skill"][0], os.path.realpath(skill))
 
 
 class TestLoadContextFiles(unittest.TestCase):

tests/test_session.py

@@ -152,7 +152,10 @@ def test_skill_found_by_frontmatter_name(self):
             with open(os.path.join(sub, "SKILL.md"), "w") as f:
                 f.write("---\nname: my-rules\ndescription: rules\n---\n# Rules")
             session._skill_dir = d
-            self.assertEqual(session.find_skill("my-rules"), os.path.join(sub, "SKILL.md"))
+            self.assertEqual(
+                session.find_skill("my-rules"),
+                os.path.realpath(os.path.join(sub, "SKILL.md")),
+            )
 
     def test_frontmatter_name_differs_from_directory_name(self):
         """Regression test: the advertised name (frontmatter) must
@@ -165,7 +168,10 @@ def test_frontmatter_name_differs_from_directory_name(self):
             with open(os.path.join(sub, "SKILL.md"), "w") as f:
                 f.write("---\nname: 天气预报助手\n---\n# body")
             session._skill_dir = d
-            self.assertEqual(session.find_skill("天气预报助手"), os.path.join(sub, "SKILL.md"))
+            self.assertEqual(
+                session.find_skill("天气预报助手"),
+                os.path.realpath(os.path.join(sub, "SKILL.md")),
+            )
 
     def test_nested_skill_dir_discovered(self):
         session = RecordingSession()
@@ -175,7 +181,10 @@ def test_nested_skill_dir_discovered(self):
             with open(os.path.join(nested, "SKILL.md"), "w") as f:
                 f.write("---\nname: deep-skill\n---\nbody")
             session._skill_dir = d
-            self.assertEqual(session.find_skill("deep-skill"), os.path.join(nested, "SKILL.md"))
+            self.assertEqual(
+                session.find_skill("deep-skill"),
+                os.path.realpath(os.path.join(nested, "SKILL.md")),
+            )
 
     def test_flat_file_without_frontmatter_returns_none(self):
         """Flat files (skills/style.md) are no longer resolvable: only
@@ -210,7 +219,10 @@ def test_symlinked_skill_dir_resolves(self):
                 f.write("---\nname: linked-skill\n---\n# Linked")
             os.symlink(sub, os.path.join(d, "linked"))
             session._skill_dir = d
-            self.assertEqual(session.find_skill("linked-skill"), os.path.join(sub, "SKILL.md"))
+            self.assertEqual(
+                session.find_skill("linked-skill"),
+                os.path.realpath(os.path.join(sub, "SKILL.md")),
+            )
 
     def test_traversal_skill_returns_none(self):
         """Path-traversal inputs are inert: lookup only matches names in