feat: granular session-scoped allow rules

Add allowForSessionGranular to SecurityRule, enabling per-argument
allow overrides scoped to a session key prefix. Lets users approve
a specific file path, command, or URL for a cron job session without
blanket-allowing the entire module.method.

- types.ts: add allowForSessionGranular to SecurityRule
- Interceptor.ts: add extractPrimaryArg(), check granular entries via glob; add reloadPolicy()
- config.ts: add Session/Memory/Agent default rules; FileSystem.delete DENY -> ASK
- test/granular-allow.test.mjs: full test coverage

Author: kere-nel

src/config.ts

@@ -20,8 +20,8 @@ export const DEFAULT_POLICY: SecurityPolicy = {
         description: 'Modification of files requires approval',
       },
       delete: {
-        action: 'DENY',
-        description: 'Deletion is strictly prohibited',
+        action: 'ASK',
+        description: 'File deletion requires approval',
       },
     },
     Shell: {
@@ -76,5 +76,26 @@ export const DEFAULT_POLICY: SecurityPolicy = {
         description: 'HTTP request may leak data',
       },
     },
+    // Internal session/agent operations — reading state is safe, never needs approval.
+    Session: {
+      history: { action: 'ALLOW', description: 'Reading session history is safe' },
+      list:    { action: 'ALLOW', description: 'Listing sessions is safe' },
+      status:  { action: 'ALLOW', description: 'Reading session status is safe' },
+      yield:   { action: 'ALLOW', description: 'Internal async yield — no user action needed' },
+      create:  { action: 'ASK',   description: 'Creating a new session' },
+      destroy: { action: 'ASK',   description: 'Destroying a session requires approval' },
+    },
+    Memory: {
+      read:   { action: 'ALLOW', description: 'Reading memory is safe' },
+      list:   { action: 'ALLOW', description: 'Listing memory entries is safe' },
+      update: { action: 'ASK',   description: 'Writing to memory requires approval' },
+      delete: { action: 'ASK',   description: 'Deleting memory entries requires approval' },
+    },
+    Agent: {
+      status: { action: 'ALLOW', description: 'Reading agent status is safe' },
+      list:   { action: 'ALLOW', description: 'Listing agents is safe' },
+      spawn:  { action: 'ASK',   description: 'Spawning a sub-agent requires approval' },
+      stop:   { action: 'ASK',   description: 'Stopping an agent requires approval' },
+    },
   },
 };

src/core/Interceptor.ts

@@ -48,6 +48,25 @@ function matchesGlob(pattern: string, str: string): boolean {
   return new RegExp(`^${regex}$`).test(norm);
 }
 
+/**
+ * Extract the primary arg value for a tool call, used for granular session allow matching.
+ * Returns the raw string value (not resolved) so globs can match commands and URLs too.
+ */
+function extractPrimaryArg(moduleName: string, params: Record<string, unknown>): string | null {
+  if (moduleName === 'Browser' || moduleName === 'Network') {
+    const v = params.url ?? params.src ?? null;
+    return v != null ? String(v) : null;
+  }
+  if (moduleName === 'Shell') {
+    const v = params.command ?? params.cmd ?? null;
+    return v != null ? String(v) : null;
+  }
+  const raw = params.path ?? params.file_path ?? params.filePath ?? params.target ?? null;
+  if (raw != null) return path.resolve(expandTilde(String(raw)));
+  const first = Object.values(params)[0];
+  return first != null ? String(first) : null;
+}
+
 /**
  * Extract the path or URL that a tool call is targeting, for path-policy evaluation.
  * Returns null if no target can be determined (policy check is skipped).
@@ -124,6 +143,15 @@ export class Interceptor {
     this.logEnabled = logEnabled;
   }
 
+  /** Hot-reload the policy without restarting the gateway. */
+  reloadPolicy(policy: SecurityPolicy): void {
+    this.policy = policy;
+    logger.info('Interceptor: policy hot-reloaded', {
+      modules: Object.keys(policy.modules),
+      defaultAction: policy.defaultAction,
+    });
+  }
+
   /**
    * Evaluate the security policy for a tool call.
    */
@@ -134,7 +162,7 @@ export class Interceptor {
     sessionKey?: string,
     intervention?: InterventionMetadata
   ): Promise<void> {
-    const baseRule = this.lookupRule(moduleName, methodName);
+    const baseRule = this.lookupRule(moduleName, methodName, sessionKey, args);
     // Path-policy check runs before intervention so a denied path is never
     // upgradeable to ASK — it's a hard DENY.
     const originalRule = applyPathPolicy(baseRule, moduleName, args);
@@ -177,14 +205,13 @@ export class Interceptor {
         );
 
         throw new Error(
-          `[ClawReins:APPROVAL_REQUIRED] ${moduleName}.${methodName}() is blocked pending human approval. ` +
-            `Risk: ${detail}\n` +
+          `Action not permitted: ${moduleName}.${methodName}() requires human authorization.\n` +
             instructions
         );
       }
 
       throw new Error(
-        `ClawReins Security Violation: ${moduleName}.${methodName}() was DENIED. ${detail}`
+        `Action not permitted: ${moduleName}.${methodName}() was denied. ${detail}`
       );
     }
   }
@@ -276,26 +303,41 @@ export class Interceptor {
     if (strict) {
       return (
         `${screenshotInstruction}` +
-        `⚠️ HIGH-RISK action requires explicit human confirmation.\n` +
         `Action: ${summary}\n` +
-        `An out-of-band approval notification has been sent to the human.\n` +
-        `WAIT — do NOT retry this tool. Do NOT attempt to self-approve.`
+        `WAIT — do NOT retry this tool. Do NOT attempt to proceed without explicit authorization.`
       );
     }
 
     return (
       `${screenshotInstruction}` +
       `Action: ${summary}\n` +
-      `An approval request has been sent to the human out-of-band.\n` +
-      `WAIT for their response before retrying. Do NOT attempt to self-approve.`
+      `WAIT for authorization before retrying. Do NOT attempt to proceed independently.`
     );
   }
 
-  private lookupRule(moduleName: string, methodName: string): SecurityRule {
+  private lookupRule(moduleName: string, methodName: string, sessionKey?: string, args?: unknown[]): SecurityRule {
     const moduleRules = this.policy.modules[moduleName];
+    const rule = moduleRules?.[methodName];
+
+    if (rule) {
+      // Blanket session allow — matches all calls to this module.method.
+      if (sessionKey && rule.allowForSessionKeys?.some(prefix => sessionKey.startsWith(prefix))) {
+        return { action: 'ALLOW', description: `Allowed for session ${sessionKey}` };
+      }
 
-    if (moduleRules && moduleRules[methodName]) {
-      return moduleRules[methodName];
+      // Granular session+arg allow — matches by session prefix AND primary arg glob.
+      if (sessionKey && args && rule.allowForSessionGranular?.length) {
+        const params = (args[0] as Record<string, unknown>) ?? {};
+        const primaryArg = extractPrimaryArg(moduleName, params);
+        if (primaryArg !== null) {
+          const matched = rule.allowForSessionGranular.some(
+            entry => sessionKey.startsWith(entry.sessionKeyPrefix) && matchesGlob(entry.argGlob, primaryArg)
+          );
+          if (matched) return { action: 'ALLOW', description: `Allowed for session ${sessionKey} with arg pattern` };
+        }
+      }
+
+      return rule;
     }
 
     return {

src/types.ts

@@ -29,6 +29,20 @@ export interface SecurityRule {
    * Examples: ["/etc/GLOB", "~/.ssh/GLOB", "GLOB/.env"]  (GLOB = **)
    */
   denyPaths?: string[];
+  /**
+   * Session key prefixes for which this rule is automatically ALLOW regardless of action.
+   * Blanket: allows ALL calls to this module.method for matching sessions.
+   */
+  allowForSessionKeys?: string[];
+  /**
+   * Granular per-session allows. Each entry requires both a session key prefix match AND a
+   * glob match on the primary arg (path, command, url). More precise than allowForSessionKeys.
+   * Example: [{sessionKeyPrefix:"agent:main:cron:abc", argGlob:"/tmp/reports/**"}]
+   */
+  allowForSessionGranular?: Array<{
+    sessionKeyPrefix: string;
+    argGlob: string;
+  }>;
 }
 
 /**
@@ -66,16 +80,6 @@ export interface InterventionMetadata {
   recommendScreenshotReview?: boolean;
   /** Current cooldown escalation level (0=normal, 1=heightened, 2=restricted). */
   cooldownLevel?: number;
-  /** Destructive-intercept severity for UI and audit context. */
-  destructiveSeverity?: 'HIGH' | 'CATASTROPHIC';
-  /** Reasons from destructive classifier. */
-  destructiveReasons?: string[];
-  /** Optional bulk count identified by destructive classifier. */
-  destructiveBulkCount?: number;
-  /** Optional user-facing target (mailbox/path/host). */
-  destructiveTarget?: string;
-  /** Require channel approvals to come via clawreins_respond (fail-secure if unavailable). */
-  requiresRespondToolApproval?: boolean;
 }
 
 /**