@hasna/hooks 0.8.0 → 0.9.0

package/dist/index.js

@@ -5998,6 +5998,18 @@ var HOOKS = [
     matcher: "^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$",
     tags: ["workspace", "repos", "structure", "guard", "safety", "orgs", "multi-agent"]
   },
+  {
+    name: "trash-guard",
+    displayName: "Trash Guard",
+    description: "Rewrites rm issued through Bash into `trash guard`, so the delete lands in a recoverable trash store; refuses the delete when there is nothing to redirect to (trash absent, a delete verb it cannot rewrite, or the protected class: /, ~, ~/.hasna, ~/.ssh, ~/.aws)",
+    version: "0.1.0",
+    category: "Git Safety",
+    event: "PreToolUse",
+    matcher: "Bash",
+    tags: ["rm", "delete", "trash", "recoverable", "guard", "safety", "bash"],
+    rewritesInput: true,
+    timeoutSeconds: 5
+  },
   {
     name: "checktests",
     displayName: "Check Tests",
@@ -6566,6 +6578,13 @@ function resolveHook(name) {
 
 // src/lib/installer.ts
 init_manifest();
+
+// src/lib/registration.ts
+function matchersOverlap(a, b) {
+  return a === b || a.includes(b) || b.includes(a);
+}
+
+// src/lib/installer.ts
 init_store();
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 var HOOKS_DIR = existsSync7(join7(__dirname2, "..", "..", "hooks", "hook-gitguard")) ? join7(__dirname2, "..", "..", "hooks") : join7(__dirname2, "..", "hooks");
@@ -6701,6 +6720,7 @@ function codewithTimeout(name) {
     case "prompt-guard":
       return 3;
     case "worktree-guard":
+    case "trash-guard":
     case "stop-sync":
       return 5;
     default:
@@ -6719,6 +6739,8 @@ function codewithStatusMessage(name) {
       return "Checking prompt safety";
     case "worktree-guard":
       return "Checking worktree safety";
+    case "trash-guard":
+      return "Redirecting rm into trash";
     case "stop-sync":
       return "Syncing turn-end heartbeat";
     default:
@@ -6786,14 +6808,32 @@ function detectConflict(name, scope, target) {
       continue;
     if (!getHookEvents(existing).some((event) => events.has(event)))
       continue;
-    const a = meta.matcher.toLowerCase();
-    const b = existing.matcher.toLowerCase();
-    if (a === b || a.includes(b) || b.includes(a)) {
+    if (matchersOverlap(meta.matcher.toLowerCase(), existing.matcher.toLowerCase())) {
       return `conflicts with '${existingName}' (same event ${meta.event}, overlapping matcher '${existing.matcher}')`;
     }
   }
   return;
 }
+function detectRewriteConflict(name, scope, target, lookup = getHook) {
+  const meta = resolveHookMeta(name);
+  if (!meta?.matcher || !meta.rewritesInput)
+    return;
+  if (!getHookEvents(meta).includes("PreToolUse"))
+    return;
+  for (const existingName of getRegisteredHooksForTarget(scope, target)) {
+    if (existingName === name)
+      continue;
+    const existing = lookup(existingName);
+    if (!existing?.matcher || !existing.rewritesInput)
+      continue;
+    if (!getHookEvents(existing).includes("PreToolUse"))
+      continue;
+    if (!matchersOverlap(meta.matcher.toLowerCase(), existing.matcher.toLowerCase()))
+      continue;
+    return `both '${name}' and '${existingName}' rewrite the tool input on overlapping PreToolUse matchers ('${meta.matcher}' / '${existing.matcher}'). Only one rewrite per tool call is applied, so one guard would silently disappear \u2014 install one of them, or narrow a matcher so they no longer overlap.`;
+  }
+  return;
+}
 function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath) {
   const shortName = shortHookName(name);
   if (!hookExists(shortName)) {
@@ -6853,6 +6893,10 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
     return { hook: shortName, success: false, error: "Already installed. Use --overwrite to replace.", scope, target };
   }
   const conflict = detectConflict(shortName, scope, target);
+  const rewriteConflict = detectRewriteConflict(shortName, scope, target);
+  if (rewriteConflict) {
+    return { hook: shortName, success: false, error: `Refused: ${rewriteConflict}`, scope, target };
+  }
   try {
     registerHook(shortName, scope, target, profile);
     return { hook: shortName, success: true, scope, target, ...conflict ? { conflict } : {} };
@@ -6924,8 +6968,12 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   for (const eventKey of uniqueEventKeys) {
     if (!settings.hooks[eventKey])
       settings.hooks[eventKey] = [];
+    const hookEntry = { type: "command", command: hookCommand };
+    if (typeof meta.timeoutSeconds === "number" && meta.timeoutSeconds > 0) {
+      hookEntry.timeout = meta.timeoutSeconds;
+    }
     const entry = {
-      hooks: [{ type: "command", command: hookCommand }]
+      hooks: [hookEntry]
     };
     if (meta.matcher) {
       entry.matcher = meta.matcher;

package/dist/lib/installer.d.ts

@@ -9,7 +9,8 @@
  * Hooks run directly from the globally installed @hasna/hooks package.
  * No files are copied. The settings entry points to `hooks run <name>`.
  */
-import { type HookEvent } from "./registry.js";
+import { type HookEvent, type HookMeta } from "./registry.js";
+import { type StaleRegistration } from "./registration.js";
 export type Scope = "global" | "project";
 export type Target = "claude" | "gemini" | "codewith" | "all";
 type SingleTarget = Exclude<Target, "all">;
@@ -47,6 +48,18 @@ export declare function hookExists(name: string): boolean;
 /** Whether a hook's event can be registered for the given target */
 export declare function isEventSupported(internalEvent: HookEvent, target: SingleTarget): boolean;
 export declare function buildCodewithTomlFragment(name: string, profile?: string): string;
+/**
+ * The one conflict class that BLOCKS an install: two PreToolUse hooks on
+ * overlapping matchers that both rewrite the tool input
+ * (`hookSpecificOutput.updatedInput`). The harness keeps ONE rewrite per tool
+ * call — last writer wins — so whichever guard loses is silently disarmed
+ * with no error anywhere. `trash-guard` is the first such hook.
+ *
+ * Every other conflict stays advisory: it still installs, with the warning.
+ */
+export declare function detectRewriteConflict(name: string, scope: Scope, target: SingleTarget, 
+/** Injected for tests: the rewrite claim is a registry concern, the overlap is not. */
+lookup?: (hookName: string) => HookMeta | undefined): string | undefined;
 export declare function installHook(name: string, options?: InstallOptions): InstallResult;
 export declare function installHooks(names: string[], options?: InstallOptions): InstallResult[];
 export declare function getRegisteredHooksForTarget(scope?: Scope, target?: SingleTarget): string[];
@@ -54,6 +67,32 @@ export declare function getRegisteredHooks(scope?: Scope): string[];
 /** @deprecated Use getRegisteredHooks instead */
 export declare const getInstalledHooks: typeof getRegisteredHooks;
 export declare function removeHook(name: string, scope?: Scope, target?: Target): boolean;
+/**
+ * Every settings registration for the scope whose hook name does not resolve.
+ *
+ * A stale registration makes the agent spawn `hooks run <name>` on every event
+ * it is wired to, and each spawn fails — the failure is invisible to `hooks
+ * install`/`hooks remove` because nothing re-checks names already written.
+ */
+export declare function scanStaleRegistrations(scope?: Scope): StaleRegistration[];
+export interface PruneStaleResult {
+    /** Settings file edited. */
+    file: string;
+    /** The registrations removed from it. */
+    removed: StaleRegistration[];
+    /** Sibling backup of the pre-edit bytes (`<settings>.bak`). */
+    backupPath: string;
+}
+/**
+ * Remove every stale registration the scope carries, and nothing else.
+ *
+ * Edits only the entries whose own command is stale: sibling hooks in the same
+ * entry, unrelated event keys, matchers and every non-hook settings key are
+ * preserved, the file stays valid JSON, and a `.bak` sibling is written before
+ * the edit. Idempotent — a second call finds nothing stale and writes nothing.
+ * A registration whose hook resolves is never touched.
+ */
+export declare function pruneStaleRegistrations(scope?: Scope): PruneStaleResult[];
 export interface UninstallResult {
     name: string;
     removed: boolean;

package/dist/lib/registration.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Settings registration checks shared by the CLI doctor and the MCP
+ * hooks_doctor.
+ *
+ * Event and matcher are separate settings fields — settings.hooks[event] is
+ * an array of { matcher?, hooks: [...] } entries — so a composite event such
+ * as 'PreToolUse:Bash' must be split before lookup, never used as a key.
+ */
+/** A settings registration whose hook name cannot resolve. */
+export interface StaleRegistration {
+    /** Settings file the registration lives in. */
+    file: string;
+    /** Settings event key holding the entry (PreToolUse, …). */
+    event: string;
+    /** The registered hook name that does not resolve. */
+    hook: string;
+    /** The raw command string from the settings entry. */
+    command: string;
+}
+/**
+ * Find settings registrations whose hook does not resolve.
+ *
+ * A registration is a `hooks run <name>` (or legacy `hook-<name>`) command;
+ * it is stale when `resolveHook(name)` finds no bundled, custom or stored
+ * hook — exactly the lookup `hooks run` performs, so a stale registration
+ * fails on every tool call it is wired to. Direct-path wiring outside the
+ * installer's own command forms is reported by `countSettingsWiring`, never
+ * treated as a hook registration.
+ */
+export declare function findStaleRegistrations(settings: Record<string, unknown>, file: string, resolves?: (name: string) => boolean): StaleRegistration[];
+/**
+ * Whether two tool matchers can select the same tool call. Deliberately loose
+ * (identical, or one a substring of the other) — a false positive costs one
+ * advisory warning, a false negative costs a silently disarmed guard.
+ */
+export declare function matchersOverlap(a: string, b: string): boolean;
+/** The metadata slice `findRewriteOverlaps` needs from a hook. */
+export interface RewriteHookInfo {
+    matcher?: string;
+    event?: string;
+    events?: string[];
+    rewritesInput?: boolean;
+}
+/** Two installed hooks that both rewrite the tool input on the same tool. */
+export interface RewriteOverlap {
+    hooks: [string, string];
+    event: string;
+    matchers: [string, string];
+}
+/**
+ * Installed hooks that both rewrite the tool input
+ * (`hookSpecificOutput.updatedInput`) on an overlapping PreToolUse matcher.
+ *
+ * This is a real defect, not a style nit: the harness applies ONE rewrite per
+ * tool call, so one of the two guards is silently disarmed. The installer
+ * refuses the pairing up front; doctor reports it for settings files it did
+ * not write (hand-edited, or written before the rule existed).
+ */
+export declare function findRewriteOverlaps(names: string[], lookup: (name: string) => RewriteHookInfo | undefined): RewriteOverlap[];
+/**
+ * Whether a hook is registered in a settings file.
+ *
+ * An entry matches when it carries a `hooks run <name>` command and, when the
+ * hook declares a matcher, the entry's matcher is absent (fires on all tools)
+ * or consistent with the hook's matcher (equal, or one regex matches the
+ * other).
+ */
+/**
+ * Count every raw hook entry wired in a settings file — including
+ * direct-path entries that never went through the CLI (`command` values that
+ * are not `hooks run <name>`). Doctor reports this count alongside the
+ * registered count so its "healthy" verdict names its bounds (P2-16b).
+ */
+export declare function countSettingsWiring(settings: Record<string, unknown>): number;
+export declare function hookRegisteredInSettings(settings: Record<string, unknown>, name: string, eventSpec: string, hookMatcher: string): boolean;

package/dist/lib/registry.d.ts

@@ -13,6 +13,20 @@ export interface HookMeta {
     events?: HookEvent[];
     matcher: string;
     tags: string[];
+    /**
+     * This hook rewrites the tool input (`hookSpecificOutput.updatedInput`).
+     * The agent harness keeps ONE rewrite per tool call — last writer wins — so
+     * two input-rewriting hooks on overlapping PreToolUse matchers silently
+     * disarm each other. Install refuses that pairing, and `hooks doctor`
+     * reports it.
+     */
+    rewritesInput?: boolean;
+    /**
+     * Timeout (seconds) written into the agent's settings entry for this hook.
+     * The harness default is 600s, and a TIMED-OUT HOOK DOES NOT BLOCK: a guard
+     * that needs a verdict on stdout must declare a timeout it can meet.
+     */
+    timeoutSeconds?: number;
 }
 export declare const CATEGORIES: readonly ["Git Safety", "Code Quality", "Security", "Notifications", "Context Management", "Workflow Automation", "Environment", "Permissions", "Observability", "Agent Teams"];
 export type Category = (typeof CATEGORIES)[number];

package/hooks/hook-agent-rules-version-check/README.md

@@ -43,7 +43,7 @@ export HOOKS_FLEET_TIMEOUT_MS=500               # configs CLI timeout (default 5
 
 ## Requirements
 
-- `configs` CLI (@hasna/configs) — optional; without it the hook falls back to cross-artifact consistency checking
+- `configs` CLI (@hasna/instructions — the package that ships the `configs` bin) — optional; without it the hook falls back to cross-artifact consistency checking
 
 ## Event
 

package/hooks/hook-trash-guard/README.md

@@ -0,0 +1,132 @@
+# trash-guard
+
+Codewith-native hook installed as `hooks run trash-guard`.
+
+PreToolUse guard for `rm` issued through the Bash tool. It rewrites the verb
+into `@hasna/trash`'s guard subcommand — `<abs>/trash guard <same args>` — so
+the delete lands in a trash store and stays recoverable. When there is nothing
+to redirect to, it **refuses** the command.
+
+## The decision, and why it fails the way it does
+
+The block decision is **self-contained**: it never waits on the trash store, a
+network, a credential or the `@hasna/trash` package. The binary is consulted
+only as an opportunistic upgrade:
+
+| `trash` on PATH | verdict |
+|---|---|
+| present | `permissionDecision: "allow"` + `updatedInput` rewriting `rm` to `<abs>/trash guard` |
+| absent | `permissionDecision: "deny"` + a reason telling the agent to install `@hasna/trash` |
+
+There is no third row. It degrades **redirect → block**, never
+**redirect → allow**: a delete this hook cannot redirect is never silently run.
+
+The rewrite emits a **complete** `tool_input` — every key the model supplied,
+plus `command`, `description`, `timeout` and `run_in_background`, plus
+`dangerouslyDisableSandbox` when it was present. That care is deliberate: the
+harness falls back to the **original** tool input when `updatedInput` is
+missing or empty, so a partial rewrite would run the raw `rm`. The hook
+re-scans the rewritten text before allowing it, and if the re-scan still finds
+a live delete verb it denies instead. A command containing both an owned `rm`
+and one handed to another guard is refused rather than partially rewritten.
+
+## What it rewrites
+
+Only `rm`'s own grammar, and only in **command position**: the verb must be the
+command, after any assignment prefixes (`FOO=1 rm …`), shell keywords, and
+recognized wrappers (`sudo`, `doas`, `env`, `nice`, `ionice`, `stdbuf`, `time`,
+`timeout`, `nohup`, `setsid`, `command`, `builtin`, `exec`). Quoting, `~`,
+`$HOME` and `${HOME}` spellings, `--`, redirections and every other byte of the
+command are preserved.
+
+Wrappers that take positional arguments are handled (`timeout 5 rm -rf x`
+rewrites the `rm`, not the duration).
+
+## What it refuses
+
+- `rmdir`, `unlink`, `shred` — their flags and semantics are not `rm`'s.
+- `git rm` (without `--cached`), `git clean` — they delete outside `rm`.
+- `find -delete`, `find -exec rm …`, `xargs rm` — the delete does not run
+  through a verb this hook can swap.
+- A delete inside a command substitution (`$(rm …)`, backticks).
+- `busybox rm` / `toybox rm` — a different applet, not GNU `rm`.
+- Shells and opaque command strings (`sh -c 'rm …'`, `eval`, `su -c …`).
+- An unparseable command (unterminated quote, substitution or here-document)
+  that mentions a delete verb.
+- The protected class, below.
+
+Each refusal carries a reason and a way forward: re-run the delete as
+`rm -- <path>`, which this hook intercepts and redirects.
+
+## The protected class
+
+Refused outright, never redirected (plan §15 decision 11.3):
+
+- the filesystem root and the system roots `pre-bash`'s protected-path rules
+  already name (`/etc`, `/usr`, `/bin`, `/home`, `/var`, …) — the root itself,
+  or any ancestor of it;
+- the home directory itself (`~`, `$HOME`, `${HOME}`);
+- `~/.hasna`, `~/.ssh`, `~/.aws` — the state and credential stores, including
+  everything under them.
+
+These are the catastrophic cases where "move it to trash" is not an acceptable
+answer. Everything else this hook owns is rewritten, not refused.
+
+## Scope: what it deliberately does NOT own
+
+Deletes under the protected repo-checkout roots `$HOME/.hasna/repos/clones` and
+`$HOME/workspace/repos` belong to **`workspace-repos-guard`**, which blocks
+every delete under them at any depth. This hook does not restate that policy:
+it recognizes the boundary and abstains, so the other hook's decision stands.
+A command that mixes a delete inside those roots with one outside is refused,
+because a partial rewrite would leave one of them unredirected.
+
+## Conflict discipline
+
+`trash-guard` declares `rewritesInput: true` in the registry. Two PreToolUse
+hooks on overlapping matchers that both rewrite the tool input are a silent
+data-loss hazard: the harness keeps one rewrite (last writer wins), so the
+losing hook's guard disappears with no error. Installing a second such hook is
+therefore **refused**, and `hooks doctor` reports more than one input-rewriting
+hook on an overlapping matcher. Other overlaps still install with the usual
+advisory warning.
+
+The registration is written with `timeout: 5`. The harness's documented
+default is 600s, and a hook that times out **does not block** — only a verdict
+already on stdout does. Five seconds is several orders of magnitude above this
+hook's measured cost (a single-pass lexer, no process spawns, no I/O beyond
+one `statSync` per PATH entry).
+
+## Known limitations
+
+The guard is a best-effort **text** classifier, not an execution sandbox.
+
+- **Variable indirection is undetectable.** `R=...; rm -rf $R`, a loop over
+  computed paths, or a script downloaded and run at runtime cannot be
+  classified before the shell expands it. This is the same limitation
+  `workspace-repos-guard` documents, and it is inherent to inspecting the
+  command string rather than the syscall. An operand that is a variable or a
+  glob is still **rewritten** (the `trash` binary classifies what the shell
+  actually expands to), but it cannot be checked against the protected class
+  here.
+- **A hook only ever sees the agent's own tool calls.** It cannot stop a file
+  being deleted by another process, by a build tool, by a script the agent
+  runs, or by `unlink(2)` called directly. Coverage is the Bash tool, wave 1,
+  nothing else — `Write`/`Edit` pre-image capture is wave 2.
+- **Nested and generated commands escape it.** `bash -c`, `eval`, `make`,
+  `npm run`, a `Dockerfile`, a heredoc-fed interpreter: the hook can only see
+  that a shell string mentions a delete verb and refuse it, never redirect
+  inside it.
+- **Threat model: accident, not adversary.** A hostile same-user agent can
+  remove the hook, edit the store, or call `unlink(2)` directly; nothing here
+  holds against that.
+- **Fail-closed only for deletes.** On an internal error the hook denies a
+  command that mentions a delete verb and stays silent otherwise, so a guard
+  defect cannot wedge unrelated work. Fail-closed cannot be guaranteed where
+  the harness itself never delivers the hook input.
+
+## Configuration
+
+None. The home directory comes from `os.homedir()`; the trash binary is
+resolved by scanning `PATH` for an executable `trash` and rewriting to the
+absolute path found, so the rewritten command does not depend on `PATH` again.

package/hooks/hook-trash-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "trash-guard",
+  "version": "0.1.0",
+  "description": "Codewith-native Trash Guard hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}