Repository navigation
Expand file tree
/
Copy pathwrite-guard.js
More file actions
289 lines (274 loc) · 12.2 KB
/
Copy pathwrite-guard.js
File metadata and controls
289 lines (274 loc) · 12.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
#!/usr/bin/env node
// write-guard.js — PreToolUse hook (matchers: Edit, Write, legacy MultiEdit, NotebookEdit)
//
// PURPOSE
// Ship the PROTECT list in the plugin instead of re-adding an ALLOW list by
// hand to every repository's settings.local.json. Allow rules are inherently
// project-specific (one repo's sources live in `src/`, another's in `lib/`),
// so they drift per machine and per project and never generalize. The set of
// files where an unreviewed agent write actually costs something is the same
// in essentially every repository, which is what makes it shippable policy.
//
// This hook grants NOTHING. It forces a confirmation on writes to that
// protected set; everything else is silent passthrough, so the session's own
// permission mode still governs the ordinary case. Pair it with `acceptEdits`
// to remove routine friction while untracked agent instructions, permission
// config, the pre-commit gate and package metadata still stop you.
//
// SECURITY MODEL — deliberately the inverse of blueprint-allow.js
// blueprint-allow.js can safely emit "allow" because it has PROVENANCE: the
// exact command text came from a reviewed, versioned plugin file, so allowing
// it means "you already reviewed this". An Edit has no provenance — its
// content is arbitrary new code. So this hook never emits "allow"; auto-
// allowing writes by directory convention would just be acceptEdits with
// worse visibility. Guard, do not grant.
//
// WHAT IS PROTECTED, AND WHY THESE
// Only files that are (a) named identically across essentially every repo,
// and (b) costly when written without review: agent instructions (the file
// that tells the next agent what to do), Claude's own permission config, the
// pre-commit gate and package metadata.
// Source, tests, CI helper scripts, changelogs and lockfiles are deliberately
// NOT protected — that is the routine work, and a new file under `.github/`
// or a fresh CHANGELOG.md is untracked by nature, so asking on it only
// harassed edits to work the user had just requested.
//
// VERSION-CONTROLLED FILES PASS THROUGH
// A protected file already tracked by git (present in the index) is never
// gated: every write to it shows up in `git diff` and is revertible, which is
// the review the confirmation was standing in for. Asking on each tracked
// write only produced a per-edit prompt the user could never dismiss, since a
// hook "ask" is not remembered across calls. Untracked, new and gitignored
// protected files (e.g. `.claude/settings.local.json`) still ask — nothing
// else records or reverts a write to them. Any failure of the git probe (no
// git, not a repository, timeout) counts as untracked, so the guard keeps
// asking rather than silently opening.
//
// FILES THIS SESSION CREATED PASS THROUGH AFTER THE FIRST ASK
// A protected file that does not exist yet asks once and is recorded in a
// per-session ledger (`write-guard-created-<session id>` in the temp dir).
// Once the file exists and is in that ledger, later writes in the same
// session pass: re-asking on every edit of a file the user just approved
// creating only repeated the same answer. The ledger entry alone is not
// enough — a denied creation leaves the file absent, so the retry still asks.
// A protected file that already existed untracked was not made by this
// session and keeps asking on every write.
//
// Why dropping the tracked-file confirmation is safe for the two entries the
// hook once held back (`.claude/settings*.json`, `.pre-commit-config.yaml`):
// revertibility alone is not the argument. Claude Code itself prompts on
// writes to `.claude/` and `.pre-commit-config.yaml` in the default and
// acceptEdits modes (permission-modes docs, protected paths), whatever this
// hook does. Do not re-add an `always` flag on the grounds that git can undo
// the write — it can, and that was never the reason.
//
// UNVERIFIED PREMISE — carried deliberately
// "ask" is a documented permissionDecision value, but whether it overrides an
// already-auto-approving permission mode (acceptEdits / an allow rule) is not
// stated in the docs section, which truncates there. If it does NOT override,
// this hook degrades to a silent no-op — it never false-blocks. Settle it live:
// in a default-permission session with acceptEdits on, create a new untracked
// `docs/AGENTS.md` (not a natively protected path, and not tracked by git) and
// look for a prompt carrying this hook's permissionDecisionReason. No prompt
// means "ask" does not override, and the decision has to become "deny".
//
// EXIT CODES
// 0 always — passthrough (no output) or a decision on stdout. Never crashes
// the session, matching every other hook in this plugin.
"use strict";
const fs = require("fs");
const os = require("os");
const path = require("path");
const { spawnSync } = require("child_process");
const GUARDED_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
// Matched against the POSIX-normalized path. Windows hosts hand us backslashes,
// so every pattern assumes "/" and the caller normalizes first — a separator
// mismatch would silently disable the whole guard on one OS.
// Anchored with `(^|\/)` so a path merely CONTAINING the name never matches:
// `src/my_changelog_helper.py` and `src/github/client.py` stay routine work.
// Case-INSENSITIVE by design: macOS and Windows filesystems are case-folding, so
// a write addressed as `changelog.md` lands in the real `CHANGELOG.md`. Under a
// case-sensitive matcher that path classifies as unprotected, and passthrough
// means auto-approved whenever the hook is paired with acceptEdits — the exact
// configuration it exists for. The cost is a false ask on case-sensitive Linux
// for a genuinely distinct `docs/claude.md`; one extra confirmation is the
// cheaper side of that trade.
const PROTECTED = [
{ re: /(^|\/)CLAUDE\.md$/i, why: "agent instructions" },
{ re: /(^|\/)AGENTS\.md$/i, why: "agent instructions" },
{ re: /(^|\/)\.claude\/settings(\.local)?\.json$/i, why: "Claude permission config" },
{ re: /(^|\/)\.pre-commit-config\.yaml$/i, why: "lint/format gate" },
{ re: /(^|\/)pyproject\.toml$/i, why: "package/release metadata" },
];
/**
* Normalize a filesystem path to POSIX separators for pattern matching.
*
* @param {string} p Raw path from tool_input.
* @returns {string} Path with "/" separators.
*/
function toPosix(p) {
return String(p).replace(/\\/g, "/");
}
/**
* Classify a path against the protected set.
*
* @param {string} filePath Raw path from tool_input.
* @returns {{why: string}|null} Match reason, or null when unprotected.
*/
function classify(filePath) {
if (!filePath) return null;
const posix = toPosix(filePath);
for (const entry of PROTECTED) {
if (entry.re.test(posix)) return { why: entry.why };
}
return null;
}
/**
* Check whether git tracks the file, so a write to it stays diffable and revertible.
*
* Runs from the file's own directory so a nested repository or a path outside
* the session cwd resolves against the repository that actually owns it.
* `--literal-pathspecs` keeps a name such as `:x` or `*.md` from being read as
* pathspec magic or a glob that could match some other tracked file.
*
* @param {string} filePath Raw path from tool_input.
* @param {string} [cwd] Session cwd from the hook payload; relative paths resolve against it.
* @returns {boolean} True only when git confirms the file is in the index.
*/
function isTracked(filePath, cwd) {
const abs = path.resolve(cwd || process.cwd(), filePath);
const res = spawnSync(
"git",
["--literal-pathspecs", "-C", path.dirname(abs), "ls-files", "--error-unmatch", "--", path.basename(abs)],
{ stdio: "ignore", timeout: 3000, windowsHide: true },
);
return res.status === 0;
}
/**
* Locate the per-session ledger of protected files this session first asked to create.
*
* The session id comes from the hook payload so two concurrent sessions never share a ledger; the name ends in
* `-<id>` per the repository sentinel convention.
*
* @param {object} data Parsed hook payload.
* @returns {string} Ledger file path.
*/
function ledgerPath(data) {
const raw = data.session_id || process.env.CSID || process.env.CLAUDE_CODE_SESSION_ID || "shared";
const sid = String(raw).replace(/[^A-Za-z0-9_-]/g, "_");
return path.join(process.env.TMPDIR || os.tmpdir(), `write-guard-created-${sid}`);
}
/**
* Check whether a path exists, a dangling symlink included.
*
* `lstat` rather than `stat`: a dangling symlink to a protected file elsewhere must read as existing, or a write
* through it would count as a creation.
*
* @param {string} abs Absolute path.
* @returns {boolean} True when anything occupies the path.
*/
function occupied(abs) {
try {
fs.lstatSync(abs);
return true;
} catch (_) {
return false;
}
}
/**
* Resolve aliases even when the final file does not exist yet.
*
* @param {string} abs Absolute target path.
* @param {number} [depth] Symlink and missing-parent traversal bound.
* @returns {string} Resolved path, or the original path when resolution is unavailable.
*/
function resolvedTarget(abs, depth = 0) {
if (depth > 40) return abs;
try {
return fs.realpathSync(abs);
} catch (_) {}
try {
if (fs.lstatSync(abs).isSymbolicLink()) {
return resolvedTarget(path.resolve(path.dirname(abs), fs.readlinkSync(abs)), depth + 1);
}
} catch (_) {}
const parent = path.dirname(abs);
return parent === abs ? abs : path.join(resolvedTarget(parent, depth + 1), path.basename(abs));
}
/**
* Check whether this session earlier asked to create the file, which now exists.
*
* Both halves are needed: a ledger entry alone would let a denied creation retry without a prompt, and existence
* alone says nothing about who made the file. Any read failure counts as not created, so the guard keeps asking.
*
* @param {string} abs Absolute path of the target.
* @param {object} data Parsed hook payload.
* @returns {boolean} True when the file is a product of this session.
*/
function createdThisSession(abs, data) {
if (!occupied(abs)) return false;
try {
const key = JSON.stringify(abs);
return fs.readFileSync(ledgerPath(data), "utf8").split("\n").includes(key);
} catch (_) {
return false;
}
}
/**
* Record that this session asked to create a not-yet-existing protected file; a failed write only loses the record.
*
* @param {string} abs Absolute path of the target.
* @param {object} data Parsed hook payload.
*/
function recordCreation(abs, data) {
try {
fs.appendFileSync(ledgerPath(data), `${JSON.stringify(abs)}\n`);
} catch (_) {
// unwritable temp dir → later edits ask again; never block the session
}
}
/**
* Build the hook decision for one tool call, or null for passthrough.
*
* `notebook_path` is read alongside `file_path` because NotebookEdit names its
* target differently; without it that matcher would ship unguarded.
*
* @param {object} data Parsed hook payload.
* @returns {object|null} hookSpecificOutput envelope, or null.
*/
function decide(data) {
if (!data || !GUARDED_TOOLS.has(data.tool_name)) return null;
const input = data.tool_input || {};
const target = input.file_path || input.notebook_path;
if (!target) return null;
const addressed = path.resolve(data.cwd || process.cwd(), target);
const abs = resolvedTarget(addressed);
const hit = classify(target) || classify(abs);
if (!hit) return null;
if (isTracked(abs, data.cwd)) return null;
if (createdThisSession(abs, data)) return null;
if (!occupied(addressed) && !occupied(abs)) recordCreation(abs, data);
return {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "ask",
permissionDecisionReason: `protected file (${hit.why}) — confirm this write`,
},
};
}
module.exports = { classify, decide, isTracked, createdThisSession, toPosix, PROTECTED, GUARDED_TOOLS };
if (require.main === module) {
let raw = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (c) => (raw += c));
process.stdin.on("end", () => {
let out = null;
try {
out = decide(JSON.parse(raw));
} catch (_) {
out = null; // malformed payload → passthrough, never block
}
if (out) process.stdout.write(JSON.stringify(out));
process.exit(0);
});
}