@node9/proxy 1.9.1 → 1.9.3

package/README.md

@@ -3,7 +3,7 @@
 ### The "Sudo" Command for AI Agents.
 
 [![NPM Version](https://img.shields.io/npm/v/@node9/proxy.svg)](https://www.npmjs.com/package/@node9/proxy)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Open in HF Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/Node9ai/node9-security-demo)
 [![Documentation](https://img.shields.io/badge/docs-node9.ai%2Fdocs-blue)](https://node9.ai/docs)
 
@@ -15,18 +15,18 @@
 
 ## The "Aha!" Moment
 
-**AIs are literal.** Ask an agent to "fix disk space" and it might run `docker system prune -af --volumes`.
+**AIs move fast.** Ask an agent to "ship the fix" and it might push straight to git without asking you.
 
 <p align="center">
-  <img src="https://github.com/user-attachments/assets/7b22e0fb-35ff-4088-8ee9-cc23216f362f" width="100%">
+  <img src="https://github.com/user-attachments/assets/4aa6e45b-9aba-4953-9ce3-548226622588" width="100%">
 </p>
 
 With Node9:
 
-1. **AI attempts:** `Bash("docker system prune -af --volumes")`
+1. **AI attempts:** `Bash("git push origin main")`
 2. **Node9 intercepts:** OS-native popup appears instantly
 3. **You block it** — one click
-4. **AI pivots:** _"I'll remove large log files instead"_
+4. **AI pivots:** _"I'll create a PR for review instead"_
 
 ---
 
@@ -128,6 +128,26 @@ configure(agent_name="my-agent", policy="require_approval")
 
 ---
 
+## Flight Recorder & HUD
+
+Every tool call your AI agent makes is recorded — command, arguments, result, and cost estimate. Node9 wires a live statusline into Claude Code that shows you what's happening in real time:
+
+```
+🛡 node9 | standard | [bash-safe] | ✅ 12 allowed  🛑 2 blocked  🚨 0 dlp | ~$0.43 | ⚡ no-force-push
+📊 claude-opus-4-6 | ctx [████████░░░░░░░] 54% | 5h [██░░░░░░░░░░░░░] 12% | 7d [█░░░░░░░░░░░░░░] 7%
+🗂 2 CLAUDE.md | 8 rules | 3 MCPs | 4 hooks
+```
+
+**Line 1 — Security state:** active mode, enabled shields, session totals (allowed / blocked / DLP hits), estimated cost, last rule that fired.
+
+**Line 2 — Context & rate limits:** model name, context window usage, 5-hour and 7-day token rate-limit bars — so you can see when an agent is burning through quota.
+
+**Line 3 — Environment:** how many CLAUDE.md files, rules, MCP servers, and hooks are active in the current project.
+
+The HUD is wired automatically by `node9 setup`. Full session logs land in `~/.node9/audit.log`.
+
+---
+
 ## 📖 Full docs
 
 Everything else — config reference, smart rules, stateful rules, trusted hosts, approval modes, CLI reference — is at **[node9.ai/docs](https://node9.ai/docs)**.

package/dist/cli.js

@@ -214,6 +214,7 @@ var init_config_schema = __esm({
         errorMap: () => ({ message: "verdict must be one of: allow, review, block" })
       }),
       reason: import_zod.z.string().optional(),
+      description: import_zod.z.string().optional(),
       // Unknown predicate names are filtered out rather than failing the whole rule.
       // Failing the whole z.array() would cause sanitizeConfig to drop the entire
       // `policy` top-level key, silently disabling ALL smart rules in the config.
@@ -791,7 +792,8 @@ var init_config = __esm({
               }
             ],
             verdict: "block",
-            reason: "Recursive delete of home directory is irreversible"
+            reason: "Recursive delete of home directory is irreversible",
+            description: "The AI wants to recursively delete your home directory. This will permanently destroy all your personal files and cannot be undone."
           },
           // ── SQL safety ────────────────────────────────────────────────────────
           {
@@ -803,7 +805,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table"
+            reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table",
+            description: "The AI is running a SQL statement that will modify every row in the table \u2014 no WHERE filter was found. This could wipe or corrupt all your data."
           },
           {
             name: "review-drop-truncate-shell",
@@ -818,7 +821,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "SQL DDL destructive statement inside a shell command"
+            reason: "SQL DDL destructive statement inside a shell command",
+            description: "The AI wants to drop or truncate a database table via the shell. This permanently deletes the table structure or all its data."
           },
           // ── Git safety ────────────────────────────────────────────────────────
           {
@@ -834,7 +838,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "block",
-            reason: "Force push overwrites remote history and cannot be undone"
+            reason: "Force push overwrites remote history and cannot be undone",
+            description: "The AI wants to force push to a remote git branch. This rewrites shared history and can permanently destroy commits that teammates have already pulled."
           },
           {
             name: "review-git-push",
@@ -849,7 +854,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "git push sends changes to a shared remote"
+            reason: "git push sends changes to a shared remote",
+            description: "The AI wants to push commits to a remote repository. Once pushed, those changes are visible to everyone with access."
           },
           {
             name: "review-git-destructive",
@@ -864,7 +870,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "Destructive git operation \u2014 discards history or working-tree changes"
+            reason: "Destructive git operation \u2014 discards history or working-tree changes",
+            description: "The AI wants to run a destructive git operation (reset, rebase, clean, or branch delete) that can permanently discard commits or uncommitted work."
           },
           // ── Shell safety ──────────────────────────────────────────────────────
           {
@@ -873,7 +880,8 @@ var init_config = __esm({
             conditions: [{ field: "command", op: "matches", value: "\\bsudo\\s", flags: "i" }],
             conditionMode: "all",
             verdict: "review",
-            reason: "Command requires elevated privileges"
+            reason: "Command requires elevated privileges",
+            description: "The AI wants to run a command as root (sudo). Commands with root access can modify system files, install software, or change security settings."
           },
           {
             name: "review-curl-pipe-shell",
@@ -888,7 +896,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "block",
-            reason: "Piping remote script into a shell is a supply-chain attack vector"
+            reason: "Piping remote script into a shell is a supply-chain attack vector",
+            description: "The AI wants to download a script from the internet and run it immediately, without you seeing what it contains. This is one of the most common ways malware gets installed."
           }
         ],
         dlp: { enabled: true, scanIgnoredTools: true }
@@ -921,7 +930,8 @@ var init_config = __esm({
         tool: "*",
         conditions: [{ field: "command", op: "matches", value: "(^|&&|\\|\\||;)\\s*rm\\b" }],
         verdict: "review",
-        reason: "rm can permanently delete files \u2014 confirm the target path"
+        reason: "rm can permanently delete files \u2014 confirm the target path",
+        description: "The AI wants to delete files. Unlike moving to trash, rm is permanent \u2014 the files cannot be recovered without a backup."
       },
       // ── SQL safety (Safe by Default) ──────────────────────────────────────────
       // These rules fire when an AI calls a database tool directly (e.g. MCP postgres,
@@ -933,14 +943,16 @@ var init_config = __esm({
         tool: "*",
         conditions: [{ field: "sql", op: "matches", value: "DROP\\s+TABLE", flags: "i" }],
         verdict: "review",
-        reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead"
+        reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to drop a database table. This permanently deletes the table and all its data \u2014 there is no undo."
       },
       {
         name: "review-truncate-sql",
         tool: "*",
         conditions: [{ field: "sql", op: "matches", value: "TRUNCATE\\s+TABLE", flags: "i" }],
         verdict: "review",
-        reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead"
+        reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to truncate a database table, which instantly deletes every row. The table structure remains but all data is gone."
       },
       {
         name: "review-drop-column-sql",
@@ -949,7 +961,8 @@ var init_config = __esm({
           { field: "sql", op: "matches", value: "ALTER\\s+TABLE.*DROP\\s+COLUMN", flags: "i" }
         ],
         verdict: "review",
-        reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead"
+        reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to drop a column from a database table. This permanently removes the column and all its data from every row."
       }
     ];
     cachedConfig = null;
@@ -1844,6 +1857,9 @@ async function evaluatePolicy(toolName, args, agent, cwd) {
         reason: matchedRule.reason,
         tier: 2,
         ruleName: matchedRule.name ?? matchedRule.tool,
+        ...(matchedRule.description ?? matchedRule.reason) && {
+          ruleDescription: matchedRule.description ?? matchedRule.reason
+        },
         ...matchedRule.verdict === "block" && matchedRule.dependsOnState?.length && {
           dependsOnStatePredicates: matchedRule.dependsOnState
         },
@@ -3289,7 +3305,8 @@ async function _authorizeHeadlessCore(toolName, args, meta, options) {
           blockedBy: "local-config",
           blockedByLabel: policyResult.blockedByLabel,
           ruleHit: policyResult.ruleName,
-          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand }
+          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand },
+          ...policyResult.ruleDescription && { ruleDescription: policyResult.ruleDescription }
         };
       }
     }
@@ -9066,6 +9083,7 @@ RAW: ${raw}
               writeTty(import_chalk5.default.red(`
 \u{1F6D1} Node9 blocked "${toolName}"`));
             }
+            if (result2?.ruleDescription) writeTty(import_chalk5.default.white(`   ${result2.ruleDescription}`));
             writeTty(import_chalk5.default.gray(`   Triggered by: ${blockedByContext}`));
             if (result2?.changeHint) writeTty(import_chalk5.default.cyan(`   To change:  ${result2.changeHint}`));
             if (result2?.recoveryCommand)

package/dist/cli.mjs

@@ -192,6 +192,7 @@ var init_config_schema = __esm({
         errorMap: () => ({ message: "verdict must be one of: allow, review, block" })
       }),
       reason: z.string().optional(),
+      description: z.string().optional(),
       // Unknown predicate names are filtered out rather than failing the whole rule.
       // Failing the whole z.array() would cause sanitizeConfig to drop the entire
       // `policy` top-level key, silently disabling ALL smart rules in the config.
@@ -769,7 +770,8 @@ var init_config = __esm({
               }
             ],
             verdict: "block",
-            reason: "Recursive delete of home directory is irreversible"
+            reason: "Recursive delete of home directory is irreversible",
+            description: "The AI wants to recursively delete your home directory. This will permanently destroy all your personal files and cannot be undone."
           },
           // ── SQL safety ────────────────────────────────────────────────────────
           {
@@ -781,7 +783,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table"
+            reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table",
+            description: "The AI is running a SQL statement that will modify every row in the table \u2014 no WHERE filter was found. This could wipe or corrupt all your data."
           },
           {
             name: "review-drop-truncate-shell",
@@ -796,7 +799,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "SQL DDL destructive statement inside a shell command"
+            reason: "SQL DDL destructive statement inside a shell command",
+            description: "The AI wants to drop or truncate a database table via the shell. This permanently deletes the table structure or all its data."
           },
           // ── Git safety ────────────────────────────────────────────────────────
           {
@@ -812,7 +816,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "block",
-            reason: "Force push overwrites remote history and cannot be undone"
+            reason: "Force push overwrites remote history and cannot be undone",
+            description: "The AI wants to force push to a remote git branch. This rewrites shared history and can permanently destroy commits that teammates have already pulled."
           },
           {
             name: "review-git-push",
@@ -827,7 +832,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "git push sends changes to a shared remote"
+            reason: "git push sends changes to a shared remote",
+            description: "The AI wants to push commits to a remote repository. Once pushed, those changes are visible to everyone with access."
           },
           {
             name: "review-git-destructive",
@@ -842,7 +848,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "review",
-            reason: "Destructive git operation \u2014 discards history or working-tree changes"
+            reason: "Destructive git operation \u2014 discards history or working-tree changes",
+            description: "The AI wants to run a destructive git operation (reset, rebase, clean, or branch delete) that can permanently discard commits or uncommitted work."
           },
           // ── Shell safety ──────────────────────────────────────────────────────
           {
@@ -851,7 +858,8 @@ var init_config = __esm({
             conditions: [{ field: "command", op: "matches", value: "\\bsudo\\s", flags: "i" }],
             conditionMode: "all",
             verdict: "review",
-            reason: "Command requires elevated privileges"
+            reason: "Command requires elevated privileges",
+            description: "The AI wants to run a command as root (sudo). Commands with root access can modify system files, install software, or change security settings."
           },
           {
             name: "review-curl-pipe-shell",
@@ -866,7 +874,8 @@ var init_config = __esm({
             ],
             conditionMode: "all",
             verdict: "block",
-            reason: "Piping remote script into a shell is a supply-chain attack vector"
+            reason: "Piping remote script into a shell is a supply-chain attack vector",
+            description: "The AI wants to download a script from the internet and run it immediately, without you seeing what it contains. This is one of the most common ways malware gets installed."
           }
         ],
         dlp: { enabled: true, scanIgnoredTools: true }
@@ -899,7 +908,8 @@ var init_config = __esm({
         tool: "*",
         conditions: [{ field: "command", op: "matches", value: "(^|&&|\\|\\||;)\\s*rm\\b" }],
         verdict: "review",
-        reason: "rm can permanently delete files \u2014 confirm the target path"
+        reason: "rm can permanently delete files \u2014 confirm the target path",
+        description: "The AI wants to delete files. Unlike moving to trash, rm is permanent \u2014 the files cannot be recovered without a backup."
       },
       // ── SQL safety (Safe by Default) ──────────────────────────────────────────
       // These rules fire when an AI calls a database tool directly (e.g. MCP postgres,
@@ -911,14 +921,16 @@ var init_config = __esm({
         tool: "*",
         conditions: [{ field: "sql", op: "matches", value: "DROP\\s+TABLE", flags: "i" }],
         verdict: "review",
-        reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead"
+        reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to drop a database table. This permanently deletes the table and all its data \u2014 there is no undo."
       },
       {
         name: "review-truncate-sql",
         tool: "*",
         conditions: [{ field: "sql", op: "matches", value: "TRUNCATE\\s+TABLE", flags: "i" }],
         verdict: "review",
-        reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead"
+        reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to truncate a database table, which instantly deletes every row. The table structure remains but all data is gone."
       },
       {
         name: "review-drop-column-sql",
@@ -927,7 +939,8 @@ var init_config = __esm({
           { field: "sql", op: "matches", value: "ALTER\\s+TABLE.*DROP\\s+COLUMN", flags: "i" }
         ],
         verdict: "review",
-        reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead"
+        reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead",
+        description: "The AI wants to drop a column from a database table. This permanently removes the column and all its data from every row."
       }
     ];
     cachedConfig = null;
@@ -1827,6 +1840,9 @@ async function evaluatePolicy(toolName, args, agent, cwd) {
         reason: matchedRule.reason,
         tier: 2,
         ruleName: matchedRule.name ?? matchedRule.tool,
+        ...(matchedRule.description ?? matchedRule.reason) && {
+          ruleDescription: matchedRule.description ?? matchedRule.reason
+        },
         ...matchedRule.verdict === "block" && matchedRule.dependsOnState?.length && {
           dependsOnStatePredicates: matchedRule.dependsOnState
         },
@@ -3267,7 +3283,8 @@ async function _authorizeHeadlessCore(toolName, args, meta, options) {
           blockedBy: "local-config",
           blockedByLabel: policyResult.blockedByLabel,
           ruleHit: policyResult.ruleName,
-          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand }
+          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand },
+          ...policyResult.ruleDescription && { ruleDescription: policyResult.ruleDescription }
         };
       }
     }
@@ -9041,6 +9058,7 @@ RAW: ${raw}
               writeTty(chalk5.red(`
 \u{1F6D1} Node9 blocked "${toolName}"`));
             }
+            if (result2?.ruleDescription) writeTty(chalk5.white(`   ${result2.ruleDescription}`));
             writeTty(chalk5.gray(`   Triggered by: ${blockedByContext}`));
             if (result2?.changeHint) writeTty(chalk5.cyan(`   To change:  ${result2.changeHint}`));
             if (result2?.recoveryCommand)

package/dist/index.js

@@ -199,6 +199,7 @@ var SmartRuleSchema = import_zod.z.object({
     errorMap: () => ({ message: "verdict must be one of: allow, review, block" })
   }),
   reason: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional(),
   // Unknown predicate names are filtered out rather than failing the whole rule.
   // Failing the whole z.array() would cause sanitizeConfig to drop the entire
   // `policy` top-level key, silently disabling ALL smart rules in the config.
@@ -492,7 +493,8 @@ var DEFAULT_CONFIG = {
           }
         ],
         verdict: "block",
-        reason: "Recursive delete of home directory is irreversible"
+        reason: "Recursive delete of home directory is irreversible",
+        description: "The AI wants to recursively delete your home directory. This will permanently destroy all your personal files and cannot be undone."
       },
       // ── SQL safety ────────────────────────────────────────────────────────
       {
@@ -504,7 +506,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table"
+        reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table",
+        description: "The AI is running a SQL statement that will modify every row in the table \u2014 no WHERE filter was found. This could wipe or corrupt all your data."
       },
       {
         name: "review-drop-truncate-shell",
@@ -519,7 +522,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "SQL DDL destructive statement inside a shell command"
+        reason: "SQL DDL destructive statement inside a shell command",
+        description: "The AI wants to drop or truncate a database table via the shell. This permanently deletes the table structure or all its data."
       },
       // ── Git safety ────────────────────────────────────────────────────────
       {
@@ -535,7 +539,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "block",
-        reason: "Force push overwrites remote history and cannot be undone"
+        reason: "Force push overwrites remote history and cannot be undone",
+        description: "The AI wants to force push to a remote git branch. This rewrites shared history and can permanently destroy commits that teammates have already pulled."
       },
       {
         name: "review-git-push",
@@ -550,7 +555,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "git push sends changes to a shared remote"
+        reason: "git push sends changes to a shared remote",
+        description: "The AI wants to push commits to a remote repository. Once pushed, those changes are visible to everyone with access."
       },
       {
         name: "review-git-destructive",
@@ -565,7 +571,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "Destructive git operation \u2014 discards history or working-tree changes"
+        reason: "Destructive git operation \u2014 discards history or working-tree changes",
+        description: "The AI wants to run a destructive git operation (reset, rebase, clean, or branch delete) that can permanently discard commits or uncommitted work."
       },
       // ── Shell safety ──────────────────────────────────────────────────────
       {
@@ -574,7 +581,8 @@ var DEFAULT_CONFIG = {
         conditions: [{ field: "command", op: "matches", value: "\\bsudo\\s", flags: "i" }],
         conditionMode: "all",
         verdict: "review",
-        reason: "Command requires elevated privileges"
+        reason: "Command requires elevated privileges",
+        description: "The AI wants to run a command as root (sudo). Commands with root access can modify system files, install software, or change security settings."
       },
       {
         name: "review-curl-pipe-shell",
@@ -589,7 +597,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "block",
-        reason: "Piping remote script into a shell is a supply-chain attack vector"
+        reason: "Piping remote script into a shell is a supply-chain attack vector",
+        description: "The AI wants to download a script from the internet and run it immediately, without you seeing what it contains. This is one of the most common ways malware gets installed."
       }
     ],
     dlp: { enabled: true, scanIgnoredTools: true }
@@ -622,7 +631,8 @@ var ADVISORY_SMART_RULES = [
     tool: "*",
     conditions: [{ field: "command", op: "matches", value: "(^|&&|\\|\\||;)\\s*rm\\b" }],
     verdict: "review",
-    reason: "rm can permanently delete files \u2014 confirm the target path"
+    reason: "rm can permanently delete files \u2014 confirm the target path",
+    description: "The AI wants to delete files. Unlike moving to trash, rm is permanent \u2014 the files cannot be recovered without a backup."
   },
   // ── SQL safety (Safe by Default) ──────────────────────────────────────────
   // These rules fire when an AI calls a database tool directly (e.g. MCP postgres,
@@ -634,14 +644,16 @@ var ADVISORY_SMART_RULES = [
     tool: "*",
     conditions: [{ field: "sql", op: "matches", value: "DROP\\s+TABLE", flags: "i" }],
     verdict: "review",
-    reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead"
+    reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to drop a database table. This permanently deletes the table and all its data \u2014 there is no undo."
   },
   {
     name: "review-truncate-sql",
     tool: "*",
     conditions: [{ field: "sql", op: "matches", value: "TRUNCATE\\s+TABLE", flags: "i" }],
     verdict: "review",
-    reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead"
+    reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to truncate a database table, which instantly deletes every row. The table structure remains but all data is gone."
   },
   {
     name: "review-drop-column-sql",
@@ -650,7 +662,8 @@ var ADVISORY_SMART_RULES = [
       { field: "sql", op: "matches", value: "ALTER\\s+TABLE.*DROP\\s+COLUMN", flags: "i" }
     ],
     verdict: "review",
-    reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead"
+    reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to drop a column from a database table. This permanently removes the column and all its data from every row."
   }
 ];
 var cachedConfig = null;
@@ -1665,6 +1678,9 @@ async function evaluatePolicy(toolName, args, agent, cwd) {
         reason: matchedRule.reason,
         tier: 2,
         ruleName: matchedRule.name ?? matchedRule.tool,
+        ...(matchedRule.description ?? matchedRule.reason) && {
+          ruleDescription: matchedRule.description ?? matchedRule.reason
+        },
         ...matchedRule.verdict === "block" && matchedRule.dependsOnState?.length && {
           dependsOnStatePredicates: matchedRule.dependsOnState
         },
@@ -2795,7 +2811,8 @@ async function _authorizeHeadlessCore(toolName, args, meta, options) {
           blockedBy: "local-config",
           blockedByLabel: policyResult.blockedByLabel,
           ruleHit: policyResult.ruleName,
-          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand }
+          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand },
+          ...policyResult.ruleDescription && { ruleDescription: policyResult.ruleDescription }
         };
       }
     }

package/dist/index.mjs

@@ -169,6 +169,7 @@ var SmartRuleSchema = z.object({
     errorMap: () => ({ message: "verdict must be one of: allow, review, block" })
   }),
   reason: z.string().optional(),
+  description: z.string().optional(),
   // Unknown predicate names are filtered out rather than failing the whole rule.
   // Failing the whole z.array() would cause sanitizeConfig to drop the entire
   // `policy` top-level key, silently disabling ALL smart rules in the config.
@@ -462,7 +463,8 @@ var DEFAULT_CONFIG = {
           }
         ],
         verdict: "block",
-        reason: "Recursive delete of home directory is irreversible"
+        reason: "Recursive delete of home directory is irreversible",
+        description: "The AI wants to recursively delete your home directory. This will permanently destroy all your personal files and cannot be undone."
       },
       // ── SQL safety ────────────────────────────────────────────────────────
       {
@@ -474,7 +476,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table"
+        reason: "DELETE/UPDATE without WHERE clause \u2014 would affect every row in the table",
+        description: "The AI is running a SQL statement that will modify every row in the table \u2014 no WHERE filter was found. This could wipe or corrupt all your data."
       },
       {
         name: "review-drop-truncate-shell",
@@ -489,7 +492,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "SQL DDL destructive statement inside a shell command"
+        reason: "SQL DDL destructive statement inside a shell command",
+        description: "The AI wants to drop or truncate a database table via the shell. This permanently deletes the table structure or all its data."
       },
       // ── Git safety ────────────────────────────────────────────────────────
       {
@@ -505,7 +509,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "block",
-        reason: "Force push overwrites remote history and cannot be undone"
+        reason: "Force push overwrites remote history and cannot be undone",
+        description: "The AI wants to force push to a remote git branch. This rewrites shared history and can permanently destroy commits that teammates have already pulled."
       },
       {
         name: "review-git-push",
@@ -520,7 +525,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "git push sends changes to a shared remote"
+        reason: "git push sends changes to a shared remote",
+        description: "The AI wants to push commits to a remote repository. Once pushed, those changes are visible to everyone with access."
       },
       {
         name: "review-git-destructive",
@@ -535,7 +541,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "review",
-        reason: "Destructive git operation \u2014 discards history or working-tree changes"
+        reason: "Destructive git operation \u2014 discards history or working-tree changes",
+        description: "The AI wants to run a destructive git operation (reset, rebase, clean, or branch delete) that can permanently discard commits or uncommitted work."
       },
       // ── Shell safety ──────────────────────────────────────────────────────
       {
@@ -544,7 +551,8 @@ var DEFAULT_CONFIG = {
         conditions: [{ field: "command", op: "matches", value: "\\bsudo\\s", flags: "i" }],
         conditionMode: "all",
         verdict: "review",
-        reason: "Command requires elevated privileges"
+        reason: "Command requires elevated privileges",
+        description: "The AI wants to run a command as root (sudo). Commands with root access can modify system files, install software, or change security settings."
       },
       {
         name: "review-curl-pipe-shell",
@@ -559,7 +567,8 @@ var DEFAULT_CONFIG = {
         ],
         conditionMode: "all",
         verdict: "block",
-        reason: "Piping remote script into a shell is a supply-chain attack vector"
+        reason: "Piping remote script into a shell is a supply-chain attack vector",
+        description: "The AI wants to download a script from the internet and run it immediately, without you seeing what it contains. This is one of the most common ways malware gets installed."
       }
     ],
     dlp: { enabled: true, scanIgnoredTools: true }
@@ -592,7 +601,8 @@ var ADVISORY_SMART_RULES = [
     tool: "*",
     conditions: [{ field: "command", op: "matches", value: "(^|&&|\\|\\||;)\\s*rm\\b" }],
     verdict: "review",
-    reason: "rm can permanently delete files \u2014 confirm the target path"
+    reason: "rm can permanently delete files \u2014 confirm the target path",
+    description: "The AI wants to delete files. Unlike moving to trash, rm is permanent \u2014 the files cannot be recovered without a backup."
   },
   // ── SQL safety (Safe by Default) ──────────────────────────────────────────
   // These rules fire when an AI calls a database tool directly (e.g. MCP postgres,
@@ -604,14 +614,16 @@ var ADVISORY_SMART_RULES = [
     tool: "*",
     conditions: [{ field: "sql", op: "matches", value: "DROP\\s+TABLE", flags: "i" }],
     verdict: "review",
-    reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead"
+    reason: "DROP TABLE is irreversible \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to drop a database table. This permanently deletes the table and all its data \u2014 there is no undo."
   },
   {
     name: "review-truncate-sql",
     tool: "*",
     conditions: [{ field: "sql", op: "matches", value: "TRUNCATE\\s+TABLE", flags: "i" }],
     verdict: "review",
-    reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead"
+    reason: "TRUNCATE removes all rows \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to truncate a database table, which instantly deletes every row. The table structure remains but all data is gone."
   },
   {
     name: "review-drop-column-sql",
@@ -620,7 +632,8 @@ var ADVISORY_SMART_RULES = [
       { field: "sql", op: "matches", value: "ALTER\\s+TABLE.*DROP\\s+COLUMN", flags: "i" }
     ],
     verdict: "review",
-    reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead"
+    reason: "DROP COLUMN is irreversible \u2014 enable the postgres shield to block instead",
+    description: "The AI wants to drop a column from a database table. This permanently removes the column and all its data from every row."
   }
 ];
 var cachedConfig = null;
@@ -1635,6 +1648,9 @@ async function evaluatePolicy(toolName, args, agent, cwd) {
         reason: matchedRule.reason,
         tier: 2,
         ruleName: matchedRule.name ?? matchedRule.tool,
+        ...(matchedRule.description ?? matchedRule.reason) && {
+          ruleDescription: matchedRule.description ?? matchedRule.reason
+        },
         ...matchedRule.verdict === "block" && matchedRule.dependsOnState?.length && {
           dependsOnStatePredicates: matchedRule.dependsOnState
         },
@@ -2765,7 +2781,8 @@ async function _authorizeHeadlessCore(toolName, args, meta, options) {
           blockedBy: "local-config",
           blockedByLabel: policyResult.blockedByLabel,
           ruleHit: policyResult.ruleName,
-          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand }
+          ...policyResult.recoveryCommand && { recoveryCommand: policyResult.recoveryCommand },
+          ...policyResult.ruleDescription && { ruleDescription: policyResult.ruleDescription }
         };
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node9/proxy",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "The Sudo Command for AI Agents. Execution Security for Claude Code & MCP.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",