scope-guard
Scope Guard
guardcommandtoastprocess
Scope Guard
Local Claude Code mod. Install: claude plugin install scope-guard@my-claude-code-mods --scope user, then reload plugins.
Allowed-path warnings with rename and pre-existing-change awareness.
/scope help
/scope [allow <path> | list | reset]
/scope resetReports are returned as command text, usable in terminal/Desktop/headless sessions. State is isolated by cwd and session ID in the plugin store; resuming the same identity restores it. Reset clears this mod's records only. Observations never block tools or execute commands twice. No network calls. Obvious secrets and terminal escapes are masked before storage/display; masking is best effort.
First release: see design for exact analysis limits. Git commands have a 10-second timeout. Lists cap at 200 entries and repository scans at 2,000 paths / 2 MiB; incomplete evidence is reported. Commands use explicit data entry; no model inference or automatic source editing. Actual engine tests cover command behavior and forwarding; live terminal/Desktop pixels have not been checked.
Development: npm test, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test scope-guard, npx tsc -p scope-guard. Engine typechecking needs local ignored declarations. Canonical runtime sources are in scripts/workflow/; run node scripts/sync-workflow.mjs after editing.
/scope allow src/auth
/scope allow tests/auth
/scope listWarnings only; no tool is blocked. Scope entries use literal file/directory boundaries, not globs. Baselines and displayed paths cap at 200; a capped baseline is reported as incomplete. Run Git analysis from the repository root.
Local preview before marketplace publication: claude --plugin-dir ./scope-guard from this checkout. Engine tests were run with Claude Code 2.1.302.
Records successful Write/Edit/MultiEdit/NotebookEdit targets and reports paths outside configured scope; it never blocks those tools.
The command.run hook answers only /scope with local report/control text. It does not intercept unrelated slash commands. The tool.call hook forwards each original event once and returns its outcome unchanged; observer failures do not retry a tool. No tool.check, permission-mode or Remote Control override is installed.
The following complete argv templates describe every program launched with process.run. Each item is an argument array passed directly to the host, with no shell command parsing. <cwd>/<repo> are the current project or Git root, <base> is the validated selected ref, <manifest> is package.json or package-lock.json, and <path> is a selected project file. [--cached] denotes two fixed variants, with and without that argument. Every call has a 10-second timeout.
git -C <cwd> status --porcelain=v1 -z --untracked-files=allOnly git is accepted by this adapter's process bridge. Dynamic path/ref arguments are project evidence, not scripts fetched from a server. These Git commands query local history, status and diffs; none is fetch, push, install or a shell interpreter. Other features' version/environment/replay bridges are absent from this mod.
This mod makes no tool.call of its own. The common Bash-replay implementation is not included in its generated adapter; observing/forwarding an existing tool call does not create another call.
There are no HTTP requests, telemetry destinations or automatic uploads in this feature. Local read results support analysis/fingerprints and local report text; masked feature records go only to the plugin store under the current cwd/session identity. No project build, startup, settings or instruction files are edited. User/agent tool calls that are forwarded retain their independent behavior and destinations.
For review: String.raw/regular-expression literals in the redactor are string-pattern data, never a shell program. Template literals beginning # format record numbers. constructor names ordinary TypeScript class initialization. These are not credential reads or command execution. Runtime command access is limited to the concrete cases documented above.
The session cwd and user-selected base ref/path scope are used to query the local Git root and changed path names. This adapter has no direct filesystem reader.
The destination of process.run is the local Git executable. Its argv contains the documented Git subcommand/options and local project paths or selected refs, with the session cwd as the working directory. File contents are not inserted into shell code, sent as stdin, or posted to a server by this adapter. Git reads the repository locally and returns stdout/stderr for this analysis. Reports return to the local slash-command caller; persisted feature records go to this plugin’s local cwd/session-scoped store. This mod has no HTTP upload, remote recipient, server-provided command source or own tool replay. It forwards independently requested tool calls once; any network activity of those calls belongs to their original inputs and permissions. The program list above describes what the mod requests; installed executables and user/system configuration retain their own capabilities.
hooks/register.ts 77 lines1import type { EngineInterface, Register } from 'claude-code'
2import { object, revision, safeText, safeData, reportText, type Observation, type Port } from './core/runtime.ts'
3export interface Model { data: object; command(args: string, io: Port): Promise<string>; observe?(event: Observation, io: Port): Promise<void> }
4import { Feature } from './core/feature.ts'
5const name = 'scope-guard'
6const command = 'scope'
7type AdapterState = { queue: Promise<unknown>; replaying: boolean }
8const state: AdapterState = { queue: Promise.resolve(), replaying: false }
9const observesTools = 'observe' in Feature.prototype
10const serial = <T>(fn: () => Promise<T>): Promise<T> => {
11 const work = state.queue.then(fn); state.queue = work.catch(() => {}); return work
12}
13const port = async ($: EngineInterface): Promise<Port> => {
14 const cwd = await $.session.cwd()
15 const unavailable = async (): Promise<never> => { throw new Error('Capability not used by this feature') }
16 const io: Port = { cwd, read: unavailable, run: unavailable, env: unavailable, revision: async () => undefined }
17 io.run = argv => {
18 if (argv[0] !== 'git') throw new Error('Only local Git evidence commands are supported')
19 return $.process.run(['git', ...argv.slice(1)], { cwd, timeoutMs: 10_000 })
20 }
21 return io
22}
23const identity = ($: EngineInterface) => Promise.all([$.session.cwd(), $.session.id()])
24const transact = async ($: EngineInterface, fn: (model: Model, io: Port) => Promise<string | void>, expected: string[], forceSave = false): Promise<string> => serial(async () => {
25 const [io, id] = await Promise.all([port($), $.session.id()])
26 if (io.cwd !== expected[0] || id !== expected[1]) return 'Session changed; operation not applied'
27 const key = `${name}:v1:${JSON.stringify([io.cwd, id])}`
28 const raw = await $.store.get(key)
29 const loaded = await identity($)
30 if (loaded[0] !== expected[0] || loaded[1] !== expected[1]) return 'Session changed; operation not applied'
31 const model = new Feature(raw)
32 const previous = JSON.stringify(safeData(model.data))
33 const result = await fn(model, io)
34 // No raw event payloads reach storage. Keep the serialized state bounded.
35 const serialized = JSON.stringify(safeData(model.data))
36 if (forceSave || serialized !== previous) {
37 if (serialized.length > 256 * 1024) throw new Error('state limit exceeded; not saved')
38 try { await $.store.set(key, JSON.parse(serialized)) }
39 catch { throw new Error('state not saved; retry after storage recovers') }
40 }
41 return reportText(result ?? '')
42})
43export const register: Register = on => {
44 on('session.start', async ($, e, next) => {
45 try { await $.command.register({ name: command, description: `${name}: /${command} help` }) } catch { /* Startup still forwards. */ }
46 return next(e)
47 })
48 on('command.run', { command }, async ($, e) => {
49 try {
50 const expected = await identity($)
51 return { text: await transact($, async (model, io) => {
52 if ((e.args ?? '').trim() === 'reset') { model.data = new Feature().data; return `${name}: records reset` }
53 return model.command(e.args ?? '', io)
54 }, expected, (e.args ?? '').trim() === 'reset') } } catch (error) { return { text: `${name}: ${safeText(error instanceof Error ? error.message : error)}` } }
55 })
56 on('tool.call', async ($, e, next) => {
57 const ownReplay = state.replaying && (next.origin?.plugin === name || next.origin?.plugin.startsWith(name + '@'))
58 if (!observesTools || ownReplay) return next(e)
59 const expected = await identity($).catch(() => undefined)
60 let before: string | undefined
61 if (['verify-board', 'handoff-pack'].includes(name) && e.tool === 'Bash') {
62 try { before = await (await port($)).revision() } catch { /* Unknown evidence. */ }
63 }
64 // next runs outside observation catch: an observer never retries a tool or hides its exception.
65 const result = await next(e)
66 try {
67 const now = await Promise.all([$.session.cwd(), $.session.id()])
68 if (!expected || expected[0] !== now[0] || expected[1] !== now[1]) return result
69 await transact($, async (model, io) => {
70 const after = before !== undefined ? await io.revision() : undefined
71 await model.observe?.({ tool: e.tool, input: object(e), result, before, after }, io)
72 }, expected)
73 } catch { try { $.ui.toast(`${name}: observation not saved`) } catch { /* Noninteractive host. */ } }
74 return result
75 })
76}
77hooks/core/runtime.ts 132 lines1import { redactSecrets } from './redact.ts'
2export type ProcessResult = { exitCode: number; stdout: string; stderr: string; isStdoutTruncated?: boolean; isStderrTruncated?: boolean }
3export type Port = {
4 cwd: string
5 read(path: string): Promise<string>
6 bytes?(path: string): Promise<string>
7 stat?(path: string): Promise<{ isLink: boolean }>
8 list?(path: string): Promise<string[]>
9 run(argv: readonly string[]): Promise<ProcessResult>
10 env(name: string): Promise<string | undefined>
11 revision(): Promise<string | undefined>
12 replay?(command: string): Promise<unknown>
13}
14export type Observation = { tool: string; input: Record<string, unknown>; result: unknown; before?: string; after?: string }
15export function object(v: unknown): Record<string, unknown> { return v !== null && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {} }
16export function safeText(v: unknown, limit = 4000): string {
17 const text = String(v ?? '').replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '')
18 // Some masking patterns backtrack on very long words. Omit an oversized line whole:
19 // cutting it first could expose an unterminated quoted secret.
20 const lines = text.split('\n')
21 // Dropping a credential's opening line could expose its quoted continuation.
22 if (lines.some(line => line.length > 8192 && /["'\\]|password|passwd|pwd|token|key|secret|authorization|credential|cookie/i.test(line))) return '[OMITTED: oversized sensitive value]'
23 return redactSecrets(lines.map(line => line.length > 8192 ? '[OMITTED: oversized line]' : line).join('\n')).slice(0, limit)
24}
25export function hash(text: string): string {
26 return [0, 0x9747b28c].map(seed => {
27 let h = (0x811c9dc5 ^ seed) >>> 0
28 for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
29 return (h >>> 0).toString(16).padStart(8, '0')
30 }).join('')
31}
32export function relativePath(root: string, path: string): string | undefined {
33 const normalize = (p: string) => {
34 const parts: string[] = []
35 for (const s of p.replace(/\\/g, '/').split('/')) {
36 if (!s || s === '.') continue
37 if (s === '..') { if (!parts.length) return undefined; parts.pop() } else parts.push(s)
38 }
39 return parts.join('/')
40 }
41 const base = normalize(root); if (base === undefined) return undefined
42 const full = normalize(path.startsWith('/') ? path : `${root}/${path}`)
43 if (full === undefined) return undefined
44 if (base === '') return root.startsWith('/') ? full : undefined
45 if (!(full === base || full.startsWith(base + '/'))) return undefined
46 return full.slice(base.length).replace(/^\//, '')
47}
48export function changedPaths(status: string): string[] {
49 const entries = status.split('\0'); const paths: string[] = []
50 for (let i = 0; i < entries.length; i++) {
51 const line = entries[i]!; if (line.length < 4) continue
52 paths.push(line.slice(3))
53 if (/[RC]/.test(line.slice(0, 2)) && entries[i + 1]) paths.push(entries[++i]!)
54 }
55 return [...new Set(paths)]
56}
57export async function git(io: Port, args: string[]): Promise<string> {
58 const r = await io.run(['git', '-C', io.cwd, ...args])
59 if (r.exitCode !== 0 || r.isStdoutTruncated || r.isStderrTruncated) throw new Error('Git evidence unavailable or incomplete')
60 if (r.stdout.length > 2 * 1024 * 1024) throw new Error('Git evidence exceeds 2 MiB limit')
61 return r.stdout
62}
63export async function statusPaths(io: Port): Promise<string[]> { return changedPaths(await git(io, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])) }
64export async function revision(io: Port): Promise<string | undefined> {
65 try {
66 const root = (await git(io, ['rev-parse', '--show-toplevel'])).replace(/\n$/, '')
67 if (!root.startsWith('/')) return undefined
68 const repo = { ...io, cwd: root }
69 const head = await git(repo, ['rev-parse', '--verify', 'HEAD'])
70 const diff = await git(repo, ['diff', '--no-ext-diff', '--no-textconv', '--binary', '--ignore-submodules=none', 'HEAD', '--'])
71 const staged = await git(repo, ['diff', '--no-ext-diff', '--no-textconv', '--binary', '--ignore-submodules=none', '--cached', 'HEAD', '--'])
72 if (/^\+Subproject commit [a-f0-9]+-dirty$/m.test(diff) || /^\+Subproject commit [a-f0-9]+-dirty$/m.test(staged)) return undefined
73 const status = await git(repo, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'])
74 const paths = (await git(repo, ['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean).sort()
75 if (paths.length > 200) return undefined
76 const bodies: string[] = [head, diff, staged, status]; let size = diff.length + staged.length + status.length
77 for (const path of paths) {
78 if (relativePath(root, path) !== path || (io.stat && (await io.stat(`${root}/${path}`)).isLink)) return undefined
79 const body = await (io.bytes ?? io.read)(`${root}/${path}`); size += body.length
80 if (size > 2 * 1024 * 1024) return undefined
81 bodies.push(path, body)
82 }
83 return hash(JSON.stringify(bodies))
84 } catch { return undefined }
85}
86export function outcome(result: unknown): 'pass' | 'fail' | 'unknown' {
87 const a = object(result), r = object(a.result)
88 if (a.deny !== undefined) return 'unknown'
89 for (const v of [a, r]) {
90 if (['interrupted', 'cancelled', 'canceled', 'timedOut', 'timed_out', 'truncated', 'output_truncated', 'isStdoutTruncated', 'isStderrTruncated', 'backgroundedByUser', 'backgroundedByTurnAbort', 'backgroundedToDeliverMessage'].some(k => v[k] === true)) return 'unknown'
91 if (['task_id', 'taskId', 'backgroundTaskId', 'background_task_id', 'timedOutAfterMs', 'rawOutputPath', 'persistedOutputPath'].some(k => v[k] !== undefined && v[k] !== null && v[k] !== '')) return 'unknown'
92 }
93 if (a.isError === true) return 'fail'
94 const text = [a.text, r.stdout, r.stderr].filter((v): v is string => typeof v === 'string').join('\n').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
95 if (text.length > 65_536) return 'unknown'
96 if (/^# fail [1-9]\d*\s*$/m.test(text) || /^\s*Tests(?::|\s+)[^\n]*\b[1-9]\d* failed\b/m.test(text) || /^=+[^\n]*\b[1-9]\d* (?:failed|errors?)\b/m.test(text) || /^test result: FAILED\./m.test(text) || /^\s*--- FAIL: /m.test(text)) return 'fail'
97 const code = 'exitCode' in r ? r.exitCode : r.exit_code
98 if ('exitCode' in r || 'exit_code' in r) return typeof code === 'number' && Number.isInteger(code) ? code === 0 ? 'pass' : 'fail' : 'unknown'
99 // Builtin Bash exposes tool failure via isError and foreground completion via interrupted/streams, not exitCode.
100 return typeof r.stdout === 'string' && typeof r.stderr === 'string' && r.interrupted === false ? 'pass' : 'unknown'
101}
102export function isCheck(command: string): boolean {
103 if (/^(?:npx\s+)?vitest\b.*\slist(?:\s|$)/.test(command.trim())) return false
104 // Known introspection-only options do not run the check itself.
105 if (/(?:^|\s)(?:--help|-h|--version|-V|--collect-only|--co|--listTests|--list-tests|--showConfig|--show-config|--list|-list)(?:\s|=|$)/.test(command)) return false
106 // Conservative whole-command allowlist; compound shell programs are not proof of a check.
107 return /^(?:(?:npm|pnpm|yarn) (?:run )?(?:test(?::[\w-]+)?|typecheck|lint)|npx (?:tsc|vitest|jest|eslint)|(?:pytest|vitest|jest|tsc|eslint)|cargo (?:test|check|clippy)|go test)\b[^;&|<>\n]*$/.test(command.trim())
108}
109export function restore<T extends object>(value: unknown, defaults: T): T {
110 const v = object(value); const out = { ...defaults } as Record<string, unknown>
111 for (const [k, fallback] of Object.entries(defaults)) {
112 const item = v[k]
113 if (Array.isArray(fallback) ? Array.isArray(item) : typeof item === typeof fallback && item !== null) out[k] = item
114 }
115 return out as T
116}
117export const entries = (args: string): string[] => args.split('|').map(s => s.trim())
118export function bounded<T>(items: T[]): T[] { return items.slice(-200) }
119// Clean string leaves before JSON serialization, never regex-rewrite serialized JSON syntax.
120export function safeData(value: unknown): unknown {
121 if (typeof value === 'string') return safeText(value)
122 if (Array.isArray(value)) return value.map(safeData)
123 if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, safeData(v)]))
124 return value
125}
126
127export function reportText(value: unknown): string {
128 const limit = 32 * 1024, notice = '\nINCOMPLETE: report truncated; filter or inspect smaller groups.'
129 const text = safeText(value, limit + 1)
130 return text.length > limit || String(value ?? '').length > limit ? text.slice(0, limit - notice.length) + notice : text
131}
132hooks/core/feature.ts 28 lines1import { bounded, object, relativePath, restore, safeText, statusPaths, type Observation, type Port } from './runtime.ts'
2export class Feature {
3 data: { allowed: string[]; baseline: string[]; baselineIncomplete: boolean; writes: string[] }
4 constructor(value?: unknown) { this.data = restore(value, { allowed: [] as string[], baseline: [] as string[], baselineIncomplete: false, writes: [] as string[] }) }
5 async observe(e: Observation, io: Port): Promise<void> {
6 if (!['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(e.tool) || object(e.result).deny !== undefined || object(e.result).isError === true) return
7 const target = e.input.file_path ?? e.input.notebook_path
8 if (typeof target === 'string') this.data.writes = bounded([...new Set([...this.data.writes, safeText(relativePath(io.cwd, target) ?? target)])])
9 }
10 async command(args: string, io: Port): Promise<string> {
11 const parsed = /^(\S+)(?:\s+([\s\S]*))?$/.exec(args.trim())
12 const verb = parsed?.[1] ?? '', path = parsed?.[2] ?? ''
13 if (verb === 'allow') {
14 const rel = relativePath(io.cwd, path)
15 if (!path || rel === undefined || /(^|\/)\.\.(\/|$)/.test(path)) return 'Invalid project-relative scope path'
16 if (!this.data.allowed.length) { const baseline = await statusPaths(io); this.data.baseline = bounded(baseline); this.data.baselineIncomplete = baseline.length > 200 }
17 this.data.allowed = bounded([...new Set([...this.data.allowed, rel || '.'])])
18 } else if (verb === 'help') return '/scope [allow <path> | list | reset] — warnings only, existing changes labelled; . allows the project.'
19 else if (verb && verb !== 'list') return 'Usage: /scope [allow <path> | list | reset]'
20 if (!this.data.allowed.length) return 'Scope Guard: No scope configured. /scope allow <path>'
21 const paths = [...new Set([...await statusPaths(io), ...this.data.writes])]
22 return ['Scope Guard — allowed: ' + this.data.allowed.join(', '), ...paths.slice(0, 200).map(path => {
23 const allowed = this.data.allowed.some(a => a === '.' ? relativePath(io.cwd, path) !== undefined : path === a || path.startsWith(a + '/'))
24 return `${this.data.baseline.includes(path) && !this.data.writes.includes(path) ? 'PRE-EXISTING' : allowed ? 'IN-SCOPE' : this.data.baselineIncomplete && !this.data.writes.includes(path) ? 'BASELINE-UNKNOWN' : 'OUTSIDE'} ${safeText(path)}`
25 }), ...(this.data.baselineIncomplete ? ['INCOMPLETE: pre-existing baseline exceeded 200 paths; unrecorded original changes cannot be distinguished'] : []), ...(paths.length > 200 ? ['INCOMPLETE: more than 200 changed paths'] : [])].join('\n')
26 }
27}
28hooks/core/redact.ts 31 lines1// Canonical source; run node scripts/sync-redactors.mjs after editing.
2// Best-effort removal of obvious secrets from command lines before they are exported.
3const VALUE = String.raw`("(?:\\[\s\S]|[^"\\])*"|'[^']*'|(?:\\[\s\S]|[^\s'"\\])+)`
4const HEADER = String.raw`(?:authorization|[a-z0-9][a-z0-9-]*-(?:key|token|secret))`
5// Only match user:password arguments, leaving username-only options (e.g. mysql -u) alone.
6const CREDENTIAL = String.raw`("(?:\\[\s\S]|[^":\\])*:(?:\\[\s\S]|[^"\\])*"|'[^':]*:[^']*'|[^\s'":]*:[^\s'"]*)`
7const RULES: [RegExp, string][] = [
8 // Shell-quoted headers must be handled before key/value rules: an escaped quote is
9 // part of the secret, while the opposite quote is ordinary data inside this shell word.
10 [new RegExp(String.raw`("` + HEADER + String.raw`\s*:\s*)(?:\\[\s\S]|[^"\\])*"`, 'gi'), '$1[REDACTED]"'],
11 [new RegExp(String.raw`('` + HEADER + String.raw`\s*:\s*)[^']*'`, 'gi'), "$1[REDACTED]'"],
12 [new RegExp(String.raw`(\b` + HEADER + String.raw`\s*:\s*)(?:\\[\s\S]|[^'"\r\n\\])+`, 'gi'), '$1[REDACTED]'],
13 [new RegExp(String.raw`((?:["']?)(?:password|passwd|pwd|token|(?:access|refresh|id|session|auth)[_-]?token|(?:api|access|secret|private)[_-]?key|client[_-]?secret|secret|authorization|credentials?|cookies?)(?:["']?)\s*:\s*)` + VALUE, 'gi'), '$1[REDACTED]'],
14 [/(\bbearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1[REDACTED]'],
15 [new RegExp(String.raw`(--(?:password|token|api-key|secret)(?:=|\s+))` + VALUE, 'gi'), '$1[REDACTED]'],
16 [/([a-z][a-z0-9+.-]*:\/\/[^\s/:@'"]*:)[^\s/@'"]*@/gi, '$1[REDACTED]@'],
17 [new RegExp(String.raw`(\s(?:--user(?:=|\s+)|-u\s*))` + CREDENTIAL, 'g'), '$1[REDACTED]'],
18 [/(\bmysql\w*\b[^\n;&|]*?\s-p)(?=\S)("[^"]*"|'[^']*'|\S+)/g, '$1[REDACTED]'],
19 [new RegExp(String.raw`\b([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z0-9_]*)=` + VALUE, 'gi'), '$1=[REDACTED]'],
20]
21
22export function redactSecrets(text: string): string {
23 return RULES.reduce((out, [pattern, replacement]) => out.replace(pattern, replacement), text)
24}
25
26// Match complete key names, including common camelCase/underscore/hyphen spellings.
27// Do not match ordinary names such as token_count or keyboard.
28export function isSecretKey(key: string): boolean {
29 return /^(?:password|passwd|pwd|authorization|proxyauthorization|apikey|accesskey|secretkey|privatekey|clientsecret|secret|token|accesstoken|refreshtoken|idtoken|sessiontoken|authtoken|credential|credentials|cookie|setcookie)$/i.test(key.replace(/[_\s-]/g, '')) || /^[a-z0-9][a-z0-9-]*-(?:key|token|secret)$/i.test(key)
30}
31