@veda-hq/sarathi 0.5.7 → 0.6.0

package/README.md

@@ -71,6 +71,30 @@ sarathi for every event the list names, with a matcher that lets every
 handler fire and a timeout at least the longest handler's. Run it in the
 project's tests.
 
+### Handlers it carries
+
+Every `command` runs with `SARATHI_HOOKS` set to the package's `hooks/`
+folder, which holds handlers any TypeScript repository can list:
+
+```json
+{ "matcher": "Edit|Write", "command": "bash \"$SARATHI_HOOKS\"/code-quality-guard.sh" }
+```
+
+| Handler | Event | What it does |
+| --- | --- | --- |
+| `format-before-write.sh` | PreToolUse, `Edit\|Write` | Hands the tool prettier-formatted input, so the file is written formatted and Claude Code has no "hook modified your file" notice to keep in context. Never blocks. |
+| `format-on-edit.sh` | PostToolUse, `Edit\|Write` | Formats the written file with prettier: the net for what the first one skips. Never blocks. |
+| `code-quality-guard.sh` | PostToolUse, `Edit\|Write` | Refuses `@ts-ignore`, `@ts-nocheck`, `eslint-disable`, `any` and skipped tests in a `.ts`/`.tsx` edit. `.claude/`, `.agent/` and `docs/` are exempt. |
+| `arch-guard.sh` | PostToolUse, `Edit\|Write` | Runs the repository's `.dependency-cruiser.js` on a `.ts`/`.tsx` edit that touches imports; refuses what it refuses, and refuses when it cannot run. `scripts/` is exempt too. |
+| `session-dedupe-guard.sh` | PreToolUse, session starts | Refuses starting a session unless the conversation called `list_sessions` successfully in the last 15 minutes. |
+
+They act on the session's checkout, the git toplevel of the event's `cwd`:
+the desktop app runs a worktree session's hooks with `$CLAUDE_PROJECT_DIR`
+set to the main checkout. They use that checkout's prettier and
+dependency-cruiser, and the project checkout's prettier when a fresh worktree
+has none installed. They need `bash`, `jq` and `git`;
+`session-dedupe-guard.sh` runs `HOOK_PYTHON`, or `python3`.
+
 ### Forbidden variables
 
 Some switches turn a session's tooling off from the environment, where no

package/dist/cli.js

@@ -12,7 +12,7 @@ import { join, resolve } from 'node:path';
 import { ConfigError, compileMatcher, entriesFor, forbiddenSet, loadConfig, longestTimeout, settingsMatcher } from './config.js';
 import { merge } from './merge.js';
 import { runAll } from './run.js';
-export const VERSION = '0.5.7';
+export const VERSION = '0.6.0';
 const USAGE = `usage: sarathi hook <Event> [--config <file>]
        sarathi check [--config <file>] [--settings <file>]
        sarathi --version

package/dist/hooks/format-before-write.js

@@ -0,0 +1,207 @@
+/**
+ * PreToolUse handler (Edit|Write): hands the tool prettier-formatted input,
+ * so the file is formatted as it is written.
+ *
+ * Formatting after the write (hooks/format-on-edit.sh) makes Claude Code tell
+ * the model "PostToolUse hook modified <file> after your edit", one notice per
+ * reformatting edit, kept in context for the rest of the session. Formatting
+ * the input instead leaves the post-write formatter nothing to change, so no
+ * notice. format-on-edit stays as the net for anything this skips.
+ *
+ * Write: `content` is formatted whole. Edit: the edit is applied to the file
+ * in memory, the result formatted, and the edit rewritten as the smallest
+ * unique old_string → new_string that yields the formatted file.
+ *
+ * Never blocks. On every doubt (unparseable code mid-edit, a non-unique old_string,
+ * a file outside the checkout, no prettier) it prints nothing and the tool runs
+ * as asked.
+ *
+ * Run: node <sarathi>/dist/hooks/format-before-write.js
+ */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, extname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const FORMATTED = new Set(['.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.yml', '.yaml', '.css']);
+/**
+ * The session's checkout: the git toplevel of the hook input's `cwd`. Not
+ * $CLAUDE_PROJECT_DIR: the desktop app sets that to the main checkout for a
+ * worktree session, and every desktop worktree lies under main, so it would
+ * admit any worktree's files and judge them by main's .prettierignore.
+ * Without a usable `cwd`, $CLAUDE_PROJECT_DIR, then the current directory.
+ */
+export function sessionRoot(event, env = process.env) {
+    const cwd = event.cwd;
+    if (typeof cwd === 'string' && cwd !== '') {
+        try {
+            const top = execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (top !== '')
+                return realpathSync(top);
+        }
+        catch {
+            // Not a directory or not a work tree: fall back.
+        }
+    }
+    return realpathSync(env['CLAUDE_PROJECT_DIR'] || process.cwd());
+}
+/**
+ * The session checkout's prettier; the project checkout's when that one has
+ * none installed (a fresh worktree before its first install). `null` when
+ * neither has one.
+ */
+export function loadPrettier(root, env = process.env) {
+    const bases = [root, env['CLAUDE_PROJECT_DIR']].filter((b) => typeof b === 'string' && b !== '');
+    for (const base of bases) {
+        try {
+            return createRequire(join(base, 'package.json'))('prettier');
+        }
+        catch {
+            // Try the next checkout.
+        }
+    }
+    return null;
+}
+/** Same scope as format-on-edit.sh: inside the checkout, not scratch, not a link. */
+function inScope(filePath, mustExist, repoRoot) {
+    if (!FORMATTED.has(extname(filePath)))
+        return false;
+    if (/(^|\/)\.(tmp|local)\//.test(filePath))
+        return false;
+    let dir;
+    try {
+        dir = realpathSync(dirname(filePath));
+    }
+    catch {
+        return false;
+    }
+    if (dir !== repoRoot && !dir.startsWith(repoRoot + sep))
+        return false;
+    try {
+        if (lstatSync(filePath).isSymbolicLink())
+            return false;
+    }
+    catch {
+        if (mustExist)
+            return false;
+    }
+    return true;
+}
+/** Index of the only occurrence of needle in haystack, or -1. */
+function uniqueIndex(haystack, needle) {
+    const at = haystack.indexOf(needle);
+    if (at === -1 || haystack.indexOf(needle, at + 1) !== -1)
+        return -1;
+    return at;
+}
+/**
+ * The smallest old → new replacement turning `before` into `after`, grown a
+ * line at a time until old is non-empty and unique in `before`.
+ */
+export function minimalEdit(before, after) {
+    let start = 0;
+    const shortest = Math.min(before.length, after.length);
+    while (start < shortest && before[start] === after[start])
+        start++;
+    let tail = 0;
+    while (tail < shortest - start && before[before.length - 1 - tail] === after[after.length - 1 - tail])
+        tail++;
+    let from = start;
+    let beforeEnd = before.length - tail;
+    let afterEnd = after.length - tail;
+    for (;;) {
+        const old = before.slice(from, beforeEnd);
+        if (old !== '' && uniqueIndex(before, old) === from) {
+            return { old_string: old, new_string: after.slice(from, afterEnd) };
+        }
+        if (from === 0 && beforeEnd === before.length)
+            return null;
+        // Back to the start of this line, or of the previous one when already there.
+        const lineStart = from < 2 ? -1 : before.lastIndexOf('\n', from - 2);
+        from = lineStart === -1 ? 0 : lineStart + 1;
+        const lineEnd = before.indexOf('\n', beforeEnd + 1);
+        const grow = (lineEnd === -1 ? before.length : lineEnd) - beforeEnd;
+        beforeEnd += grow;
+        afterEnd += grow;
+    }
+}
+/** The Edit tool's own semantics: exactly one match, or every match with replace_all. */
+function applyEdit(current, input) {
+    const { old_string: oldString, new_string: newString, replace_all: all } = input;
+    if (typeof oldString !== 'string' || typeof newString !== 'string' || oldString === '')
+        return null;
+    if (all === true)
+        return current.split(oldString).join(newString);
+    const at = uniqueIndex(current, oldString);
+    if (at === -1)
+        return null;
+    return current.slice(0, at) + newString + current.slice(at + oldString.length);
+}
+async function format(prettier, filePath, text, repoRoot) {
+    const info = await prettier.getFileInfo(filePath, { ignorePath: join(repoRoot, '.prettierignore') });
+    if (info.ignored || !info.inferredParser)
+        return null;
+    const options = (await prettier.resolveConfig(filePath)) ?? {};
+    return prettier.format(text, { ...options, filepath: filePath });
+}
+/** The tool input to run instead, or `null` to let the tool run as asked. */
+export async function updatedInput(event, prettier, root) {
+    const input = event.tool_input ?? {};
+    const filePath = input['file_path'];
+    if (typeof filePath !== 'string' || filePath === '')
+        return null;
+    if (event.tool_name === 'Write') {
+        const content = input['content'];
+        if (typeof content !== 'string' || !inScope(filePath, false, root))
+            return null;
+        const formatted = await format(prettier, filePath, content, root);
+        if (formatted === null || formatted === content)
+            return null;
+        return { ...input, content: formatted };
+    }
+    if (event.tool_name === 'Edit') {
+        if (!inScope(filePath, true, root))
+            return null;
+        const current = readFileSync(filePath, 'utf8');
+        const edited = applyEdit(current, input);
+        if (edited === null)
+            return null;
+        const formatted = await format(prettier, filePath, edited, root);
+        if (formatted === null || formatted === edited || formatted === current)
+            return null;
+        const edit = minimalEdit(current, formatted);
+        if (edit === null)
+            return null;
+        return { file_path: filePath, ...edit, replace_all: false };
+    }
+    return null;
+}
+/** The hook's whole answer for one raw stdin: the JSON to print, or '' for none. Never throws. */
+export async function respond(raw, env = process.env) {
+    try {
+        const event = JSON.parse(raw);
+        const root = sessionRoot(event, env);
+        const prettier = loadPrettier(root, env);
+        if (prettier === null)
+            return '';
+        const next = await updatedInput(event, prettier, root);
+        if (next === null)
+            return '';
+        return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: next } });
+    }
+    catch {
+        return '';
+    }
+}
+async function main() {
+    let raw = '';
+    for await (const chunk of process.stdin)
+        raw += String(chunk);
+    process.stdout.write(await respond(raw));
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    void main();
+}

package/dist/run.js

@@ -6,6 +6,7 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { DEFAULT_TIMEOUT_SECONDS } from './config.js';
 const GUARD_SCRIPTS = {
     worktree: 'worktree_guard.py',
@@ -16,8 +17,12 @@ export function kavachDir() {
     const require = createRequire(import.meta.url);
     return join(dirname(require.resolve('@veda-hq/kavach/package.json')), 'python', 'kavach');
 }
-/** How one entry runs: a command through `sh -c`, a guard through the configured Python. */
-export function plan(entry, config, guardDir = kavachDir) {
+/** The folder holding sarathi's own handlers (hooks/), given to every command as SARATHI_HOOKS. */
+export function hooksDir() {
+    return fileURLToPath(new URL('../hooks', import.meta.url));
+}
+/** How one entry runs: a command through `sh -c` with SARATHI_HOOKS set, a guard through the configured Python. */
+export function plan(entry, config, guardDir = kavachDir, handlers = hooksDir) {
     const timeoutMs = (entry.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000;
     if (entry.guard !== undefined) {
         const env = config.kavach.config === undefined ? {} : { KAVACH_CONFIG: config.kavach.config };
@@ -31,7 +36,7 @@ export function plan(entry, config, guardDir = kavachDir) {
         };
     }
     const command = entry.command ?? '';
-    return { label: command, file: '/bin/sh', args: ['-c', command], env: {}, timeoutMs, failClosed: entry.failClosed === true };
+    return { label: command, file: '/bin/sh', args: ['-c', command], env: { SARATHI_HOOKS: handlers() }, timeoutMs, failClosed: entry.failClosed === true };
 }
 /** Runs one plan with `input` on stdin. Never rejects: a handler that cannot start ends with code `null`. */
 export function runPlan(step, input, cwd) {

package/hooks/arch-guard.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# PostToolUse handler for Edit/Write on TypeScript files: runs the session
+# checkout's dependency-cruiser rules (.dependency-cruiser.js) on the edited
+# file, so a forbidden import is refused at edit time.
+# depcruise costs about 2 s, so it runs only when the edit touches imports.
+# Exit 2 = the violation goes back to the agent to fix at once.
+#
+# Runs depcruise in the SESSION's checkout (hook input `cwd`), with that
+# checkout's config and node_modules (lib/session-root.sh).
+
+input=$(cat)
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input")
+
+case "$file_path" in
+  *.ts | *.tsx) ;;
+  *) exit 0 ;;
+esac
+[ -f "$file_path" ] || exit 0
+
+# Only pay the depcruise cost when the edit could change the dependency graph
+content=$(jq -r '.tool_input.new_string // .tool_input.content // ""' <<<"$input")
+if ! grep -qE '(^|\n)[[:space:]]*(import[[:space:]]|export[[:space:]]+.*[[:space:]]from[[:space:]]|.*require\()' <<<"$content"; then
+  exit 0
+fi
+
+# Checked before sourcing: bash exits on a missing `.` file before any `||`.
+lib="$(dirname "$0")/lib/session-root.sh"
+# shellcheck source=lib/session-root.sh
+if [ ! -r "$lib" ] || ! . "$lib"; then
+  echo 'arch-guard: cannot load lib/session-root.sh — blocking edit (guard could not run)' >&2
+  exit 2
+fi
+root=$(session_root "$input" "${CLAUDE_PROJECT_DIR:-$PWD}")
+case "$(rel_to_root "$file_path" "$root")" in
+  */.claude/* | .claude/* | */.agent/* | .agent/* | */docs/* | docs/* | */scripts/* | scripts/*) exit 0 ;;
+esac
+
+cd "$root" || { echo 'arch-guard: cannot cd to repo root — blocking edit (guard could not run)' >&2; exit 2; }
+result=$(npx depcruise --config .dependency-cruiser.js "$file_path" 2>&1)
+if [ $? -ne 0 ]; then
+  {
+    echo "ARCHITECTURE VIOLATION in $file_path (this repository's dependency rules, .dependency-cruiser.js):"
+    echo "$result" | grep -v '^$' | head -15
+    echo "Fix the import structure — do not suppress the rule."
+  } >&2
+  exit 2
+fi
+
+exit 0

package/hooks/code-quality-guard.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# PostToolUse handler for Edit/Write on TypeScript files: refuses the escape
+# hatches a strict TypeScript codebase forbids (@ts-ignore, @ts-nocheck,
+# eslint-disable, `any`, skipped tests), so the agent fixes the cause at once.
+# Exit 2 = the reason goes back to the agent as an error it must address.
+
+set -euo pipefail
+
+input=$(cat)
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input")
+
+case "$file_path" in
+  *.ts | *.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Agent, skill and doc sources may legitimately mention the patterns. Judged
+# relative to the session's checkout: a desktop worktree sits under
+# <main>/.claude/worktrees/, so its absolute paths all match `*/.claude/*`.
+# Checked before sourcing: bash exits on a missing `.` file before any `||`.
+lib="$(dirname "$0")/lib/session-root.sh"
+# shellcheck source=lib/session-root.sh
+if [ ! -r "$lib" ] || ! . "$lib"; then
+  echo 'code-quality-guard: cannot load lib/session-root.sh — blocking edit (guard could not run)' >&2
+  exit 2
+fi
+root=$(session_root "$input" "${CLAUDE_PROJECT_DIR:-$PWD}")
+case "$(rel_to_root "$file_path" "$root")" in
+  */.claude/* | .claude/* | */.agent/* | .agent/* | */docs/* | docs/*) exit 0 ;;
+esac
+
+content=$(jq -r '.tool_input.new_string // .tool_input.content // ""' <<<"$input")
+[ -z "$content" ] && exit 0
+
+violations=()
+
+grep -qE '@ts-ignore|@ts-nocheck' <<<"$content" && violations+=("@ts-ignore/@ts-nocheck forbidden (strict mode: fix the type error)")
+grep -qE 'eslint-disable' <<<"$content" && violations+=("eslint-disable forbidden (fix the source, not the linter)")
+grep -qE ':[[:space:]]*any\b|\bas[[:space:]]+any\b' <<<"$content" && violations+=("'any' type forbidden (use a precise type, unknown, or a generic)")
+grep -qE '\b(describe|it|test)\.skip\(|\bxit\(|\bxtest\(|\bxdescribe\(' <<<"$content" && violations+=("skipped tests forbidden (every test runs: fix or delete it)")
+
+if [ ${#violations[@]} -gt 0 ]; then
+  {
+    echo "CODE QUALITY VIOLATION in $file_path — fix before proceeding:"
+    for v in "${violations[@]}"; do echo "  - $v"; done
+  } >&2
+  exit 2
+fi
+
+exit 0

package/hooks/format-before-write.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# PreToolUse handler (Edit|Write): hands the tool prettier-formatted input.
+# The handler itself is dist/hooks/format-before-write.js (source:
+# src/hooks/format-before-write.ts); this names it beside the others, so a
+# hook list runs every handler as `bash "$SARATHI_HOOKS"/<name>.sh`.
+exec node "${BASH_SOURCE[0]%/*}/../dist/hooks/format-before-write.js"

package/hooks/format-on-edit.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# PostToolUse handler: formats every edited or written file with the session
+# checkout's prettier, so a commit-time format check finds nothing to fix.
+# Never blocks: formatting problems surface at commit time anyway.
+# format-before-write is the first line; this is the net for what it skips.
+
+input=$(cat)
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input")
+
+[ -z "$file_path" ] && exit 0
+[ -f "$file_path" ] || exit 0
+
+# Never format through a symlink. Only the leaf's PARENT is resolved below, so
+# a link sitting inside the checkout could otherwise name a target outside it
+# and be judged by where the link lives rather than what it rewrites.
+[ -L "$file_path" ] && exit 0
+
+# Skip local scratch and tmp artifacts: nothing there is ever committed.
+case "$file_path" in
+  */.local/* | .local/* | */.tmp/* | .tmp/*) exit 0 ;;
+esac
+
+# Skip anything outside this checkout. Agent memory is writable and is
+# markdown, so it would otherwise be reflowed by this repository's prettier
+# settings, which are not its own.
+#
+# Both sides are resolved PHYSICALLY (pwd -P) before comparing. A lexical
+# compare breaks whenever the checkout is reached through a symlink (on macOS
+# /tmp is /private/tmp), classifying a repository file as outside or a file
+# merely *named* under the repository as inside.
+#
+# "This checkout" is the SESSION's (hook input `cwd`), not
+# $CLAUDE_PROJECT_DIR: the desktop app sets that to the main checkout for a
+# worktree session, and every desktop worktree lies under main
+# (lib/session-root.sh).
+lib="$(dirname "$0")/lib/session-root.sh"
+# shellcheck source=lib/session-root.sh
+[ -r "$lib" ] && . "$lib" || exit 0
+repo_root=$(session_root "$input" "${CLAUDE_PROJECT_DIR:-$PWD}")
+repo_root=$(cd "$repo_root" && pwd -P) || exit 0
+file_dir=$(cd "$(dirname "$file_path")" 2>/dev/null && pwd -P) || exit 0
+case "$file_dir" in
+  "$repo_root" | "$repo_root"/*) ;;
+  *) exit 0 ;;
+esac
+
+# The session checkout's prettier; a fresh worktree has no node_modules until
+# its first install, so then the project checkout's. Either way it runs in the
+# session checkout, so that checkout's config and .prettierignore decide.
+prettier="$repo_root/node_modules/.bin/prettier"
+[ -x "$prettier" ] || prettier="${CLAUDE_PROJECT_DIR:-$repo_root}/node_modules/.bin/prettier"
+
+case "$file_path" in
+  *.ts | *.tsx | *.js | *.jsx | *.json | *.md | *.yml | *.yaml | *.css)
+    cd "$repo_root" && "$prettier" --write --ignore-unknown "$file_path" >/dev/null 2>&1 || true
+    ;;
+esac
+
+exit 0

package/hooks/lib/session-root.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Sourced by sarathi's shell handlers: which checkout is the session's.
+#
+# The Claude desktop app launches worktree sessions with
+# `--project-config-root <main checkout>`. Every hook then runs with its cwd
+# and $CLAUDE_PROJECT_DIR set to the MAIN checkout, so neither of those names
+# the checkout the session works in. The hook input's `cwd` still does.
+
+# session_root <hook-input-json> <fallback-dir>
+#   The git toplevel of the input's `cwd`; <fallback-dir> when the input has
+#   no usable `cwd` (absent, not a directory, not inside a work tree).
+session_root() {
+  local cwd root
+  cwd=$(jq -r 'if (.cwd | type) == "string" then .cwd else "" end' <<<"$1" 2>/dev/null) || cwd=""
+  if [ -n "$cwd" ] && [ -d "$cwd" ]; then
+    root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null) || root=""
+    if [ -n "$root" ]; then
+      printf '%s\n' "$root"
+      return 0
+    fi
+  fi
+  printf '%s\n' "$2"
+}
+
+# rel_to_root <path> <root>
+#   <path> relative to <root> when it lies inside it, else <path> unchanged.
+#   Compared physically: git prints a resolved toplevel (/private/tmp on
+#   macOS), the tools a logical path. Path filters must use this, because the
+#   desktop app's worktrees live under <main>/.claude/worktrees/ and an
+#   absolute path there always matches `*/.claude/*`.
+rel_to_root() {
+  local dir real_root base
+  dir=$(cd "$(dirname "$1")" 2>/dev/null && pwd -P) || { printf '%s\n' "$1"; return 0; }
+  real_root=$(cd "$2" 2>/dev/null && pwd -P) || { printf '%s\n' "$1"; return 0; }
+  base=$(basename "$1")
+  case "$dir" in
+    "$real_root") printf '%s\n' "$base" ;;
+    "$real_root"/*) printf '%s\n' "${dir#"$real_root"/}/$base" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}

package/hooks/session-dedupe-guard.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# PreToolUse handler: look before starting a session. Refuses create_session
+# and start_session unless this conversation called list_sessions, and got a
+# result that is not an error, in the last LOOK_WINDOW_MINUTES (two sessions
+# fixing the same bug minutes apart is what it stops). A hook cannot call
+# list_sessions itself, so it enforces the look, not the verdict.
+# start_session is judged only where the transcript records list_sessions as
+# available (a deferred-tools entry naming it, or a call to it), so a desktop
+# session without the tool is never stuck. Anything it cannot read (input,
+# transcript) is allowed.
+#
+# The input is read from stdin, so no size limit applies to it.
+# HOOK_PYTHON is the launcher's interpreter; python3 without one.
+
+PY_SRC=$(cat <<'PYEOF'
+import datetime, json, sys
+
+LOOK_WINDOW_MINUTES = 15
+LIST = "mcp__claude-code-remote__list_sessions"
+CREATE = "mcp__claude-code-remote__create_session"
+START = "mcp__ccd_session__start_session"
+
+try:
+    data = json.loads(sys.stdin.read() or "{}")
+    tool = data.get("tool_name")
+    path = data.get("transcript_path")
+    if tool not in (CREATE, START) or not path:
+        sys.exit(0)
+    with open(path) as handle:
+        lines = handle.readlines()
+except Exception:
+    sys.exit(0)
+
+calls, good, listed = {}, set(), False
+for line in lines:
+    try:
+        entry = json.loads(line)
+        record = entry.get("attachment") or {}
+        content = (entry.get("message") or {}).get("content")
+    except Exception:
+        continue
+    if isinstance(record, dict) and record.get("type") == "deferred_tools_record":
+        for tool_entry in record.get("entries") or []:
+            if isinstance(tool_entry, dict) and tool_entry.get("name") == LIST:
+                listed = True
+    if not isinstance(content, list):
+        continue
+    for item in content:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == "tool_use" and item.get("name") == LIST:
+            calls[item.get("id")] = entry.get("timestamp")
+        elif item.get("type") == "tool_result" and item.get("is_error") is not True:
+            good.add(item.get("tool_use_id"))
+
+# The tool is available when the transcript records it (a deferred-tools entry
+# naming it, or a call to it), not when some text merely mentions its name.
+if tool == START and not listed and not calls:
+    sys.exit(0)
+
+now = datetime.datetime.now(datetime.timezone.utc)
+for use_id, stamp in calls.items():
+    if use_id not in good or not isinstance(stamp, str):
+        continue
+    try:
+        when = datetime.datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+    except ValueError:
+        continue
+    if now - when <= datetime.timedelta(minutes=LOOK_WINDOW_MINUTES):
+        sys.exit(0)
+
+print(
+    "BLOCKED: before starting a session, look for one already doing this work: "
+    "call " + LIST + " (mine: true), read its titles, and start only if none "
+    "covers it; then retry. A look counts for " + str(LOOK_WINDOW_MINUTES)
+    + " minutes. Why: two sessions doing the same work duplicate it.",
+    file=sys.stderr,
+)
+sys.exit(2)
+PYEOF
+)
+exec "${HOOK_PYTHON:-python3}" -c "$PY_SRC"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/sarathi",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Runs a project's Claude Code hooks from one entry per event, with kavach's guards built in, and carries the sarathi plugin's agents.",
   "keywords": [
     "coding agents",
@@ -29,10 +29,11 @@
   },
   "files": [
     "dist",
+    "hooks",
     "!dist/**/*.test.js"
   ],
   "dependencies": {
-    "@veda-hq/kavach": "0.5.6"
+    "@veda-hq/kavach": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "24.19.2",
@@ -41,8 +42,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts --test-coverage-exclude=src/bin.ts src/**/*.test.ts",
-    "smoke": "node dist/bin.js --version && node dist/bin.js check --config test/fixture/sarathi.json --settings test/fixture/settings.json",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude=src/bin.ts 'src/**/*.test.ts'",
+    "smoke": "node dist/bin.js --version && node dist/bin.js check --config test/fixture/sarathi.json --settings test/fixture/settings.json && echo {} | bash hooks/format-before-write.sh",
     "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
   }
 }