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

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

@@ -8,6 +8,88 @@ 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
+
+- **`code_repo_dependencies` marks each contract `generic`.** A stoplisted key
+  (DEBUG, PORT, ...) still makes its edge, as before, but its entry in the
+  edge's `contracts` now carries `"generic": true`, so a reader can hide the
+  keys that couple every repo to every other without the tool deciding for
+  them. Additive: every other field is unchanged.
+- **`code_interface_providers`, `code_interface_consumers` and the
+  `cross_repo` rows of `code_cross_repo_impact` return each binding's
+  `confidence`.** An endpoint
+  consumer under 0.5 makes no `code_repo_dependencies` edge, but these tools
+  return every row, so without the score a reader could not tell the rows that
+  made an edge from the phantoms. Additive.
+- **`code_interface_providers` and `code_interface_consumers` take
+  `in_repo`**, an exact repo URI to narrow to. It is applied in the query, so
+  the 500-row limit counts that repo's rows: a key bound in more than 500
+  places across every repo could otherwise cut off the repo being asked about.
+  Named `in_repo` rather than `repo` because the remote proxy fills an omitted
+  `repo` with the caller's detected one, which would have narrowed every
+  existing call. Omitted, every repo, as before.
+
+### Changed
+
+- **Requires witan-core 0.39 or later.** Nothing new is imported, so an older
+  witan-core loads, but it runs without 0.39.0's fewer lost writes between
+  parallel agents (jittered conflict retries and `WriteContention`, and
+  in-process serialisation of `s3://` writes), and without the refusal text
+  that `log_safe_message` puts on the `mcp.tool_call` log line. The floor
+  makes an external install pick them up.
+
 ## [0.20.1] - 2026-09-22
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.20.1
+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.38
+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.20.1 → 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.20.1 → witan_code-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.20.1"
+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
@@ -142,7 +146,22 @@ dependencies = [
     # parses the keyed `code-schema.pg`, and it restores the null fields 0.11
     # drops from query rows. An older witan-core imports fine and then fails
     # on the first schema init.
-    "witan-core[cli,remote,observability,sentry]>=0.38,<1",
+    #
+    # ★ >=0.39 IS A BEHAVIOUR FLOOR, not an import one: nothing here imports a
+    # 0.39 symbol, and an older witan-core loads fine. It runs without two
+    # things, though. 0.39.0 carries #394's conflict-retry fix (jittered
+    # backoff, and `WriteContention` when a write exhausts its retries) and
+    # #373's in-process serialisation of `s3://` writes, which reduce the
+    # 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.
+    #
+    # ★ >=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
@@ -225,7 +244,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.20.1"
+current_version = "0.22.0"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

{witan_code-0.20.1 → witan_code-0.22.0}/tests/test_bridge.py

@@ -410,6 +410,22 @@ def test_cross_repo_env_and_endpoint_linkage(tmp_path, monkeypatch):
         "endpoint", "/api/v1/courses/{id}/"
     )
     assert any(c["repo"] == "https://github.com/test/repo-a" for c in ep_consumers)
+    # The trust score comes back with each row, so a reader can tell the
+    # consumer rows that made a code_repo_dependencies edge (>= 0.5) from the
+    # ones that did not.
+    assert all(isinstance(c["confidence"], float) for c in ep_consumers)
+
+    # `in_repo` narrows in the query, to that exact repo.
+    only_b = _fn(srv.code_interface_providers)(
+        "env_var", "MITOL_APP_BASE_URL", in_repo="https://github.com/test/repo-b"
+    )
+    assert only_b == providers
+    assert (
+        _fn(srv.code_interface_providers)(
+            "env_var", "MITOL_APP_BASE_URL", in_repo="https://github.com/test/repo-a"
+        )
+        == []
+    )
 
 
 @requires_stack

{witan_code-0.20.1 → 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.20.1 → 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.20.1 → 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.20.1 → witan_code-0.22.0}/tests/test_visualize.py

@@ -353,6 +353,41 @@ def test_build_graph_confidence_on_emitted_edge_contracts():
     assert ep_contracts[0]["confidence"] == 0.75
 
 
+def test_build_graph_flags_generic_contracts_without_dropping_them():
+    """A stoplisted key still makes its edge, flagged, so a reader can hide it."""
+    rows = [
+        {
+            "kind": "env_var",
+            "key_norm": "PORT",
+            "role": "consumer",
+            "repo": A,
+            "generic": "1",
+        },
+        {
+            "kind": "env_var",
+            "key_norm": "PORT",
+            "role": "provider",
+            "repo": B,
+            "generic": "1",
+        },
+        {
+            "kind": "env_var",
+            "key_norm": "MITOL_APP_BASE_URL",
+            "role": "consumer",
+            "repo": A,
+        },
+        {
+            "kind": "env_var",
+            "key_norm": "MITOL_APP_BASE_URL",
+            "role": "provider",
+            "repo": B,
+        },
+    ]
+    g = visualize.build_graph(rows)
+    flags = {c["key"]: c["generic"] for c in g.edges[(A, B)].contracts}
+    assert flags == {"PORT": True, "MITOL_APP_BASE_URL": False}
+
+
 def test_build_graph_rejects_invalid_min_precision():
     with pytest.raises(ValueError):
         visualize.build_graph(ROWS, min_precision="nonsense")

{witan_code-0.20.1 → 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.20.1 → 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"