Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(hooks): make the augment hook silent when its console script is missing (#1141)

Raghav Chamadiyaababacc75888
diff --git a/docs/agent/HOOKS.md b/docs/agent/HOOKS.md
index 4a5d4adf6..19396d70b 100644
--- a/docs/agent/HOOKS.md
+++ b/docs/agent/HOOKS.md
@@ -199,12 +199,32 @@ and `.codex/hooks.json` (Codex when `--codex` is passed):
| Client | Hook type | Matcher | Command |
|--------|-----------|---------|---------|
-| Claude Code | `SessionStart` | `startup\|resume\|clear` | `repowise-augment` |
-| Claude Code | `PostToolUse` | `Bash\|PowerShell\|Grep\|Glob\|Read\|Edit\|Write\|mcp__.*[Rr]epowise.*__.*` | `repowise-augment` |
+| Claude Code | `SessionStart` | `startup\|resume\|clear` | `repowise-augment` [^guard] |
+| Claude Code | `PostToolUse` | `Bash\|PowerShell\|Grep\|Glob\|Read\|Edit\|Write\|mcp__.*[Rr]epowise.*__.*` | `repowise-augment` [^guard] |
| Claude Code | `PreToolUse` (opt-in) | `Bash\|PowerShell` | `repowise-rewrite` |
| Codex | `SessionStart` / `UserPromptSubmit` | lifecycle | context reminder |
| Codex | `PostToolUse` | `Bash`, `apply_patch\|Edit\|Write` | staleness check |
+[^guard]: The command is written wrapped in a presence check rather than as the
+ bare name:
+
+ ```sh
+ if command -v repowise-augment >/dev/null 2>&1; then exec repowise-augment; fi
+ ```
+
+ The Claude Code plugin ships these hooks independently of the CLI, so
+ "plugin installed, `repowise` not installed" is a supported state — and a
+ partially written install reaches it too (on Windows an MCP server holds
+ `repowise.exe` open, so an installer can abort after writing only some
+ console scripts). Unguarded, either state prints `command not found` on
+ every matched tool call: non-blocking, unactionable, and endless. The guard
+ is POSIX (`command -v` + `exec`, verified under `sh`, `bash` and `dash`) and
+ forwards stdin unchanged, so the hook behaves identically when the script is
+ present. An older install carrying the bare name is rewritten on the next
+ `repowise init`. Codex hooks keep the bare name: their execution model is
+ not documented as shell-based, and a directly `exec`'d guard would try to
+ run a binary named `if`.
+
`SessionStart` deliberately excludes `compact`: the block usually survives
compaction in the summary, and re-emitting it there would double it up. `init`
also sets `env.ENABLE_TOOL_SEARCH=true` so the MCP tool schemas load on demand
diff --git a/packages/cli/src/repowise/cli/editor_integrations/claude_config.py b/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
index b861acf99..5d083089c 100644
--- a/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
+++ b/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
@@ -220,6 +220,18 @@ _LEGACY_AUGMENT_MATCHERS = (
# and re-emitting it there would double it up.
_SESSION_START_MATCHER = "startup|resume|clear"
+#: Hook commands run through a shell, so absence of the console script is a
+#: ``command not found`` on *every* matched tool call — non-blocking, but
+#: repeated forever. The plugin ships these hooks independently of the CLI, so
+#: "installed the plugin, never installed repowise" is a supported state, not a
+#: broken one; a partially-written install (Windows holds ``repowise.exe`` open
+#: while an MCP server runs, so uv can abort mid-install) reaches it too.
+#: ``augment_hook`` already exits 0 silently on any internal failure — this
+#: extends the same courtesy to the script not being there at all.
+_AUGMENT_HOOK_COMMAND = (
+ "if command -v repowise-augment >/dev/null 2>&1; then exec repowise-augment; fi"
+)
+
def _session_start_entry() -> dict:
return {
@@ -227,7 +239,7 @@ def _session_start_entry() -> dict:
"hooks": [
{
"type": "command",
- "command": "repowise-augment",
+ "command": _AUGMENT_HOOK_COMMAND,
"timeout": 10,
"statusMessage": "Loading repowise context...",
}
@@ -249,7 +261,7 @@ def install_claude_code_hooks() -> Path | None:
"hooks": [
{
"type": "command",
- "command": "repowise-augment",
+ "command": _AUGMENT_HOOK_COMMAND,
"timeout": 10,
"statusMessage": "Checking codebase context...",
}
@@ -492,8 +504,11 @@ def _migrate_legacy_hook(hook_list: list) -> bool:
for entry in hook_list:
for hook in entry.get("hooks", []):
cmd = hook.get("command", "")
- if cmd == "repowise augment":
- hook["command"] = "repowise-augment"
+ # Both the old subcommand form and the unguarded console script
+ # migrate to the guarded command, so an install predating the guard
+ # stops emitting "command not found" without needing a re-init.
+ if cmd in ("repowise augment", "repowise-augment"):
+ hook["command"] = _AUGMENT_HOOK_COMMAND
changed = True
matcher = entry.get("matcher", "")
only_repowise = entry.get("hooks") and all(_is_repowise_hook(h) for h in entry["hooks"])
diff --git a/plugins/claude-code/hooks/hooks.json b/plugins/claude-code/hooks/hooks.json
index 9745a47db..960bea5c6 100644
--- a/plugins/claude-code/hooks/hooks.json
+++ b/plugins/claude-code/hooks/hooks.json
@@ -6,7 +6,7 @@
"hooks": [
{
"type": "command",
- "command": "repowise-augment",
+ "command": "if command -v repowise-augment >/dev/null 2>&1; then exec repowise-augment; fi",
"timeout": 10,
"statusMessage": "Loading repowise context..."
}
@@ -19,7 +19,7 @@
"hooks": [
{
"type": "command",
- "command": "repowise-augment",
+ "command": "if command -v repowise-augment >/dev/null 2>&1; then exec repowise-augment; fi",
"timeout": 10,
"statusMessage": "Checking codebase context..."
}
diff --git a/tests/unit/cli/test_claude_plugin.py b/tests/unit/cli/test_claude_plugin.py
index 002765f78..21ced1877 100644
--- a/tests/unit/cli/test_claude_plugin.py
+++ b/tests/unit/cli/test_claude_plugin.py
@@ -1,9 +1,12 @@
from __future__ import annotations
import json
+import os
import re
from pathlib import Path
+import pytest
+
from repowise.cli.editor_integrations import claude_config
ROOT = Path(__file__).resolve().parents[3]
@@ -50,8 +53,10 @@ def test_claude_plugin_hooks_match_installer() -> None:
for h in entry["hooks"]
]
- assert rows("PostToolUse") == [(claude_config._AUGMENT_MATCHER, "repowise-augment")]
- assert rows("SessionStart") == [(claude_config._SESSION_START_MATCHER, "repowise-augment")]
+ command = claude_config._AUGMENT_HOOK_COMMAND
+
+ assert rows("PostToolUse") == [(claude_config._AUGMENT_MATCHER, command)]
+ assert rows("SessionStart") == [(claude_config._SESSION_START_MATCHER, command)]
commands = [
hook["command"]
@@ -59,7 +64,57 @@ def test_claude_plugin_hooks_match_installer() -> None:
for entry in entries
for hook in entry["hooks"]
]
- assert commands == ["repowise-augment"] * 2
+ assert commands == [command] * 2
+
+
+def _posix_bash() -> str | None:
+ """Path to a POSIX bash, or None.
+
+ On Windows ``shutil.which("bash")`` finds ``system32\\bash.exe`` first — the
+ WSL launcher, which is not the shell Claude Code runs hooks with and does
+ not behave like one here. Prefer Git Bash explicitly, which is what a hook
+ actually gets on this platform.
+ """
+ import shutil
+
+ if os.name == "nt":
+ for candidate in (
+ r"C:\Program Files\Git\bin\bash.exe",
+ r"C:\Program Files\Git\usr\bin\bash.exe",
+ ):
+ if Path(candidate).is_file():
+ return candidate
+ found = shutil.which("bash")
+ return None if found is None or "system32" in found.lower() else found
+ return shutil.which("bash")
+
+
+def test_the_augment_hook_is_silent_when_the_console_script_is_absent(tmp_path: Path) -> None:
+ """The plugin installs independently of the CLI, so the script may not exist.
+
+ An unguarded command name makes that state print ``command not found`` on
+ every matched tool call — non-blocking noise the user cannot act on and
+ cannot escape short of disabling the plugin. Run the real command with a
+ PATH that resolves nothing: it must say nothing and exit 0.
+ """
+ import subprocess
+
+ bash = _posix_bash()
+ if bash is None: # pragma: no cover - hooks need a shell to run at all
+ pytest.skip("no POSIX bash available to execute a hook command")
+
+ # An empty PATH would also strip the variables process creation needs on
+ # Windows; an empty *directory* is the honest "script isn't installed" state.
+ proc = subprocess.run(
+ [bash, "-c", claude_config._AUGMENT_HOOK_COMMAND],
+ capture_output=True,
+ text=True,
+ env={**os.environ, "PATH": str(tmp_path)},
+ )
+
+ assert proc.returncode == 0, f"exited {proc.returncode}: {proc.stderr!r}"
+ assert proc.stdout == ""
+ assert proc.stderr == ""
def test_claude_plugin_skills_have_metadata() -> None:
diff --git a/tests/unit/cli/test_mcp_config.py b/tests/unit/cli/test_mcp_config.py
index 2b52b41dd..6c7b199c8 100644
--- a/tests/unit/cli/test_mcp_config.py
+++ b/tests/unit/cli/test_mcp_config.py
@@ -414,9 +414,11 @@ def test_install_claude_code_hooks_creates_missing_file(
saved = json.loads(settings_path.read_text(encoding="utf-8"))
assert "PreToolUse" not in saved["hooks"]
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
+ ]
+ assert _session_start_repowise_entries(saved) == [
+ ("startup|resume|clear", claude_config._AUGMENT_HOOK_COMMAND)
]
- assert _session_start_repowise_entries(saved) == [("startup|resume|clear", "repowise-augment")]
def test_install_claude_code_hooks_preserves_user_pretool_hooks(
@@ -452,7 +454,7 @@ def test_install_claude_code_hooks_preserves_user_pretool_hooks(
assert saved["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == "echo read"
# PostToolUse now has the repowise hook.
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
]
@@ -498,7 +500,7 @@ def test_install_claude_code_hooks_migrates_pre_0_6_1_command(
saved = json.loads(settings_path.read_text(encoding="utf-8"))
assert "PreToolUse" not in saved["hooks"]
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
]
@@ -538,7 +540,7 @@ def test_install_claude_code_hooks_migrates_pre_0_6_2_matcher(
saved = json.loads(settings_path.read_text(encoding="utf-8"))
assert "PreToolUse" not in saved["hooks"]
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
]
@@ -594,7 +596,7 @@ def test_migrate_claude_code_hooks_handles_full_legacy_payload(
saved = json.loads(settings_path.read_text(encoding="utf-8"))
assert "PreToolUse" not in saved["hooks"]
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
]
# Idempotent: a second run finds nothing to do.
@@ -632,7 +634,7 @@ def test_migrate_claude_code_hooks_widens_legacy_matchers(
assert claude_config.migrate_claude_code_hooks() is True
saved = json.loads(settings_path.read_text(encoding="utf-8"))
assert _post_repowise_entries(saved) == [
- (claude_config._AUGMENT_MATCHER, "repowise-augment")
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
]
@@ -647,11 +649,17 @@ def test_migrate_claude_code_hooks_never_widens_user_matcher(
json.dumps(
{
"hooks": {
+ # Commands are already in the guarded shape, so the only
+ # migration that could fire here is the matcher widening
+ # this test is about.
"PostToolUse": [
{
"matcher": "Bash|Grep|Glob",
"hooks": [
- {"type": "command", "command": "repowise-augment"},
+ {
+ "type": "command",
+ "command": claude_config._AUGMENT_HOOK_COMMAND,
+ },
{"type": "command", "command": "my-linter"},
],
}
@@ -661,7 +669,12 @@ def test_migrate_claude_code_hooks_never_widens_user_matcher(
"SessionStart": [
{
"matcher": "startup|resume|clear",
- "hooks": [{"type": "command", "command": "repowise-augment"}],
+ "hooks": [
+ {
+ "type": "command",
+ "command": claude_config._AUGMENT_HOOK_COMMAND,
+ }
+ ],
}
],
}
@@ -716,18 +729,21 @@ def test_migrate_claude_code_hooks_noop_when_already_current(
monkeypatch.setattr(Path, "home", lambda: tmp_path)
settings_path = tmp_path / ".claude" / "settings.json"
settings_path.parent.mkdir(parents=True)
+ # The guarded command, not the bare script name: a bare name is now a
+ # legacy shape the migration rewrites, so using it here would assert a
+ # no-op that must not happen.
payload = {
"hooks": {
"PostToolUse": [
{
"matcher": claude_config._AUGMENT_MATCHER,
- "hooks": [{"type": "command", "command": "repowise-augment"}],
+ "hooks": [{"type": "command", "command": claude_config._AUGMENT_HOOK_COMMAND}],
}
],
"SessionStart": [
{
"matcher": "startup|resume|clear",
- "hooks": [{"type": "command", "command": "repowise-augment"}],
+ "hooks": [{"type": "command", "command": claude_config._AUGMENT_HOOK_COMMAND}],
}
],
}
@@ -768,7 +784,9 @@ def test_migrate_claude_code_hooks_backfills_session_start(
assert claude_config.migrate_claude_code_hooks() is True
saved = json.loads(settings_path.read_text(encoding="utf-8"))
- assert _session_start_repowise_entries(saved) == [("startup|resume|clear", "repowise-augment")]
+ assert _session_start_repowise_entries(saved) == [
+ ("startup|resume|clear", claude_config._AUGMENT_HOOK_COMMAND)
+ ]
# Idempotent on the second pass.
assert claude_config.migrate_claude_code_hooks() is False
@@ -829,7 +847,9 @@ def test_migrate_claude_code_hooks_preserves_user_session_start(
saved = json.loads(settings_path.read_text(encoding="utf-8"))
session = saved["hooks"]["SessionStart"]
assert session[0]["hooks"][0]["command"] == "echo mine"
- assert _session_start_repowise_entries(saved) == [("startup|resume|clear", "repowise-augment")]
+ assert _session_start_repowise_entries(saved) == [
+ ("startup|resume|clear", claude_config._AUGMENT_HOOK_COMMAND)
+ ]
def test_migrate_claude_code_hooks_silent_when_settings_missing(
@@ -866,8 +886,12 @@ def test_plugin_hooks_json_mirrors_settings_entries(repo_root: Path) -> None:
for h in entry["hooks"]
]
- assert rows("PostToolUse") == [(claude_config._AUGMENT_MATCHER, "repowise-augment")]
- assert rows("SessionStart") == [(claude_config._SESSION_START_MATCHER, "repowise-augment")]
+ assert rows("PostToolUse") == [
+ (claude_config._AUGMENT_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
+ ]
+ assert rows("SessionStart") == [
+ (claude_config._SESSION_START_MATCHER, claude_config._AUGMENT_HOOK_COMMAND)
+ ]
def test_install_claude_code_hooks_rejects_invalid_existing_file(