claude-toolkit 0.18.0-rc.0 → 0.18.1-rc.0

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## 0.18.0 (unreleased)
+## 0.18.1 (2026-11-07)
+
+The edit hooks now check for their tool the way the package manager will look for it. Reported against `testRunner: "bun run --cwd apps/web vitest run"`: the guard read `apps/web` (the value of `--cwd`) as the tool, found nothing by that name and skipped the hook, silently and on every edit. Under `bash` (macOS, Windows Git Bash, Fedora) that was the whole story; under `dash` (Debian, Ubuntu, GitHub's `ubuntu-latest`) the same config happened to run, because `command -v apps/web` accepts any existing directory. This is not a regression from 0.17: those hooks tested a variable Claude Code never sets and never ran.
+
+- fix(hooks): `parseHookCommand` replaces the "first word after the first `run`/`exec`/`x`/`npx`/`bunx`" rule. It reads only the `run`/`exec`/`x` forms of bun, bunx, npm, npx, pnpm and yarn, with a flag table per package manager, so the values of `--cwd`, `--filter`, `--env-file`, `-p`, `--prefix`, `-C` and the like are never taken for the tool, and `turbo run`, `nx run`, `vitest run --project`, `cargo run --bin` and `pnpm vitest run --project unit` are no longer misread. A form it does not recognise (a workspace selector, an unknown flag, `bun --cwd X run`) is guarded on its first word only: the command runs and a failure reaches Claude, instead of the hook skipping with no trace. `npx`, `npm exec`, `bunx` and `bun x` never run unchecked, because they would download a missing package: with an unrecognised flag the first word after the flags is checked (a value taken for the tool is no installed tool, so the hook skips), and a command with no tool word never runs. A file after `bun run` (`bun run check.ts`) is a file target and runs, with or without a directory.
+- fix(hooks): `has-tool <name> [<dir> [<scope>]]` looks where the command runs. `--cwd`, `-C`, `--dir` and `--prefix` move the lookup to that directory, and bins are found in that directory and the ones above it, up to the checkout root (never above it), as bun, npm and pnpm resolve them. This is what pnpm and Bun 1.3 workspaces need: their dev tools live in the package's own `node_modules/.bin`, not the root's. `<scope>` (`any`, `script`, `bin`, `local`) follows what each command can run: `npm run` and `pnpm run` run scripts only; `npx` and `npm exec` run bins only. Only new trailing arguments were added, so a 0.18.0 helper (for example the one in a main checkout, seen from a worktree) still works with the new hook text. A word with a `/` that is not `@scope/name` is a file, not a package.
+- fix(hooks): the `PATH` fallback behaves the same in every shell. `command -v` also accepts builtins (a script named `test`) and, in `dash`, any existing path, so it now counts only when it answers with an absolute path. `npx` and `npm exec` never use it. Yarn commands are satisfied by `.pnp.cjs`, since Plug'n'Play has no `node_modules/.bin`.
+- fix(hooks): a `bun`/`npm`/`pnpm`/`yarn` command that runs with no tool check (for example `bun run --filter web test`) skips a checkout with no `node_modules` or Plug'n'Play, so a fresh worktree stays quiet. The install hook is exempt.
+- fix(cli): the `prepare` hint names the package manager the project uses (the `packageManager` field of its `package.json`, else its one lockfile) instead of the `bun` that the first run writes to the config. A project on pnpm or npm no longer gets `&& bun run claude-toolkit:refresh`, which fails an install on a machine without bun.
+- fix(skills): `ct-verification-before-completion` no longer prescribes a bare `tsc --noEmit`, which checks no files and reports 0 errors when the root `tsconfig.json` only lists `references`.
+- docs: README documents how the tool is looked up per command, a "Monorepos and other package managers" section (forms that work, forms that never can, and what a hook run from the repo root changes for Vitest, `tsc`, Biome, Cargo and Playwright), and that the default hooks need bun on every machine. CLAUDE.md describes `parseHookCommand`, the `has-tool` arguments and the fail-open rule, and no longer claims stack hook overrides that the generator never applied.
+- test: the hook tests run under every shell found among `sh`, `bash` and `dash`. CI's `sh` is `dash`, which passed the 0.18.0 code whenever the misread word named an existing directory.
+
+Behaviour changes to know about:
+
+- Commands the old rule skipped silently now run, so failures that were hidden now reach Claude: the monorepo forms above, and commands for other programs such as `turbo run test` or `cargo run --bin x`, as long as their first word is on the `PATH`.
+- Commands that ran by accident now skip: `npm run <bin>` and `pnpm run <bin>` when the name is not a script, a script named after a shell builtin (`bun run test` with no `test` script), and an `npx` tool installed only globally (add it as a devDependency).
+- Not changed: every hook still runs from the repo root, so Vitest ignores a package's `vitest.config.ts`, and `tsc --noEmit` against a root `tsconfig.json` with only `references` checks nothing. README now says so and shows how to target a package. The protected-branch guard still blocks writes outside the repo while the session is on a protected branch, which also blocks Claude's own scratch and memory files; that is the next patch.
+
+## 0.18.0 (2026-09-29)
 
 The edit hooks finally run, and safely. Every config value that reaches a hook command is checked against an allowlist first. The format and test hooks read the edited file from Claude Code's stdin JSON, skip tools that are not installed and files git ignores, and report failures to Claude as context without ever blocking. `.claude/settings.json` is merged instead of overwritten, the skill hook's output is advisory, and the shipped commands, agents and skills lose their broadest pre-approvals.
 

package/README.md

@@ -175,7 +175,7 @@ The generated `.claude/settings.json` registers these hooks. Each command is pla
 | Install            | edits `package.json`                                       | `hooks.installCommand` + `hooks.autoInstall: true` | off                            |
 
 - **They never block.** The format, test, type-check, extra-check and install hooks always exit 0. When a command fails, Claude gets the last lines of its output as context next to the edit and decides what to do. The install hook also writes the last 20 lines of its output to Claude Code's debug log (`claude --debug-file <path>`).
-- **They skip missing tools and ignored files.** A hook does nothing unless its tool is installed: the word after `run`, `exec`, `x`, `npx` or `bunx` must be a `node_modules/.bin` entry, a `package.json` script or a command on the `PATH`; a command without such a prefix (e.g. `tsc --noEmit`) must itself be on the `PATH` — use `bun run tsc --noEmit`. Tools are looked up in the edited file's checkout. In a Claude Code worktree (under `.claude/worktrees/`), Claude Code reads the worktree's own `.claude/`. With `.claude/` gitignored, a fresh worktree has none, so the toolkit's hooks, skills, commands and permission rules only apply there after you install dependencies in the worktree. That install provides the tools the hooks look for, and the `prepare` line then runs `claude-toolkit refresh` to generate the worktree's `.claude/`. The default formatter stays silent until Biome is installed. Files that git ignores (build output, dependencies) are skipped too. If your `biome.json` excludes files with `files.includes`, add `--no-errors-on-unmatched` to the formatter so edits to excluded files are not reported as failures.
+- **They skip missing tools and ignored files.** A hook does nothing, and prints nothing, unless its command can run: its first word must be on Claude Code's `PATH` (the defaults need `bun`), and a `bun`, `bunx`, `npm`, `npx`, `pnpm` or `yarn` command must find its tool where that command looks for it, as [Monorepos and other package managers](#monorepos-and-other-package-managers) spells out. A bare command (e.g. `tsc --noEmit`) is looked up on the `PATH` only — use `bun run tsc --noEmit`. The lookup starts in the edited file's checkout. In a Claude Code worktree (under `.claude/worktrees/`), Claude Code reads the worktree's own `.claude/`. With `.claude/` gitignored, a fresh worktree has none, so the toolkit's hooks, skills, commands and permission rules only apply there after you install dependencies in the worktree. That install provides the tools the hooks look for, and the `prepare` line then runs `claude-toolkit refresh` to generate the worktree's `.claude/`. The default formatter stays silent until Biome is installed. Files that git ignores (build output, dependencies) are skipped too. If your `biome.json` excludes files with `files.includes`, add `--no-errors-on-unmatched` to the formatter so edits to excluded files are not reported as failures.
 - **Commands are allowlisted.** A hook command may only contain letters, digits, spaces and `. _ / @ : = + -`, and must start with the program to run (not `eval`, `exec`, `command`, `.`, `source`, a shell with `-c`, or an option). Anything else — quotes, `$`, `;`, `|`, `&&`, redirects, newlines — stops `bunx claude-toolkit` and `claude-toolkit refresh` with an error naming the field and the value. Put such a command in a `package.json` script and reference the script:
 
   ```json
@@ -188,6 +188,56 @@ The generated `.claude/settings.json` registers these hooks. Each command is pla
 
 - **`settings.json` is merged, not overwritten.** The toolkit owns only hook entries whose command starts with `# claude-toolkit:` (and the unmarked entries that 0.17 and earlier wrote), and it sets `includeCoAuthoredBy` and its `env` defaults only when they are missing. Your `permissions` (including `deny` rules), your own hooks, `model` and every other key survive regeneration. A `settings.json` that is not a JSON object is saved as `settings.json.bak` before a new one is written.
 
+### Monorepos and other package managers
+
+Every hook runs from the root of the edited file's checkout, and the format and test commands get the edited file's path appended. A `bun`, `bunx`, `npm`, `npx`, `pnpm` or `yarn` command is checked for its tool before it runs, where that command would look for it:
+
+| Command                                                          | The tool must be…                                                                          |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `bun run <tool>`                                                 | a `package.json` script, a `node_modules/.bin` entry, or a command on the `PATH`          |
+| `bun x <tool>`, `bunx <tool>`, `pnpm exec <tool>`, `yarn exec <tool>` | a `node_modules/.bin` entry, or a command on the `PATH`                               |
+| `npm run <script>`, `pnpm run <script>`                          | a `package.json` script                                                                    |
+| `npx <tool>`, `npm exec <tool>`                                  | a `node_modules/.bin` entry. A tool installed only globally is skipped: `npx` would download a missing package, so add the tool as a devDependency |
+| `yarn run <tool>`                                                | a script or a `node_modules/.bin` entry                                                    |
+
+Yarn Plug'n'Play has no `node_modules`, so a `yarn run` or `yarn exec` check is satisfied by the presence of `.pnp.cjs`. Scripts are read from the directory the command runs in; `.bin` entries are looked up there and in the directories above it, up to the checkout root. `--cwd` (bun, Yarn), `-C` or `--dir` (pnpm) and `--prefix` or `-C` (npm) move the command to another directory, and the lookup follows. In a pnpm workspace, and in a new Bun 1.3 workspace, a package's dev tools live in the package's own `node_modules/.bin`, not the root's, so target the package:
+
+```ts
+hooks: {
+  testRunner: "bun run --cwd apps/web vitest run",
+  formatter: "pnpm -C apps/web exec biome format --write",
+  typeCheck: "npm --prefix apps/web run typecheck",
+},
+```
+
+Any other command runs with only its first word checked: `cargo check`, `turbo run test`, `nx run web:test`, and the forms that select workspaces (`--filter`, `-F`, `-w`, `--workspace`, `pnpm -r`, `yarn workspace`). Such a hook runs and reports failures to Claude instead of skipping. It still waits until the checkout has a `node_modules` folder (or Plug'n'Play), so a fresh worktree stays quiet. A file after `bun run` (`bun run check.ts`, `bun run scripts/fmt.mjs`) is run the same way. `npx`, `npm exec`, `bunx` and `bun x` are the exception, because they download a missing package: with a flag the toolkit does not know, the hook checks the first word after the flags and skips when that is not an installed tool, and with no tool word at all it never runs.
+
+To run a package's tests for every test file in the repo, point the hook at a script in the root `package.json`, called with your package manager. `--passWithNoTests` keeps edits to other packages' tests quiet:
+
+```json
+{ "scripts": { "test:file": "bun run --cwd apps/web vitest run --passWithNoTests" } }
+```
+
+```ts
+hooks: { testRunner: "bun run test:file" },
+```
+
+Forms that do not work, whatever the toolkit does:
+
+- `bun --cwd apps/web run …` prints bun's usage and exits 0 without running anything. Put the flag after `run`.
+- `bun run --filter web vitest run` fails: bun's `--filter` runs scripts only, so use `bun run --filter web test`.
+- `pnpm -C apps/web vitest run` and `pnpm --filter web vitest run` need `exec` (`pnpm -C apps/web exec vitest run`).
+- A script that does `cd apps/web && vitest run` fails where the tool is installed only in the package.
+
+Running from the root also changes what the tools see:
+
+- **Vitest** ignores a package's `vitest.config.ts` when run from the root, so passing tests can be reported as failures. Target the package as above, or define `test.projects` at the root.
+- **`tsc --noEmit`** checks nothing, and exits 0, when the root `tsconfig.json` only lists `references` (most Vite templates). Use `tsc -b --noEmit` and gitignore the `.tsbuildinfo` files it writes.
+- **Biome** reads the nearest `biome.json`; a nested one needs `"root": false` or every file under it fails.
+- **Cargo** looks for `Cargo.toml` at the root: use `cargo check --manifest-path worker/Cargo.toml` when the crate is in a subfolder.
+- **Playwright** `*.spec.ts` files match the test hook, which runs the test command on them. Keep the test command away from them or exclude them in its config.
+- **Machines without bun** skip every default hook, and cannot run `bunx claude-toolkit`. Everything that must work for the whole team needs bun, or hook commands written for your package manager.
+
 ## Project Setup
 
 Add `.claude/` to your `.gitignore` (it's generated, not tracked):

package/bin/cli.ts

@@ -24,7 +24,7 @@ import { basename, join, resolve } from "node:path";
 import { detectStacks } from "../src/detect.js";
 import { generate, readMarker, readToolkitVersion } from "../src/generator.js";
 import { DEFAULT_HOOKS } from "../src/hook-commands.js";
-import { buildRefreshHint } from "../src/refresh-hint.js";
+import { buildRefreshHint, inferPackageManager, LOCKFILE_NAMES } from "../src/refresh-hint.js";
 import type { ClaudeToolkitConfig } from "../src/types.js";
 
 const CONFIG_FILENAME = "claude-toolkit.config.ts";
@@ -199,15 +199,17 @@ async function printRefreshHint(
 ): Promise<void> {
 	const pkgPath = join(projectDir, "package.json");
 	if (!existsSync(pkgPath)) return;
-	let scripts: Record<string, unknown>;
+	let pkg: { scripts?: Record<string, unknown>; packageManager?: unknown };
 	try {
-		scripts = JSON.parse(await readFile(pkgPath, "utf-8")).scripts ?? {};
+		pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
 	} catch {
 		return; // an unparsable package.json is not worth failing the run over
 	}
+	// A first run writes "bun" to the config whatever the project uses.
+	const lockfiles = LOCKFILE_NAMES.filter((name) => existsSync(join(projectDir, name)));
 	const lines = buildRefreshHint({
-		scripts,
-		packageManager,
+		scripts: pkg.scripts ?? {},
+		packageManager: inferPackageManager(pkg.packageManager, lockfiles) ?? packageManager,
 		yarnBerry: existsSync(join(projectDir, ".yarnrc.yml")),
 		previousVersion,
 	});

package/core/hooks/hook-input.cjs

@@ -1,13 +1,14 @@
 /**
  * Input helper for the generated PostToolUse hooks. Filesystem only: it reads the
- * hook's JSON from stdin and, for has-tool, the package.json and node_modules/.bin of the
- * current directory (the hook first cds to the edited file's checkout). It never starts
- * a process and never reads environment variables.
+ * hook's JSON from stdin and, for has-tool, the package.json and node_modules/.bin files
+ * around the current directory (the hook first cds to the edited file's checkout). It
+ * never starts a process and never reads environment variables.
  *
  *   node hook-input.cjs path             Print tool_input.file_path; nothing on bad input.
- *   node hook-input.cjs has-tool <name>  Exit 0 when <name> is a node_modules/.bin entry
- *                                        or a package.json script in the current
- *                                        directory; exit 1 otherwise.
+ *   node hook-input.cjs has-tool <name> [<dir> [<scope>]]
+ *                                        Exit 0 when <name> is something a command run in
+ *                                        <dir> (default ".") can find, 1 otherwise. <scope>
+ *                                        is any (default), script, bin or local; see hasTool.
  *   node hook-input.cjs context <title>  Read command output from stdin and print it as
  *                                        PostToolUse additionalContext JSON.
  */
@@ -17,6 +18,8 @@ const path = require("node:path");
 
 // npm, pnpm and yarn create bare, .cmd and .ps1 shims; bun on Windows creates .exe and .bunx.
 const BIN_SUFFIXES = ["", ".cmd", ".ps1", ".exe", ".bunx"];
+// Where has-tool looks; an unknown scope counts as "any", so a newer hook works with this helper.
+const SCOPES = new Set(["any", "script", "bin", "local"]);
 // Code points below SPACE, and DEL, are control characters (newlines included).
 const SPACE = 0x20;
 const DEL = 0x7f;
@@ -67,19 +70,53 @@ function readScripts(root) {
 	}
 }
 
+/** Nearest ancestor-or-self holding .git (a worktree has a .git file). */
+function checkoutTop(cwd) {
+	for (let dir = cwd; ; dir = path.dirname(dir)) {
+		if (fs.existsSync(path.join(dir, ".git"))) return dir;
+		if (path.dirname(dir) === dir) return null;
+	}
+}
+
+/** `start` and its parents up to the checkout top, never above it. */
+function lookupDirs(start, cwd) {
+	const top = checkoutTop(cwd) ?? cwd;
+	const rel = path.relative(top, start);
+	if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return [start];
+	const dirs = [];
+	for (let dir = start; ; dir = path.dirname(dir)) {
+		dirs.push(dir);
+		if (dir === top || path.dirname(dir) === dir) return dirs;
+	}
+}
+
+/** "prettier@3" is prettier, "@biomejs/biome" is biome, a path is "". */
+function binName(name) {
+	const bare = name.replace(/(.)@[^/]*$/, "$1");
+	const scoped = /^@[^/]+\/([^/]+)$/.exec(bare);
+	if (scoped) return scoped[1];
+	return bare.includes("/") || bare === "." || bare === ".." ? "" : bare;
+}
+
 /**
- * True when `name` is a package.json script or a node_modules/.bin entry in `root` (the
- * current directory unless given). A version suffix is ignored ("prettier@3" counts as "prettier"), and a scoped package is looked
- * up by its last segment ("@biomejs/biome" as "biome").
+ * scope: any = a script of `dir`, else a .bin entry in `dir` or a parent; script; bin = .bin
+ * in `dir` or a parent; local = .bin in `dir` only.
  */
-function hasTool(name, root = process.cwd()) {
+function hasTool(name, dir = ".", scope = "any", cwd = process.cwd()) {
 	if (typeof name !== "string" || name === "") return false;
-	if (typeof readScripts(root)[name] === "string") return true;
-	const bare = name.replace(/(.)@[^/]*$/, "$1");
-	const binName = bare.split("/").pop() ?? "";
-	if (binName === "") return false;
-	const binDir = path.join(root, "node_modules", ".bin");
-	return BIN_SUFFIXES.some((suffix) => fs.existsSync(path.join(binDir, binName + suffix)));
+	const start = path.resolve(cwd, dir);
+	if ((scope === "any" || scope === "script") && typeof readScripts(start)[name] === "string") {
+		return true;
+	}
+	if (scope === "script") return false;
+	const bin = binName(name);
+	if (bin === "") return false;
+	const dirs = scope === "local" ? [start] : lookupDirs(start, cwd);
+	return dirs.some((d) =>
+		BIN_SUFFIXES.some((suffix) =>
+			fs.existsSync(path.join(d, "node_modules", ".bin", bin + suffix)),
+		),
+	);
 }
 
 /** PostToolUse JSON that hands `title` and the tail of `output` to Claude as context. */
@@ -94,13 +131,14 @@ function contextJson(title, output) {
 
 /** Run one subcommand; returns the exit code. */
 function main(argv) {
-	const [command, arg] = argv;
+	const [command, arg, dir, scope] = argv;
 	if (command === "path") {
 		const filePath = filePathFrom(readStdin());
 		if (filePath !== "") process.stdout.write(`${filePath}\n`);
 		return 0;
 	}
-	if (command === "has-tool") return hasTool(arg) ? 0 : 1;
+	if (command === "has-tool")
+		return hasTool(arg, dir || ".", SCOPES.has(scope) ? scope : "any") ? 0 : 1;
 	if (command === "context") {
 		process.stdout.write(`${contextJson(arg ?? "", readStdin())}\n`);
 		return 0;

package/core/skills/ct-verification-before-completion/SKILL.md

@@ -12,7 +12,7 @@ description: Evidence-based completion claims -- never say "done" without proof
 Before claiming complete, run and show output for each:
 
 1. **Tests pass** -- Full suite or related tests. Show actual output, not just "tests pass".
-2. **Types check** -- `tsc --noEmit` with zero errors on changed files.
+2. **Types check** -- The project's type-check script (or `tsc --noEmit`) with zero errors on changed files. When the root `tsconfig` only lists `references`, use `tsc -b` or the script: a plain `tsc --noEmit` there checks nothing and reports 0 errors.
 3. **Lint passes** -- Fix violations introduced by your changes.
 4. **Feature works** -- Show actual output (API response, CLI output, screenshot) for user-facing changes.
 
@@ -45,7 +45,7 @@ Before completing work that touches dependencies, inputs, or external data:
 ```
 ## Completed: [task name]
 - Tests: X passing (Y new, Z existing) -- [command output]
-- Types: tsc --noEmit: 0 errors
+- Types: [type-check command]: 0 errors
 - Lint: 0 violations
 - Security: audit clean, no exposed secrets
 - Manual: [endpoint/action]: [status/result]

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.18.0-rc.0",
+	"version": "0.18.1-rc.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
@@ -46,11 +46,11 @@
 		"url": "git+https://github.com/william-queant/claude-toolkit.git"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.10",
-		"@types/bun": "^1.3.11",
+		"@biomejs/biome": "^2.6.6",
+		"@types/bun": "^1.4.4",
 		"husky": "^9.1.7",
-		"lint-staged": "^16.4.0",
-		"typescript": "^6.0.2"
+		"lint-staged": "^17.6.0",
+		"typescript": "^7.0.2"
 	},
 	"engines": {
 		"bun": ">=1.3.0"

package/src/hook-commands.ts

@@ -120,37 +120,362 @@ const TYPECHECK_PATTERNS = ["*.ts", "*.tsx", "*.mts", "*.cts"];
 const EXTRA_CHECK_PATTERNS = ["*.rs"];
 const INSTALL_PATTERNS = ["package.json", "*/package.json"];
 
-/** Words after which the next non-flag word names the tool: `bun run x`, `pnpm exec x`, `npx x`. */
-const TOOL_PREFIXES = new Set(["run", "exec", "x", "npx", "bunx"]);
+export type Scope = "any" | "script" | "bin" | "local";
+
+export interface ToolCheck {
+	tool: string;
+	/** Relative to the checkout root. */
+	dir: string;
+	scope: Scope;
+	/** Also accept an executable on the PATH. */
+	path: boolean;
+	/** Yarn Plug'n'Play has no .bin: a .pnp.cjs satisfies the check. */
+	pnp: boolean;
+}
+
+/** A null `check` guards the runner only: the command runs and failures reach Claude. */
+export interface ParsedCommand {
+	runner: string;
+	check: ToolCheck | null;
+	/** Never run: the tool is unknown and the runner would download it. */
+	blocked?: boolean;
+}
+
+interface Flags {
+	dir?: string[];
+	/** The directory is the only place the runner looks (npm's `--prefix`). */
+	localDir?: boolean;
+	workspace?: string[];
+	workspaceBool?: string[];
+	values?: string[];
+	booleans?: string[];
+}
+
+const flagTable = (f: Flags) => ({
+	dir: new Set(f.dir ?? []),
+	localDir: f.localDir ?? false,
+	workspace: new Set(f.workspace ?? []),
+	workspaceBool: new Set(f.workspaceBool ?? []),
+	values: new Set(f.values ?? []),
+	booleans: new Set(f.booleans ?? []),
+});
+type FlagTable = ReturnType<typeof flagTable>;
+
+// Checked against bun 1.3, npm 10-11, pnpm 8-12, Yarn 1 and 4. An unlisted flag means no tool check.
+const BUN = flagTable({
+	dir: ["--cwd"],
+	workspace: ["--filter", "-F"],
+	values: [
+		"--env-file",
+		"--conditions",
+		"--preload",
+		"-r",
+		"--config",
+		"-c",
+		"--shell",
+		"--elide-lines",
+	],
+	booleans: ["--bun", "-b", "--silent", "--if-present", "--no-install"],
+});
+const BUNX = flagTable({
+	values: ["-p", "--package", "--cache-dir", "--registry", "--config"],
+	booleans: ["--bun", "-b", "--silent", "--no-install", "--verbose"],
+});
+const NPM = flagTable({
+	dir: ["--prefix", "-C"],
+	localDir: true,
+	workspace: ["-w", "--workspace"],
+	workspaceBool: ["--workspaces", "-ws", "--include-workspace-root"],
+	values: [
+		"-p",
+		"--package",
+		"-c",
+		"--call",
+		"--script-shell",
+		"--loglevel",
+		"--registry",
+		"--cache",
+		"--userconfig",
+		"--globalconfig",
+		"--tag",
+		"--otp",
+		"--before",
+	],
+	booleans: [
+		"--silent",
+		"-s",
+		"--if-present",
+		"--ignore-scripts",
+		"--yes",
+		"-y",
+		"--no",
+		"--quiet",
+		"-q",
+		"--foreground-scripts",
+	],
+});
+const PNPM = flagTable({
+	dir: ["-C", "--dir"],
+	workspace: ["--filter", "-F", "--filter-prod"],
+	workspaceBool: ["-r", "--recursive"],
+	values: ["--reporter", "--loglevel", "--workspace-concurrency"],
+	booleans: [
+		"--silent",
+		"-s",
+		"--parallel",
+		"--stream",
+		"--aggregate-output",
+		"--if-present",
+		"-w",
+		"--workspace-root",
+	],
+});
+const YARN = flagTable({
+	dir: ["--cwd"],
+	booleans: ["--silent", "-s", "-T", "--top-level", "-B", "--binaries-only"],
+});
+
+interface FlagState {
+	dir: string | null;
+	/** Before bun's `run`, `--cwd DIR` prints usage and runs nothing. */
+	spaceDir: boolean;
+	localDir: boolean;
+	workspace: boolean;
+	unknown: boolean;
+}
+const freshState = (): FlagState => ({
+	dir: null,
+	spaceDir: false,
+	localDir: false,
+	workspace: false,
+	unknown: false,
+});
+
+/** Returns the index of the first non-flag word (or of `--`). */
+function readFlags(words: string[], start: number, table: FlagTable, state: FlagState): number {
+	let i = start;
+	while (i < words.length) {
+		const word = words[i] ?? "";
+		if (word === "--" || !word.startsWith("-")) return i;
+		const eq = word.indexOf("=");
+		const name = eq === -1 ? word : word.slice(0, eq);
+		const inline = eq === -1 ? undefined : word.slice(eq + 1);
+		const takesValue = table.dir.has(name) || table.workspace.has(name) || table.values.has(name);
+		let value = inline;
+		if (takesValue && value === undefined) {
+			i += 1;
+			value = words[i];
+		}
+		if (table.dir.has(name)) {
+			if (value === undefined || value === "" || value.startsWith("-")) state.unknown = true;
+			else
+				Object.assign(state, {
+					dir: value,
+					spaceDir: inline === undefined,
+					localDir: table.localDir,
+				});
+		} else if (table.workspace.has(name) || table.workspaceBool.has(name)) {
+			state.workspace = true;
+		} else if (table.values.has(name)) {
+			if (value === undefined) state.unknown = true;
+		} else if (!table.booleans.has(name) && inline === undefined) {
+			state.unknown = true;
+		}
+		i += 1;
+	}
+	return i;
+}
+
+const unversioned = (word: string) => word.replace(/(.)@[^/]*$/, "$1");
+const isFileTarget = (word: string) =>
+	(word.includes("/") && !/^@[^/]+\/[^/]+$/.test(unversioned(word))) ||
+	/\.[cm]?[jt]sx?$/.test(word);
+
+interface Resolution {
+	scope: Scope;
+	path: boolean;
+	/** npx, npm exec, bunx and bun x fetch missing packages. */
+	downloads: boolean;
+	pnp?: boolean;
+}
+
+function checkTool(
+	runner: string,
+	words: string[],
+	from: number,
+	state: FlagState,
+	how: Resolution,
+): ParsedCommand {
+	const tool = words[words[from] === "--" ? from + 1 : from];
+	const dir = state.dir ?? ".";
+	if (how.downloads) {
+		// Never run unchecked: an unknown flag's value is checked as the tool, fails, and the hook skips.
+		if (tool === undefined || tool.startsWith("-")) return { runner, check: null, blocked: true };
+		const scope = state.localDir && state.dir !== null ? "local" : "bin";
+		return { runner, check: { tool, dir, scope, path: how.path, pnp: false } };
+	}
+	const unchecked: ParsedCommand = { runner, check: null };
+	if (tool === undefined || tool.startsWith("-") || isFileTarget(tool)) return unchecked;
+	if (state.unknown || state.workspace) return unchecked;
+	return { runner, check: { tool, dir, scope: how.scope, path: how.path, pnp: how.pnp ?? false } };
+}
+
+const NPM_RUN = new Set(["run", "run-script", "rum", "urn"]);
+
+function parseBun(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const at = readFlags(words, 0, BUN, state);
+	const sub = words[at];
+	if ((sub === "run" || sub === "x") && state.spaceDir) {
+		return { runner, check: null }; // bun prints usage and runs nothing
+	}
+	if (sub === "run") {
+		const from = readFlags(words, at + 1, BUN, state);
+		return checkTool(runner, words, from, state, { scope: "any", path: true, downloads: false });
+	}
+	if (sub === "x") {
+		const from = readFlags(words, at + 1, BUNX, state);
+		return checkTool(runner, words, from, state, { scope: "bin", path: true, downloads: true });
+	}
+	return { runner, check: null };
+}
+
+function parseBunx(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const from = readFlags(words, 0, BUNX, state);
+	return checkTool(runner, words, from, state, { scope: "bin", path: true, downloads: true });
+}
+
+function parseNpm(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const at = readFlags(words, 0, NPM, state);
+	const sub = words[at];
+	if (sub !== undefined && NPM_RUN.has(sub)) {
+		const from = readFlags(words, at + 1, NPM, state);
+		// npm reads its own flags anywhere before "--": `npm run test --workspace web`.
+		const end = words.indexOf("--", from + 1);
+		const after = words.slice(from + 1, end === -1 ? undefined : end);
+		for (const [k, word] of after.entries()) {
+			if (word.startsWith("-")) readFlags(after, k, NPM, state);
+		}
+		return checkTool(runner, words, from, state, {
+			scope: "script",
+			path: false,
+			downloads: false,
+		});
+	}
+	if (sub === "exec" || sub === "x") {
+		const from = readFlags(words, at + 1, NPM, state);
+		return checkTool(runner, words, from, state, { scope: "bin", path: false, downloads: true });
+	}
+	return { runner, check: null };
+}
+
+function parseNpx(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const from = readFlags(words, 0, NPM, state);
+	return checkTool(runner, words, from, state, { scope: "bin", path: false, downloads: true });
+}
+
+function parsePnpm(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const at = readFlags(words, 0, PNPM, state);
+	const sub = words[at];
+	if (sub === "run") {
+		const from = readFlags(words, at + 1, PNPM, state);
+		return checkTool(runner, words, from, state, {
+			scope: "script",
+			path: false,
+			downloads: false,
+		});
+	}
+	if (sub === "exec") {
+		const from = readFlags(words, at + 1, PNPM, state);
+		return checkTool(runner, words, from, state, { scope: "bin", path: true, downloads: false });
+	}
+	return { runner, check: null };
+}
+
+function parseYarn(runner: string, words: string[]): ParsedCommand {
+	const state = freshState();
+	const at = readFlags(words, 0, YARN, state);
+	const sub = words[at];
+	if (sub === "run") {
+		const from = readFlags(words, at + 1, YARN, state);
+		return checkTool(runner, words, from, state, {
+			scope: "any",
+			path: false,
+			downloads: false,
+			pnp: true,
+		});
+	}
+	if (sub === "exec") {
+		const from = readFlags(words, at + 1, YARN, state);
+		return checkTool(runner, words, from, state, {
+			scope: "bin",
+			path: true,
+			downloads: false,
+			pnp: true,
+		});
+	}
+	return { runner, check: null };
+}
+
+const PARSERS: Record<string, (runner: string, words: string[]) => ParsedCommand> = {
+	bun: parseBun,
+	bunx: parseBunx,
+	npm: parseNpm,
+	npx: parseNpx,
+	pnpm: parsePnpm,
+	yarn: parseYarn,
+};
+
+const JS_RUNNERS = new Set(Object.keys(PARSERS));
 
 /**
- * The executables an allowlisted command needs. `runner` is its first word (after any
- * VAR=value assignments); `tool` is the first non-flag word after run, exec, x, npx or
- * bunx, or the runner itself when there is none.
+ * Unrecognised forms are guarded on their runner only: a failure then reaches Claude, while a
+ * wrong guess would skip a working hook with no trace.
  */
+export function parseHookCommand(command: string): ParsedCommand {
+	const words = command.trim().split(/\s+/);
+	const at = words.findIndex((word) => !word.includes("="));
+	const runner = at === -1 ? "" : (words[at] ?? "");
+	const parse = PARSERS[runner];
+	return parse ? parse(runner, words.slice(at + 1)) : { runner, check: null };
+}
+
 export function commandTools(command: string): { runner: string; tool: string } {
-	const words = command
-		.trim()
-		.split(/\s+/)
-		.filter((word) => !word.includes("="));
-	const runner = words[0] ?? "";
-	const at = words.findIndex((word) => TOOL_PREFIXES.has(word));
-	const tool = at === -1 ? undefined : words.slice(at + 1).find((word) => !word.startsWith("-"));
-	return { runner, tool: tool ?? runner };
+	const { runner, check } = parseHookCommand(command);
+	return { runner, tool: check?.tool ?? runner };
 }
 
-/** sh lines that exit 0 silently unless the command's runner and tool are installed. */
-function toolGuard(command: string): string[] {
-	// runner and tool are words of an allowlisted command (HOOK_COMMAND_PATTERN): no shell syntax.
-	const { runner, tool } = commandTools(command);
-	const runnerLine = `command -v ${runner} >/dev/null 2>&1 || exit 0`;
-	// A bare command (no run/exec/x/npx/bunx) is found by sh through PATH only: a
-	// node_modules/.bin entry or package.json script of that name cannot run it.
-	if (runner === tool) return [runnerLine];
-	return [
-		runnerLine,
-		`${HOOK_INPUT} has-tool ${tool} || command -v ${tool} >/dev/null 2>&1 || exit 0`,
-	];
+// `command -v` also accepts builtins and, in dash, any existing path.
+const ON_PATH = (tool: string) =>
+	`{ found="$(command -v ${tool} 2>/dev/null)" && case "$found" in /*) ;; *) false;; esac; }`;
+
+const DEPENDENCIES_LINE =
+	'[ -d node_modules ] || [ -d "$top/node_modules" ] || [ -f .pnp.cjs ] || [ -f "$top/.pnp.cjs" ] || exit 0';
+
+/**
+ * sh lines that exit 0 unless the command can run. Interpolated words come from an allowlisted
+ * command (HOOK_COMMAND_PATTERN). Not `needsDependencies` for install: it runs in fresh checkouts.
+ */
+function toolGuard(command: string, needsDependencies = false): string[] {
+	const { runner, check, blocked } = parseHookCommand(command);
+	const lines = [`command -v ${runner} >/dev/null 2>&1 || exit 0`];
+	if (blocked) return [...lines, "exit 0"];
+	if (check === null) {
+		if (needsDependencies && JS_RUNNERS.has(runner)) lines.push(DEPENDENCIES_LINE);
+		return lines;
+	}
+	const args = [check.tool];
+	if (check.dir !== "." || check.scope !== "any") args.push(check.dir);
+	if (check.scope !== "any") args.push(check.scope);
+	const found = [`${HOOK_INPUT} has-tool ${args.join(" ")}`];
+	if (check.pnp) found.unshift("[ -f .pnp.cjs ]", "[ -f .pnp.js ]");
+	if (check.path && !check.tool.includes("/")) found.push(ON_PATH(check.tool));
+	lines.push(`${found.join(" || ")} || exit 0`);
+	return lines;
 }
 
 /** A PostToolUse hook that runs one allowlisted command after matching edits. */
@@ -181,7 +506,7 @@ function editHookCommand(hook: EditHook): string {
 		...PREAMBLE,
 		`case "$f" in ${hook.patterns.join("|")}) ;; *) exit 0;; esac`,
 		...PROJECT_LINES,
-		...toolGuard(hook.command),
+		...toolGuard(hook.command, true),
 		`out="$(${run} 2>&1)" && exit 0`,
 		`printf '%s\\n' "$out" | ${HOOK_INPUT} context "claude-toolkit ${hook.id} hook: ${hook.command} failed for $f"`,
 		"exit 0",

package/src/refresh-hint.ts

@@ -42,6 +42,29 @@ const CAVEATS: Record<PackageManager | "yarn-berry", string | null> = {
 		'Yarn 2+ never runs "prepare" for your own project; "postinstall" runs whenever your dependencies change.',
 };
 
+const LOCKFILES: Record<string, PackageManager> = {
+	"bun.lock": "bun",
+	"bun.lockb": "bun",
+	"pnpm-lock.yaml": "pnpm",
+	"package-lock.json": "npm",
+	"yarn.lock": "yarn",
+};
+export const LOCKFILE_NAMES = Object.keys(LOCKFILES);
+
+/** The package.json `packageManager` field, else the one lockfile; null when unsure. */
+export function inferPackageManager(
+	packageManagerField: unknown,
+	lockfiles: string[],
+): PackageManager | null {
+	if (typeof packageManagerField === "string") {
+		const name = packageManagerField.split("@")[0] ?? "";
+		if (name === "bun" || name === "npm" || name === "pnpm" || name === "yarn") return name;
+		return null;
+	}
+	const found = new Set(lockfiles.map((file) => LOCKFILES[file]).filter(Boolean));
+	return found.size === 1 ? ([...found][0] ?? null) : null;
+}
+
 /** Compare x.y.z numerically. A prerelease counts as its release: 0.17.0-rc.0 is not before 0.17.0. */
 export function isBefore(version: string, floor: string): boolean {
 	const parts = (v: string) =>

package/templates/claude-toolkit.config.ts

@@ -7,16 +7,17 @@ export default defineConfig({
 	// Package manager used for install/run commands
 	packageManager: "bun",
 
-	// Hook automation — commands run after Claude edits a matching file. A command may only
-	// use letters, digits, spaces and . _ / @ : = + -; for anything else, add a package.json
-	// script and reference it as "bun run <script>".
+	// Hook automation — commands run exactly as written after Claude edits a matching file, from
+	// the repo root. A command may only use letters, digits, spaces and . _ / @ : = + -; for
+	// anything else, add a package.json script and reference it with your package manager
+	// (e.g. "bun run <script>"). In a monorepo, target a package: "bun run --cwd apps/web vitest run".
 	hooks: {
 		formatter: "bun run biome format --write",
 		testRunner: "bun run vitest run",
 		typeCheck: "bun run tsc --noEmit",
 		// typeCheckOnEdit: true, // also run typeCheck after every .ts/.tsx edit (slow on large projects)
 		// autoInstall: true, // run the install command after every package.json edit
-		// extraChecks: ['cargo check --target wasm32-unknown-unknown'],
+		// extraChecks: ['cargo check --target wasm32-unknown-unknown'], // runs at the repo root: add --manifest-path DIR/Cargo.toml for a crate in a subfolder
 	},
 
 	// Directory → skill mappings (merged with stack defaults)

package/templates/configs/biome.base.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.6.6/schema.json",
 	"vcs": {
 		"enabled": true,
 		"clientKind": "git",