witan-code 0.21.0__tar.gz → 0.22.0__tar.gz

{witan_code-0.21.0 → witan_code-0.22.0}/CHANGELOG.md

@@ -8,6 +8,56 @@ a MINOR bump may include breaking changes).
 
 <!-- scriv-insert-here -->
 
+## [0.22.0] - 2026-09-25
+
+### Added
+
+- **`witan-code inject-context --client pi`.** The status block told every
+  agent to run Claude's `ToolSearch` and then call `code_*` tools directly,
+  including under Pi, which has no `ToolSearch` and reaches MCP tools only
+  through pi-mcp-adapter's `mcp` proxy under a server-prefixed name. With
+  `--client pi` the block instead says to find the exact name with
+  `mcp({ search: "code_find_definition callers impact" })` and call it with
+  `mcp({ tool: "<name>", args: {...} })`, and points at `/skill:witan-code`.
+  The default (`--client claude`, what the Claude hook runs) is unchanged.
+
+### Changed
+
+- **The Pi extension passes `--client pi`**, so a Pi install needs a
+  `witan-code` CLI from this release or later: an older one rejects the flag
+  and the extension, as with any failure, injects no block.
+- **The `witan-code` skill's tool reference is client-neutral**, with short
+  notes on reaching the tools from Claude Code (`ToolSearch`) and Pi (the
+  `mcp` proxy).
+
+- `witan-code setup --agent pi` (and `--agent all` when Pi is detected) now
+  warns when the pi-mcp-adapter Pi package is not declared in Pi's settings,
+  since Pi ignores the witan-code MCP entry in `~/.pi/agent/mcp.json` without
+  it. The warning comes from agent-config-kit's preflight via
+  `witan_core.cli.report_install`. The README and the `setup` help document
+  the prerequisite (`pi install npm:pi-mcp-adapter`).
+
+- The `agent-config-kit` floor is raised from `>=0.7` to `>=0.10`, the first
+  release whose `InstallResult` carries the `prerequisites` that warning is
+  built from; on an older agent-config-kit the warning silently never
+  appeared.
+
+- The `witan-core` floor is raised from `>=0.39` to `>=0.40`, the first
+  release whose `report_install` prints those `prerequisites`; on 0.39 the
+  server still runs but the warning is silently dropped.
+
+### Fixed
+
+- **The Pi extension now waits as long for the code-graph status block as
+  Claude does.** `codegraph.ts`'s `before_agent_start` gave `witan-code
+  inject-context` 5s, against the 15s the Claude `UserPromptSubmit` hook gets,
+  so a cold store read that ran past 5s was killed before it could fill the
+  cache, and that prompt, and the next cold one, got no block. Both
+  now read one value (`INJECT_CONTEXT_TIMEOUT_SECONDS` in `witan_code.setup`,
+  `INJECT_CONTEXT_TIMEOUT_MS` in the extension), and a test fails if they, or
+  the `configs/pi/extensions` mirror, drift. Every other Pi handler stays
+  detached, and a timeout still degrades to no context.
+
 ## [0.21.0] - 2026-09-23
 
 ### Added

{witan_code-0.21.0 → witan_code-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.21.0
+Version: 0.22.0
 Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
 Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
 Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -10,7 +10,7 @@ License-Expression: BSD-3-Clause
 Keywords: agent,code-graph,coding-agent,mcp,static-analysis,tree-sitter
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
-Requires-Dist: agent-config-kit<1,>=0.7
+Requires-Dist: agent-config-kit<1,>=0.10
 Requires-Dist: cyclopts<5,>=4
 Requires-Dist: fastmcp<5,>=4
 Requires-Dist: joserfc<2,>=1.0
@@ -26,7 +26,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter-yaml<0.8,>=0.7
 Requires-Dist: tree-sitter<0.26,>=0.25
-Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.39
+Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.40
 Provides-Extra: tasks
 Requires-Dist: fastmcp-tasks<5,>=4; extra == 'tasks'
 Description-Content-Type: text/markdown
@@ -299,6 +299,12 @@ witan-code setup --dry-run          # preview without writing
 witan-code setup --author "Jane Doe"  # attribution (default: git config user.name)
 ```
 
+On Pi, the MCP server entry (`~/.pi/agent/mcp.json`) is read only by the
+third-party pi-mcp-adapter Pi package, since Pi core has no MCP support:
+install it with `pi install npm:pi-mcp-adapter`, restart Pi, and confirm it
+in `pi list`. `witan-code setup --agent pi` warns when it cannot find the
+package declared in Pi's settings.
+
 If `witan` is *also* installed and witan-code is importable in that same
 environment (e.g. via the `--with` in the `uv tool install`/MCP server's
 `uvx` invocation), `witan setup` folds this same bundle in automatically —
@@ -715,7 +721,10 @@ A Pi equivalent of all four lives in one extension,
   can tell "no cross-repo consumers" from "no cross-repo data"), and the
   `ToolSearch` call that makes the `code_*` tools callable when the harness
   delivers them deferred — followed by a `code_find_definition` →
-  `code_callers`/`code_impact` call template.
+  `code_callers`/`code_impact` call template. `--client pi` (what the Pi
+  extension passes) swaps the `ToolSearch` step for pi-mcp-adapter's `mcp`
+  proxy: `mcp({ search: ... })` for the exact server-prefixed name, then
+  `mcp({ tool: ..., args: {...} })`. The default stays Claude's.
   Independent of `witan`'s own `inject-context` hook (no cross-package
   coupling) — register it alone for a witan-code-only install. Prints
   nothing when the repo has neither a store nor an index in flight.

{witan_code-0.21.0 → witan_code-0.22.0}/README.md

@@ -266,6 +266,12 @@ witan-code setup --dry-run          # preview without writing
 witan-code setup --author "Jane Doe"  # attribution (default: git config user.name)
 ```
 
+On Pi, the MCP server entry (`~/.pi/agent/mcp.json`) is read only by the
+third-party pi-mcp-adapter Pi package, since Pi core has no MCP support:
+install it with `pi install npm:pi-mcp-adapter`, restart Pi, and confirm it
+in `pi list`. `witan-code setup --agent pi` warns when it cannot find the
+package declared in Pi's settings.
+
 If `witan` is *also* installed and witan-code is importable in that same
 environment (e.g. via the `--with` in the `uv tool install`/MCP server's
 `uvx` invocation), `witan setup` folds this same bundle in automatically —
@@ -682,7 +688,10 @@ A Pi equivalent of all four lives in one extension,
   can tell "no cross-repo consumers" from "no cross-repo data"), and the
   `ToolSearch` call that makes the `code_*` tools callable when the harness
   delivers them deferred — followed by a `code_find_definition` →
-  `code_callers`/`code_impact` call template.
+  `code_callers`/`code_impact` call template. `--client pi` (what the Pi
+  extension passes) swaps the `ToolSearch` step for pi-mcp-adapter's `mcp`
+  proxy: `mcp({ search: ... })` for the exact server-prefixed name, then
+  `mcp({ tool: ..., args: {...} })`. The default stays Claude's.
   Independent of `witan`'s own `inject-context` hook (no cross-package
   coupling) — register it alone for a witan-code-only install. Prints
   nothing when the repo has neither a store nor an index in flight.

{witan_code-0.21.0 → witan_code-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.21.0"
+version = "0.22.0"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -17,7 +17,11 @@ dependencies = [
     # Same blind spot as the witan-core floors below — the workspace resolves
     # agent-config-kit by path — except there is NO `check-core-floor`
     # equivalent for this dependency, so this line is the only guard.
-    "agent-config-kit>=0.7,<1",
+    # >=0.10: `witan-code setup`'s install report promises a warning when Pi
+    # lacks pi-mcp-adapter, which comes from `InstallResult.prerequisites`,
+    # added in 0.10.0. witan_core's `report_install` reads it with getattr, so
+    # an older resolution does not fail — it just silently drops the warning.
+    "agent-config-kit>=0.10,<1",
     # `remote`: the ADR-0005 client stack (OIDC device grant + MCP-client
     # proxy) behind `witan-code login` and the read commands' remote mode.
     # Costs nothing extra in practice — fastmcp is already required here and
@@ -151,7 +155,13 @@ dependencies = [
     # code-graph writes parallel agents lose to each other. And
     # `ClusterGraphMissing` sets `log_safe_message`, which only 0.39 reads: on
     # 0.38 its text never reaches the `mcp.tool_call` log line.
-    "witan-core[cli,remote,observability,sentry]>=0.39,<1",
+    #
+    # ★ >=0.40 IS A BEHAVIOUR FLOOR too: `witan-code setup --agent pi` promises
+    # a warning when Pi lacks pi-mcp-adapter, and
+    # `witan_core.cli.report_install` only prints `InstallResult.prerequisites`
+    # from 0.40.0. It reads the field with getattr, so 0.39 imports and runs —
+    # and silently drops the warning.
+    "witan-core[cli,remote,observability,sentry]>=0.40,<1",
     "fastmcp>=4,<5",
     "cyclopts>=4,<5",
     # [targets.<name>] override models (config.py) — also transitively pulled
@@ -234,7 +244,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.21.0"
+current_version = "0.22.0"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

{witan_code-0.21.0 → witan_code-0.22.0}/tests/test_cli_hooks.py

@@ -14,7 +14,7 @@ def test_inject_context_cmd_prints_backend_output_without_extra_newline(
     import witan_code.context as context_module
 
     monkeypatch.setattr(
-        context_module, "inject_context", lambda: "## Code Graph\n\ntext.\n"
+        context_module, "inject_context", lambda client: "## Code Graph\n\ntext.\n"
     )
 
     cli.inject_context_cmd()
@@ -27,7 +27,7 @@ def test_inject_context_cmd_prints_nothing_for_empty_backend_output(
 ):
     import witan_code.context as context_module
 
-    monkeypatch.setattr(context_module, "inject_context", lambda: "")
+    monkeypatch.setattr(context_module, "inject_context", lambda client: "")
 
     cli.inject_context_cmd()
 
@@ -37,7 +37,7 @@ def test_inject_context_cmd_prints_nothing_for_empty_backend_output(
 def test_inject_context_cmd_never_raises_when_backend_fails(monkeypatch, capsys):
     import witan_code.context as context_module
 
-    def _boom():
+    def _boom(client):
         raise RuntimeError("graph read failed")
 
     monkeypatch.setattr(context_module, "inject_context", _boom)
@@ -45,3 +45,32 @@ def test_inject_context_cmd_never_raises_when_backend_fails(monkeypatch, capsys)
     cli.inject_context_cmd()  # must not raise
 
     assert capsys.readouterr().out == ""
+
+
+def test_inject_context_cmd_defaults_to_the_claude_client(monkeypatch, capsys):
+    """The Claude hook runs the bare command, so the default must stay Claude."""
+    import witan_code.context as context_module
+
+    seen = []
+    monkeypatch.setattr(
+        context_module, "inject_context", lambda client: seen.append(client) or ""
+    )
+
+    command, bound, _ = cli.app.parse_args(["inject-context"])
+    command(*bound.args, **bound.kwargs)
+
+    assert seen == ["claude"]
+
+
+def test_inject_context_cmd_passes_an_explicit_pi_client_through(monkeypatch):
+    import witan_code.context as context_module
+
+    seen = []
+    monkeypatch.setattr(
+        context_module, "inject_context", lambda client: seen.append(client) or ""
+    )
+
+    command, bound, _ = cli.app.parse_args(["inject-context", "--client", "pi"])
+    command(*bound.args, **bound.kwargs)
+
+    assert seen == ["pi"]

{witan_code-0.21.0 → witan_code-0.22.0}/tests/test_context.py

@@ -393,3 +393,52 @@ def test_inject_context_block_stays_small(tmp_path, monkeypatch):
     _stub_store_stats(monkeypatch)
 
     assert len(context.inject_context()) < 600
+
+
+def _indexed(tmp_path, monkeypatch):
+    monkeypatch.setenv("WITAN_REPO", "https://github.com/test/cg")
+    code_dir = tmp_path / "code"
+    monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
+    _lock(tmp_path, monkeypatch, tmp_path / "project")
+    (code_dir / "https_github.com_test_cg.omni").mkdir(parents=True)
+    _stub_store_stats(monkeypatch)
+
+
+def test_inject_context_default_and_explicit_claude_render_the_same(
+    tmp_path, monkeypatch
+):
+    _indexed(tmp_path, monkeypatch)
+
+    default = context.inject_context()
+
+    assert default == context.inject_context(client="claude")
+    assert "ToolSearch" in default
+    assert "mcp({" not in default
+    assert "`/witan-code`" in default
+
+
+def test_inject_context_for_pi_names_the_mcp_proxy_not_toolsearch(
+    tmp_path, monkeypatch
+):
+    """Pi has no ToolSearch; its MCP tools sit behind pi-mcp-adapter's `mcp`.
+
+    The adapter prefixes each tool with its server name, and that prefix
+    depends on the user's config, so the block must search first and then
+    call whatever exact name the search returned.
+    """
+    _indexed(tmp_path, monkeypatch)
+
+    text = context.inject_context(client="pi")
+
+    assert "ToolSearch" not in text
+    assert "select:" not in text
+    assert 'mcp({ search: "code_find_definition callers impact" })' in text
+    assert 'mcp({ tool: "<exact name the search returned>", args: {' in text
+    # Search sees only cached metadata; a lazy server with no cache entry
+    # needs a connect first, or the block dead-ends.
+    assert 'mcp({ connect: "witan-code" })' in text
+    assert "/skill:witan-code" in text  # Pi's skill command form
+    # The status lines above the discovery line are client-neutral.
+    assert "https://github.com/test/cg" in text
+    assert "3 files" in text
+    assert "No other repo is indexed" in text

{witan_code-0.21.0 → witan_code-0.22.0}/tests/test_setup.py

@@ -10,6 +10,7 @@ correct.
 """
 
 import json
+import re
 from pathlib import Path
 
 from agent_config_kit import apply
@@ -138,3 +139,93 @@ def test_setup_does_not_abort_on_a_refused_omnigraph_binary(tmp_path, monkeypatc
     cli.setup(agent="claude", author="tester")
 
     assert calls == [{"dry_run": False, "strict": False}]
+
+
+def _pi_setup_output(tmp_path, monkeypatch, capsys, *, dry_run: bool) -> str:
+    import witan_core
+
+    from witan_code import cli
+
+    monkeypatch.setattr(witan_core, "install_omnigraph", lambda dry_run, **kw: None)
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+    cli.setup(agent="pi", author="tester", dry_run=dry_run)
+
+    return " ".join(capsys.readouterr().out.split())
+
+
+def test_setup_pi_warns_when_pi_mcp_adapter_is_missing(tmp_path, monkeypatch, capsys):
+    """`witan-code setup --agent pi` inherits agent-config-kit's MCP
+    prerequisite preflight: Pi ignores ~/.pi/agent/mcp.json without the
+    pi-mcp-adapter package, so the report must say so on dry-run and apply."""
+    for dry_run in (True, False):
+        out = _pi_setup_output(tmp_path, monkeypatch, capsys, dry_run=dry_run)
+        assert "WARNING:" in out
+        assert "pi install npm:pi-mcp-adapter" in out
+
+
+def test_setup_pi_notes_when_pi_mcp_adapter_is_installed(tmp_path, monkeypatch, capsys):
+    settings = tmp_path / ".pi" / "agent" / "settings.json"
+    settings.parent.mkdir(parents=True)
+    settings.write_text(json.dumps({"packages": ["npm:pi-mcp-adapter"]}))
+
+    out = _pi_setup_output(tmp_path, monkeypatch, capsys, dry_run=True)
+
+    assert "WARNING:" not in out
+    assert "note:" in out
+    assert "pi-mcp-adapter is declared in" in out
+
+
+# --- Pi extension source contract ------------------------------------------
+#
+# The Pi extension is TypeScript that no test here can execute, so these read
+# its source. They pin two things a Python-side change cannot see drifting:
+# the Pi prompt-injection budget matching the Claude hook's, and the three
+# copies of the file (package, configs/pi mirror) staying byte-identical.
+
+_PKG_EXT = Path(setup.__file__).parent / "extensions" / "pi" / "codegraph.ts"
+_REPO_ROOT = Path(__file__).resolve().parents[4]
+_CONFIG_EXT = _REPO_ROOT / "configs" / "pi" / "extensions" / "codegraph.ts"
+
+
+def _ts_const_ms(source: str, name: str) -> int:
+    match = re.search(rf"^const {name} = ([\d_]+);$", source, re.MULTILINE)
+    assert match, f"{name} is not declared as a numeric const"
+    return int(match.group(1).replace("_", ""))
+
+
+def test_pi_inject_context_timeout_matches_the_claude_hook():
+    """A 5s Pi budget killed the cold read every Claude prompt waits out."""
+    source = _PKG_EXT.read_text()
+    timeout_ms = _ts_const_ms(source, "INJECT_CONTEXT_TIMEOUT_MS")
+
+    assert timeout_ms == setup.INJECT_CONTEXT_TIMEOUT_SECONDS * 1000
+    assert setup.INJECT_CONTEXT_TIMEOUT_SECONDS >= 15
+    # The one blocking call is the one that uses the constant; nothing else
+    # hard-codes its own number.
+    assert "timeout: INJECT_CONTEXT_TIMEOUT_MS" in source
+    assert source.count("spawnSync(") == 1
+    assert "timeout: 5000" not in source
+
+
+def test_claude_inject_context_hook_uses_the_shared_constant(tmp_path):
+    bundle = setup.witan_code_bundle(tmp_path, "tester")
+    (hook,) = [
+        h
+        for h in bundle.hooks
+        if getattr(h, "command", None) == "witan-code inject-context"
+    ]
+    assert hook.timeout_seconds == setup.INJECT_CONTEXT_TIMEOUT_SECONDS
+
+
+def test_configs_pi_mirror_matches_the_package_extension():
+    assert _CONFIG_EXT.read_bytes() == _PKG_EXT.read_bytes(), (
+        f"{_CONFIG_EXT} drifted from {_PKG_EXT}; copy the package file over it"
+    )
+
+
+def test_pi_extension_asks_for_pi_rendered_context():
+    """Without `--client pi` the block tells Pi to call a ToolSearch it lacks."""
+    source = _PKG_EXT.read_text()
+
+    assert 'spawnSync("witan-code", ["inject-context", "--client", "pi"]' in source

{witan_code-0.21.0 → witan_code-0.22.0}/witan_code/cli.py

@@ -582,19 +582,27 @@ def stitch(repo: str | None = None, *, unresolved: bool = False) -> None:
 
 
 @app.command(name="inject-context")
-def inject_context_cmd() -> None:
+def inject_context_cmd(*, client: Literal["claude", "pi"] = "claude") -> None:
     """Print a short code-graph status block for the UserPromptSubmit hook.
 
     Registered as the bare ``UserPromptSubmit`` hook command; always exits 0
     and prints nothing when there's no store or in-flight index for the
     current repo.
+
+    Parameters
+    ----------
+    client
+        Which agent the block's tool-discovery instructions are written for:
+        ``claude`` (``ToolSearch``, the default) or ``pi`` (pi-mcp-adapter's
+        ``mcp`` proxy). The Pi extension passes ``--client pi``; nothing is
+        inferred from the environment.
     """
     import sys
 
     from . import context as context_module
 
     try:
-        text = context_module.inject_context()
+        text = context_module.inject_context(client=client)
     except Exception:  # noqa: BLE001 — must never fail the hook
         return
     if text:
@@ -946,6 +954,11 @@ def setup(
     `witan setup` — running both is fine (each only touches its own entries);
     running just this one is enough for a witan-code-only install.
 
+    Pi has no built-in MCP support: the witan-code entry written to
+    ``~/.pi/agent/mcp.json`` is read only by the pi-mcp-adapter Pi package
+    (``pi install npm:pi-mcp-adapter``). The install report warns when that
+    package is not declared in Pi's settings.
+
     Re-run after every upgrade to refresh installed files.
 
     Parameters

{witan_code-0.21.0 → witan_code-0.22.0}/witan_code/context.py

@@ -21,6 +21,11 @@ cannot see in its tool list is not actionable, so the block leads with the
 ``ToolSearch`` that makes the tools callable and then gives a call template to
 fill in.
 
+That unlock step is Claude Code's. Pi has no ``ToolSearch``: its MCP tools
+reach the agent through pi-mcp-adapter's ``mcp`` proxy tool, so the Pi
+extension asks for ``--client pi`` and gets the proxy's search-then-call
+instructions instead (see :func:`_discovery_line`).
+
 Kept short on purpose: this is prepended to *every* prompt, so tokens spent
 here are spent for the life of every session.
 """
@@ -35,6 +40,7 @@ import stat
 import tempfile
 import time
 from pathlib import Path
+from typing import Literal
 
 from . import config as cfg_module
 from . import repo as repo_module
@@ -144,6 +150,54 @@ def indexing_in_progress() -> bool:
 # under any prefix and puts the three workhorse tools first.
 _TOOLSEARCH_QUERY = '`ToolSearch(query="+code_ find_definition callers impact")`'
 
+# Which agent the block is rendered for. Passed explicitly by the caller (the
+# Pi extension runs `witan-code inject-context --client pi`), never inferred
+# from the environment: an ambient variable leaking across a nested shell or a
+# subprocess would silently hand one agent the other's calling convention.
+Client = Literal["claude", "pi"]
+
+# Pi has no ToolSearch. Under pi-mcp-adapter's default config (no
+# `directTools`, which `witan-code setup --agent pi` does not set) every MCP
+# tool sits behind the adapter's single `mcp` proxy tool, and its name carries
+# a server prefix (`toolPrefix`, default "server": `witan-code_code_callers`
+# for a server named `witan-code`, `witan_code_callers` when witan serves the
+# code tools itself). The prefix is config-dependent, so the block has the
+# agent search first and call whatever name the search returned. Search
+# tokenizes on non-alphanumerics and ranks by term matches, so this query puts
+# the three workhorse tools first under any prefix — the same job the `+code_`
+# form does for ToolSearch. Syntax per pi-mcp-adapter's README "Usage" table
+# (`mcp({ search })`, `mcp({ tool, args })`).
+_PI_SEARCH_CALL = '`mcp({ search: "code_find_definition callers impact" })`'
+_PI_TOOL_CALL = (
+    '`mcp({ tool: "<exact name the search returned>", args: { name: "X" } })`'
+)
+# Search reads only the adapter's cached tool metadata, and servers are lazy by
+# default, so a server with no valid cache entry (first use after the cache
+# file already existed, or unused for the cache's 7-day lifetime) returns no
+# matches. Connecting refreshes the metadata; the block names both server
+# names setup registers, since either may be the one serving `code_*` tools.
+_PI_CONNECT_CALL = '`mcp({ connect: "witan-code" })` (or `"witan"`)'
+
+
+def _discovery_line(client: Client) -> str:
+    """How to reach the ``code_*`` tools from this client, then what to call."""
+    if client == "pi":
+        return (
+            "`code_*` tools are behind the `mcp` proxy tool, not in your tool "
+            f"list — find their exact names with {_PI_SEARCH_CALL}, then call "
+            f"one with {_PI_TOOL_CALL} instead of grep (if the search finds "
+            f"nothing, run {_PI_CONNECT_CALL} and search again): "
+            "`code_find_definition` "
+            "→ `symbol_id` → `code_callers` / `code_impact` (blast radius "
+            "before editing). More: `/skill:witan-code`."
+        )
+    return (
+        "`code_*` tools may not be in your tool list — load them with "
+        f"{_TOOLSEARCH_QUERY}, then use them instead of grep: "
+        '`code_find_definition(name="X")` → `symbol_id` → `code_callers` / '
+        "`code_impact` (blast radius before editing). More: `/witan-code`."
+    )
+
 
 def _coverage_line(store: store_module.StoreRef, cfg: cfg_module.Config) -> str:
     """One line on whether cross-repo resolution can answer anything here.
@@ -245,11 +299,14 @@ def _bridge_ok(cfg: cfg_module.Config) -> bool | None:
     return ok
 
 
-def inject_context() -> str:
+def inject_context(client: Client = "claude") -> str:
     """A short markdown status block, or "" when there's nothing worth saying.
 
     Silent when the repo has neither a store nor an index in flight (nothing
     to report), so this hook adds no noise for repos that don't use witan-code.
+
+    ``client`` picks the tool-discovery instructions: Claude's ``ToolSearch``
+    (the default) or Pi's ``mcp`` proxy. Everything else is client-neutral.
     """
     cfg = cfg_module.load()
     slug = store_module.detect_repo(cfg)
@@ -311,10 +368,5 @@ def inject_context() -> str:
     coverage = _coverage_line(store, cfg)
     if coverage:
         lines.append(coverage)
-    lines.append(
-        "`code_*` tools may not be in your tool list — load them with "
-        f"{_TOOLSEARCH_QUERY}, then use them instead of grep: "
-        '`code_find_definition(name="X")` → `symbol_id` → `code_callers` / '
-        "`code_impact` (blast radius before editing). More: `/witan-code`."
-    )
+    lines.append(_discovery_line(client))
     return "\n".join(lines) + "\n"

{witan_code-0.21.0 → witan_code-0.22.0}/witan_code/extensions/pi/codegraph.ts

@@ -9,16 +9,21 @@
  *                        tool runs.
  *  - before_agent_start: report whether the code graph is indexed (file
  *                        count, last-updated) or still being built, plus
- *                        cross-repo coverage and the ToolSearch +
- *                        code_find_definition calls to make against it.
+ *                        cross-repo coverage and how to reach the code_*
+ *                        tools. Runs `inject-context --client pi`, so the
+ *                        block names pi-mcp-adapter's `mcp` proxy
+ *                        (search, then call) rather than Claude's
+ *                        ToolSearch, which Pi does not have.
  *  - session_shutdown  : opportunistically compact the current repo's store
  *                        and the shared cross-repo bridge store (throttled;
  *                        see witan_code.maintenance) — no session-id
  *                        dependency, unlike workflow-session-checkpoint, so
  *                        this one *is* mirrored under Pi.
  *
- * Best-effort and non-blocking: a missing CLI, non-git dir, or parse failure
- * never disrupts the session. Requires `witan-code` on PATH
+ * Best-effort: a missing CLI, non-git dir, or parse failure never disrupts
+ * the session. Every handler is detached and non-blocking except
+ * before_agent_start, which waits up to INJECT_CONTEXT_TIMEOUT_MS for the
+ * status block (the same budget the Claude hook gets). Requires `witan-code` on PATH
  * (`witan-code setup --agent pi`, or `uv tool install --editable
  * mcp/servers/witan-code`); otherwise it silently no-ops.
  *
@@ -31,6 +36,20 @@ import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
+/**
+ * How long before_agent_start waits for `witan-code inject-context`: 15s, the
+ * same budget as the Claude `UserPromptSubmit` hook `witan-code setup`
+ * installs (`witan_code.setup.INJECT_CONTEXT_TIMEOUT_SECONDS`;
+ * tests/test_setup.py asserts the two agree). The first prompt in a cache
+ * window can pay a ~10s cold store read that must finish once to populate the
+ * on-disk cache; the 5s this used to be killed that read every time, so the
+ * cache never filled and every prompt came back with no block.
+ *
+ * Only this prompt-injection read waits. session_start's index, the per-edit
+ * reindex, and session_shutdown's checkpoint all stay detached.
+ */
+const INJECT_CONTEXT_TIMEOUT_MS = 15_000;
+
 const SRC_EXT = /\.(py|pyi|ts|tsx|js|jsx|mjs|cjs)$/;
 const EDIT_TOOLS = new Set(["edit", "write"]);
 
@@ -96,12 +115,14 @@ export default function codegraphExtension(pi: ExtensionAPI): void {
 	});
 
 	// Report code-graph readiness before each turn (mirrors the Claude
-	// `witan-code inject-context` UserPromptSubmit hook).
+	// `witan-code inject-context` UserPromptSubmit hook). A timeout, a
+	// missing CLI, or a non-zero exit all land in the `r.status !== 0` branch:
+	// no context, never a thrown error.
 	pi.on("before_agent_start", async (event: any, ctx: any) => {
 		try {
-			const r = spawnSync("witan-code", ["inject-context"], {
+			const r = spawnSync("witan-code", ["inject-context", "--client", "pi"], {
 				encoding: "utf8",
-				timeout: 5000,
+				timeout: INJECT_CONTEXT_TIMEOUT_MS,
 				cwd: ctx?.cwd,
 			});
 			const text = (r.stdout ?? "").trim();

{witan_code-0.21.0 → witan_code-0.22.0}/witan_code/setup.py

@@ -33,6 +33,17 @@ _WITAN_CODE_ARGS = [
 # git `main`.
 _CLI_HOOK_PLATFORMS = ("claude", "pi")
 
+# How long the prompt-path `witan-code inject-context` may run before its
+# output is abandoned — the Claude `UserPromptSubmit` hook below AND the Pi
+# extension's `before_agent_start` (`extensions/pi/codegraph.ts`, which spells
+# it `INJECT_CONTEXT_TIMEOUT_MS`; tests/test_setup.py asserts the two agree).
+# The first prompt in a cache window can pay a cold store read of ~10s, and it
+# has to finish once to populate the on-disk cache: a timeout inside that cold
+# path kills the read, discards the block, and leaves every later prompt cold
+# too. 15s gives that path headroom while still degrading a hung git/store
+# read to "no context" rather than a stalled turn.
+INJECT_CONTEXT_TIMEOUT_SECONDS = 15
+
 
 def witan_code_bundle(
     pkg_dir: Path, author: str, *, binary: str = "witan-code"
@@ -71,8 +82,9 @@ def witan_code_bundle(
     # Bare CLI commands, no wrapper script — portable everywhere `binary`
     # installs (Windows included, where bash/setsid don't exist), matching
     # witan's own `witan inject-context`/`session-checkpoint` hooks. The
-    # prompt-path timeouts mirror witan's: a hung git or store read must
-    # degrade to no context/no compaction, never stall the agent.
+    # prompt-path timeouts exist for the same reason as witan's: a hung git or
+    # store read must degrade to no context/no compaction, never stall the
+    # agent (INJECT_CONTEXT_TIMEOUT_SECONDS says why inject-context gets 15s).
     hooks: list[Hook] = [
         DeclarativeHook(
             event=HookEvent.SESSION_START,
@@ -86,7 +98,7 @@ def witan_code_bundle(
         DeclarativeHook(
             event=HookEvent.USER_PROMPT_SUBMIT,
             command=f"{binary} inject-context",
-            timeout_seconds=15,
+            timeout_seconds=INJECT_CONTEXT_TIMEOUT_SECONDS,
         ),
         DeclarativeHook(
             event=HookEvent.STOP,

{witan_code-0.21.0 → witan_code-0.22.0}/witan_code/skills/witan-code/SKILL.md

@@ -19,9 +19,11 @@ A per-repo, tree-sitter-derived graph of symbols (functions, methods, classes,
 modules) and their relationships (`Calls`, `References`, `Imports`,
 `Inherits`), plus a cross-repo bridge linking services through shared
 contracts (env vars, HTTP endpoints, packages, deployments). Indexing is
-automatic — a `SessionStart` hook seeds/refreshes the whole repo in the
-background, and a `PostToolUse` hook incrementally reindexes each file you
-edit — so you rarely need to invoke the CLI yourself.
+automatic — a session-start hook seeds/refreshes the whole repo in the
+background, and a post-edit hook incrementally reindexes each file you edit
+(Claude Code's `SessionStart`/`PostToolUse` hooks; under Pi, the witan-code
+extension's `session_start`/`tool_result` handlers) — so you rarely need to
+invoke the CLI yourself.
 
 ## When to use this vs. grep / the `Explore` agent
 
@@ -57,10 +59,33 @@ results as a high-recall starting point, not a verified answer. `Defines` and
 Before relying on results, confirm the current repo has a graph: call
 `code_symbols_in_file` on a file you know exists, or `code_search_symbol` with
 a term you expect to match. An empty result on a file/symbol you know exists
-usually means indexing hasn't finished yet (the `SessionStart` hook runs
+usually means indexing hasn't finished yet (the session-start index runs
 detached in the background on a fresh repo) — wait a few seconds and retry
 before concluding the graph is broken.
 
+## Calling the tools
+
+The tables below give each tool's bare name and arguments. How you reach one
+depends on the agent:
+
+- **Claude Code** — the `code_*` tools often arrive deferred (listed, no
+  schema). Load them with
+  `ToolSearch(query="+code_ find_definition callers impact")`, then call them
+  directly: `code_find_definition(name="X")`. Their full names carry an
+  `mcp__<server>__` prefix that depends on your MCP config, which is why the
+  `+code_` query form is used rather than `select:`.
+- **Pi** — Pi has no `ToolSearch`. pi-mcp-adapter puts every MCP tool behind
+  its `mcp` proxy tool, under a server-prefixed name (for example
+  `witan-code_code_find_definition`, or `witan_code_find_definition` when
+  witan serves the code tools). Search for the exact name, then call it with
+  `args`:
+  `mcp({ search: "code_find_definition callers impact" })`, then
+  `mcp({ tool: "<exact name the search returned>", args: { name: "X" } })`.
+  Search reads only cached tool metadata, so if it finds nothing, run
+  `mcp({ connect: "witan-code" })` (or `"witan"`) and search again.
+  `mcp({ describe: "<name>" })` shows a tool's parameters. Invoke this skill
+  as `/skill:witan-code`.
+
 ## Tool reference
 
 | Question | Tool |