@hasna/hooks 0.10.3 → 0.10.5

package/hooks/hook-trash-guard/src/hook.ts

@@ -47,9 +47,9 @@
  */
 
 import { homedir } from "os";
-import { dirname, isAbsolute, join, normalize, resolve, sep } from "path";
-import { readFileSync, realpathSync, statSync } from "fs";
-import { spawnSync } from "node:child_process";
+import { isAbsolute, join, normalize, resolve, sep } from "path";
+import { BINARY_FAILURES, findTrashBinary, inspectTrashBinary, type TrashBinaryInspection } from "./binary.js";
+export { findTrashBinary, inspectTrashBinary } from "./binary.js";
 import {
   SYSTEM_PROTECTED_ROOTS,
   getCommand,
@@ -876,42 +876,6 @@ function gitHasDryRun(segment: Segment, verbIndex: number): boolean {
 /* Rewrite                                                             */
 /* ------------------------------------------------------------------ */
 
-/**
- * A command called trash may be Apple's unrelated system utility. Resolve
- * package provenance before executing a bounded, credential-free identity
- * probe. Never invoke an unknown executable merely to discover what it is.
- */
-export function findTrashBinary(env: NodeJS.ProcessEnv = process.env): string | null {
-  const pathValue = env.PATH ?? "";
-  const deadline = Date.now() + 2_000;
-  for (const dir of pathValue.split(":").slice(0, 64)) {
-    if (!isAbsolute(dir) || Date.now() >= deadline) continue;
-    const candidate = resolve(dir, "trash");
-    try {
-      const stat = statSync(candidate);
-      if (!stat.isFile() || (stat.mode & 0o111) === 0 || (stat.mode & 0o022) !== 0) continue;
-      const executable = realpathSync(candidate);
-      const packageRoot = resolve(dirname(executable), "../..");
-      const manifestPath = join(packageRoot, "package.json");
-      const manifestStat = statSync(manifestPath);
-      if (!manifestStat.isFile() || manifestStat.size > 16_384 || (manifestStat.mode & 0o022) !== 0) continue;
-      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-      if (manifest.name !== "@hasna/trash" || typeof manifest.version !== "string" ||
-          typeof manifest.bin?.trash !== "string" || realpathSync(resolve(packageRoot, manifest.bin.trash)) !== executable) continue;
-      const probe = spawnSync(candidate, ["--identity"], {
-        encoding: "utf8", timeout: Math.max(1, Math.min(500, deadline - Date.now())), maxBuffer: 2_048,
-        env: { PATH: pathValue }, stdio: ["ignore", "pipe", "pipe"],
-      });
-      if (probe.error || probe.status !== 0) continue;
-      const identity = JSON.parse(probe.stdout);
-      if (identity.name === "@hasna/trash" && identity.version === manifest.version &&
-          identity.guardProtocol === "hasna.trash.guard.v1") return candidate;
-    } catch {
-      // Missing, unrelated, malformed or unresponsive packages are not targets.
-    }
-  }
-  return null;
-}
 
 function shellQuoteWord(word: string): string {
   if (/^[A-Za-z0-9_\-./+=:,@%^]+$/.test(word)) return word;
@@ -922,8 +886,11 @@ function shellQuoteWord(word: string): string {
  * Replace the verb token of every owned `rm` with `<quoted trash> guard`,
  * leaving every other byte of the command untouched.
  */
-export function rewriteCommand(command: string, hits: RmHit[], trashPath: string): string {
-  const replacement = `${shellQuoteWord(trashPath)} guard`;
+export function rewriteCommand(command: string, hits: RmHit[], trashPath: string, execution?: GuardDependencies["execution"]): string {
+  const replacement = execution
+    ? ["/usr/bin/env", "-i", `HOME=${execution.home}`, `PATH=${execution.path}`, `HASNA_TRASH_AGENT=${execution.agent}`,
+      execution.runtime, "--config=/dev/null", "--no-env-file", "--no-macros", "--no-install", trashPath, "guard"].map(shellQuoteWord).join(" ")
+    : `${shellQuoteWord(trashPath)} guard`;
   const ordered = [...hits].sort((a, b) => b.word.start - a.word.start);
   let out = command;
   for (const hit of ordered) {
@@ -991,6 +958,25 @@ export interface GuardDependencies {
   home: string;
   cwd: string;
   findTrash: (env?: NodeJS.ProcessEnv) => string | null;
+  inspectTrash?: (env?: NodeJS.ProcessEnv) => TrashBinaryInspection;
+  /** Only the verified native worker supplies this execution capability. */
+  execution?: { runtime: string; home: string; path: string; agent: string };
+}
+
+/** Environment-changing shell constructs could run before even /usr/bin/env.
+ * Refuse them in execution mode rather than pretending an outer clean env is
+ * enough. Ordinary command/control-flow/quoting stays with the existing lexer. */
+function changesExecutionEnvironment(command: string): boolean {
+  const stateCommands = new Set(["export", "set", "unset", "readonly", "declare", "typeset", "local", "alias", "unalias", "read", "readarray", "mapfile", "getopts", "trap", "enable", "function", "env", "sudo", "doas", "stdbuf"]);
+  const parsed = lexCommand(command);
+  return parsed.segments.some((segment) => {
+    const index = commandWordIndex(segment);
+    const prefix = segment.words.slice(0, index < 0 ? segment.words.length : index);
+    if (prefix.some((word) => ASSIGNMENT_RE.test(decodeWord(word.text)) || stateCommands.has(baseVerb(decodeWord(word.text))))) return true;
+    if (index < 0) return false;
+    const word = segment.words[index]!;
+    return stateCommands.has(baseVerb(decodeWord(word.text))) || /^\s*\(\s*\)\s*\{/.test(command.slice(word.end));
+  });
 }
 
 function deny(reason: string): CodewithHookOutput {
@@ -1025,6 +1011,11 @@ function allowRewrite(updatedInput: Record<string, unknown>): CodewithHookOutput
  */
 function resolveTrash(deps: GuardDependencies): { path: string | null; error: string | null } {
   try {
+    if (deps.inspectTrash) {
+      const inspection = deps.inspectTrash();
+      return inspection.ok ? { path: inspection.path, error: null }
+        : { path: null, error: `${inspection.code}: ${BINARY_FAILURES[inspection.code]}` };
+    }
     return { path: deps.findTrash(), error: null };
   } catch (cause) {
     return { path: null, error: cause instanceof Error ? cause.message : String(cause) };
@@ -1108,8 +1099,12 @@ export function evaluate(input: CodewithHookInput, deps: GuardDependencies): Cod
   }
   const trashPath = trash.path;
 
-  const rewritten = rewriteCommand(command, scanned.rmHits, trashPath);
+  if (deps.execution && changesExecutionEnvironment(command)) {
+    return deny("[trash-guard] A deletion combined with shell environment changes cannot use the verified native execution context. Run the deletion as a separate plain rm command.");
+  }
+  const rewritten = rewriteCommand(command, scanned.rmHits, trashPath, deps.execution);
   const updatedInput = buildUpdatedInput(input.tool_input, rewritten);
+  if (deps.execution) updatedInput.hasna_execution = "hasna.hooks.execution.v1";
 
   if (!updatedInputIsComplete(updatedInput, command, scanned.rmHits, deps.cwd, deps.home)) {
     // Never allow a partial rewrite: the harness falls back to the ORIGINAL
@@ -1137,7 +1132,7 @@ export async function run(): Promise<void> {
   const command = getCommand(input);
   try {
     const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
-    const verdict = evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary });
+    const verdict = evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary });
     // Native Codex rejects `continue` in PreToolUse JSON. Silence is the
     // documented no-op for both Codex and Claude; emit only actual decisions.
     if (!("continue" in verdict && verdict.continue === true)) respond(verdict);

package/hooks/native-safety-entry.ts

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
-import { evaluate as evaluateTrash, findTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
+import { evaluate as evaluateTrash, findTrashBinary, inspectTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
 import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
 import type { CodewithHookInput } from "./codewith-native-common";
 
@@ -13,6 +13,14 @@ if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" ||
   || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
   || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
 if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
+const requestedExecution = (input as CodewithHookInput & { hasna_execution?: { schema: string; agent: string } }).hasna_execution;
+if (requestedExecution !== undefined && (!requestedExecution || Object.keys(requestedExecution).sort().join() !== "agent,schema"
+  || requestedExecution.schema !== "hasna.hooks.execution.v1" || typeof requestedExecution.agent !== "string"
+  || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(requestedExecution.agent))) throw new Error("Invalid execution capability");
+const execution = requestedExecution === undefined ? undefined : {
+  runtime: process.execPath, home: homedir(), path: process.env.PATH!, agent: requestedExecution.agent,
+};
+if (execution && (!isAbsolute(execution.runtime) || !execution.path)) throw new Error("Invalid bound execution context");
 if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
   if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
   const patch = input.tool_input.command ?? input.tool_input.patch;
@@ -24,5 +32,5 @@ const handoff = input.tool_name === "Bash" && scanCommand(input.tool_input.comma
 const verdict = repos.decision === "block"
   ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: repos.reason } }
   : handoff ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "[workspace-repos-guard] Deletion under a protected repository checkout is refused." } }
-  : name === "trash-guard" ? evaluateTrash(input, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary }) : { continue: true };
+  : name === "trash-guard" ? evaluateTrash(input, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary, execution }) : { continue: true };
 process.stdout.write(JSON.stringify({ verdict: "continue" in verdict ? null : verdict }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -20,6 +20,10 @@
     "./storage": {
       "types": "./dist/storage.d.ts",
       "import": "./dist/storage.js"
+    },
+    "./native-safety": {
+      "types": "./dist/native-safety.d.ts",
+      "import": "./dist/native-safety.js"
     }
   },
   "main": "./dist/index.js",
@@ -37,7 +41,7 @@
     "postinstall": "node scripts/ensure-profiles-dir.mjs",
     "scan:artifact": "bun scripts/artifact-scan.ts",
     "prepack": "bun run build && bun run scan:artifact",
-    "build:native-safety": "bun build ./hooks/native-safety-entry.ts --outdir ./bin --target bun --define import.meta.main=false"
+    "build:native-safety": "bun build ./hooks/native-safety-entry.ts --outdir ./bin --target bun --define import.meta.main=false && bun build ./src/native-safety.ts --outdir ./dist --target bun"
   },
   "keywords": [
     "claude-code",

package/scripts/validate-package.ts

@@ -1,6 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { copyFile, mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 type PackageJson = {
@@ -227,10 +227,19 @@ async function validatePackedNativeSafety(packageDir: string, smokeDir: string):
   const home = join(smokeDir, "native-safety-home");
   await mkdir(home, { mode: 0o700 });
   const settings = join(home, ".codex", "hooks.json");
+  // The supervisor retains its install-time runtime directory. A station's Bun
+  // directory may also contain Trash, so isolate the runtime for this negative
+  // control instead of inheriting the station's executable lookup.
+  const runtimeDir = join(smokeDir, "native-runtime");
+  await mkdir(runtimeDir, { mode: 0o700 });
+  const runtime = join(runtimeDir, "bun");
+  await copyFile(await realpath(process.execPath), runtime);
+  // An unrelated system trash utility remains subject to the package
+  // provenance check; only a verified @hasna/trash is a supported guard.
   const env: NodeJS.ProcessEnv = { ...process.env, HOME: home, HASNA_STATION: "no-such-station", HASNA_HOOKS_CODEX_SETTINGS_PATH: settings };
   for (const key of Object.keys(env)) if (/^(HASNA_HOOKS_|HOOKS_)/.test(key) && key !== "HASNA_HOOKS_CODEX_SETTINGS_PATH") delete env[key];
   const cli = join(packageDir, "bin/index.js");
-  const installed = spawnSync(process.execPath, [cli, "safety", "install", "trash-guard", "--target", "codex"], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  const installed = spawnSync(runtime, [cli, "safety", "install", "trash-guard", "--target", "codex"], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
   if (installed.status !== 0 || !JSON.parse(installed.stdout).success) throw new Error("Packed native safety registration failed");
   if (existsSync(join(home, ".hasna", "hooks"))) throw new Error("Stateless safety registration created app state");
   const native = JSON.parse(await readFile(settings, "utf8"));
@@ -243,7 +252,7 @@ async function validatePackedNativeSafety(packageDir: string, smokeDir: string):
   if (refused.status !== 0 || JSON.parse(refused.stdout).hookSpecificOutput.permissionDecision !== "deny") throw new Error("Packed native missing-Trash refusal failed");
   const probe = join(smokeDir, "native-registration.ts");
   await writeFile(probe, `import { getRegisteredHooksForTarget } from "@hasna/hooks"; console.log(JSON.stringify(getRegisteredHooksForTarget("global", "codex")));`);
-  const listed = spawnSync(process.execPath, [probe], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  const listed = spawnSync(runtime, [probe], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
   if (listed.status !== 0 || JSON.stringify(JSON.parse(listed.stdout)) !== '["trash-guard"]') throw new Error("Packed SDK cannot recognize the compiled CLI safety registration");
   const worker = join(packageDir, "bin/native-safety-entry.js");
   const bytes = await readFile(worker);