@datafog/fogclaw 0.1.5 → 0.1.6

package/README.md

@@ -7,11 +7,15 @@ FogClaw uses a dual-engine approach: battle-tested regex patterns for structured
 ## Features
 
 - **Automatic guardrail** — intercepts messages before they reach the LLM via OpenClaw's `before_agent_start` hook
-- **On-demand tools** — `fogclaw_scan` and `fogclaw_redact` tools the agent can invoke explicitly
+- **On-demand tools** — `fogclaw_scan`, `fogclaw_preview`, and `fogclaw_redact`
 - **Dual detection engine** — regex for structured PII (<1ms), GLiNER for zero-shot NER (~50-200ms)
 - **Custom entity types** — define any entity label (e.g., "project codename", "competitor name") and GLiNER detects them with zero training
 - **Configurable actions** — per-entity-type behavior: `redact`, `block`, or `warn`
+- **Per-entity confidence tuning** — tighten or relax detection confidence by label
+- **Policy allowlist** — whitelist exact strings or regex patterns to skip enforcement on known-safe values
+- **Policy preview** — run a dry-run simulation before changing runtime policy
 - **Multiple redaction strategies** — `token`, `mask`, or `hash`
+- **Audit trail summary logging** — optional structured action summaries without logging raw entity content
 - **Graceful degradation** — falls back to regex-only mode if GLiNER fails to load
 
 ## Installation
@@ -60,6 +64,10 @@ cp fogclaw.config.example.json fogclaw.config.json
   "redactStrategy": "token",
   "model": "onnx-community/gliner_large-v2.1",
   "confidence_threshold": 0.5,
+  "entityConfidenceThresholds": {
+    "PERSON": 0.6,
+    "ORGANIZATION": 0.7
+  },
   "custom_entities": ["project codename", "competitor name"],
   "entityActions": {
     "SSN": "block",
@@ -67,7 +75,15 @@ cp fogclaw.config.example.json fogclaw.config.json
     "EMAIL": "redact",
     "PHONE": "redact",
     "PERSON": "warn"
-  }
+  },
+  "allowlist": {
+    "values": ["noreply@example.com"],
+    "patterns": ["^internal-"],
+    "entities": {
+      "PERSON": ["john doe"]
+    }
+  },
+  "auditEnabled": true
 }
 ```
 
@@ -113,13 +129,13 @@ Incoming message
  +-----------+
  | GLiNER    |  persons, orgs, locations + your custom entities
  |  (ONNX)   |  confidence: 0.0-1.0
- +-----+-----+
+ +-----------+
        |
        v
  +-----------+
  | Merge &   |  deduplicate overlapping spans, prefer higher confidence
  | Normalize |
- +-----+-----+
+ +-----------+
        |
        v
   Apply action per entity type (redact / block / warn)
@@ -162,8 +178,11 @@ Plus any labels you add via `custom_entities` in the config.
 | `redactStrategy` | `string` | `"token"` | How to redact: `"token"`, `"mask"`, or `"hash"` |
 | `model` | `string` | `"onnx-community/gliner_large-v2.1"` | HuggingFace model path for GLiNER (or a local `.onnx` path for advanced setups). |
 | `confidence_threshold` | `number` | `0.5` | Minimum confidence for GLiNER detections (0-1) |
+| `entityConfidenceThresholds` | `object` | `{}` | Per-label confidence overrides, e.g. `{ "PERSON": 0.7, "ORGANIZATION": 0.85 }` |
 | `custom_entities` | `string[]` | `[]` | Custom entity labels for zero-shot detection |
 | `entityActions` | `object` | `{}` | Per-entity-type action overrides |
+| `allowlist` | `object` | `{}` | Exception rules to skip enforcement via exact values or regex patterns |
+| `auditEnabled` | `boolean` | `true` | Emit structured audit logs for guardrail decisions |
 
 ## OpenClaw Tools
 
@@ -175,6 +194,21 @@ Scan text for PII and custom entities. Returns detected entities with types, pos
 - `text` (required) — text to scan
 - `custom_labels` (optional) — additional entity labels for zero-shot detection
 
+### `fogclaw_preview`
+
+Preview what the guardrail would do for a message.
+
+**Parameters:**
+- `text` (required) — text to simulate
+- `strategy` (optional) — `"token"`, `"mask"`, or `"hash"` (defaults to config)
+- `custom_labels` (optional) — additional entity labels for zero-shot detection
+
+**Response:**
+- `entities`: detected entities and metadata
+- `totalEntities`: total entities found
+- `actionPlan`: counts and labels grouped by `blocked`, `warned`, `redacted`
+- `redactedText`: message with only redacted entities applied
+
 ### `fogclaw_redact`
 
 Scan and redact PII/custom entities from text. Returns sanitized text with entities replaced.
@@ -219,6 +253,12 @@ npm run build     # compile TypeScript
 npm run lint      # type-check without emitting
 ```
 
+## Security Notes
+
+- Keep `api.logger` output free of raw sensitive values.
+- Use allowlists and `auditEnabled` according to your governance requirements.
+- Consider `block` actions for high-risk entity types in regulated environments.
+
 ## License
 
 MIT

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { FogClawConfig } from "./types.js";
+import { type FogClawConfig } from "./types.js";
 export declare const DEFAULT_CONFIG: FogClawConfig;
 export declare function loadConfig(overrides: Partial<FogClawConfig>): FogClawConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAmC,MAAM,YAAY,CAAC;AAKjF,eAAO,MAAM,cAAc,EAAE,aAQ5B,CAAC;AAEF,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CA8B3E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAoGpB,eAAO,MAAM,cAAc,EAAE,aAe5B,CAAC;AAEF,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CA2D3E"}

package/dist/config.js

@@ -1,5 +1,74 @@
+import { canonicalType, } from "./types.js";
 const VALID_GUARDRAIL_MODES = ["redact", "block", "warn"];
 const VALID_REDACT_STRATEGIES = ["token", "mask", "hash"];
+function ensureStringList(value, path) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${path} must be an array of strings`);
+    }
+    const entries = value.filter((entry) => {
+        if (typeof entry !== "string") {
+            throw new Error(`${path} must contain only strings`);
+        }
+        return true;
+    });
+    return entries.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function ensureEntityAllowlist(value) {
+    if (value == null) {
+        return { values: [], patterns: [], entities: {} };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("allowlist must be an object");
+    }
+    const raw = value;
+    const values = ensureStringList(raw.values ?? [], "allowlist.values");
+    const patterns = ensureStringList(raw.patterns ?? [], "allowlist.patterns");
+    for (const pattern of patterns) {
+        try {
+            new RegExp(pattern);
+        }
+        catch {
+            throw new Error(`allowlist.patterns contains invalid regex pattern: "${pattern}"`);
+        }
+    }
+    const entitiesValue = raw.entities ?? {};
+    if (typeof entitiesValue !== "object" ||
+        Array.isArray(entitiesValue) ||
+        entitiesValue === null) {
+        throw new Error("allowlist.entities must be an object mapping entity labels to string arrays");
+    }
+    const entities = {};
+    for (const [entityType, entryValue] of Object.entries(entitiesValue)) {
+        const normalizedType = canonicalType(entityType);
+        entities[normalizedType] = ensureStringList(entryValue, `allowlist.entities.${entityType}`);
+    }
+    return {
+        values: [...new Set(values)],
+        patterns: [...new Set(patterns)],
+        entities,
+    };
+}
+function ensureEntityConfidenceThresholds(value) {
+    if (!value) {
+        return {};
+    }
+    if (typeof value !== "object" || Array.isArray(value) || value === null) {
+        throw new Error("entityConfidenceThresholds must be an object");
+    }
+    const raw = value;
+    const normalized = {};
+    for (const [entityType, rawThreshold] of Object.entries(raw)) {
+        if (typeof rawThreshold !== "number" || Number.isNaN(rawThreshold)) {
+            throw new Error(`entityConfidenceThresholds["${entityType}"] must be a number between 0 and 1, got ${String(rawThreshold)}`);
+        }
+        if (rawThreshold < 0 || rawThreshold > 1) {
+            throw new Error(`entityConfidenceThresholds["${entityType}"] must be between 0 and 1, got ${rawThreshold}`);
+        }
+        const canonicalTypeKey = canonicalType(entityType);
+        normalized[canonicalTypeKey] = rawThreshold;
+    }
+    return normalized;
+}
 export const DEFAULT_CONFIG = {
     enabled: true,
     guardrail_mode: "redact",
@@ -8,9 +77,32 @@ export const DEFAULT_CONFIG = {
     confidence_threshold: 0.5,
     custom_entities: [],
     entityActions: {},
+    entityConfidenceThresholds: {},
+    allowlist: {
+        values: [],
+        patterns: [],
+        entities: {},
+    },
+    auditEnabled: true,
 };
 export function loadConfig(overrides) {
-    const config = { ...DEFAULT_CONFIG, ...overrides };
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...overrides,
+        entityActions: {
+            ...DEFAULT_CONFIG.entityActions,
+            ...(overrides.entityActions ?? {}),
+        },
+        entityConfidenceThresholds: {
+            ...DEFAULT_CONFIG.entityConfidenceThresholds,
+            ...(overrides.entityConfidenceThresholds ?? {}),
+        },
+    };
+    config.allowlist = ensureEntityAllowlist(overrides.allowlist ?? DEFAULT_CONFIG.allowlist);
+    config.entityConfidenceThresholds = ensureEntityConfidenceThresholds(config.entityConfidenceThresholds);
+    if (typeof config.enabled !== "boolean") {
+        throw new Error(`enabled must be true or false`);
+    }
     if (!VALID_GUARDRAIL_MODES.includes(config.guardrail_mode)) {
         throw new Error(`Invalid guardrail_mode "${config.guardrail_mode}". Must be one of: ${VALID_GUARDRAIL_MODES.join(", ")}`);
     }
@@ -20,11 +112,18 @@ export function loadConfig(overrides) {
     if (config.confidence_threshold < 0 || config.confidence_threshold > 1) {
         throw new Error(`confidence_threshold must be between 0 and 1, got ${config.confidence_threshold}`);
     }
+    if (typeof config.auditEnabled !== "boolean") {
+        throw new Error(`auditEnabled must be true or false`);
+    }
+    const normalizedActions = {};
     for (const [entityType, action] of Object.entries(config.entityActions)) {
         if (!VALID_GUARDRAIL_MODES.includes(action)) {
             throw new Error(`Invalid action "${action}" for entity type "${entityType}". Must be one of: ${VALID_GUARDRAIL_MODES.join(", ")}`);
         }
+        const normalizedType = canonicalType(entityType);
+        normalizedActions[normalizedType] = action;
     }
+    config.entityActions = normalizedActions;
     return config;
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,qBAAqB,GAAsB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC7E,MAAM,uBAAuB,GAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5E,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,QAAQ;IACxB,cAAc,EAAE,OAAO;IACvB,KAAK,EAAE,kCAAkC;IACzC,oBAAoB,EAAE,GAAG;IACzB,eAAe,EAAE,EAAE;IACnB,aAAa,EAAE,EAAE;CAClB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,SAAiC;IAC1D,MAAM,MAAM,GAAkB,EAAE,GAAG,cAAc,EAAE,GAAG,SAAS,EAAE,CAAC;IAElE,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,CAAC,cAAc,sBAAsB,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzG,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,CAAC,cAAc,sBAAsB,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,oBAAoB,GAAG,CAAC,IAAI,MAAM,CAAC,oBAAoB,GAAG,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,qDAAqD,MAAM,CAAC,oBAAoB,EAAE,CACnF,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QACxE,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,sBAAsB,UAAU,sBAAsB,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { Entity, FogClawConfig, ScanResult, RedactResult, RedactStrategy, G
  * Registers:
  * - `before_agent_start` hook for automatic PII guardrail
  * - `fogclaw_scan` tool for on-demand entity detection
+ * - `fogclaw_preview` tool for dry-run policy simulation
  * - `fogclaw_redact` tool for on-demand redaction
  */
 declare const fogclaw: {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,QAAA,MAAM,OAAO;;;kBAIG,GAAG;CA+LlB,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAyEpB;;;;;;;;GAQG;AACH,QAAA,MAAM,OAAO;;;kBAIG,GAAG;CAqQlB,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/index.js

@@ -4,12 +4,61 @@ import { loadConfig } from "./config.js";
 export { Scanner } from "./scanner.js";
 export { redact } from "./redactor.js";
 export { loadConfig, DEFAULT_CONFIG } from "./config.js";
+function resolveAction(entity, config) {
+    return config.entityActions[entity.label] ?? config.guardrail_mode;
+}
+function buildGuardrailPlan(entities, config) {
+    const blocked = [];
+    const warned = [];
+    const redacted = [];
+    for (const entity of entities) {
+        const action = resolveAction(entity, config);
+        if (action === "block")
+            blocked.push(entity);
+        else if (action === "warn")
+            warned.push(entity);
+        else
+            redacted.push(entity);
+    }
+    return { blocked, warned, redacted };
+}
+function planToSummary(plan) {
+    return {
+        total: plan.blocked.length + plan.warned.length + plan.redacted.length,
+        blocked: plan.blocked.length,
+        warned: plan.warned.length,
+        redacted: plan.redacted.length,
+        labels: {
+            blocked: [...new Set(plan.blocked.map((entity) => entity.label))],
+            warned: [...new Set(plan.warned.map((entity) => entity.label))],
+            redacted: [...new Set(plan.redacted.map((entity) => entity.label))],
+        },
+    };
+}
+function buildGuardrailContext(plan, config) {
+    const contextParts = [];
+    if (plan.blocked.length > 0) {
+        const types = [...new Set(plan.blocked.map((entity) => entity.label))].join(", ");
+        contextParts.push(`[FOGCLAW GUARDRAIL — BLOCKED] The user's message contains sensitive information (${types}). ` +
+            `Do NOT process or repeat this information. Ask the user to rephrase without sensitive data.`);
+    }
+    if (plan.warned.length > 0) {
+        const types = [...new Set(plan.warned.map((entity) => entity.label))].join(", ");
+        contextParts.push(`[FOGCLAW NOTICE] PII detected in user message: ${types}. Handle with care.`);
+    }
+    if (plan.redacted.length > 0) {
+        const labels = [...new Set(plan.redacted.map((entity) => entity.label))].join(", ");
+        contextParts.push(`[FOGCLAW REDACTED] ${plan.redacted.length} entity(ies) prepared for ${config.redactStrategy} redaction (${labels}).`);
+    }
+    return contextParts;
+}
 /**
  * OpenClaw plugin definition.
  *
  * Registers:
  * - `before_agent_start` hook for automatic PII guardrail
  * - `fogclaw_scan` tool for on-demand entity detection
+ * - `fogclaw_preview` tool for dry-run policy simulation
  * - `fogclaw_redact` tool for on-demand redaction
  */
 const fogclaw = {
@@ -36,35 +85,23 @@ const fogclaw = {
             const result = await scanner.scan(message);
             if (result.entities.length === 0)
                 return;
-            // Classify entities by their configured action
-            const blocked = [];
-            const warned = [];
-            const toRedact = [];
-            for (const entity of result.entities) {
-                const action = config.entityActions[entity.label] ?? config.guardrail_mode;
-                if (action === "block")
-                    blocked.push(entity);
-                else if (action === "warn")
-                    warned.push(entity);
-                else if (action === "redact")
-                    toRedact.push(entity);
+            const plan = buildGuardrailPlan(result.entities, config);
+            const contextParts = buildGuardrailContext(plan, config);
+            if (config.auditEnabled) {
+                const summary = planToSummary(plan);
+                api.logger?.info(`[FOGCLAW AUDIT] guardrail_scan ${JSON.stringify({
+                    totalEntities: summary.total,
+                    blocked: summary.blocked,
+                    warned: summary.warned,
+                    redacted: summary.redacted,
+                    blockedLabels: summary.labels.blocked,
+                    warnedLabels: summary.labels.warned,
+                    redactedLabels: summary.labels.redacted,
+                })}`);
             }
-            const contextParts = [];
-            // "block" — inject a strong instruction to refuse
-            if (blocked.length > 0) {
-                const types = [...new Set(blocked.map((e) => e.label))].join(", ");
-                contextParts.push(`[FOGCLAW GUARDRAIL — BLOCKED] The user's message contains sensitive information (${types}). ` +
-                    `Do NOT process or repeat this information. Ask the user to rephrase without sensitive data.`);
-            }
-            // "warn" — inject a warning notice
-            if (warned.length > 0) {
-                const types = [...new Set(warned.map((e) => e.label))].join(", ");
-                contextParts.push(`[FOGCLAW NOTICE] PII detected in user message: ${types}. Handle with care.`);
-            }
-            // "redact" — replace PII with tokens
-            if (toRedact.length > 0) {
-                const redacted = redact(message, toRedact, config.redactStrategy);
-                contextParts.push(`[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redacted.redacted_text}`);
+            if (plan.redacted.length > 0) {
+                const redactedResult = redact(message, plan.redacted, config.redactStrategy);
+                contextParts.push(`[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redactedResult.redacted_text}`);
             }
             if (contextParts.length > 0) {
                 return { prependContext: contextParts.join("\n\n") };
@@ -100,7 +137,7 @@ const fogclaw = {
                                 entities: result.entities,
                                 count: result.entities.length,
                                 summary: result.entities.length > 0
-                                    ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((e) => e.label))].join(", ")}`
+                                    ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((entity) => entity.label))].join(", ")}`
                                     : "No entities detected",
                             }, null, 2),
                         },
@@ -108,6 +145,66 @@ const fogclaw = {
                 };
             },
         });
+        // --- TOOL: Policy preview ---
+        api.registerTool({
+            name: "fogclaw_preview",
+            id: "fogclaw_preview",
+            description: "Preview which entities will be blocked, warned, or redacted and the redacted message, without changing runtime behavior.",
+            schema: {
+                type: "object",
+                properties: {
+                    text: {
+                        type: "string",
+                        description: "Text to run through FogClaw policy preview",
+                    },
+                    strategy: {
+                        type: "string",
+                        description: 'Override redaction strategy for the preview: "token" ([EMAIL_1]), "mask" (****), or "hash" ([EMAIL_a1b2c3...]).',
+                        enum: ["token", "mask", "hash"],
+                    },
+                    custom_labels: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional entity labels for zero-shot detection",
+                    },
+                },
+                required: ["text"],
+            },
+            handler: async ({ text, strategy, custom_labels, }) => {
+                const result = await scanner.scan(text, custom_labels);
+                const plan = buildGuardrailPlan(result.entities, config);
+                const summary = planToSummary(plan);
+                const redacted = redact(text, plan.redacted, strategy ?? config.redactStrategy);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                entities: result.entities,
+                                totalEntities: summary.total,
+                                actionPlan: {
+                                    blocked: {
+                                        count: summary.blocked,
+                                        labels: summary.labels.blocked,
+                                    },
+                                    warned: {
+                                        count: summary.warned,
+                                        labels: summary.labels.warned,
+                                    },
+                                    redacted: {
+                                        count: summary.redacted,
+                                        labels: summary.labels.redacted,
+                                    },
+                                },
+                                redactedText: redacted.redacted_text,
+                                redactionStrategy: strategy ?? config.redactStrategy,
+                                mapping: redacted.mapping,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            },
+        });
         // --- TOOL: On-demand redact ---
         api.registerTool({
             name: "fogclaw_redact",
@@ -150,7 +247,7 @@ const fogclaw = {
                 };
             },
         });
-        api.logger?.info(`[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}`);
+        api.logger?.info(`[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}, audit: ${config.auditEnabled}`);
     },
 };
 export default fogclaw;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/scanner.d.ts

@@ -1,11 +1,22 @@
-import type { FogClawConfig, ScanResult } from "./types.js";
+import type { Entity, FogClawConfig } from "./types.js";
 export declare class Scanner {
     private regexEngine;
     private glinerEngine;
     private glinerAvailable;
     private config;
+    private allowlist;
     constructor(config: FogClawConfig);
     initialize(): Promise<void>;
-    scan(text: string, extraLabels?: string[]): Promise<ScanResult>;
+    scan(text: string, extraLabels?: string[]): Promise<{
+        entities: Entity[];
+        text: string;
+    }>;
+    private filterByConfidence;
+    private filterByPolicy;
+    private shouldAllowlistEntity;
+    private getThresholdForLabel;
+    private computeGlinerThreshold;
+    private buildAllowlistCache;
+    get isGlinerAvailable(): boolean;
 }
 //# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIpE,qBAAa,OAAO;IAClB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IAY3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAqBtE"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuBxD,qBAAa,OAAO;IAClB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAwB;gBAE7B,MAAM,EAAE,aAAa;IAa3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IA4B/F,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,mBAAmB;IAuB3B,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF"}