makarasty-tools

1import type { Register } from 'claude-code'
2import { register as router } from './router.ts'
3import { register as gitGuard } from './git-guard.ts'
4import { register as reads } from './reads.ts'
5
6// The engine loads one hooks module per plugin: this is it.
7export const register: Register = (on, options) => {
8  router(on, options)
9  gitGuard(on, options)
10  reads(on, options)
11}
12

1import type { Register } from 'claude-code'
2
3// Picks a cheaper model for a subagent only where the caller says it is safe.
4// Untagged work keeps the parent's model: on three replayed ports Sonnet tied twice
5// and once closed a task the shell left open, which its own tests did not catch [M39].
6export type Route = { to?: 'sonnet' | 'haiku'; why: string }
7
8export type SpawnFacts = {
9  model?: string
10  parentModel: string
11  subagentType: string
12  description: string
13  plugin: string
14  builtIn: boolean
15  workflow: boolean
16  fork: boolean
17}
18
19const TOP = /opus|fable/i
20// The fleet's own coder and reviewer: their prompt carries the task file, so a tag is as safe as on general-purpose
21// for the coder; the reviewer is the check, so it is never routed down.
22const FLEET = /^(makarasty:)?fleet-(coder|reviewer)$/
23
24export function route(f: SpawnFacts): Route {
25  if (f.model) return { why: 'model named' }
26  // provider.plugin may carry the marketplace (makarasty@...): only the name before it is checked.
27  const fleet = /^makarasty(@|$)/.test(f.plugin) && FLEET.test(f.subagentType)
28  if ((!f.builtIn && !fleet) || f.workflow || f.fork) return { why: 'not a plain built-in spawn' }
29  if (!TOP.test(f.parentModel)) return { why: 'parent below the top tier' }
30  if (f.subagentType === 'Explore') return { to: 'haiku', why: 'locator' }
31  if (f.subagentType !== 'general-purpose' && !fleet) return { why: 'other agent' }
32  // The reviewer is the independent check that makes a tag safe, so it keeps the parent's model [M41].
33  if (fleet && /fleet-reviewer$/.test(f.subagentType)) return { why: 'reviewer is the check' }
34  if (/^\s*\[mech\]/i.test(f.description)) return { to: 'haiku', why: 'tagged mech' }
35  if (/^\s*\[exec\]/i.test(f.description)) return { to: 'sonnet', why: 'tagged exec' }
36  return { why: 'untagged' }
37}
38
39type Stats = { routed: Record<string, number>; kept: Record<string, number>; last: string[] }
40
41export const register: Register = on => {
42  // Parallel spawns would each read the old stats and overwrite each other: one writer at a time.
43  let writes = Promise.resolve()
44  // A user's own Explore.md or general-purpose.md also reports provider "engine"; only the offer says where it came from.
45  const ownNames = new Set<string>()
46  on('agent.offer', ($, e, next) => {
47    if (e.source !== 'built-in') ownNames.add(e.agent)
48    return next(e)
49  })
50  on('agent.spawn', async ($, e, next) => {
51    if ((await $.env.get('MAKARASTY_ROUTER')) === 'off') return next(e)
52    const r = route({
53      model: e.model,
54      parentModel: e.parentModel,
55      subagentType: e.subagentType,
56      description: e.description,
57      plugin: e.provider.plugin,
58      builtIn: e.provider.plugin === 'engine' && !ownNames.has(e.subagentType),
59      workflow: e.workflow !== undefined,
60      fork: e.fork,
61    })
62    const line = `${new Date().toISOString().slice(0, 16)} ${r.to ?? 'keep'} (${r.why}) ${e.subagentType}: ${e.description}`
63    writes = writes.then(async () => {
64      const s = ((await $.store.get('stats')) as Stats | undefined) ?? { routed: {}, kept: {}, last: [] }
65      if (r.to) s.routed[r.to] = (s.routed[r.to] ?? 0) + 1
66      else s.kept[r.why] = (s.kept[r.why] ?? 0) + 1
67      s.last = [line, ...s.last].slice(0, 50)
68      await $.store.set('stats', s)
69    }).catch(() => {})
70    return next(r.to ? { ...e, model: r.to } : e)
71  }).catch(($, e, next) => next(e))
72
73  on('session.start', async ($, e, next) => {
74    await $.command.register({ name: 'router', description: 'What the model router changed: counts and the last 50 spawns' })
75    return next(e)
76  })
77
78  on('command.run', { command: 'router' }, async $ => {
79    const s = (await $.store.get('stats')) as Stats | undefined
80    if (!s) return { text: 'The router has not seen a spawn yet.' }
81    return { text: `routed ${JSON.stringify(s.routed)}, kept ${JSON.stringify(s.kept)}\n${s.last.join('\n')}` }
82  })
83}
84

1import type { Register } from 'claude-code'
2
3// Refuses git commands that throw away uncommitted work. Several sessions often share one working tree, so
4// "my changes" is never all the changes: a stash once wiped 171 files of other sessions' work. A function
5// hook, so the check is a few regexes inside the engine and no shell call pays a process for it.
6// Allowed on purpose: commit, branch switch without force, reset (mixed/soft), stash list/show, clean -n,
7// restore --staged, push --force-with-lease. The person can still run anything themselves with `!`.
8type Rule = [RegExp | ((s: string) => boolean), string]
9const RULES: Rule[] = [
10  // Read-only stash subcommands pass, and create, which only writes a commit object; branch applies and
11  // drops the stash, so it is refused too.
12  [(s) => /^stash(\s|$)/.test(s) && !/^stash\s+(list|show|create)(\s|$)/.test(s), "git stash pulls every uncommitted change out of the tree, other sessions' included"],
13  [/^reset\b.*\s--(hard|merge|keep)\b/, 'git reset --hard/--merge/--keep overwrites uncommitted changes'],
14  [(s) => /^clean\b/.test(s) && /\s(-\w*f|--force)/.test(s) && !/\s(-[a-z]*n[a-z]*|--dry-run)\b/.test(s), "git clean -f deletes untracked files, other sessions' new files included"],
15  // A trailing `--` with no path after it (`checkout main --`) only ends the options.
16  [/^checkout\b.*\s(--\s+\S|\.(\s|$))/, 'git checkout -- <path> / . discards uncommitted changes'],
17  [/^checkout\b.*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)(?=\s|$)/, 'git checkout -f discards uncommitted changes'],
18  // A tree-ish then a path (`checkout HEAD a.ts`) overwrites the file. One bare name could be a branch or a
19  // path and stays allowed; -b/-B/--orphan take a start point as their second word.
20  [(s) => /^checkout\b/.test(s) && !/\s(-[bB]|--orphan)(\s|$)/.test(s) && s.split(' ').slice(1).filter((w) => !w.startsWith('-')).length >= 2,
21    'git checkout <tree-ish> <path> discards uncommitted changes'],
22  [/^switch\b.*\s(-[a-zA-Z]*f[a-zA-Z]*|--force|--discard-changes)(?=\s|$)/, 'git switch --discard-changes discards uncommitted changes'],
23  [(s) => /^restore\b/.test(s) && !(/\s(--staged|-S)\b/.test(s) && !/\s(--worktree|-W)\b/.test(s)), 'git restore without --staged discards uncommitted changes'],
24  // A reversed patch (`git diff | git apply -R`) undoes every uncommitted change it lists in the tree;
25  // only --cached keeps it to the index. --check, --stat, --numstat and --summary apply nothing, unless --apply.
26  [(s) => /^apply\b/.test(s) && /\s(-[a-zA-Z0-9]*R[a-zA-Z0-9]*|--reverse)(\s|$)/.test(s) && !/\s--cached(\s|$)/.test(s)
27    && (!/\s--(check|stat|numstat|summary)(\s|$)/.test(s) || /\s--apply(\s|$)/.test(s)),
28    'git apply -R reverses uncommitted changes in the tree (git apply -R --cached, --check or --stat is allowed)'],
29  [/^worktree\s+remove\b/, 'git worktree remove follows a node_modules junction and empties the main checkout: unlink reparse points first and clean only through fleet.sh clean'],
30  [(s) => /^push\b/.test(s) && (/\s--force(\s|$)/.test(s) || /\s-[a-zA-Z]*f[a-zA-Z]*(\s|$)/.test(s) || /\s\+\S/.test(s)), 'git push --force overwrites commits on the remote (--force-with-lease is allowed)'],
31  [(s) => /^branch\b/.test(s) && (/\s-[a-zA-Z]*D/.test(s) || (/\s(-[a-zA-Z]*d[a-zA-Z]*|--delete)(\s|$)/.test(s) && /\s(-[a-zA-Z]*f[a-zA-Z]*|--force)(\s|$)/.test(s))), 'git branch -D deletes a branch with commits that may be unmerged'],
32  // From dcg (Dicklesworthstone/destructive_command_guard): history and object store rewrites.
33  [/^filter-branch\b/, 'git filter-branch rewrites every commit of the branch and checks the rewritten tree out'],
34  [/^reflog\s+expire\b/, 'git reflog expire drops the reflog entries that are the only way back to a lost commit'],
35  [/^update-ref\b.*\s(-d|--delete)(\s|$)/, 'git update-ref -d deletes a ref, and the commits only it reaches'],
36  [/^read-tree\b.*\s--reset\b/, 'git read-tree --reset overwrites the index, and with -u the files too'],
37  // Plain `git rm` refuses a file with local changes; -f removes it anyway.
38  [(s) => /^rm\b/.test(s) && !/\s--cached(\s|$)/.test(s) && /\s(-[a-zA-Z]*f[a-zA-Z]*|--force)(\s|$)/.test(s), 'git rm -f deletes files with uncommitted changes (plain git rm and git rm --cached are allowed)'],
39  [/^gc\b.*\s--prune=now\b/, 'git gc --prune=now deletes unreachable objects at once, the last copy of a dropped stash or reset commit'],
40]
41// In place of git or its subcommand, a variable hides what runs; refused rather than guessed.
42const VARIABLE = 'the command or its subcommand is a variable, so what it runs cannot be read before it runs: write git and the subcommand out'
43// Global options that sit between `git` and the subcommand; these take a value.
44const GLOBAL_WITH_VALUE = /^(-C|-c|--git-dir|--work-tree|--namespace)$/
45const SHELL = /(^|[\\/])((ba|z|da|k)?sh|pwsh|powershell|cmd)(\.exe)?$/i
46const WRAPPER = /^(env|command|sudo|nohup|time|exec|builtin|nice|xargs|timeout|watch|coproc|ionice|stdbuf|setsid)$/
47// Subcommands a variable head is refused on; `rm` stays out so `"$DOCKER" rm -f web` runs.
48const VIA_GUARDED = /^(stash|reset|checkout|switch|restore|clean|worktree|push|branch|filter-branch|reflog|update-ref|read-tree|gc|apply|submodule)$/
49const GIT = /(^|[\\/])git(\.exe)?$/i
50// The flag after which a shell takes its command line: bash -c / -lc, powershell -Command, cmd /c.
51const SHELL_CMD = /^-\w*c$|^-command$|^\/c$/i
52const MARK = /^\u0001(\d+)\u0001$/
53// Redirections (2>&1, > /dev/null, &>f, *> $null, < f) are not part of the command.
54const REDIR = /[\d*]*(?:>>?|<)&?\s*[^\s;&|()<>]+|&>>?\s*[^\s;&|()<>]+/g
55
56// Index of the `)` that closes a paren whose body starts at `from`. `esc` is the shell's escape character.
57function closing(s: string, from: number, esc: string): number {
58  for (let d = 1, i = from; i < s.length; i++) {
59    const c = s[i]
60    if (c === esc) i++
61    else if (c === "'") { const e = s.indexOf("'", i + 1); i = e < 0 ? s.length : e }
62    else if (c === '(') d++
63    else if (c === ')' && --d === 0) return i
64  }
65  return s.length
66}
67
68// Code hidden inside a double-quoted string runs too: $(...), and in Bash `...`. In PowerShell a backtick is
69// the escape character, never a substitution.
70function substs(body: string, into: string[], ps: boolean): void {
71  const esc = ps ? '`' : '\\'
72  for (let i = 0; i < body.length; i++) {
73    if (body[i] === esc) i++
74    else if (body[i] === '$' && body[i + 1] === '(') { const e = closing(body, i + 2, esc); into.push(body.slice(i + 2, e)); i = e }
75    else if (!ps && body[i] === '`') { const e = body.indexOf('`', i + 1); if (e < 0) break; into.push(body.slice(i + 1, e)); i = e }
76  }
77}
78
79// Replaces every quoted string with a numbered mark (kept in `lits`), pulls $(...) and backticks into `nested`,
80// and turns subshell parens into separators.
81// shortcut: quotes inside a $( ) that hold parens can mis-pair; upgrade to a real shell parser if that bites.
82function lex(src: string, lits: string[], nested: string[], ps: boolean): string {
83  const esc = ps ? '`' : '\\'
84  let out = ''
85  for (let i = 0; i < src.length; i++) {
86    const c = src[i]!
87    if (c === esc) { out += src.slice(i, i + 2); i++ }
88    else if (c === "'") {
89      const e = src.indexOf("'", i + 1), end = e < 0 ? src.length : e
90      out += `\u0001${lits.push(src.slice(i + 1, end)) - 1}\u0001`; i = end
91    } else if (c === '"') {
92      let end = i + 1
93      while (end < src.length && src[end] !== '"') end += src[end] === esc ? 2 : 1
94      const body = src.slice(i + 1, end)
95      substs(body, nested, ps)
96      out += `\u0001${lits.push(ps ? body.replace(/`(.)/g, '$1') : body.replace(/\\(["\\$`])/g, '$1')) - 1}\u0001`; i = end
97    } else if (c === '$' && src[i + 1] === '(') { const e = closing(src, i + 2, esc); nested.push(src.slice(i + 2, e)); out += ' ; '; i = e }
98    else if (!ps && c === '`') { const e = src.indexOf('`', i + 1), end = e < 0 ? src.length : e; nested.push(src.slice(i + 1, end)); out += ' ; '; i = end }
99    else out += c === '(' || c === ')' ? ';' : c
100  }
101  return out
102}
103
104// A git subcommand line, and the variable that stood in for git when one did.
105type Sub = { sub: string; via?: string }
106function subcommands(cmd: string, ps: boolean, depth = 0): Sub[] {
107  if (depth > 4) return []
108  // A line continuation (PowerShell backtick, Bash backslash before the newline) is one command, not two.
109  cmd = cmd.replace(ps ? /`\r?\n/g : /\\\r?\n/g, ' ')
110  const lits: string[] = [], nested: string[] = []
111  // A heredoc on a shell's own stdin (`bash <<EOF`, flags only) is code; one fed to a script (`sh x.sh <<EOF`)
112  // or any other command (commit messages) is that command's text.
113  for (const m of cmd.matchAll(/(?:^|[\s;&|(/\\])(?:ba|z|da|k)?sh(?:\.exe)?(?:[ \t]+-[\w-]+)*[ \t]*<<-?\s*['"]?(\w+)['"]?\n([\s\S]*?)\n\s*\1\b/g)) nested.push(m[2]!)
114  const cleaned = lex(cmd
115    .replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\s*\1\b/g, ' ') // heredoc bodies (commit messages)
116    .replace(/@'[\s\S]*?'@|@"[\s\S]*?"@/g, ' '), lits, nested, ps) // PowerShell here-strings
117    .replace(REDIR, ' ')
118  const out: Sub[] = []
119  // A quoted word as the shell hands it on: `"git"`, `& "C:\Program Files\Git\cmd\git.exe"`.
120  const unq = (w: string): string => { const m = MARK.exec(w); return m ? lits[+m[1]!]! : w }
121  // Words another command runs as a command line: one quoted word is a command line of its own; unquoted,
122  // the words are, their quoted words put back in quotes.
123  const handOn = (rest: string[]): void => {
124    if (rest[0] && !MARK.test(rest[0])) nested.push(rest.map((w) => { const m = MARK.exec(w); return m ? `'${lits[+m[1]!]}'` : w }).join(' '))
125    else for (const w of rest) { const m = MARK.exec(w); if (m) nested.push(lits[+m[1]!]!) }
126  }
127  // A brace standing alone opens or closes a block (`% { git stash }`, `try { ... }`); `@{u}` and `-I{}` stay words.
128  for (const seg of cleaned.split(/&&|\|\||[;|&\n]|(?:^|\s)[{}](?=\s|$)/)) {
129    const words = seg.trim().split(/\s+/)
130    // A closing brace glued to the last word (`{git stash}`) or standing alone ends a block, not an argument.
131    // `{}` (find -exec's file, xargs -I{}) is a word, not a block.
132    const last = words.pop()!.replace(/(?<!\{)\}$/, '')
133    if (last) words.push(last)
134    let at = 0, wrapped = false
135    // PS call operator, VAR=x prefixes, shell keywords before a command, env/command/sudo and their flags
136    while (at < words.length) {
137      const w = words[at]!
138      if (/^(&|\{|!|if|then|do|else|elif|while|until|\w+=\S*)$/.test(w) || (wrapped && w.startsWith('-'))) at++
139      // An opening brace glued to the command (`{git stash}`) opens a block.
140      else if (w.length > 1 && w.startsWith('{')) words[at] = w.slice(1)
141      // PowerShell captures output with `$x = git stash`, which still runs git.
142      else if (/^\$[\w:]+$/.test(w) && words[at + 1] === '=') at += 2
143      // A wrapper's own arguments (`timeout 60`, `sudo -u bob`, `nice -n 10`) end where git or a shell starts.
144      else if (WRAPPER.test(w)) {
145        const g = words.findIndex((x, k) => k > at && (GIT.test(unq(x)) || SHELL.test(unq(x))))
146        if (g > 0) { at = g; break }
147        wrapped = true; at++
148      }
149      else break
150    }
151    const head = unq(words[at] ?? '')
152    // bash -c "..." / eval "..." / iex "...": the string is a command line of its own.
153    // Unquoted (`cmd /c git stash`), the rest of the line is that command, its quoted words put back in quotes.
154    const flag = /^(eval|iex|invoke-expression)$/i.test(head) ? at : SHELL.test(head) ? words.findIndex((w, k) => k > at && SHELL_CMD.test(w)) : -1
155    if (flag >= 0) handOn(words.slice(flag + 1))
156    // find -exec / -execdir runs the words after it, up to `\;` or `+`, once per file.
157    const exec = words.findIndex((w, k) => k > at && /^-exec(dir)?$/.test(w))
158    if (exec >= 0) handOn(words.slice(exec + 1))
159    // A bare variable head (`$g`, `"$DOCKER"`) may stand for git: only the very next word is read, as a subcommand,
160    // so `$_ -match 'x'` or `"$d" rm -f web` pass. A path to a tool (`$env:X\dotnet.exe`) is that tool, not git.
161    const via = head.startsWith('$') && !GIT.test(head) ? head : undefined
162    if (via ? !/^\$\{?[\w:]+\}?$/.test(via) : !GIT.test(head)) continue
163    let i = at + 1
164    if (via) { if (!VIA_GUARDED.test(unq(words[i] ?? ''))) continue }
165    else while (i < words.length && words[i]!.startsWith('-')) i += GLOBAL_WITH_VALUE.test(words[i]!) ? 2 : 1
166    if (i < words.length) out.push({ sub: [unq(words[i]!), ...words.slice(i + 1)].join(' '), via })
167    // `git submodule foreach [--recursive] <command>` runs that command in every submodule.
168    if (unq(words[i] ?? '') === 'submodule') {
169      let f = words.findIndex((w, k) => k > i && unq(w) === 'foreach')
170      if (f > 0) { f++; while (f < words.length && words[f]!.startsWith('-')) f++; handOn(words.slice(f)) }
171    }
172  }
173  // shortcut: a string one shell hands another (`powershell -Command` from Bash) is lexed by the outer shell's
174  // escapes; lex nested by the inner shell if that ever hides a command.
175  for (const n of nested) out.push(...subcommands(n, ps, depth + 1))
176  return out
177}
178
179// null = let it run, otherwise why it would destroy work. `tool` is the tool the command runs in.
180// shortcut: with no tool the command is read as Bash, so a PowerShell backtick counts as a substitution
181// (over-blocks) and a backtick continuation is not joined; the hook always passes it, guess only for a new caller.
182export function check(cmd: string, tool = 'Bash'): string | null {
183  for (const { sub, via } of subcommands(cmd, tool === 'PowerShell')) {
184    const name = sub.split(' ')[0]!
185    if (!via && name.startsWith('$')) return `git ${name}: ${VARIABLE}`
186    // shortcut: a bare `$var` before a guarded subcommand word is read as git, so `$pkg restore` is refused too.
187    for (const [rule, why] of RULES) if (typeof rule === 'function' ? rule(sub) : rule.test(sub)) return via ? `${via} ${name}: ${VARIABLE}` : `git ${name}: ${why}`
188  }
189  return null
190}
191// Worth lexing: names git, or holds a variable that may stand in for it.
192const MAYBE = /\bgit\b|\$/i
193
194// What a shell call is told, or null to let it run.
195export function denial(command: string, off: boolean, tool = 'Bash'): string | null {
196  if (off || !MAYBE.test(command)) return null
197  const why = check(command, tool)
198  return why && `Blocked by makarasty-tools git-guard: ${why}. Other sessions share this tree. ` +
199    'Revert only your own edits with Edit/Write, save work with a commit or `git diff > file`; ' +
200    'to see pre-fix code, `git show HEAD:<path>` into the scratchpad or use a worktree; ' +
201    'or ask the user to run the command themselves with `!` if it is truly needed. MAKARASTY_GIT_GUARD=off turns this off.'
202}
203
204export const register: Register = on => {
205  on('tool.call', { tool: /^(Bash|PowerShell)$/ }, async ($, e, next) => {
206    const command = e.tool === 'Bash' || e.tool === 'PowerShell' ? e.command : ''
207    const deny = MAYBE.test(command) && denial(command, (await $.env.get('MAKARASTY_GIT_GUARD')) === 'off', e.tool)
208    return deny ? { deny } : next(e)
209  }).catch(($, e, next) => next(e))
210}
211

1import type { Register } from 'claude-code'
2
3// Agents read files through the shell when a dedicated tool would answer in a twentieth of the time: on the
4// operator's machine 84 K of 115 K shell calls in four weeks were grep, sed, cat, ls and the like, each one
5// 0.1-1 s of harness before the command ran, against 0.02-0.07 s for Read and Grep [M40]. One line, every turn.
6export const READS = 'Read, search and list files with the Read, Grep and Glob tools, not with cat, head, tail, sed -n, grep, rg, find or ls through Bash or PowerShell: a dedicated tool answers in about 0.02-0.07 s, a shell call costs 0.1-1 s before its command even runs, and every agent pays that on every call. Use the shell for what only a shell does: running programs, git, builds and tests.'
7
8type Section = { id: string; text: string; scope: 'shared' | 'session' }
9
10// The prompt's sections with the line added last, or as they were.
11export function withReads<S extends Section>(sections: readonly S[], tools: readonly string[], off: boolean): readonly (S | Section)[] {
12  return off || !tools.includes('Read') ? sections : [...sections, { id: 'makarasty-tools:reads', text: READS, scope: 'session' }]
13}
14
15export const register: Register = on => {
16  on('prompt.compose', async ($, e, next) => {
17    const composed = await next(e)
18    return { ...composed, sections: withReads(composed.sections, e.tools, (await $.env.get('MAKARASTY_READS')) === 'off') }
19  }).catch(($, e, next) => next(e))
20}
21