graphite-code 1.2.0__tar.gz → 1.2.1__tar.gz

{graphite_code-1.2.0 → graphite_code-1.2.1}/CHANGELOG.md

@@ -15,6 +15,75 @@ machine-checkable identity; the version is for humans.
 
 ## [Unreleased]
 
+## [1.2.1] — 2026-10-11
+
+A patch release. It carries one fix, to the agent hooks (#80). No stable
+surface in `docs/compatibility.md` changes: nothing under `docs/reference/` or
+`docs/schemas/` moves, `graphite agent-hook` still always exits 0, and the
+wording of a hook's message is not a stable surface. The graph itself does not
+change: on this repository, measured against the deployed 1.2.0 engine,
+8581 of 8581 node ids survive, 23612 of 23612 edge triples are unchanged,
+every relation count is equal, and `analysis` is identical. Only the engine
+fingerprint moves, because graphite's own bytes did.
+
+### Fixed
+
+**The agent hooks find the repository from a subfolder (#80).** A hook payload
+carries the session's directory, and in Claude Code that follows a `cd` in the
+shell. All three hooks took it for the repository root. One directory below the
+root, with the graph fresh at the root:
+
+- `session-start` said `Graph status: missing`, the status that licenses a full
+  fallback from graph-first. The remedy it printed, `python -m graphite build .`,
+  is refused there ("nested Git roots are unsupported").
+- `pre-tool-use` wrote nothing: no refusal in strict mode and no reminder. A
+  `cd` into any subfolder switched the gate off.
+- `stop` created a `.graphite/local/` in the subfolder for its cursor and looked
+  for the turn's usage there.
+- The subfolder was registered as an open project. The daemon cannot build
+  one, so it logged `project_snapshot_failed` for it at every discovery cycle,
+  and the repository's own marker was no longer renewed.
+
+The repository is now the nearest directory upward that holds `.git`, the test
+the build already uses to refuse a nested path (`ingest.enclosing_git_root`).
+It is taken only where graphite is set up: a `graph-out/graph.json`, or the
+`GRAPHITE.md` that `init` commits. In a subfolder of any other checkout, and in
+a directory outside every checkout, the hooks read the session's directory as
+they did. A repository inside the repository, with its own `.git`, stays its
+own root.
+
+One reading changes inside a checkout that is set up. A folder there that has
+its own `GRAPHITE.md` or `graph-out/` but no `.git` was read as a project of
+its own: `Graph status: missing`, or `unknown` over a leftover graph, with a
+`build .` that is refused there. It is now read as part of the checkout.
+
+Below the root:
+
+- The graph, the freshness check, the usage ledger and the activation marker
+  are the repository's.
+- A search's relative paths, and a search that names no path, belong to the
+  directory the shell is in. `grep <symbol> core.py` beside the file is one
+  file. A search with no path in a `docs/` that holds no code is text. `..` and
+  `../src` are judged as the directories they are.
+- Once the command line has run a `cd` the hook does not follow, or any command
+  it does not model, the shell may be anywhere in the repository. A search then
+  keeps an absolute path, and a relative one that names a file in the session's
+  directory. With a directory, or no path, it is judged as a search of the
+  whole repository: from a `docs/` with no code, `cd ../src ; grep -rn <symbol> .`
+  is refused. At the root this case resolves paths against the root, as before.
+- Every status, refusal and reminder ends by naming the root: "This session is
+  below the repository root: run graphite from `<root>`." The CLI still looks
+  for the graph in its own working directory (#81), so the commands those
+  messages print work from the root only.
+
+The hooks no longer register a directory below a checkout's root with the
+daemon, whether or not graphite is set up in that checkout.
+
+Nothing changes for a session at the repository root. Measured on the 1.2.0
+wheel and on this change: 32 strict-hook arms from the #72 work (25 refused, 7
+allowed) and 12 hook arms on a checkout with `.git` and `GRAPHITE.md` read the
+same on both.
+
 ## [1.2.0] — 2026-10-10
 
 A minor release. Query and search results, channel rounds and Python

{graphite_code-1.2.0 → graphite_code-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphite-code
-Version: 1.2.0
+Version: 1.2.1
 Summary: Local-first, zero-LLM knowledge graph extraction for codebases.
 Project-URL: Homepage, https://github.com/jared0565/graphite
 Project-URL: Repository, https://github.com/jared0565/graphite
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
 
-**Status: 1.2.0, production/stable.** Published on PyPI as
+**Status: 1.2.1, production/stable.** Published on PyPI as
 [`graphite-code`](https://pypi.org/project/graphite-code/) with PEP 740
 attestations; supported on Windows, Linux and macOS with Python 3.11–3.14
 (every cell gates CI). What 1.x promises — CLI, JSON outputs, `graph.json`,

{graphite_code-1.2.0 → graphite_code-1.2.1}/README.md

@@ -2,7 +2,7 @@
 
 Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
 
-**Status: 1.2.0, production/stable.** Published on PyPI as
+**Status: 1.2.1, production/stable.** Published on PyPI as
 [`graphite-code`](https://pypi.org/project/graphite-code/) with PEP 740
 attestations; supported on Windows, Linux and macOS with Python 3.11–3.14
 (every cell gates CI). What 1.x promises — CLI, JSON outputs, `graph.json`,

{graphite_code-1.2.0 → graphite_code-1.2.1}/src/graphite/__init__.py

@@ -38,4 +38,4 @@ __all__ = ["__version__"]
 #: Coarse and hand-maintained by construction. It is a release label, not
 #: evidence that a given fix is present -- to answer that, survey for the marker
 #: the fix introduced, or compare `graphite --version` fingerprints.
-__version__ = "1.2.0"
+__version__ = "1.2.1"

{graphite_code-1.2.0 → graphite_code-1.2.1}/src/graphite/agent_hooks.py

@@ -21,7 +21,9 @@ from .config import Config
 from .freshness import check_graph_freshness
 from .graph_io import load_validated_graph_bundle
 from .health import _edge_language, is_placeholder, persisted_resolution
+from .hook_entry import MARKER as _SETUP_MARKER
 from .incident_ledger import record_incident, repo_ledger_dir
+from .ingest import enclosing_git_root
 
 SESSION_CONTRACT = (
     "graphite-first: this repo uses a shared code graph. For cross-file questions "
@@ -34,22 +36,64 @@ SESSION_CONTRACT = (
 _FRESHNESS_BUDGET_SECONDS = 2.0
 
 
-def _payload_root(payload: dict[str, Any]) -> Path:
+def _payload_cwd(payload: dict[str, Any]) -> Path:
+    """The directory the session is in. It follows a `cd` in the shell."""
     cwd = payload.get("cwd")
     if isinstance(cwd, str) and cwd:
         return Path(cwd)
     return Path.cwd()
 
 
+def _repo_root(cwd: Path) -> Path:
+    """The repository a session in `cwd` belongs to: where its graph is.
+
+    Taking the session's directory for the root made the graph "missing" one
+    `cd` below it, and switched the gate off there (#80). The repository is the
+    nearest directory upward that holds `.git`, the one place a build of it can
+    run (`ingest.enclosing_git_root`).
+
+    That directory is used only where graphite is already set up: it has a
+    graph, or the `GRAPHITE.md` that `init` commits. Anywhere else `cwd` stands,
+    as it did before, so a session that wanders into a subfolder of some other
+    checkout does not hand the daemon that whole project to build.
+    """
+    top = enclosing_git_root(cwd)
+    if top is None or top == cwd:
+        return cwd
+    if (top / "graph-out" / "graph.json").is_file() or (top / _SETUP_MARKER).is_file():
+        return top
+    return cwd
+
+
+def _where_to_run(root: Path, cwd: Path) -> str:
+    """One sentence for a session below the repository root, else nothing.
+
+    The commands these hooks print are run where the agent is, and the CLI
+    looks for the graph in its own working directory. Below the root `query`,
+    `context` and `check .` report the graph missing and `build .` is refused,
+    so a status or a refusal that names no directory sends the agent to a
+    command that fails.
+    """
+    if cwd == root:
+        return ""
+    return f" This session is below the repository root: run graphite from `{root}`."
+
+
 def _activate(root: Path) -> None:
     """Register this repo as open, so the daemon supervises it and leaves the
     rest of the machine alone.
 
+    A directory below a checkout's root is never registered. No build can run
+    there (`ingest` refuses it), so the daemon would fail on it at every
+    discovery cycle for as long as the marker lived.
+
     Guarded separately from the caller's own try/except: activation is
     bookkeeping, and this module is fail-open by contract -- a broken registry
     must never cost the agent its session context or its graph-first reminder.
     """
     try:
+        if enclosing_git_root(root) not in (None, root):
+            return
         mark_active(root, "claude")
     except Exception:
         return
@@ -97,7 +141,8 @@ def _freshness_within_budget(root: Path) -> tuple[str, str | None]:
 
 def handle_session_start(payload: dict[str, Any]) -> dict[str, Any] | None:
     try:
-        root = _payload_root(payload)
+        cwd = _payload_cwd(payload)
+        root = _repo_root(cwd)
         _activate(root)
         if (root / "graph-out" / "graph.json").is_file():
             state, reason = _freshness_within_budget(root)
@@ -121,7 +166,7 @@ def handle_session_start(payload: dict[str, Any]) -> dict[str, Any] | None:
         return {
             "hookSpecificOutput": {
                 "hookEventName": "SessionStart",
-                "additionalContext": f"{SESSION_CONTRACT}\n{status}",
+                "additionalContext": f"{SESSION_CONTRACT}\n{status}{_where_to_run(root, cwd)}",
             }
         }
     except Exception:
@@ -435,14 +480,22 @@ def _shell_path(text: str, msys: bool) -> Path:
     return Path(text)
 
 
-def _cd_target(start: Path, arguments: list[str], msys: bool) -> Path | None:
-    """The directory `cd <arguments>` leaves the shell in, or None when unknown."""
+def _cd_target(start: Path | None, arguments: list[str], msys: bool) -> Path | None:
+    """The directory `cd <arguments>` leaves the shell in, or None when unknown.
+
+    `start` is None when the hook does not know where the shell is. From there
+    only an absolute path leads somewhere known.
+    """
     if len(arguments) != 1 or os.environ.get("CDPATH"):
         return None  # with `CDPATH` set, `cd docs` may land somewhere other than `./docs`
     text = arguments[0]
     if text.startswith("-") or _SHELL_EXPANSION_CHARS.intersection(text):
         return None
-    target = start / _shell_path(text, msys)  # an absolute path replaces `start`
+    target = _shell_path(text, msys)
+    if start is not None:
+        target = start / target  # an absolute path replaces `start`
+    elif not target.is_absolute():
+        return None
     try:
         return target if target.is_dir() else None
     except OSError:  # pragma: no cover - a path the platform cannot stat
@@ -542,7 +595,29 @@ def _search_in(name: str, rest: list[str], base: Path | None, msys: bool) -> _Se
     return _Search(positional[0], _located(positional[1:], base, msys), fold_case)
 
 
-def _bash_searches(command: str, root: Path, msys: bool = False) -> list[_Search]:
+def _unplaced(search: _Search, cwd: Path) -> _Search:
+    """`search` when the hook does not know which directory it runs in.
+
+    An absolute path says where it is. A relative one that names a file in the
+    session's directory is still one file's text, as it is at the root:
+    `ls && grep x notes.md`. A directory, a path that is not there, and a
+    search that names no path could be anywhere in the repository. The search
+    is then one of all of it, and no path is left to earn an exemption.
+    """
+    placed: list[str] = []
+    for text in search.paths:
+        path = Path(text)
+        if not path.is_absolute():
+            path = cwd / path
+            if not path.is_file():
+                return search._replace(paths=[])
+        placed.append(str(path))
+    return search._replace(paths=placed)
+
+
+def _bash_searches(
+    command: str, root: Path, msys: bool = False, cwd: Path | None = None
+) -> list[_Search]:
     """Every search `command` runs that is not downstream of a pipe.
 
     All of them, not the first: `grep x notes.md ; grep -rn <symbol> src/` is
@@ -557,12 +632,23 @@ def _bash_searches(command: str, root: Path, msys: bool = False) -> list[_Search
     `cd docs && ls && grep ...` is not followed. In every such case, and when
     the directory is not one the hook can find, paths resolve against the
     repository root as they did before `cd` was read at all.
+
+    `cwd` is the directory the shell starts in when that is below the root
+    (#80). The line's first command runs there, and so does a search reached
+    through searches alone. Once a `cd` or a command the hook does not model
+    has run, the shell may be anywhere. At the root that costs nothing, since
+    the root holds every directory it could be in. Below the root the session's
+    directory holds only itself: from a `docs/` with no code in it,
+    `cd ../src ; grep` would pass as a search of `docs/`. There the search
+    keeps only the paths that do not depend on where the shell is (`_unplaced`).
     """
     searches: list[_Search] = []
-    base: Path | None = None
+    base: Path | None = cwd  # None is the repository root
+    placed = True  # `base` is where the shell is
+    moved = False  # a `cd`, or a command the hook does not model, has run
     for head in _bash_command_heads(command):
         if head.before != "&&":
-            base = None
+            base, placed = (None, False) if moved else (cwd, True)
         argv = head.argv
         while argv and _ENV_ASSIGNMENT_RE.match(argv[0]):
             argv = argv[1:]
@@ -574,16 +660,22 @@ def _bash_searches(command: str, root: Path, msys: bool = False) -> list[_Search
             name = name[:-4]
         rest = argv[1:]
         if name in _CD_COMMANDS:
-            base = _cd_target(base or root, rest, msys) if head.after == "&&" else None
+            moved = True
+            # At the root an unplaced shell is read as being at the root. Below
+            # it, only an absolute path leads somewhere known.
+            start = base or (root if cwd is None else None)
+            base = _cd_target(start, rest, msys) if head.after == "&&" else None
+            placed = base is not None
             continue
         if name == "git" and rest and rest[0] == "grep":
             name, rest = "grep", rest[1:]
         if name not in _SEARCH_COMMANDS:
-            base = None  # `popd`, `builtin cd ..`, a function: the shell may have moved
+            # `popd`, `builtin cd ..`, a function: the shell may have moved
+            base, placed, moved = None, False, True
             continue
         found = _search_in(name, rest, base, msys)
         if found is not None:
-            searches.append(found)
+            searches.append(found if placed or cwd is None else _unplaced(found, cwd))
     return searches
 
 
@@ -692,7 +784,7 @@ def _denial_for(root: Path, searches: list[_Search]) -> str | None:
     return None
 
 
-def _strict_denial(payload: dict[str, Any], root: Path) -> str | None:
+def _strict_denial(payload: dict[str, Any], root: Path, cwd: Path | None = None) -> str | None:
     try:
         tool_input = payload.get("tool_input")
         if not isinstance(tool_input, dict):
@@ -702,6 +794,10 @@ def _strict_denial(payload: dict[str, Any], root: Path) -> str | None:
             return None
         target = tool_input.get("path")
         paths = [target] if isinstance(target, str) and target else []
+        if cwd is not None:
+            # Below the root: with no `path` the tool searches the session's
+            # directory, and a relative one starts there.
+            paths = _located(paths, cwd, False)
         # The Grep tool matches case exactly unless `-i` is set. A value that
         # is not plainly "off" is read as on: unsure folds.
         # The tool is built on ripgrep, so it is read as `rg` with no flags of
@@ -747,7 +843,7 @@ def _cursor_number(value: Any, cast: type) -> Any:
 def handle_stop(payload: dict[str, Any]) -> dict[str, Any] | None:
     """Turn-end savings summary; silent unless graphite was used this turn."""
     try:
-        root = _payload_root(payload)
+        root = _repo_root(_payload_cwd(payload))
         # Stop fires once per assistant turn, which makes it the heartbeat that
         # keeps a working session inside the activation TTL. It must run before
         # the session_id guard below, which returns early on most turns.
@@ -821,9 +917,14 @@ def handle_pre_tool_use(payload: dict[str, Any], mode: str) -> dict[str, Any] |
         tool_name = payload.get("tool_name")
         if tool_name not in ("Grep", "Glob", "Bash", "PowerShell"):
             return None
-        root = _payload_root(payload)
+        cwd = _payload_cwd(payload)
+        root = _repo_root(cwd)
         if not (root / "graph-out" / "graph.json").is_file():
             return None
+        # Two directories, not one: the graph is at `root`, and a search's
+        # relative paths start where the shell is.
+        below = None if cwd == root else cwd
+        where = _where_to_run(root, cwd)
         denial: str | None = None
         if tool_name in ("Bash", "PowerShell"):
             # The matcher now routes EVERY Bash call here, so anything that is
@@ -835,13 +936,13 @@ def handle_pre_tool_use(payload: dict[str, Any], mode: str) -> dict[str, Any] |
             command = tool_input.get("command") if isinstance(tool_input, dict) else None
             # On Windows the Bash tool is Git Bash, which spells drives `/c/...`.
             msys = tool_name == "Bash" and os.name == "nt"
-            searches = _bash_searches(command, root, msys) if isinstance(command, str) else []
+            searches = _bash_searches(command, root, msys, below) if isinstance(command, str) else []
             if not searches:
                 return None
             if mode == "strict":
                 denial = _denial_for(root, searches)
         elif mode == "strict" and tool_name == "Grep":
-            denial = _strict_denial(payload, root)
+            denial = _strict_denial(payload, root, below)
         if denial is not None:
             health = persisted_resolution(
                 root,
@@ -858,19 +959,19 @@ def handle_pre_tool_use(payload: dict[str, Any], mode: str) -> dict[str, Any] |
                     "hookSpecificOutput": {
                         "hookEventName": "PreToolUse",
                         "permissionDecision": "deny",
-                        "permissionDecisionReason": denial,
+                        "permissionDecisionReason": denial + where,
                     }
                 }
             return {
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
-                    "additionalContext": PRE_TOOL_REMINDER + STRICT_SUSPENSION_NOTE,
+                    "additionalContext": PRE_TOOL_REMINDER + STRICT_SUSPENSION_NOTE + where,
                 }
             }
         return {
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "additionalContext": PRE_TOOL_REMINDER,
+                "additionalContext": PRE_TOOL_REMINDER + where,
             }
         }
     except Exception:

{graphite_code-1.2.0 → graphite_code-1.2.1}/src/graphite/ingest.py

@@ -157,6 +157,19 @@ def _normalize_git_path(root: Path, value: str) -> str | None:
     return native_path.as_posix()
 
 
+def enclosing_git_root(path: Path) -> Path | None:
+    """The nearest directory, from `path` upward, that holds `.git`.
+
+    `.git` is a directory in a clone and a file in a linked worktree or a
+    submodule, so it is tested for existence only. None means `path` is in no
+    repository at all.
+    """
+    for directory in (path, *path.parents):
+        if os.path.lexists(directory / ".git"):
+            return directory
+    return None
+
+
 def _git_ls_files(
     root: Path,
     *,
@@ -164,9 +177,9 @@ def _git_ls_files(
     is_eligible: Callable[[str], bool] | None = None,
 ) -> list[str] | None:
     """Return bounded Git files, or None only when *root* is not a Git repository."""
-    git_dir = root / ".git"
-    if not os.path.lexists(git_dir):
-        if any(os.path.lexists(ancestor / ".git") for ancestor in root.parents):
+    enclosing = enclosing_git_root(root)
+    if enclosing != root:
+        if enclosing is not None:
             raise IngestError("nested Git roots are unsupported")
         return None
     try: