Check That the Kit Is Wired In, Not Only That Its Bytes Are Right

`--report` compared the deployed hook and the CLAUDE.md blocks and never
looked at settings.json, where the hook is registered and the permission
rules live. A machine with every byte correct and the PreToolUse entry
removed carries a complete, current, entirely inert kit, and every check
here called it CURRENT.
That is the worst verdict this tool can give, since the whole question it
answers is whether the guard is in force on this machine.
`registration_problems` now reads settings.json and reports an unregistered
hook, a hook registered more than once, a missing managed permission rule,
and a settings file that is absent or unreadable.
`stampVersion` was written into every stamp, described in its own comment
as the way a reader detects a format change, and never validated. A stamp
from another format version now says so rather than being read as valid.
Nine cases added, all failing against the previous code, including that
re-running clears an unregistered hook.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ptr727

host-setup/agent-safety/install.py

@@ -224,6 +224,7 @@ def build_stamp(claude_home, installed):
 # Shape rather than presence: a partial write leaves keys missing, and a hand edit leaves a key holding the wrong type.
 # A key check alone passes `"source": "git"` and then raises inside the line that formats it, which is the crash it was added to prevent.
 STAMP_SHAPE= {
+"stampVersion": int,
 "host": dict,
 "source": dict,
 "payloadDigest": str,
@@ -242,6 +243,47 @@ def stamp_problems(stamp):
 out.append(f"{key} is missing")
 elifnotisinstance(stamp[key], want):
 out.append(f"{key} is {type(stamp[key]).__name__} where {want.__name__} is required")
+# The version carries the format rather than the content, so a mismatch either way is unreadable.
+# A newer stamp holds fields this code does not know, and an older one lacks fields it reads.
+# Carrying the field and never checking it is the version telling nobody anything.
+ifstamp.get("stampVersion") notin (None, STAMP_VERSION) andisinstance(stamp.get("stampVersion"), int):
+out.append(f"stampVersion is {stamp['stampVersion']} where this installer writes {STAMP_VERSION}")
+returnout
+
+
+defregistration_problems(claude_home):
+"""Whether settings.json still wires the kit in, which decides if any of it actually runs.
+
+ The hook's bytes being correct says nothing about whether Claude Code invokes it. An entry
+ removed from settings.json leaves a machine carrying a complete, current, and entirely inert
+ kit, which every other check here reports as fine.
+ """
+settings=claude_home/"settings.json"
+ifnotsettings.is_file():
+return ["settings.json is missing, so the hook is not registered"]
+try:
+data=json.loads(settings.read_text(encoding="utf-8") or"{}")
+except (json.JSONDecodeError, OSError) ase:
+return [f"settings.json cannot be read ({e})"]
+ifnotisinstance(data, dict):
+return ["settings.json does not hold an object at its root"]
+out= []
+groups=data.get("hooks", {}).get("PreToolUse") ifisinstance(data.get("hooks"), dict) elseNone
+registered=0
+forgroupingroupsor []:
+ifnotisinstance(group, dict):
+continue
+forhookingroup.get("hooks") or []:
+ifisinstance(hook, dict) and"gh-write-guard"instr(hook.get("command", "")):
+registered+=1
+ifregistered==0:
+out.append("the PreToolUse hook is not registered in settings.json, so the guard never runs")
+elifregistered>1:
+out.append(f"the PreToolUse hook is registered {registered} times, so it runs more than once")
+allow=data.get("permissions", {}).get("allow") ifisinstance(data.get("permissions"), dict) elseNone
+for_, ruleinMANAGED_PERMISSIONS:
+ifnotisinstance(allow, list) orrulenotinallow:
+out.append(f"the permission rule {rule} is absent from settings.json")
 returnout
 
 
@@ -303,6 +345,8 @@ def report(claude_home):
 problems.append("the deployed hook or CLAUDE.md is missing, so the kit is not fully installed")
 eliflive_installed!=current:
 problems.append("the installed content differs from what this checkout would write")
+# Correct bytes on disk are not a running guard, so the wiring is checked as well.
+problems.extend(registration_problems(claude_home))
 iflive!=stamp.get("blocks"):
 problems.append(f"CLAUDE.md now holds {liveor'no blocks'}, where the stamp recorded {stamp.get('blocks') or'none'}")
 ifstamp.get("source", {}).get("dirty"):

host-setup/agent-safety/test_install.py

@@ -241,6 +241,82 @@ def test_the_formatter_stays_printable_on_a_stamp_the_validator_would_reject(sel
 self.assertIsInstance(install.stamp_line(broken), str)
 
 
+classTestRegistration(StampCase):
+"""Correct bytes on disk are not a running guard. These are the inert-kit cases."""
+
+def_settings(self):
+returnjson.loads((self.home/"settings.json").read_text(encoding="utf-8"))
+
+def_write(self, data):
+ (self.home/"settings.json").write_text(json.dumps(data, indent=2) +"\n", encoding="utf-8")
+
+deftest_an_unregistered_hook_reports_stale_rather_than_current(self):
+"""Every byte is correct and the guard never runs, which every other check calls fine."""
+self.install()
+data=self._settings()
+data["hooks"]["PreToolUse"] = []
+self._write(data)
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("never runs", r.stdout)
+
+deftest_a_removed_permission_rule_reports_stale(self):
+self.install()
+data=self._settings()
+data["permissions"]["allow"] = []
+self._write(data)
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("permission rule", r.stdout)
+
+deftest_a_duplicated_hook_registration_reports_stale(self):
+self.install()
+data=self._settings()
+group=data["hooks"]["PreToolUse"][0]
+group["hooks"].append(dict(group["hooks"][0]))
+self._write(data)
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("more than once", r.stdout)
+
+deftest_a_deleted_settings_file_reports_stale_rather_than_crashing(self):
+self.install()
+ (self.home/"settings.json").unlink()
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertNotIn("Traceback", r.stderr)
+
+deftest_reinstalling_clears_an_unregistered_hook(self):
+self.install()
+data=self._settings()
+data["hooks"]["PreToolUse"] = []
+self._write(data)
+self.assertEqual(run(self.home, "--report").returncode, 1)
+self.install()
+self.assertEqual(run(self.home, "--report").returncode, 0)
+
+
+classTestStampVersion(StampCase):
+deftest_a_stamp_from_a_different_format_version_is_rejected(self):
+"""The field exists so a shape change is detectable, which needs it to be read."""
+self.install()
+stamp=json.loads(self.stamp.read_text(encoding="utf-8"))
+stamp["stampVersion"] =install.STAMP_VERSION+1
+self.stamp.write_text(json.dumps(stamp) +"\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 2, r.stdout+r.stderr)
+self.assertIn("stampVersion", r.stderr)
+
+deftest_a_stamp_version_of_the_wrong_type_is_rejected(self):
+self.install()
+stamp=json.loads(self.stamp.read_text(encoding="utf-8"))
+stamp["stampVersion"] ="1"
+self.stamp.write_text(json.dumps(stamp) +"\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 2, r.stdout+r.stderr)
+self.assertIn("stampVersion", r.stderr)
+
+
 classTestStampContent(StampCase):
 deftest_the_stamp_names_the_machine_the_source_and_what_was_installed(self):
 self.install()