@datafog/fogclaw 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0
+
+### Added
+
+- **Tool result PII scanning** — new `tool_result_persist` hook scans file reads, API responses, and web fetches for PII before they enter the session transcript. Uses regex engine (sync) for <1ms latency on the hot path.
+- **Outbound message PII scanning** — new `message_sending` hook provides a last-chance gate that catches PII in agent replies before delivery to Telegram, Slack, Discord, and other external channels. Uses full Scanner (regex + GLiNER).
+- **Policy allowlist** — whitelist exact strings, regex patterns, or per-entity-type values to skip enforcement on known-safe content (e.g., `noreply@example.com`).
+- **Per-entity confidence thresholds** — tune GLiNER detection sensitivity per label (e.g., require 0.7 for PERSON, 0.85 for ORGANIZATION).
+- **Audit trail logging** — structured audit log entries with `source` field (`guardrail`, `tool_result`, `outbound`) when `auditEnabled: true`. Logs entity counts and labels without raw PII.
+- **Policy preview tool** — `fogclaw_preview` shows which entities would be blocked, warned, or redacted without changing runtime behavior.
+- **Scanning architecture documentation** — README now includes a comparison matrix showing engine trade-offs across all three hooks.
+- **Control UI hints** — `openclaw.plugin.json` includes `uiHints` for policy configuration in OpenClaw's Control UI.
+
+### Changed
+
+- `resolveAction` extracted to shared `types.ts` module (was duplicated across files).
+- README updated with three-layer scanning overview and defense-in-depth flow diagram.
+
+## 0.1.6
+
+Initial scoped release as `@datafog/fogclaw`.
+
+- Dual-engine PII detection (regex + GLiNER via ONNX)
+- `before_agent_start` hook for automatic prompt guardrail
+- `fogclaw_scan` and `fogclaw_redact` tools
+- Configurable per-entity actions (`redact`, `block`, `warn`)
+- Multiple redaction strategies (`token`, `mask`, `hash`)
+- Custom entity types via GLiNER zero-shot NER
+- Graceful degradation to regex-only when GLiNER unavailable

package/README.md

@@ -6,12 +6,19 @@ FogClaw uses a dual-engine approach: battle-tested regex patterns for structured
 
 ## Features
 
+- **Three-layer scanning** — inbound prompts, tool results, and outbound messages are all scanned for PII before they cross trust boundaries
 - **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
+- **Tool result scanning** — redacts PII in file reads, API responses, and web fetches before they enter the session transcript (`tool_result_persist`)
+- **Outbound message scanning** — last-chance gate that catches PII in agent replies before delivery to external channels (`message_sending`)
+- **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 +67,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 +78,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,18 +132,54 @@ 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)
 ```
 
+## Scanning Architecture
+
+FogClaw hooks into three points in the OpenClaw message lifecycle. Each hook uses the detection engine best suited to its runtime constraints:
+
+| Hook | Direction | Engine | Latency | Async | Entity Coverage |
+|------|-----------|--------|---------|-------|-----------------|
+| `before_agent_start` | Inbound (user prompt) | Regex + GLiNER | ~50-200ms | Yes | Full — structured PII + names, orgs, custom entities |
+| `tool_result_persist` | Internal (tool results) | Regex only | <1ms | No (sync) | Structured PII — emails, SSNs, phones, credit cards, IPs |
+| `message_sending` | Outbound (agent reply) | Regex + GLiNER | ~50-200ms | Yes | Full — structured PII + names, orgs, custom entities |
+
+**Why regex-only for tool results?** OpenClaw's `tool_result_persist` hook requires synchronous handlers — async returns are rejected. GLiNER inference runs a synchronous ONNX native call that blocks the event loop for 100-500ms per invocation, which would degrade gateway responsiveness (delayed heartbeats, WebSocket pings, HTTP responses). Regex covers the high-confidence structured patterns most common in tool output (credentials in file reads, contact info in API responses). Person names and organization names are caught on the async inbound and outbound paths, providing defense-in-depth without hot-path latency.
+
+```
+User prompt ──► before_agent_start (regex + GLiNER)
+                        │
+                        ▼
+                   Agent + LLM
+                        │
+              ┌─────────┼─────────┐
+              ▼         ▼         ▼
+         Tool call  Tool call  Tool call
+              │         │         │
+              ▼         ▼         ▼
+     tool_result_persist (regex only, sync)
+                        │
+                        ▼
+                   Agent reply
+                        │
+                        ▼
+              message_sending (regex + GLiNER)
+                        │
+                        ▼
+                  External channel
+              (Telegram, Slack, etc.)
+```
+
 ## Detected Entity Types
 
 ### Regex Engine (structured PII)
@@ -162,8 +217,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 +233,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 +292,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/extract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Utilities for extracting text from AgentMessage tool result payloads
+ * and replacing text content after redaction.
+ *
+ * AgentMessage shapes handled:
+ * - Plain string
+ * - Object with `content: string`
+ * - Object with `content: [{ type: "text", text: "..." }, ...]`
+ *
+ * When multiple text blocks exist in a content array, they are joined
+ * with a null byte separator (\0) so entity offsets stay valid across
+ * the concatenated string. replaceText splits on the same separator
+ * to map redacted text back to individual blocks.
+ */
+/**
+ * Extract all text content from an AgentMessage tool result payload.
+ * Returns an empty string if no text content is found.
+ */
+export declare function extractText(message: unknown): string;
+/**
+ * Replace text content in an AgentMessage tool result payload with
+ * the redacted version. Returns a shallow copy; does not mutate.
+ *
+ * If the message shape is not recognized or has no text, returns
+ * the original message unchanged.
+ */
+export declare function replaceText(message: unknown, redactedText: string): unknown;
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CA4BpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAqC3E"}

package/dist/extract.js

@@ -0,0 +1,91 @@
+/**
+ * Utilities for extracting text from AgentMessage tool result payloads
+ * and replacing text content after redaction.
+ *
+ * AgentMessage shapes handled:
+ * - Plain string
+ * - Object with `content: string`
+ * - Object with `content: [{ type: "text", text: "..." }, ...]`
+ *
+ * When multiple text blocks exist in a content array, they are joined
+ * with a null byte separator (\0) so entity offsets stay valid across
+ * the concatenated string. replaceText splits on the same separator
+ * to map redacted text back to individual blocks.
+ */
+// Separator between text segments from content block arrays.
+// Null byte won't appear in regex PII patterns or normal text content.
+const SEGMENT_SEP = "\0";
+/**
+ * Extract all text content from an AgentMessage tool result payload.
+ * Returns an empty string if no text content is found.
+ */
+export function extractText(message) {
+    if (message == null)
+        return "";
+    if (typeof message === "string")
+        return message;
+    if (typeof message !== "object")
+        return "";
+    const msg = message;
+    const content = msg.content;
+    if (content == null)
+        return "";
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const textParts = [];
+        for (const block of content) {
+            if (block != null &&
+                typeof block === "object" &&
+                block.type === "text" &&
+                typeof block.text === "string") {
+                textParts.push(block.text);
+            }
+        }
+        if (textParts.length === 0)
+            return "";
+        return textParts.join(SEGMENT_SEP);
+    }
+    return "";
+}
+/**
+ * Replace text content in an AgentMessage tool result payload with
+ * the redacted version. Returns a shallow copy; does not mutate.
+ *
+ * If the message shape is not recognized or has no text, returns
+ * the original message unchanged.
+ */
+export function replaceText(message, redactedText) {
+    if (message == null)
+        return message;
+    if (typeof message === "string")
+        return redactedText;
+    if (typeof message !== "object")
+        return message;
+    const msg = message;
+    const content = msg.content;
+    if (content == null)
+        return message;
+    if (typeof content === "string") {
+        return { ...msg, content: redactedText };
+    }
+    if (Array.isArray(content)) {
+        const segments = redactedText.split(SEGMENT_SEP);
+        let segmentIndex = 0;
+        const newContent = content.map((block) => {
+            if (block != null &&
+                typeof block === "object" &&
+                block.type === "text" &&
+                typeof block.text === "string" &&
+                segmentIndex < segments.length) {
+                const replaced = { ...block, text: segments[segmentIndex] };
+                segmentIndex++;
+                return replaced;
+            }
+            return block;
+        });
+        return { ...msg, content: newContent };
+    }
+    return message;
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6DAA6D;AAC7D,uEAAuE;AACvE,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAE3C,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAE5B,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEhD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IACE,KAAK,IAAI,IAAI;gBACb,OAAO,KAAK,KAAK,QAAQ;gBACxB,KAAiC,CAAC,IAAI,KAAK,MAAM;gBAClD,OAAQ,KAAiC,CAAC,IAAI,KAAK,QAAQ,EAC3D,CAAC;gBACD,SAAS,CAAC,IAAI,CAAE,KAAiC,CAAC,IAAc,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,OAAO,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,YAAoB;IAChE,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IACpC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC;IACrD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEhD,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAE5B,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IAEpC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACvC,IACE,KAAK,IAAI,IAAI;gBACb,OAAO,KAAK,KAAK,QAAQ;gBACxB,KAAiC,CAAC,IAAI,KAAK,MAAM;gBAClD,OAAQ,KAAiC,CAAC,IAAI,KAAK,QAAQ;gBAC3D,YAAY,GAAG,QAAQ,CAAC,MAAM,EAC9B,CAAC;gBACD,MAAM,QAAQ,GAAG,EAAE,GAAI,KAAiC,EAAE,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;gBACzF,YAAY,EAAE,CAAC;gBACf,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;QAEH,OAAO,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

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":"AAgBA,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;AAqEpB;;;;;;;;GAQG;AACH,QAAA,MAAM,OAAO;;;kBAIG,GAAG;CA8QlB,CAAC;AAEF,eAAe,OAAO,CAAC"}