@soleri/cli 9.0.1 → 9.2.0

package/src/hook-packs/installer.ts

@@ -1,128 +1,241 @@
 /**
- * Hook pack installer — copies hookify files to ~/.claude/ (global) or project .claude/ (local).
+ * Hook pack installer — copies hookify files and scripts to ~/.claude/ (global) or project .claude/ (local).
+ * Also manages lifecycle hooks in ~/.claude/settings.json.
  */
-import { existsSync, copyFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import {
+  existsSync,
+  copyFileSync,
+  unlinkSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+} from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { getPack } from './registry.js';
+import type { HookPackLifecycleHook } from './registry.js';
+
+const PACK_MARKER = '_soleriPack';
 
-/** Resolve the target .claude/ directory. */
 function resolveClaudeDir(projectDir?: string): string {
   if (projectDir) return join(projectDir, '.claude');
   return join(homedir(), '.claude');
 }
 
-/**
- * Resolve all hookify file paths for a pack, handling composed packs.
- * Returns a map of hook name → source file path.
- */
 function resolveHookFiles(packName: string): Map<string, string> {
   const pack = getPack(packName);
   if (!pack) return new Map();
-
   const files = new Map<string, string>();
-
   if (pack.manifest.composedFrom) {
-    // Composed pack: gather files from constituent packs
     for (const subPackName of pack.manifest.composedFrom) {
       const subFiles = resolveHookFiles(subPackName);
-      for (const [hook, path] of subFiles) {
-        files.set(hook, path);
-      }
+      for (const [hook, path] of subFiles) { files.set(hook, path); }
     }
   } else {
-    // Direct pack: look for hookify files in the pack directory
     for (const hook of pack.manifest.hooks) {
       const filePath = join(pack.dir, `hookify.${hook}.local.md`);
-      if (existsSync(filePath)) {
-        files.set(hook, filePath);
+      if (existsSync(filePath)) { files.set(hook, filePath); }
+    }
+  }
+  return files;
+}
+
+function resolveScripts(packName: string): Map<string, { sourcePath: string; targetDir: string; file: string }> {
+  const pack = getPack(packName);
+  if (!pack) return new Map();
+  const scripts = new Map<string, { sourcePath: string; targetDir: string; file: string }>();
+  if (pack.manifest.composedFrom) {
+    for (const subPackName of pack.manifest.composedFrom) {
+      const subScripts = resolveScripts(subPackName);
+      for (const [name, info] of subScripts) { scripts.set(name, info); }
+    }
+  } else if (pack.manifest.scripts) {
+    for (const script of pack.manifest.scripts) {
+      const sourcePath = join(pack.dir, 'scripts', script.file);
+      if (existsSync(sourcePath)) {
+        scripts.set(script.name, { sourcePath, targetDir: script.targetDir, file: script.file });
       }
     }
   }
+  return scripts;
+}
 
-  return files;
+function resolveLifecycleHooks(packName: string): { packName: string; hook: HookPackLifecycleHook }[] {
+  const pack = getPack(packName);
+  if (!pack) return [];
+  const hooks: { packName: string; hook: HookPackLifecycleHook }[] = [];
+  if (pack.manifest.composedFrom) {
+    for (const subPackName of pack.manifest.composedFrom) { hooks.push(...resolveLifecycleHooks(subPackName)); }
+  } else if (pack.manifest.lifecycleHooks) {
+    for (const hook of pack.manifest.lifecycleHooks) { hooks.push({ packName: pack.manifest.name, hook }); }
+  }
+  return hooks;
+}
+
+interface SettingsHookEntry { type: 'command'; command: string; timeout?: number; [key: string]: unknown; }
+
+function readClaudeSettings(claudeDir: string): Record<string, unknown> {
+  const settingsPath = join(claudeDir, 'settings.json');
+  if (!existsSync(settingsPath)) return {};
+  try { return JSON.parse(readFileSync(settingsPath, 'utf-8')); } catch { return {}; }
+}
+
+function writeClaudeSettings(claudeDir: string, settings: Record<string, unknown>): void {
+  const settingsPath = join(claudeDir, 'settings.json');
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+
+function addLifecycleHooks(claudeDir: string, lifecycleHooks: { packName: string; hook: HookPackLifecycleHook }[]): string[] {
+  if (lifecycleHooks.length === 0) return [];
+  const settings = readClaudeSettings(claudeDir);
+  const hooks = (settings['hooks'] ?? {}) as Record<string, unknown>;
+  const added: string[] = [];
+  for (const { packName: sourcePack, hook } of lifecycleHooks) {
+    const eventKey = hook.event;
+    const eventHooks = (hooks[eventKey] ?? []) as SettingsHookEntry[];
+    const alreadyExists = eventHooks.some((h) => h.command === hook.command && h[PACK_MARKER] === sourcePack);
+    if (!alreadyExists) {
+      const entry: SettingsHookEntry = { type: hook.type, command: hook.command, [PACK_MARKER]: sourcePack };
+      if (hook.timeout) { entry.timeout = hook.timeout; }
+      eventHooks.push(entry);
+      hooks[eventKey] = eventHooks;
+      added.push(`${eventKey}:${hook.matcher}`);
+    }
+  }
+  settings['hooks'] = hooks;
+  writeClaudeSettings(claudeDir, settings);
+  return added;
+}
+
+function removeLifecycleHooks(claudeDir: string, packName: string): string[] {
+  const settings = readClaudeSettings(claudeDir);
+  const hooks = (settings['hooks'] ?? {}) as Record<string, SettingsHookEntry[]>;
+  const removed: string[] = [];
+  for (const [eventKey, eventHooks] of Object.entries(hooks)) {
+    if (!Array.isArray(eventHooks)) continue;
+    const before = eventHooks.length;
+    const filtered = eventHooks.filter((h) => h[PACK_MARKER] !== packName);
+    if (filtered.length < before) {
+      removed.push(eventKey);
+      if (filtered.length === 0) { delete hooks[eventKey]; } else { hooks[eventKey] = filtered; }
+    }
+  }
+  if (removed.length > 0) { settings['hooks'] = hooks; writeClaudeSettings(claudeDir, settings); }
+  return removed;
 }
 
-/**
- * Install a hook pack to ~/.claude/ (default) or project .claude/ (--project).
- * Skips files that already exist (idempotent).
- */
 export function installPack(
   packName: string,
   options?: { projectDir?: string },
-): { installed: string[]; skipped: string[] } {
+): { installed: string[]; skipped: string[]; scripts: string[]; lifecycleHooks: string[] } {
   const pack = getPack(packName);
-  if (!pack) {
-    throw new Error(`Unknown hook pack: "${packName}"`);
-  }
-
+  if (!pack) { throw new Error(`Unknown hook pack: "${packName}"`); }
   const claudeDir = resolveClaudeDir(options?.projectDir);
   mkdirSync(claudeDir, { recursive: true });
-
   const hookFiles = resolveHookFiles(packName);
   const installed: string[] = [];
   const skipped: string[] = [];
-
   for (const [hook, sourcePath] of hookFiles) {
     const destPath = join(claudeDir, `hookify.${hook}.local.md`);
-    if (existsSync(destPath)) {
-      skipped.push(hook);
-    } else {
-      copyFileSync(sourcePath, destPath);
-      installed.push(hook);
-    }
+    if (existsSync(destPath)) { skipped.push(hook); } else { copyFileSync(sourcePath, destPath); installed.push(hook); }
   }
-
-  return { installed, skipped };
+  const scriptFiles = resolveScripts(packName);
+  const installedScripts: string[] = [];
+  for (const [, { sourcePath, targetDir, file }] of scriptFiles) {
+    const destDir = join(claudeDir, targetDir);
+    mkdirSync(destDir, { recursive: true });
+    const destPath = join(destDir, file);
+    copyFileSync(sourcePath, destPath);
+    chmodSync(destPath, 0o755);
+    installedScripts.push(`${targetDir}/${file}`);
+  }
+  const lcHooks = resolveLifecycleHooks(packName);
+  const addedHooks = addLifecycleHooks(claudeDir, lcHooks);
+  return { installed, skipped, scripts: installedScripts, lifecycleHooks: addedHooks };
 }
 
-/**
- * Remove a hook pack's files from target directory.
- */
 export function removePack(
   packName: string,
   options?: { projectDir?: string },
-): { removed: string[] } {
+): { removed: string[]; scripts: string[]; lifecycleHooks: string[] } {
   const pack = getPack(packName);
-  if (!pack) {
-    throw new Error(`Unknown hook pack: "${packName}"`);
-  }
-
+  if (!pack) { throw new Error(`Unknown hook pack: "${packName}"`); }
   const claudeDir = resolveClaudeDir(options?.projectDir);
   const removed: string[] = [];
-
   for (const hook of pack.manifest.hooks) {
     const filePath = join(claudeDir, `hookify.${hook}.local.md`);
-    if (existsSync(filePath)) {
-      unlinkSync(filePath);
-      removed.push(hook);
+    if (existsSync(filePath)) { unlinkSync(filePath); removed.push(hook); }
+  }
+  const removedScripts: string[] = [];
+  if (pack.manifest.scripts) {
+    for (const script of pack.manifest.scripts) {
+      const filePath = join(claudeDir, script.targetDir, script.file);
+      if (existsSync(filePath)) { unlinkSync(filePath); removedScripts.push(`${script.targetDir}/${script.file}`); }
     }
   }
-
-  return { removed };
+  if (pack.manifest.composedFrom) {
+    for (const subPackName of pack.manifest.composedFrom) {
+      const subPack = getPack(subPackName);
+      if (subPack?.manifest.scripts) {
+        for (const script of subPack.manifest.scripts) {
+          const filePath = join(claudeDir, script.targetDir, script.file);
+          if (existsSync(filePath)) { unlinkSync(filePath); removedScripts.push(`${script.targetDir}/${script.file}`); }
+        }
+      }
+    }
+  }
+  const removedHooks = removeLifecycleHooks(claudeDir, packName);
+  if (pack.manifest.composedFrom) {
+    for (const subPackName of pack.manifest.composedFrom) { removedHooks.push(...removeLifecycleHooks(claudeDir, subPackName)); }
+  }
+  return { removed, scripts: removedScripts, lifecycleHooks: removedHooks };
 }
 
-/**
- * Check if a pack is installed.
- * Returns true (all hooks present), false (none present), or 'partial'.
- */
 export function isPackInstalled(
   packName: string,
   options?: { projectDir?: string },
 ): boolean | 'partial' {
   const pack = getPack(packName);
   if (!pack) return false;
-
   const claudeDir = resolveClaudeDir(options?.projectDir);
+  let total = 0;
   let present = 0;
-
   for (const hook of pack.manifest.hooks) {
-    if (existsSync(join(claudeDir, `hookify.${hook}.local.md`))) {
-      present++;
+    total++;
+    if (existsSync(join(claudeDir, `hookify.${hook}.local.md`))) { present++; }
+  }
+  if (pack.manifest.scripts) {
+    for (const script of pack.manifest.scripts) {
+      total++;
+      if (existsSync(join(claudeDir, script.targetDir, script.file))) { present++; }
     }
   }
-
+  if (pack.manifest.composedFrom) {
+    for (const subPackName of pack.manifest.composedFrom) {
+      const subPack = getPack(subPackName);
+      if (subPack?.manifest.scripts) {
+        for (const script of subPack.manifest.scripts) {
+          total++;
+          if (existsSync(join(claudeDir, script.targetDir, script.file))) { present++; }
+        }
+      }
+    }
+  }
+  if (total === 0) {
+    const lcHooks = resolveLifecycleHooks(packName);
+    if (lcHooks.length > 0) {
+      const settings = readClaudeSettings(claudeDir);
+      const hooksObj = (settings['hooks'] ?? {}) as Record<string, SettingsHookEntry[]>;
+      for (const { packName: sourcePack, hook } of lcHooks) {
+        total++;
+        const eventHooks = hooksObj[hook.event];
+        if (Array.isArray(eventHooks) && eventHooks.some((h) => h.command === hook.command && h[PACK_MARKER] === sourcePack)) { present++; }
+      }
+    }
+  }
+  if (total === 0) return false;
   if (present === 0) return false;
-  if (present === pack.manifest.hooks.length) return true;
+  if (present === total) return true;
   return 'partial';
 }

package/src/hook-packs/registry.ts

@@ -6,73 +6,65 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
-interface HookPackManifest {
+export interface HookPackScript {
+  name: string;
+  file: string;
+  targetDir: string;
+}
+
+export interface HookPackLifecycleHook {
+  event: string;
+  matcher: string;
+  type: 'command';
+  command: string;
+  timeout?: number;
+  statusMessage?: string;
+}
+
+export interface HookPackManifest {
   name: string;
   description: string;
   hooks: string[];
   composedFrom?: string[];
   version?: string;
-  /** Whether this pack is built-in or user-defined */
+  scripts?: HookPackScript[];
+  lifecycleHooks?: HookPackLifecycleHook[];
   source?: 'built-in' | 'local';
 }
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/** Root directory containing all built-in hook packs. */
-function getBuiltinRoot(): string {
-  return __dirname;
-}
-
-/** Local custom packs directory. */
-function getLocalRoot(): string {
-  return join(process.cwd(), '.soleri', 'hook-packs');
-}
+function getBuiltinRoot(): string { return __dirname; }
+function getLocalRoot(): string { return join(process.cwd(), '.soleri', 'hook-packs'); }
 
-/** Scan a directory for pack manifests. */
 function scanPacksDir(root: string, source: 'built-in' | 'local'): HookPackManifest[] {
   if (!existsSync(root)) return [];
   const entries = readdirSync(root, { withFileTypes: true });
   const packs: HookPackManifest[] = [];
-
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const manifestPath = join(root, entry.name, 'manifest.json');
     if (!existsSync(manifestPath)) continue;
-
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as HookPackManifest;
       manifest.source = source;
       packs.push(manifest);
-    } catch {
-      // Skip malformed manifests
-    }
+    } catch { /* Skip malformed manifests */ }
   }
-
   return packs;
 }
 
-/**
- * List all available hook packs (built-in + local custom).
- * Local packs in .soleri/hook-packs/ override built-in packs with the same name.
- */
 export function listPacks(): HookPackManifest[] {
   const builtIn = scanPacksDir(getBuiltinRoot(), 'built-in');
   const local = scanPacksDir(getLocalRoot(), 'local');
-
-  // Local packs override built-in packs with same name
   const byName = new Map<string, HookPackManifest>();
   for (const pack of builtIn) byName.set(pack.name, pack);
   for (const pack of local) byName.set(pack.name, pack);
-
   return Array.from(byName.values());
 }
 
-/**
- * Get a specific pack by name. Local packs take precedence.
- */
 export function getPack(name: string): { manifest: HookPackManifest; dir: string } | null {
-  // Check local first
   const localDir = join(getLocalRoot(), name);
   const localManifest = join(localDir, 'manifest.json');
   if (existsSync(localManifest)) {
@@ -80,41 +72,36 @@ export function getPack(name: string): { manifest: HookPackManifest; dir: string
       const manifest = JSON.parse(readFileSync(localManifest, 'utf-8')) as HookPackManifest;
       manifest.source = 'local';
       return { manifest, dir: localDir };
-    } catch {
-      // Fall through to built-in
-    }
+    } catch { /* Fall through */ }
   }
-
-  // Then built-in
   const builtinDir = join(getBuiltinRoot(), name);
   const builtinManifest = join(builtinDir, 'manifest.json');
   if (!existsSync(builtinManifest)) return null;
-
   try {
     const manifest = JSON.parse(readFileSync(builtinManifest, 'utf-8')) as HookPackManifest;
     manifest.source = 'built-in';
     return { manifest, dir: builtinDir };
-  } catch {
-    return null;
-  }
+  } catch { return null; }
 }
 
-/**
- * Get names of packs that are fully installed in ~/.claude/.
- */
 export function getInstalledPacks(): string[] {
   const claudeDir = join(homedir(), '.claude');
   const packs = listPacks();
   const installed: string[] = [];
-
   for (const pack of packs) {
+    if (pack.hooks.length === 0) {
+      if (pack.scripts && pack.scripts.length > 0) {
+        const allScripts = pack.scripts.every((script) =>
+          existsSync(join(claudeDir, script.targetDir, script.file)),
+        );
+        if (allScripts) { installed.push(pack.name); }
+      }
+      continue;
+    }
     const allPresent = pack.hooks.every((hook) =>
       existsSync(join(claudeDir, `hookify.${hook}.local.md`)),
     );
-    if (allPresent) {
-      installed.push(pack.name);
-    }
+    if (allPresent) { installed.push(pack.name); }
   }
-
   return installed;
 }

package/src/hook-packs/yolo-safety/manifest.json

@@ -0,0 +1,23 @@
+{
+  "name": "yolo-safety",
+  "version": "1.0.0",
+  "description": "Anti-deletion guardrail for YOLO mode — intercepts destructive commands, stages files for review",
+  "hooks": [],
+  "scripts": [
+    {
+      "name": "anti-deletion",
+      "file": "anti-deletion.sh",
+      "targetDir": "hooks"
+    }
+  ],
+  "lifecycleHooks": [
+    {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "type": "command",
+      "command": "bash ~/.claude/hooks/anti-deletion.sh",
+      "timeout": 10,
+      "statusMessage": "Checking for destructive commands..."
+    }
+  ]
+}

package/src/hook-packs/yolo-safety/scripts/anti-deletion.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# Anti-Deletion Staging Hook for Claude Code (Soleri Hook Pack: yolo-safety)
+# PreToolUse -> Bash: intercepts rm, rmdir, mv (of project dirs), git clean, reset --hard
+# Copies target files to ~/.soleri/staging/<timestamp>/ then blocks the command.
+#
+# Catastrophic commands (rm -rf /, rm -rf ~) should stay in deny rules —
+# this hook handles targeted deletes only.
+#
+# Dependencies: jq (required), perl (optional, for heredoc stripping)
+
+set -euo pipefail
+
+STAGING_ROOT="$HOME/.soleri/staging"
+PROJECTS_DIR="$HOME/projects"
+INPUT=$(cat)
+
+# Extract the command from stdin JSON
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# No command found — let it through
+if [ -z "$CMD" ]; then
+  exit 0
+fi
+
+# --- Strip heredocs and quoted strings to avoid false positives ---
+# Commands like: gh issue comment --body "$(cat <<'EOF' ... rmdir ... EOF)"
+# contain destructive keywords in text, not as actual commands.
+
+# Remove heredoc blocks: <<'EOF'...EOF and <<EOF...EOF (multiline)
+STRIPPED=$(echo "$CMD" | perl -0777 -pe "s/<<'?\\w+'?.*?^\\w+$//gms" 2>/dev/null || echo "$CMD")
+# Remove double-quoted strings (greedy but good enough for this check)
+STRIPPED=$(echo "$STRIPPED" | sed -E 's/"[^"]*"//g' 2>/dev/null || echo "$STRIPPED")
+# Remove single-quoted strings
+STRIPPED=$(echo "$STRIPPED" | sed -E "s/'[^']*'//g" 2>/dev/null || echo "$STRIPPED")
+
+# --- Detect destructive commands (on stripped command only) ---
+
+IS_RM=false
+IS_RMDIR=false
+IS_MV_PROJECT=false
+IS_GIT_CLEAN=false
+IS_RESET_HARD=false
+IS_GIT_CHECKOUT_DOT=false
+IS_GIT_RESTORE_DOT=false
+
+# Check for rm commands (but not git rm which is safe — it stages, doesn't destroy)
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)rm\s'; then
+  if ! echo "$STRIPPED" | grep -qE '(^|\s)git\s+rm\s'; then
+    IS_RM=true
+  fi
+fi
+
+# Check for rmdir commands
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)rmdir\s'; then
+  IS_RMDIR=true
+fi
+
+# Check for mv commands that move project directories or git repos
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)mv\s'; then
+  MV_SOURCES=$(echo "$STRIPPED" | sed -E 's/^.*\bmv\s+//' | sed -E 's/-(f|i|n|v)\s+//g')
+  if echo "$MV_SOURCES" | grep -qE "(~/projects|$HOME/projects|\\\$HOME/projects|\\.git)"; then
+    IS_MV_PROJECT=true
+  fi
+fi
+
+# Check for git clean
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)git\s+clean\b'; then
+  IS_GIT_CLEAN=true
+fi
+
+# Check for git reset --hard
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)git\s+reset\s+--hard'; then
+  IS_RESET_HARD=true
+fi
+
+# Check for git checkout -- . (restores all files, discards changes)
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)git\s+checkout\s+--\s+\.'; then
+  IS_GIT_CHECKOUT_DOT=true
+fi
+
+# Check for git restore . (restores all files, discards changes)
+if echo "$STRIPPED" | grep -qE '(^|\s|;|&&|\|\|)git\s+restore\s+\.'; then
+  IS_GIT_RESTORE_DOT=true
+fi
+
+# Not a destructive command — let it through
+if [ "$IS_RM" = false ] && [ "$IS_RMDIR" = false ] && [ "$IS_MV_PROJECT" = false ] && \
+   [ "$IS_GIT_CLEAN" = false ] && [ "$IS_RESET_HARD" = false ] && \
+   [ "$IS_GIT_CHECKOUT_DOT" = false ] && [ "$IS_GIT_RESTORE_DOT" = false ]; then
+  exit 0
+fi
+
+# --- Handle git clean (block outright) ---
+
+if [ "$IS_GIT_CLEAN" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: git clean would remove untracked files. Use git stash --include-untracked to save them first, or ask the user to run git clean manually."
+  }'
+  exit 0
+fi
+
+# --- Handle git reset --hard (block outright) ---
+
+if [ "$IS_RESET_HARD" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: git reset --hard would discard uncommitted changes. Use git stash to save them first, or ask the user to run this manually."
+  }'
+  exit 0
+fi
+
+# --- Handle git checkout -- . (block outright) ---
+
+if [ "$IS_GIT_CHECKOUT_DOT" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: git checkout -- . would discard all uncommitted changes. Use git stash to save them first, or ask the user to run this manually."
+  }'
+  exit 0
+fi
+
+# --- Handle git restore . (block outright) ---
+
+if [ "$IS_GIT_RESTORE_DOT" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: git restore . would discard all uncommitted changes. Use git stash to save them first, or ask the user to run this manually."
+  }'
+  exit 0
+fi
+
+# --- Handle mv of project directories (block outright) ---
+
+if [ "$IS_MV_PROJECT" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: mv of a project directory or git repo detected. Moving project directories can cause data loss if the operation fails midway. Ask the user to run this manually, or use cp + verify + rm instead."
+  }'
+  exit 0
+fi
+
+# --- Handle rmdir (block outright) ---
+
+if [ "$IS_RMDIR" = true ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: rmdir detected. Removing directories can break project structure. Ask the user to confirm this operation manually."
+  }'
+  exit 0
+fi
+
+# --- Handle rm commands — copy to staging, then block ---
+
+# Create timestamped staging directory
+TIMESTAMP=$(date +%Y-%m-%d_%H%M%S)
+STAGE_DIR="$STAGING_ROOT/$TIMESTAMP"
+
+# Extract file paths from the rm command
+# Strip rm and its flags, keeping only the file arguments
+FILES=$(echo "$CMD" | sed -E 's/^.*\brm\s+//' | sed -E 's/-(r|f|rf|fr|v|i|rv|fv|rfv|frv)\s+//g' | tr ' ' '\n' | grep -v '^-' | grep -v '^$')
+
+if [ -z "$FILES" ]; then
+  jq -n '{
+    continue: false,
+    stopReason: "BLOCKED: rm command detected but could not parse file targets. Please specify files explicitly."
+  }'
+  exit 0
+fi
+
+STAGED=()
+MISSING=()
+
+mkdir -p "$STAGE_DIR"
+
+while IFS= read -r filepath; do
+  # Expand path (handle ~, relative paths)
+  expanded=$(eval echo "$filepath" 2>/dev/null || echo "$filepath")
+
+  if [ -e "$expanded" ]; then
+    # Preserve directory structure in staging
+    target_dir="$STAGE_DIR/$(dirname "$expanded")"
+    mkdir -p "$target_dir"
+    # COPY instead of MOVE — originals stay intact, staging is a backup
+    if [ -d "$expanded" ]; then
+      cp -R "$expanded" "$target_dir/" 2>/dev/null && STAGED+=("$expanded") || MISSING+=("$expanded")
+    else
+      cp "$expanded" "$target_dir/" 2>/dev/null && STAGED+=("$expanded") || MISSING+=("$expanded")
+    fi
+  else
+    MISSING+=("$expanded")
+  fi
+done <<< "$FILES"
+
+# Build response
+STAGED_COUNT=${#STAGED[@]}
+MISSING_COUNT=${#MISSING[@]}
+
+if [ "$STAGED_COUNT" -eq 0 ] && [ "$MISSING_COUNT" -gt 0 ]; then
+  # All files were missing — let the rm fail naturally
+  rmdir "$STAGE_DIR" 2>/dev/null || true
+  exit 0
+fi
+
+STAGED_LIST=$(printf '%s, ' "${STAGED[@]}" | sed 's/, $//')
+
+jq -n \
+  --arg staged "$STAGED_LIST" \
+  --arg dir "$STAGE_DIR" \
+  --argjson count "$STAGED_COUNT" \
+  '{
+    continue: false,
+    stopReason: ("BLOCKED & BACKED UP: " + ($count | tostring) + " item(s) copied to " + $dir + " — files: " + $staged + ". The originals are untouched. To proceed with deletion, ask the user to run the rm command manually.")
+  }'