kanit-gates 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
kanit/__init__.py ADDED
@@ -0,0 +1,6 @@
1
+ """kanit: evidence gates for coding agents.
2
+
3
+ Agents must show proof before they claim. Tool gates stop dangerous actions;
4
+ reply gates send back answers that claim work the transcript cannot prove.
5
+ """
6
+ __version__ = "0.1.0"
kanit/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
kanit/audit.py ADDED
@@ -0,0 +1,168 @@
1
+ """Append-only audit log and loud failure reporting.
2
+
3
+ Lesson from production (04.11.2026): our engine crashed on a missing rule field ~906 times
4
+ in nine hours and failed open; every gate silently stopped working. Here a crash still lets
5
+ the session continue (unless KANIT_FAIL_CLOSED=1), but it is logged and shown on screen.
6
+ Logging itself never raises: a log that cannot be written must not take a decision down with it.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import os
13
+ import sys
14
+ import tempfile
15
+ import time
16
+
17
+ WARN_EVERY_S = 600
18
+ ROTATE_BYTES = 20 * 1024 * 1024 # a log above this is moved to <name>.1 (one generation kept)
19
+ _NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
20
+
21
+
22
+ def project_dir() -> str:
23
+ """The project root. Claude Code sets CLAUDE_PROJECT_DIR for hooks; unlike the hook's `cwd` it does
24
+ not follow a `cd` inside the session, so `cd src/api` cannot step out of the project's rules."""
25
+ p = os.environ.get("CLAUDE_PROJECT_DIR")
26
+ return p if p and os.path.isdir(p) else os.getcwd()
27
+
28
+
29
+ def home() -> str:
30
+ return os.environ.get("KANIT_HOME") or os.path.join(project_dir(), ".kanit")
31
+
32
+
33
+ # Logs live next to the project's rules; keep them out of git, keep rules.json in.
34
+ GITIGNORE = "# written by kanit: logs stay local, rules.json is meant to be committed\n*.jsonl\n*.jsonl.1\nfailure.json\n"
35
+
36
+
37
+ def ensure_home() -> str:
38
+ """Create the audit directory on first use, with a .gitignore so logs are never committed by accident."""
39
+ h = home()
40
+ os.makedirs(h, exist_ok=True)
41
+ gi = os.path.join(h, ".gitignore")
42
+ if not os.path.lexists(gi):
43
+ fd = os.open(gi, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NOFOLLOW, 0o644)
44
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
45
+ f.write(GITIGNORE)
46
+ return h
47
+
48
+
49
+ def _append(name: str, row: dict) -> None:
50
+ path = os.path.join(home(), name)
51
+ try:
52
+ ensure_home()
53
+ row = dict(row, t=row.get("t") or time.time())
54
+ line = json.dumps(row, ensure_ascii=True) + "\n" # ASCII: lone surrogates and odd code pages cannot break it
55
+ try:
56
+ if os.lstat(path).st_size > ROTATE_BYTES:
57
+ os.replace(path, path + ".1")
58
+ except OSError:
59
+ pass
60
+ # O_NOFOLLOW: a planted symlink (.kanit/evals.jsonl -> ~/.bashrc) is refused, not appended to
61
+ fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | _NOFOLLOW, 0o644)
62
+ with os.fdopen(fd, "a", encoding="utf-8") as f:
63
+ f.write(line)
64
+ except Exception as e: # never raise, never swallow silently
65
+ try:
66
+ sys.stderr.write("kanit: audit write failed (%s): %r\n" % (path, e))
67
+ except Exception:
68
+ pass
69
+
70
+
71
+ def read_jsonl(name: str) -> list:
72
+ path = os.path.join(home(), name)
73
+ rows = []
74
+ try:
75
+ with open(path, encoding="utf-8", errors="replace") as f:
76
+ for line in f:
77
+ try:
78
+ rows.append(json.loads(line))
79
+ except ValueError:
80
+ continue
81
+ except OSError:
82
+ pass
83
+ return rows
84
+
85
+
86
+ def log_hit(session: str, event: str, rule: dict, excerpt: str, shadow: bool = False) -> None:
87
+ row = {"session": session, "event": event, "rule": rule["id"], "action": rule["action"], "excerpt": excerpt[:160]}
88
+ if shadow:
89
+ row["shadow"] = True
90
+ _append("audit.jsonl", row)
91
+
92
+
93
+ def log_eval(session: str, event: str, evaluated: list, hits: list, **extra) -> None:
94
+ """Denominator for every rule: how often it was checked, not only how often it fired."""
95
+ _append("evals.jsonl", dict({"session": session, "event": event, "evaluated": evaluated, "hits": hits}, **extra))
96
+
97
+
98
+ def _throttle(key: str, now: float) -> tuple:
99
+ """Count events per hour under `key`; return (show_warning_now, count_last_hour)."""
100
+ path = os.path.join(home(), "failure.json")
101
+ try:
102
+ with open(path, encoding="utf-8") as f:
103
+ state = json.load(f)
104
+ if not isinstance(state, dict):
105
+ state = {}
106
+ except (OSError, ValueError):
107
+ state = {}
108
+ s = state.get(key) if isinstance(state.get(key), dict) else {}
109
+ if now - s.get("last", 0) > 3600:
110
+ s["count"] = 0
111
+ s["count"] = s.get("count", 0) + 1
112
+ s["last"] = now
113
+ show = now - s.get("last_warned", 0) > WARN_EVERY_S
114
+ if show:
115
+ s["last_warned"] = now
116
+ state[key] = s
117
+ if len(state) > 200: # keep the newest keys only
118
+ state = dict(sorted(state.items(), key=lambda kv: -(kv[1].get("last", 0) if isinstance(kv[1], dict) else 0))[:100])
119
+ try:
120
+ ensure_home()
121
+ fd, tmp = tempfile.mkstemp(dir=home(), prefix=".failure-")
122
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
123
+ json.dump(state, f)
124
+ os.replace(tmp, path) # replaces a planted symlink instead of writing through it
125
+ except Exception as e:
126
+ try:
127
+ sys.stderr.write("kanit: failure state write failed: %r\n" % e)
128
+ except Exception:
129
+ pass
130
+ return show, s["count"]
131
+
132
+
133
+ def _key(kind: str, text: str) -> str:
134
+ """One throttle per distinct problem: a second, different error is never hidden behind the first."""
135
+ return "%s:%s" % (kind, hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:16])
136
+
137
+
138
+ def fail_loud(exc: BaseException, now: float = 0.0) -> str:
139
+ """Record an engine failure; return the on-screen warning ("" while throttled).
140
+
141
+ The caller prints it inside its single JSON object: a hook must emit exactly one.
142
+ """
143
+ now = now or time.time()
144
+ text = repr(exc)[:200]
145
+ _append("audit.jsonl", {"event": "engine_error", "error": text})
146
+ show, count = _throttle(_key("engine_error", type(exc).__name__ + str(exc)[:80]), now)
147
+ if not show:
148
+ return ""
149
+ return ("kanit ENGINE ERROR: gates are NOT enforcing (%d times in the last hour). Last: %s. Log: %s"
150
+ % (count, repr(exc)[:120], os.path.join(home(), "audit.jsonl")))
151
+
152
+
153
+ def rule_errors(errors: list, now: float = 0.0) -> str:
154
+ """Invalid rules are skipped, never fatal; return a throttled warning text ("" when quiet)."""
155
+ if not errors:
156
+ return ""
157
+ now = now or time.time()
158
+ _append("audit.jsonl", {"event": "rule_error", "errors": errors[:20]})
159
+ show, _ = _throttle(_key("rule_error", "\n".join(errors)), now)
160
+ if not show:
161
+ return ""
162
+ return "kanit: %d invalid rule(s) skipped, the rest still enforce: %s" % (len(errors), "; ".join(errors[:3]))
163
+
164
+
165
+ def notice(key: str, text: str, now: float = 0.0) -> str:
166
+ """A one-off notice for the human: returned the first time `key` is seen within the hour, then ""."""
167
+ show, count = _throttle(_key("notice", key), now or time.time())
168
+ return text if show and count == 1 else ""
kanit/cli.py ADDED
@@ -0,0 +1,419 @@
1
+ """Command line: hook | test-rules | stats | doctor."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import signal
9
+ import stat
10
+ import sys
11
+ import time
12
+
13
+ from . import __version__, audit, engine, transcript
14
+
15
+ RULES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rules")
16
+ CORE_RULES = os.path.join(RULES_DIR, "core.json")
17
+
18
+
19
+ def packaged_rules() -> list:
20
+ """core.json first, then the other packaged rule sets (e.g. tr.json) in name order."""
21
+ extra = sorted(os.path.join(RULES_DIR, f) for f in os.listdir(RULES_DIR) if f.endswith(".json") and f != "core.json")
22
+ return [CORE_RULES] + extra
23
+
24
+
25
+ def shadow() -> bool:
26
+ """KANIT_SHADOW=1: evaluate and log everything, print nothing. For trying kanit on real traffic."""
27
+ return os.environ.get("KANIT_SHADOW") == "1"
28
+
29
+
30
+ def rule_paths() -> list:
31
+ """Packaged rules, then project rules (.kanit/rules.json), then KANIT_RULES (os.pathsep list)."""
32
+ paths = packaged_rules()
33
+ project = os.path.join(audit.project_dir(), ".kanit", "rules.json")
34
+ if os.path.exists(project):
35
+ paths.append(project)
36
+ paths.extend(p for p in os.environ.get("KANIT_RULES", "").split(os.pathsep) if p)
37
+ return paths
38
+
39
+
40
+ def _disabled() -> list:
41
+ # set by the human in the environment of the hook process; the agent cannot change it
42
+ return [x.strip() for x in os.environ.get("KANIT_DISABLE", "").split(",") if x.strip()]
43
+
44
+
45
+ def _emit(obj: dict) -> None:
46
+ # ASCII-only JSON: the hook's stdout may use any code page (cp1252 on Windows); \uXXXX always prints
47
+ print(json.dumps(obj, ensure_ascii=True))
48
+
49
+
50
+ def _read_payload(stream) -> dict:
51
+ """Claude Code sends UTF-8. Read bytes when we can, so the console code page never decides."""
52
+ buf = getattr(stream, "buffer", None)
53
+ raw = buf.read().decode("utf-8", "replace") if buf is not None else stream.read()
54
+ payload = json.loads(raw)
55
+ if not isinstance(payload, dict):
56
+ raise ValueError("hook payload is not a JSON object")
57
+ return payload
58
+
59
+
60
+ PRIOR_MAX_BYTES = 2 * 1024 * 1024
61
+ # Claude Code lets a call through when a hook times out (10 s PreToolUse, 20 s Stop here), so kanit
62
+ # stops itself first and decides on purpose instead of timing out open.
63
+ BUDGET_S = {"PreToolUse": 6.0, "Stop": 14.0, "SubagentStop": 14.0}
64
+ DEFAULT_BUDGET_S = 6.0
65
+
66
+
67
+ class OverBudget(Exception):
68
+ """Raised by the timer when evaluation takes longer than the event's budget."""
69
+
70
+
71
+ def _arm(seconds: float) -> None:
72
+ if not hasattr(signal, "setitimer"): # Windows: no interval timer, Claude Code's own timeout applies
73
+ return
74
+
75
+ def _expired(signum, frame):
76
+ raise OverBudget()
77
+
78
+ signal.signal(signal.SIGALRM, _expired)
79
+ signal.setitimer(signal.ITIMER_REAL, seconds)
80
+
81
+
82
+ def _disarm() -> None:
83
+ if hasattr(signal, "setitimer"):
84
+ signal.setitimer(signal.ITIMER_REAL, 0)
85
+
86
+
87
+ def with_prior(tool_input: dict) -> dict:
88
+ """For a Write that replaces an existing file, add its current text as "_prior", so "only_added"
89
+ rules compare against what is already there. Missing, unreadable, special (FIFO, device) or very
90
+ large files count as empty."""
91
+ path = tool_input.get("file_path")
92
+ if "content" not in tool_input or not isinstance(path, str) or not path:
93
+ return tool_input
94
+ try:
95
+ st = os.stat(path)
96
+ if not stat.S_ISREG(st.st_mode) or st.st_size > PRIOR_MAX_BYTES:
97
+ return tool_input
98
+ with open(path, encoding="utf-8", errors="replace") as f:
99
+ return dict(tool_input, _prior=f.read(PRIOR_MAX_BYTES + 1))
100
+ except (OSError, ValueError):
101
+ return tool_input
102
+
103
+
104
+ def weakened(rules: list) -> list:
105
+ """Packaged rules that project files or KANIT_RULES turned off or changed (KANIT_DISABLE is the
106
+ human's own switch and is not counted). The agent may find a way to write .kanit/rules.json, so
107
+ the human is told whenever it weakens the packaged set."""
108
+ base = {r["id"]: r for r in engine.load_rules(packaged_rules())[0]}
109
+ final = {r["id"]: r for r in rules}
110
+ return sorted(rid for rid in base if final.get(rid) != base[rid])
111
+
112
+
113
+ def _weakened_note(session: str) -> str:
114
+ extra = rule_paths()[len(packaged_rules()):]
115
+ if not extra:
116
+ return ""
117
+ ids = weakened(engine.load_rules(rule_paths())[0])
118
+ if not ids:
119
+ return ""
120
+ digest = hashlib.sha256()
121
+ for p in extra:
122
+ try:
123
+ digest.update(engine.read_rules_file_bytes(p))
124
+ except (OSError, ValueError):
125
+ digest.update(p.encode("utf-8", "replace"))
126
+ text = ("kanit: project rules turn off or change %d packaged rule(s): %s. If you did not make this change, "
127
+ "check %s." % (len(ids), ", ".join(ids[:8]) + (" ..." if len(ids) > 8 else ""), ", ".join(extra)))
128
+ return audit.notice(session + ":" + digest.hexdigest(), text)
129
+
130
+
131
+ def run_hook(payload: dict) -> int:
132
+ if payload.get("cwd") and isinstance(payload["cwd"], str) and os.path.isdir(payload["cwd"]):
133
+ os.chdir(payload["cwd"])
134
+ event_name = payload.get("hook_event_name", "")
135
+ session = str(payload.get("session_id", ""))
136
+ rules, errors = engine.load_rules(rule_paths(), _disabled())
137
+ note = audit.rule_errors(errors)
138
+ extra_log = {}
139
+
140
+ if event_name == "PreToolUse":
141
+ event, tool = "tool", str(payload.get("tool_name", ""))
142
+ applicable = [r for r in rules if engine.applies(r, event, tool)]
143
+ tool_input = payload.get("tool_input") or {}
144
+ if not isinstance(tool_input, dict):
145
+ tool_input = {}
146
+ if any(r.get("only_added") for r in applicable):
147
+ tool_input = with_prior(tool_input)
148
+ hits = engine.tool_hits(applicable, tool, tool_input)
149
+ elif event_name in ("Stop", "SubagentStop"):
150
+ event = "reply"
151
+ applicable = [r for r in rules if engine.applies(r, event)]
152
+ # a subagent's reply is judged on the subagent's own transcript
153
+ path = payload.get("agent_transcript_path") or payload.get("transcript_path") or ""
154
+ path = path if isinstance(path, str) else ""
155
+ reply = payload.get("last_assistant_message")
156
+ reply = reply if isinstance(reply, str) and reply else transcript.last_reply(path)
157
+ acts, started = transcript.turn_state(path)
158
+ if not started:
159
+ # the turn began outside what we can read (compaction, very long turn): its evidence is
160
+ # unknown, so rules that need this turn's tool calls are not applied rather than misfiring
161
+ applicable = [r for r in applicable if not r.get("needs_turn")]
162
+ extra_log["turn_unknown"] = True
163
+ turn = ["%s: %s" % (a["tool"], a["text"]) for a in acts]
164
+ seen = transcript.session_text(path) if any(r.get("check") == "urls_seen" for r in applicable) else ""
165
+ hits = engine.reply_hits(applicable, reply, turn, seen)
166
+ if any(r.get("check") == "urls_seen" for r, _ in hits) and transcript.longer_than_tail(path):
167
+ # a link given early in a long session is outside the tail we read: look it up in the whole file
168
+ seen += "\n" + transcript.older_text_with(path, engine.URL_RE.findall(reply))
169
+ hits = engine.reply_hits(applicable, reply, turn, seen)
170
+ else:
171
+ if note and not shadow():
172
+ _emit({"systemMessage": note})
173
+ return 0
174
+
175
+ audit.log_eval(session, event, [r["id"] for r in applicable], [r["id"] for r, _ in hits], **extra_log)
176
+ for r, excerpt in hits:
177
+ audit.log_hit(session, event, r, excerpt, shadow=shadow())
178
+ if shadow():
179
+ return 0
180
+ out = engine.decide(hits, event, bool(payload.get("stop_hook_active"))) or {}
181
+ for extra in (note, _weakened_note(session)):
182
+ if extra:
183
+ out["systemMessage"] = (out.get("systemMessage", "") + "\n" + extra).strip()
184
+ if out:
185
+ _emit(out)
186
+ return 0
187
+
188
+
189
+ def _over_budget(payload: dict) -> int:
190
+ event_name = payload.get("hook_event_name", "") if isinstance(payload, dict) else ""
191
+ budget = BUDGET_S.get(event_name, DEFAULT_BUDGET_S)
192
+ audit._append("audit.jsonl", {"session": str(payload.get("session_id", "")) if isinstance(payload, dict) else "",
193
+ "event": "over_budget", "hook": event_name, "budget_s": budget})
194
+ if shadow():
195
+ return 0
196
+ if event_name == "PreToolUse":
197
+ _emit({"hookSpecificOutput": {
198
+ "hookEventName": "PreToolUse", "permissionDecision": "deny",
199
+ "permissionDecisionReason": ("kanit could not finish checking this call within %.0f s (a very large or "
200
+ "unusual input). Split the command, or write long content with the "
201
+ "Write tool." % budget)}})
202
+ else:
203
+ _emit({"systemMessage": "kanit warning: this reply could not be checked within %.0f s and was not checked." % budget})
204
+ return 0
205
+
206
+
207
+ def hook(stream=None) -> int:
208
+ payload = {}
209
+ try:
210
+ _arm(DEFAULT_BUDGET_S)
211
+ payload = _read_payload(stream or sys.stdin)
212
+ _arm(BUDGET_S.get(payload.get("hook_event_name"), DEFAULT_BUDGET_S))
213
+ return run_hook(payload)
214
+ except OverBudget:
215
+ _disarm()
216
+ return _over_budget(payload)
217
+ except Exception as e: # fail loud, then fail open (or closed when asked); one JSON object only
218
+ _disarm()
219
+ out = {}
220
+ warning = audit.fail_loud(e)
221
+ if warning:
222
+ out["systemMessage"] = warning
223
+ if os.environ.get("KANIT_FAIL_CLOSED") == "1" and isinstance(payload, dict) \
224
+ and payload.get("hook_event_name") == "PreToolUse":
225
+ out["hookSpecificOutput"] = {"hookEventName": "PreToolUse", "permissionDecision": "deny",
226
+ "permissionDecisionReason": "kanit engine error and KANIT_FAIL_CLOSED=1: %r" % e}
227
+ if out and not shadow(): # in shadow mode the error is still in audit.jsonl and `kanit doctor`
228
+ _emit(out)
229
+ return 0
230
+ finally:
231
+ _disarm()
232
+
233
+
234
+ def check(kind: str, text: str, tool: str = "", tool_input=None, turn=(), seen: str = "", out=None) -> int:
235
+ """Dry run without Claude Code: which active rules fire on this tool call or reply.
236
+
237
+ Exit code: 1 when a deny rule fires, 0 otherwise (warn hits are printed but do not fail)."""
238
+ w = out or sys.stdout
239
+ rules, errors = engine.load_rules(rule_paths(), _disabled())
240
+ for e in errors:
241
+ w.write("PROBLEM %s\n" % e)
242
+ if kind == "reply":
243
+ hits = engine.reply_hits([r for r in rules if engine.applies(r, "reply")], text, list(turn), seen)
244
+ else:
245
+ if kind == "bash":
246
+ tool, tool_input = "Bash", {"command": text}
247
+ hits = engine.tool_hits([r for r in rules if engine.applies(r, "tool", tool)], tool, tool_input or {})
248
+ for r, excerpt in hits:
249
+ w.write('%-4s %s\n %s\n matched: "%s"\n' % (r["action"].upper(), r["id"], r["message"], excerpt[:80]))
250
+ if not hits:
251
+ w.write("pass: no rule fired (%d rules checked)\n" % len(rules))
252
+ return 1 if any(r["action"] == "deny" for r, _ in hits) else 0
253
+
254
+
255
+ def _first_sentence(msg: str) -> str:
256
+ cut = msg.find(". ")
257
+ return msg if cut < 0 else msg[:cut + 1]
258
+
259
+
260
+ def rules_table(paths=None, markdown: bool = False, out=None) -> int:
261
+ """List active rules. --markdown prints the table used in README.md (a test keeps them equal)."""
262
+ w = out or sys.stdout
263
+ rules, errors = engine.load_rules(paths or rule_paths(), _disabled())
264
+ if markdown:
265
+ w.write("| id | on | action | what it stops |\n|---|---|---|---|\n")
266
+ for r in rules:
267
+ w.write("| `%s` | %s | %s | %s |\n" % (r["id"], r["event"], r["action"], _first_sentence(r["message"]).replace("|", "\\|")))
268
+ else:
269
+ for r in rules:
270
+ w.write("%-34s %-5s %-4s %s\n" % (r["id"], r["event"], r["action"], _first_sentence(r["message"])))
271
+ for e in errors:
272
+ w.write("PROBLEM %s\n" % e)
273
+ return 1 if errors else 0
274
+
275
+
276
+ def _fires(rule: dict, example: dict) -> bool:
277
+ if rule["event"] == "tool":
278
+ return bool(engine.tool_hits([rule], example.get("tool", "Bash"), example.get("input") or {}))
279
+ return bool(engine.reply_hits([rule], example.get("reply", ""), example.get("turn") or [], example.get("seen", "")))
280
+
281
+
282
+ def test_rules(paths=None) -> int:
283
+ """Every rule must prove itself: at least one example it fires on, all misses stay quiet."""
284
+ rules, errors = engine.load_rules(paths or rule_paths())
285
+ failures = list(errors)
286
+ n_examples = 0
287
+ for r in rules:
288
+ ex = r.get("examples") or {}
289
+ if not ex.get("hit"):
290
+ failures.append("%s: no 'hit' example; a rule that never proves it fires is not a gate" % r["id"])
291
+ for e in ex.get("hit") or []:
292
+ n_examples += 1
293
+ if not _fires(r, e):
294
+ failures.append("%s: should fire on %s" % (r["id"], json.dumps(e, ensure_ascii=False)[:120]))
295
+ for e in ex.get("miss") or []:
296
+ n_examples += 1
297
+ if _fires(r, e):
298
+ failures.append("%s: should NOT fire on %s" % (r["id"], json.dumps(e, ensure_ascii=False)[:120]))
299
+ for f in failures:
300
+ print("FAIL " + f)
301
+ print("rules %d · examples %d · failures %d" % (len(rules), n_examples, len(failures)))
302
+ return 1 if failures else 0
303
+
304
+
305
+ def stats(window: int = 600, out=None) -> dict:
306
+ """Per rule: times checked, raw hits, unique hits (same session + rule within `window` s = one)."""
307
+ table = {}
308
+ evals = audit.read_jsonl("evals.jsonl")
309
+ for row in evals:
310
+ for rid in row.get("evaluated") or []:
311
+ table.setdefault(rid, {"checked": 0, "raw": 0, "unique": 0})["checked"] += 1
312
+ last = {}
313
+ for row in sorted(audit.read_jsonl("audit.jsonl"), key=lambda x: x.get("t", 0)):
314
+ rid = row.get("rule")
315
+ if not rid:
316
+ continue
317
+ s = table.setdefault(rid, {"checked": 0, "raw": 0, "unique": 0})
318
+ s["raw"] += 1
319
+ key = (row.get("session"), rid)
320
+ if row.get("t", 0) - last.get(key, -1e18) > window:
321
+ s["unique"] += 1
322
+ last[key] = row.get("t", 0)
323
+ w = out or sys.stdout
324
+ w.write("%-36s %8s %6s %7s %7s\n" % ("rule", "checked", "raw", "unique", "rate"))
325
+ for rid, s in sorted(table.items(), key=lambda kv: -kv[1]["unique"]):
326
+ rate = "%.2f%%" % (100.0 * s["unique"] / s["checked"]) if s["checked"] else "n/a"
327
+ w.write("%-36s %8d %6d %7d %7s\n" % (rid, s["checked"], s["raw"], s["unique"], rate))
328
+ replies = [r for r in evals if r.get("event") == "reply"]
329
+ if replies:
330
+ w.write("\nreply checks: %d · turn start not readable (evidence rules skipped): %d\n"
331
+ % (len(replies), sum(1 for r in replies if r.get("turn_unknown"))))
332
+ return table
333
+
334
+
335
+ def doctor() -> int:
336
+ problems = []
337
+ print("kanit %s · python %s" % (__version__, sys.version.split()[0]))
338
+ if sys.version_info < (3, 9):
339
+ problems.append("python >= 3.9 required")
340
+ rules, errors = engine.load_rules(rule_paths(), _disabled())
341
+ problems.extend(errors)
342
+ print("rules: %d active from %s" % (len(rules), ", ".join(rule_paths())))
343
+ try:
344
+ audit.ensure_home()
345
+ probe = os.path.join(audit.home(), ".probe")
346
+ with open(probe, "w") as f:
347
+ f.write("ok")
348
+ os.remove(probe)
349
+ print("audit log: %s (writable)" % audit.home())
350
+ except OSError as e:
351
+ problems.append("audit dir not writable: %s" % e)
352
+ errs = [r for r in audit.read_jsonl("audit.jsonl") if r.get("event") == "engine_error" and r.get("t", 0) > time.time() - 86400]
353
+ if errs:
354
+ problems.append("%d engine errors in the last 24 h, last: %s" % (len(errs), errs[-1].get("error")))
355
+ day = [r for r in audit.read_jsonl("evals.jsonl") if r.get("event") == "reply" and r.get("t", 0) > time.time() - 86400]
356
+ unknown = sum(1 for r in day if r.get("turn_unknown"))
357
+ if unknown:
358
+ print("note: %d of %d reply checks in the last 24 h could not read the start of the turn (no transcript, "
359
+ "or a compaction); evidence rules were skipped for them" % (unknown, len(day)))
360
+ for p in problems:
361
+ print("PROBLEM " + p)
362
+ print("ok" if not problems else "%d problem(s)" % len(problems))
363
+ return 1 if problems else 0
364
+
365
+
366
+ def main(argv=None) -> int:
367
+ for s in (sys.stdout, sys.stderr): # human output on a narrow code page: replace, never crash
368
+ try:
369
+ s.reconfigure(errors="replace")
370
+ except (AttributeError, ValueError):
371
+ pass
372
+ ap = argparse.ArgumentParser(prog="kanit", description="Evidence gates for coding agents.")
373
+ ap.add_argument("--version", action="version", version="kanit " + __version__)
374
+ sub = ap.add_subparsers(dest="cmd")
375
+ sub.add_parser("hook", help="read a Claude Code hook payload on stdin")
376
+ c = sub.add_parser("check", help="dry run: which rules fire on a shell command, tool call or reply",
377
+ description="Examples: kanit check bash 'git push --force' "
378
+ "kanit check reply 'All tests pass.' --turn 'Edit: app.py' "
379
+ "kanit check tool Write --input '{\"file_path\": \".env\"}'")
380
+ c.add_argument("kind", choices=("bash", "tool", "reply"))
381
+ c.add_argument("text", help="the shell command, the tool name (kind tool) or the reply text")
382
+ c.add_argument("--input", default="{}", help="tool input as JSON (kind tool)")
383
+ c.add_argument("--turn", action="append", default=[], help="a tool call made this turn, e.g. 'Bash: pytest' (repeatable)")
384
+ c.add_argument("--seen", default="", help="text the agent saw this session (for the link rule)")
385
+ r = sub.add_parser("rules", help="list active rules")
386
+ r.add_argument("--markdown", action="store_true", help="print the README table")
387
+ t = sub.add_parser("test-rules", help="check every rule against its own examples")
388
+ t.add_argument("paths", nargs="*")
389
+ s = sub.add_parser("stats", help="per-rule checked / hit counts from the audit log")
390
+ s.add_argument("--window", type=int, default=600, help="dedupe window in seconds (default 600)")
391
+ sub.add_parser("doctor", help="check install, rules and audit log")
392
+ a = ap.parse_args(argv)
393
+ if a.cmd == "hook":
394
+ return hook()
395
+ if a.cmd == "check":
396
+ if a.kind == "tool":
397
+ try:
398
+ tool_input = json.loads(a.input)
399
+ except ValueError as e:
400
+ ap.error("--input is not valid JSON: %s" % e)
401
+ if not isinstance(tool_input, dict):
402
+ ap.error("--input must be a JSON object")
403
+ return check("tool", "", tool=a.text, tool_input=tool_input)
404
+ return check(a.kind, a.text, turn=a.turn, seen=a.seen)
405
+ if a.cmd == "rules":
406
+ return rules_table(markdown=a.markdown)
407
+ if a.cmd == "test-rules":
408
+ return test_rules(a.paths or None)
409
+ if a.cmd == "stats":
410
+ stats(a.window)
411
+ return 0
412
+ if a.cmd == "doctor":
413
+ return doctor()
414
+ ap.print_help()
415
+ return 2
416
+
417
+
418
+ if __name__ == "__main__":
419
+ sys.exit(main())