pic-guard 0.6.1

package/config/pic-plugin.example.json

@@ -0,0 +1,5 @@
+{
+    "bridge_url": "http://127.0.0.1:7580",
+    "bridge_timeout_ms": 500,
+    "log_level": "info"
+}

package/dist/hooks/pic-audit/handler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * pic-audit — PIC post-execution audit trail for OpenClaw.
+ *
+ * Hook: tool_result_persist (priority 200)
+ *
+ * Fires after a tool call completes. Logs a structured audit record.
+ * This provides an audit trail for compliance and debugging.
+ *
+ * This hook is read-only — it never modifies the tool result or blocks
+ * execution. It runs at priority 200 (after all functional hooks).
+ *
+ * IMPORTANT: This hook is SYNCHRONOUS ONLY — async handlers are rejected
+ * by the OpenClaw hook runner.
+ *
+ * LIMITATION: The real tool_result_persist event contains
+ * { toolName?, toolCallId?, message, isSynthetic? } — it does NOT include
+ * params or __pic metadata (pic-gate strips __pic before execution, and
+ * the persist event receives the result message, not the original call).
+ */
+/** Real shape of tool_result_persist event (from OpenClaw src/plugins/types.ts). */
+interface ToolResultPersistEvent {
+    toolName?: string;
+    toolCallId?: string;
+    message: Record<string, unknown>;
+    isSynthetic?: boolean;
+}
+/** Real shape of tool_result_persist context. */
+interface ToolResultPersistContext {
+    agentId?: string;
+    sessionKey?: string;
+    toolName?: string;
+    toolCallId?: string;
+}
+/**
+ * Factory: creates the tool_result_persist handler with captured plugin config.
+ */
+export declare function createPicAuditHandler(pluginConfig: Record<string, unknown>): (event: ToolResultPersistEvent, ctx: ToolResultPersistContext) => void;
+export {};

package/dist/hooks/pic-audit/handler.js

@@ -0,0 +1,60 @@
+/**
+ * pic-audit — PIC post-execution audit trail for OpenClaw.
+ *
+ * Hook: tool_result_persist (priority 200)
+ *
+ * Fires after a tool call completes. Logs a structured audit record.
+ * This provides an audit trail for compliance and debugging.
+ *
+ * This hook is read-only — it never modifies the tool result or blocks
+ * execution. It runs at priority 200 (after all functional hooks).
+ *
+ * IMPORTANT: This hook is SYNCHRONOUS ONLY — async handlers are rejected
+ * by the OpenClaw hook runner.
+ *
+ * LIMITATION: The real tool_result_persist event contains
+ * { toolName?, toolCallId?, message, isSynthetic? } — it does NOT include
+ * params or __pic metadata (pic-gate strips __pic before execution, and
+ * the persist event receives the result message, not the original call).
+ */
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig) {
+    return {
+        bridge_url: typeof pluginConfig.bridge_url === "string"
+            ? pluginConfig.bridge_url
+            : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms: typeof pluginConfig.bridge_timeout_ms === "number"
+            ? pluginConfig.bridge_timeout_ms
+            : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level: pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+            ? pluginConfig.log_level
+            : DEFAULT_CONFIG.log_level,
+    };
+}
+/**
+ * Factory: creates the tool_result_persist handler with captured plugin config.
+ */
+export function createPicAuditHandler(pluginConfig) {
+    return function handler(event, ctx) {
+        const config = resolveConfig(pluginConfig);
+        const toolName = event.toolName ?? ctx.toolName ?? "unknown";
+        const entry = {
+            timestamp: new Date().toISOString(),
+            event: "tool_result_persist",
+            tool: toolName,
+            toolCallId: event.toolCallId ?? ctx.toolCallId,
+            isSynthetic: event.isSynthetic ?? false,
+        };
+        // ── Log ────────────────────────────────────────────────────────────
+        if (config.log_level === "debug") {
+            console.debug(`[pic-audit] ${JSON.stringify(entry)}`);
+        }
+        else if (config.log_level === "info") {
+            console.log(`[pic-audit] tool=${entry.tool} callId=${entry.toolCallId ?? "n/a"} ` +
+                `synthetic=${entry.isSynthetic}`);
+        }
+    };
+}

package/dist/hooks/pic-gate/handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * pic-gate — PIC Standard pre-execution gate for OpenClaw.
+ *
+ * Hook: before_tool_call (priority 100)
+ *
+ * Sends the tool call (including any __pic proposal in params) to the PIC
+ * HTTP bridge for verification.
+ *
+ * - allowed  → strips __pic from params, tool proceeds
+ * - blocked  → returns { block: true, blockReason } — NEVER throws
+ * - bridge unreachable → blocked (fail-closed)
+ *
+ * IMPORTANT: Config comes from pluginConfig closure (captured in register()),
+ * NOT from ctx.pluginConfig (which doesn't exist in hook contexts).
+ */
+/** Real shape of before_tool_call event (from OpenClaw src/plugins/types.ts). */
+interface BeforeToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+}
+/** Real return type for before_tool_call hook. */
+type BeforeToolCallReturn = {
+    block: true;
+    blockReason: string;
+} | {
+    params: Record<string, unknown>;
+} | void;
+/**
+ * Factory: creates the before_tool_call handler with captured plugin config.
+ */
+export declare function createPicGateHandler(pluginConfig: Record<string, unknown>): (event: BeforeToolCallEvent, ctx: Record<string, unknown>) => Promise<BeforeToolCallReturn>;
+export {};

package/dist/hooks/pic-gate/handler.js

@@ -0,0 +1,67 @@
+/**
+ * pic-gate — PIC Standard pre-execution gate for OpenClaw.
+ *
+ * Hook: before_tool_call (priority 100)
+ *
+ * Sends the tool call (including any __pic proposal in params) to the PIC
+ * HTTP bridge for verification.
+ *
+ * - allowed  → strips __pic from params, tool proceeds
+ * - blocked  → returns { block: true, blockReason } — NEVER throws
+ * - bridge unreachable → blocked (fail-closed)
+ *
+ * IMPORTANT: Config comes from pluginConfig closure (captured in register()),
+ * NOT from ctx.pluginConfig (which doesn't exist in hook contexts).
+ */
+import { verifyToolCall } from "../../lib/pic-client.js";
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig) {
+    return {
+        bridge_url: typeof pluginConfig.bridge_url === "string"
+            ? pluginConfig.bridge_url
+            : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms: typeof pluginConfig.bridge_timeout_ms === "number"
+            ? pluginConfig.bridge_timeout_ms
+            : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level: pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+            ? pluginConfig.log_level
+            : DEFAULT_CONFIG.log_level,
+    };
+}
+/**
+ * Factory: creates the before_tool_call handler with captured plugin config.
+ */
+export function createPicGateHandler(pluginConfig) {
+    return async function handler(event, _ctx) {
+        const config = resolveConfig(pluginConfig);
+        // Defensive: ensure params is an object (fail-closed if malformed event)
+        const params = event.params ?? {};
+        if (typeof params !== "object" || params === null) {
+            return { block: true, blockReason: "PIC gate: malformed event (params not an object)" };
+        }
+        // Defensive: ensure toolName is a non-empty string
+        const toolName = event.toolName;
+        if (typeof toolName !== "string" || toolName.trim() === "") {
+            return { block: true, blockReason: "PIC gate: malformed event (toolName missing or empty)" };
+        }
+        // ── Verify against PIC bridge ──────────────────────────────────────
+        const result = await verifyToolCall(toolName, params, config);
+        // ── Blocked ────────────────────────────────────────────────────────
+        if (!result.allowed) {
+            const reason = result.error?.message ?? "PIC contract violation (no details)";
+            if (config.log_level === "debug" || config.log_level === "info") {
+                console.log(`[pic-gate] BLOCKED tool=${toolName} reason="${reason}"`);
+            }
+            return { block: true, blockReason: reason };
+        }
+        // ── Allowed — strip __pic metadata before tool executes ────────────
+        const { __pic, __pic_request_id, ...cleanParams } = params;
+        if (config.log_level === "debug") {
+            console.debug(`[pic-gate] ALLOWED tool=${toolName} eval_ms=${result.eval_ms}`);
+        }
+        return { params: cleanParams };
+    };
+}

package/dist/hooks/pic-init/handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * pic-init — PIC awareness injection for OpenClaw.
+ *
+ * Hook: before_agent_start (priority 50)
+ *
+ * Returns a prependContext string that informs the agent about PIC governance
+ * requirements, so it includes __pic proposals in high-impact tool calls.
+ *
+ * Also performs an early health check against the PIC bridge to surface
+ * connectivity issues at session start rather than at first tool call.
+ */
+/**
+ * Factory: creates the before_agent_start handler with captured plugin config.
+ */
+export declare function createPicInitHandler(pluginConfig: Record<string, unknown>): (event: {
+    prompt: string;
+    messages?: unknown[];
+}, ctx: Record<string, unknown>) => Promise<{
+    prependContext?: string;
+}>;

package/dist/hooks/pic-init/handler.js

@@ -0,0 +1,86 @@
+/**
+ * pic-init — PIC awareness injection for OpenClaw.
+ *
+ * Hook: before_agent_start (priority 50)
+ *
+ * Returns a prependContext string that informs the agent about PIC governance
+ * requirements, so it includes __pic proposals in high-impact tool calls.
+ *
+ * Also performs an early health check against the PIC bridge to surface
+ * connectivity issues at session start rather than at first tool call.
+ */
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+const PIC_AWARENESS_MESSAGE = `\
+[PIC Standard] This session is governed by Provenance & Intent Contracts.
+
+For high-impact tool calls (money transfers, data exports, irreversible
+actions), you MUST include a __pic field in the tool parameters with:
+  - intent: why this action is needed (string)
+  - impact: impact class (e.g., "money", "privacy", "irreversible")
+  - provenance: array of { id, trust } identifying instruction origins
+  - claims: array of { text, evidence } — verifiable assertions
+  - action: { tool, args } binding the proposal to the specific call
+
+Example __pic structure:
+{
+  "intent": "Transfer funds for approved invoice",
+  "impact": "money",
+  "provenance": [{ "id": "user_request", "trust": "trusted" }],
+  "claims": [{ "text": "Invoice verified", "evidence": ["invoice_hash"] }],
+  "action": { "tool": "payments_send", "args": { "amount": 100 } }
+}
+
+Tool calls without valid __pic proposals will be BLOCKED for high-impact
+operations. Low-impact tools may proceed without __pic.`;
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig) {
+    return {
+        bridge_url: typeof pluginConfig.bridge_url === "string"
+            ? pluginConfig.bridge_url
+            : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms: typeof pluginConfig.bridge_timeout_ms === "number"
+            ? pluginConfig.bridge_timeout_ms
+            : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level: pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+            ? pluginConfig.log_level
+            : DEFAULT_CONFIG.log_level,
+    };
+}
+/**
+ * Factory: creates the before_agent_start handler with captured plugin config.
+ */
+export function createPicInitHandler(pluginConfig) {
+    return async function handler(_event, _ctx) {
+        const config = resolveConfig(pluginConfig);
+        if (config.log_level === "debug") {
+            console.debug("[pic-init] Injected awareness message:", PIC_AWARENESS_MESSAGE);
+        }
+        // ── Early health check (best-effort, never blocks) ─────────────────
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), config.bridge_timeout_ms);
+        try {
+            const resp = await fetch(`${config.bridge_url}/health`, {
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                console.warn(`[pic-init] PIC bridge health check failed: HTTP ${resp.status}`);
+            }
+            else if (config.log_level === "debug") {
+                console.debug("[pic-init] PIC bridge is healthy");
+            }
+        }
+        catch {
+            console.warn(`[pic-init] PIC bridge unreachable at ${config.bridge_url} — ` +
+                "tool calls will be blocked (fail-closed) until the bridge is started.");
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (config.log_level === "debug" || config.log_level === "info") {
+            console.log("[pic-init] PIC awareness injected into session");
+        }
+        return { prependContext: PIC_AWARENESS_MESSAGE };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PIC Standard plugin for OpenClaw.
+ *
+ * Entry point — registers lifecycle hooks using api.on() for typed hook system.
+ *
+ * IMPORTANT: Use api.on() for lifecycle hooks (before_tool_call, etc.), NOT api.registerHook().
+ * - api.registerHook() → internal hooks (old system, requires config flag)
+ * - api.on() → typed hooks (new system, always active, used by hook runner)
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+export default function register(api: OpenClawPluginApi): void;

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * PIC Standard plugin for OpenClaw.
+ *
+ * Entry point — registers lifecycle hooks using api.on() for typed hook system.
+ *
+ * IMPORTANT: Use api.on() for lifecycle hooks (before_tool_call, etc.), NOT api.registerHook().
+ * - api.registerHook() → internal hooks (old system, requires config flag)
+ * - api.on() → typed hooks (new system, always active, used by hook runner)
+ */
+import { createPicAuditHandler } from "./hooks/pic-audit/handler.js";
+import { createPicGateHandler } from "./hooks/pic-gate/handler.js";
+import { createPicInitHandler } from "./hooks/pic-init/handler.js";
+export default function register(api) {
+    const pluginConfig = (api.pluginConfig ?? {});
+    // pic-init: Inject PIC awareness at session start
+    api.on("before_agent_start", createPicInitHandler(pluginConfig), { priority: 50 });
+    // pic-gate: Verify tool calls before execution (fail-closed)
+    api.on("before_tool_call", createPicGateHandler(pluginConfig), { priority: 100 });
+    // pic-audit: Log verification outcomes after execution
+    api.on("tool_result_persist", createPicAuditHandler(pluginConfig), { priority: 200 });
+}

package/dist/lib/pic-client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PIC HTTP Bridge client – fail-closed HTTP client for the PIC verifier.
+ *
+ * Calls POST /verify on the Python-side bridge and returns a typed response.
+ * On ANY failure (timeout, connection refused, malformed response) the client
+ * returns { allowed: false } — never throws.
+ */
+import type { PICVerifyResponse, PICPluginConfig } from "./types.js";
+/**
+ * Verify a tool call against the PIC HTTP bridge.
+ *
+ * @param toolName  - The tool being invoked (e.g. "exec", "write_file").
+ * @param toolArgs  - Full tool arguments (should include __pic if the agent provided one).
+ * @param config    - Plugin configuration (bridge URL, timeout).
+ * @returns           PICVerifyResponse — always resolves, never rejects.
+ */
+export declare function verifyToolCall(toolName: string, toolArgs: Record<string, unknown>, config?: PICPluginConfig): Promise<PICVerifyResponse>;

package/dist/lib/pic-client.js

@@ -0,0 +1,112 @@
+/**
+ * PIC HTTP Bridge client – fail-closed HTTP client for the PIC verifier.
+ *
+ * Calls POST /verify on the Python-side bridge and returns a typed response.
+ * On ANY failure (timeout, connection refused, malformed response) the client
+ * returns { allowed: false } — never throws.
+ */
+import { DEFAULT_CONFIG } from "./types.js";
+/** Valid PIC error codes for runtime validation. */
+const VALID_ERROR_CODES = [
+    "PIC_INVALID_REQUEST",
+    "PIC_LIMIT_EXCEEDED",
+    "PIC_SCHEMA_INVALID",
+    "PIC_VERIFIER_FAILED",
+    "PIC_TOOL_BINDING_MISMATCH",
+    "PIC_EVIDENCE_REQUIRED",
+    "PIC_EVIDENCE_FAILED",
+    "PIC_POLICY_VIOLATION",
+    "PIC_INTERNAL_ERROR",
+    "PIC_BRIDGE_UNREACHABLE",
+];
+// TODO: Future telemetry hook point
+// - count of failed bridge calls
+// - average eval_ms
+// - distribution of error.code values
+/**
+ * Verify a tool call against the PIC HTTP bridge.
+ *
+ * @param toolName  - The tool being invoked (e.g. "exec", "write_file").
+ * @param toolArgs  - Full tool arguments (should include __pic if the agent provided one).
+ * @param config    - Plugin configuration (bridge URL, timeout).
+ * @returns           PICVerifyResponse — always resolves, never rejects.
+ */
+export async function verifyToolCall(toolName, toolArgs, config = DEFAULT_CONFIG) {
+    const body = {
+        tool_name: toolName,
+        tool_args: toolArgs,
+    };
+    if (config.log_level === "debug") {
+        console.debug(`[pic-client] POST ${config.bridge_url}/verify tool=${toolName}`);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.bridge_timeout_ms);
+    try {
+        const resp = await fetch(`${config.bridge_url}/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        // Fail-closed on HTTP errors (5xx, 4xx, etc.)
+        if (!resp.ok) {
+            return failClosed(`Bridge returned HTTP ${resp.status}`);
+        }
+        const json = (await resp.json());
+        // Sanity-check the response shape
+        if (typeof json.allowed !== "boolean") {
+            console.warn(`[pic-client] Malformed response: ${JSON.stringify(json)}`);
+            return failClosed("Malformed bridge response: missing 'allowed'");
+        }
+        // Normalize eval_ms
+        const eval_ms = typeof json.eval_ms === "number" ? json.eval_ms : 0;
+        if (json.allowed === true) {
+            // Success case: allowed: true, error: null
+            if (config.log_level === "debug") {
+                console.debug(`[pic-client] result: allowed=true eval_ms=${eval_ms}`);
+            }
+            return { allowed: true, error: null, eval_ms };
+        }
+        // Denial case: allowed: false, error: PICError
+        const error = json.error;
+        if (!error || typeof error.code !== "string") {
+            console.warn(`[pic-client] Malformed denial response: ${JSON.stringify(json)}`);
+            return failClosed("Malformed bridge response: denial missing error code");
+        }
+        if (!VALID_ERROR_CODES.includes(error.code)) {
+            console.warn(`[pic-client] Unknown error code: ${error.code}`);
+            return failClosed(`Malformed bridge response: unknown error code '${error.code}'`);
+        }
+        const picError = {
+            code: error.code,
+            message: typeof error.message === "string" ? error.message : "Unknown error",
+            details: typeof error.details === "object" ? error.details : undefined,
+        };
+        if (config.log_level === "debug") {
+            console.debug(`[pic-client] result: allowed=false eval_ms=${eval_ms} code=${picError.code}`);
+        }
+        return { allowed: false, error: picError, eval_ms };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown bridge error";
+        return failClosed(message);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Fail-closed helper: returns a block response when the bridge is unreachable
+ * or returns garbage.  This ensures the plugin never silently allows a tool
+ * call just because the bridge is down.
+ */
+function failClosed(reason) {
+    return {
+        allowed: false,
+        error: {
+            code: "PIC_BRIDGE_UNREACHABLE",
+            message: `PIC bridge error: ${reason}`,
+        },
+        eval_ms: 0,
+    };
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PIC Standard – TypeScript types for the HTTP bridge protocol.
+ *
+ * These mirror the Python-side contracts defined in:
+ *   sdk-python/pic_standard/integrations/http_bridge.py
+ *   sdk-python/pic_standard/errors.py         (PICErrorCode)
+ *
+ * Verification logic lives in sdk-python/pic_standard/pipeline.py
+ */
+/**
+ * All possible PIC error codes.
+ * Mirrors PICErrorCode enum in sdk-python/pic_standard/errors.py.
+ */
+export type PICErrorCode = "PIC_INVALID_REQUEST" | "PIC_LIMIT_EXCEEDED" | "PIC_SCHEMA_INVALID" | "PIC_VERIFIER_FAILED" | "PIC_TOOL_BINDING_MISMATCH" | "PIC_EVIDENCE_REQUIRED" | "PIC_EVIDENCE_FAILED" | "PIC_POLICY_VIOLATION" | "PIC_INTERNAL_ERROR" | "PIC_BRIDGE_UNREACHABLE";
+/** Body sent to POST /verify on the PIC HTTP bridge. */
+export interface PICVerifyRequest {
+    tool_name: string;
+    tool_args: Record<string, unknown>;
+}
+/** Structured error returned when allowed === false. */
+export interface PICError {
+    code: PICErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Response from POST /verify. Always 200 — decision is in `allowed`.
+ *
+ * Modeled as a discriminated union to match the wire format:
+ * - allowed: true  → error: null
+ * - allowed: false → error: PICError
+ */
+export type PICVerifyResponse = {
+    allowed: true;
+    error: null;
+    eval_ms: number;
+} | {
+    allowed: false;
+    error: PICError;
+    eval_ms: number;
+};
+/** Configuration for the pic-guard OpenClaw plugin. */
+export interface PICPluginConfig {
+    /** URL of the PIC HTTP bridge (default: "http://127.0.0.1:7580"). */
+    bridge_url: string;
+    /** HTTP timeout in milliseconds (default: 500). */
+    bridge_timeout_ms: number;
+    /** Log level: "debug" | "info" | "warn" (default: "info"). */
+    log_level: "debug" | "info" | "warn";
+}
+/** Sensible defaults matching PICEvaluateLimits on the Python side. */
+export declare const DEFAULT_CONFIG: PICPluginConfig;

package/dist/lib/types.js

@@ -0,0 +1,15 @@
+/**
+ * PIC Standard – TypeScript types for the HTTP bridge protocol.
+ *
+ * These mirror the Python-side contracts defined in:
+ *   sdk-python/pic_standard/integrations/http_bridge.py
+ *   sdk-python/pic_standard/errors.py         (PICErrorCode)
+ *
+ * Verification logic lives in sdk-python/pic_standard/pipeline.py
+ */
+/** Sensible defaults matching PICEvaluateLimits on the Python side. */
+export const DEFAULT_CONFIG = {
+    bridge_url: "http://127.0.0.1:7580",
+    bridge_timeout_ms: 500,
+    log_level: "info",
+};

package/hooks/pic-audit/HOOK.md

@@ -0,0 +1,22 @@
+---
+name: pic-audit
+description: PIC post-execution audit trail — logs verification outcomes after tool execution
+metadata:
+  openclaw:
+    events: ["tool_result_persist"]
+    priority: 200
+---
+
+# pic-audit — PIC Post-Execution Audit Trail
+
+Fires after every tool execution via `tool_result_persist`. Logs a
+structured audit record capturing the PIC verification outcome for
+the tool call that just completed.
+
+## Behavior
+
+- Logs structured JSON at debug level
+- Logs summary line at info level
+- Records: tool name, whether PIC was present, verification result
+- Never modifies the tool result
+- Never throws

package/hooks/pic-audit/handler.ts

@@ -0,0 +1,101 @@
+/**
+ * pic-audit — PIC post-execution audit trail for OpenClaw.
+ *
+ * Hook: tool_result_persist (priority 200)
+ *
+ * Fires after a tool call completes. Logs a structured audit record.
+ * This provides an audit trail for compliance and debugging.
+ *
+ * This hook is read-only — it never modifies the tool result or blocks
+ * execution. It runs at priority 200 (after all functional hooks).
+ *
+ * IMPORTANT: This hook is SYNCHRONOUS ONLY — async handlers are rejected
+ * by the OpenClaw hook runner.
+ *
+ * LIMITATION: The real tool_result_persist event contains
+ * { toolName?, toolCallId?, message, isSynthetic? } — it does NOT include
+ * params or __pic metadata (pic-gate strips __pic before execution, and
+ * the persist event receives the result message, not the original call).
+ */
+
+import type { PICPluginConfig } from "../../lib/types.js";
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+
+/** Real shape of tool_result_persist event (from OpenClaw src/plugins/types.ts). */
+interface ToolResultPersistEvent {
+    toolName?: string;
+    toolCallId?: string;
+    message: Record<string, unknown>;
+    isSynthetic?: boolean;
+}
+
+/** Real shape of tool_result_persist context. */
+interface ToolResultPersistContext {
+    agentId?: string;
+    sessionKey?: string;
+    toolName?: string;
+    toolCallId?: string;
+}
+
+/** Structured audit entry written to console. */
+interface PICAuditEntry {
+    timestamp: string;
+    event: "tool_result_persist";
+    tool: string;
+    toolCallId?: string;
+    isSynthetic: boolean;
+}
+
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig: Record<string, unknown>): PICPluginConfig {
+    return {
+        bridge_url:
+            typeof pluginConfig.bridge_url === "string"
+                ? pluginConfig.bridge_url
+                : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms:
+            typeof pluginConfig.bridge_timeout_ms === "number"
+                ? pluginConfig.bridge_timeout_ms
+                : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level:
+            pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+                ? pluginConfig.log_level
+                : DEFAULT_CONFIG.log_level,
+    };
+}
+
+/**
+ * Factory: creates the tool_result_persist handler with captured plugin config.
+ */
+export function createPicAuditHandler(
+    pluginConfig: Record<string, unknown>,
+): (event: ToolResultPersistEvent, ctx: ToolResultPersistContext) => void {
+    return function handler(
+        event: ToolResultPersistEvent,
+        ctx: ToolResultPersistContext,
+    ): void {
+        const config = resolveConfig(pluginConfig);
+
+        const toolName = event.toolName ?? ctx.toolName ?? "unknown";
+
+        const entry: PICAuditEntry = {
+            timestamp: new Date().toISOString(),
+            event: "tool_result_persist",
+            tool: toolName,
+            toolCallId: event.toolCallId ?? ctx.toolCallId,
+            isSynthetic: event.isSynthetic ?? false,
+        };
+
+        // ── Log ────────────────────────────────────────────────────────────
+        if (config.log_level === "debug") {
+            console.debug(`[pic-audit] ${JSON.stringify(entry)}`);
+        } else if (config.log_level === "info") {
+            console.log(
+                `[pic-audit] tool=${entry.tool} callId=${entry.toolCallId ?? "n/a"} ` +
+                `synthetic=${entry.isSynthetic}`,
+            );
+        }
+    };
+}

package/hooks/pic-gate/HOOK.md

@@ -0,0 +1,65 @@
+---
+name: pic-gate
+description: PIC Standard pre-execution gate — verifies tool calls against the PIC bridge
+metadata:
+  openclaw:
+    events: ["before_tool_call"]
+    priority: 100
+---
+
+# pic-gate — PIC Standard Pre-Execution Gate
+
+Intercepts every tool call via `before_tool_call` and verifies the agent's
+PIC proposal against the PIC HTTP bridge before execution.
+
+## Behavior
+
+|
+ Condition
+|
+ Result
+|
+|
+-----------
+|
+--------
+|
+|
+ Bridge returns
+`allowed: true`
+|
+ Tool executes;
+`__pic`
+ stripped from params
+|
+|
+ Bridge returns
+`allowed: false`
+|
+ Tool blocked with
+`blockReason`
+|
+|
+ Bridge unreachable / timeout
+|
+ Tool blocked (fail-closed)
+|
+
+## Requirements
+
+- OpenClaw ≥ v2026.2.1 (before_tool_call hook support)
+- PIC HTTP bridge running (`pic-cli serve` or programmatic `start_bridge()`)
+- Python 3.10+ with `pic-standard` installed (for the bridge, not the hook)
+- Default bridge URL: `http://127.0.0.1:7580`
+
+## Configuration
+
+Set via `config/pic-plugin.example.json`:
+
+```json
+{
+  "bridge_url": "http://127.0.0.1:7580",
+  "bridge_timeout_ms": 500,
+  "log_level": "info"
+}
+```

package/hooks/pic-gate/handler.ts

@@ -0,0 +1,108 @@
+/**
+ * pic-gate — PIC Standard pre-execution gate for OpenClaw.
+ *
+ * Hook: before_tool_call (priority 100)
+ *
+ * Sends the tool call (including any __pic proposal in params) to the PIC
+ * HTTP bridge for verification.
+ *
+ * - allowed  → strips __pic from params, tool proceeds
+ * - blocked  → returns { block: true, blockReason } — NEVER throws
+ * - bridge unreachable → blocked (fail-closed)
+ *
+ * IMPORTANT: Config comes from pluginConfig closure (captured in register()),
+ * NOT from ctx.pluginConfig (which doesn't exist in hook contexts).
+ */
+
+import { verifyToolCall } from "../../lib/pic-client.js";
+import type { PICPluginConfig } from "../../lib/types.js";
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+
+/** Real shape of before_tool_call event (from OpenClaw src/plugins/types.ts). */
+interface BeforeToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+}
+
+/** Real return type for before_tool_call hook. */
+type BeforeToolCallReturn =
+    | { block: true; blockReason: string }
+    | { params: Record<string, unknown> }
+    | void;
+
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig: Record<string, unknown>): PICPluginConfig {
+    return {
+        bridge_url:
+            typeof pluginConfig.bridge_url === "string"
+                ? pluginConfig.bridge_url
+                : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms:
+            typeof pluginConfig.bridge_timeout_ms === "number"
+                ? pluginConfig.bridge_timeout_ms
+                : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level:
+            pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+                ? pluginConfig.log_level
+                : DEFAULT_CONFIG.log_level,
+    };
+}
+
+/**
+ * Factory: creates the before_tool_call handler with captured plugin config.
+ */
+export function createPicGateHandler(
+    pluginConfig: Record<string, unknown>,
+): (event: BeforeToolCallEvent, ctx: Record<string, unknown>) => Promise<BeforeToolCallReturn> {
+    return async function handler(
+        event: BeforeToolCallEvent,
+        _ctx: Record<string, unknown>,
+    ): Promise<BeforeToolCallReturn> {
+        const config = resolveConfig(pluginConfig);
+
+        // Defensive: ensure params is an object (fail-closed if malformed event)
+        const params = event.params ?? {};
+        if (typeof params !== "object" || params === null) {
+            return { block: true, blockReason: "PIC gate: malformed event (params not an object)" };
+        }
+
+        // Defensive: ensure toolName is a non-empty string
+        const toolName = event.toolName;
+        if (typeof toolName !== "string" || toolName.trim() === "") {
+            return { block: true, blockReason: "PIC gate: malformed event (toolName missing or empty)" };
+        }
+
+        // ── Verify against PIC bridge ──────────────────────────────────────
+        const result = await verifyToolCall(toolName, params, config);
+
+        // ── Blocked ────────────────────────────────────────────────────────
+        if (!result.allowed) {
+            const reason =
+                result.error?.message ?? "PIC contract violation (no details)";
+
+            if (config.log_level === "debug" || config.log_level === "info") {
+                console.log(
+                    `[pic-gate] BLOCKED tool=${toolName} reason="${reason}"`,
+                );
+            }
+
+            return { block: true, blockReason: reason };
+        }
+
+        // ── Allowed — strip __pic metadata before tool executes ────────────
+        const { __pic, __pic_request_id, ...cleanParams } = params as Record<
+            string,
+            unknown
+        > & { __pic?: unknown; __pic_request_id?: unknown };
+
+        if (config.log_level === "debug") {
+            console.debug(
+                `[pic-gate] ALLOWED tool=${toolName} eval_ms=${result.eval_ms}`,
+            );
+        }
+
+        return { params: cleanParams };
+    };
+}

package/hooks/pic-init/HOOK.md

@@ -0,0 +1,20 @@
+---
+name: pic-init
+description: PIC awareness injection — informs the agent about PIC governance at session start
+metadata:
+  openclaw:
+    events: ["before_agent_start"]
+    priority: 50
+---
+
+# pic-init — PIC Awareness Injection
+
+Fires once at session start via `before_agent_start`. Pushes a system
+message that tells the agent about PIC governance so it knows to include
+`__pic` proposals in tool calls.
+
+## Behavior
+
+- Pushes a concise PIC awareness message into `event.messages`
+- Checks bridge health to warn early if the bridge is unreachable
+- Never blocks, never throws

package/hooks/pic-init/handler.ts

@@ -0,0 +1,104 @@
+/**
+ * pic-init — PIC awareness injection for OpenClaw.
+ *
+ * Hook: before_agent_start (priority 50)
+ *
+ * Returns a prependContext string that informs the agent about PIC governance
+ * requirements, so it includes __pic proposals in high-impact tool calls.
+ *
+ * Also performs an early health check against the PIC bridge to surface
+ * connectivity issues at session start rather than at first tool call.
+ */
+
+import type { PICPluginConfig } from "../../lib/types.js";
+import { DEFAULT_CONFIG } from "../../lib/types.js";
+
+const PIC_AWARENESS_MESSAGE = `\
+[PIC Standard] This session is governed by Provenance & Intent Contracts.
+
+For high-impact tool calls (money transfers, data exports, irreversible
+actions), you MUST include a __pic field in the tool parameters with:
+  - intent: why this action is needed (string)
+  - impact: impact class (e.g., "money", "privacy", "irreversible")
+  - provenance: array of { id, trust } identifying instruction origins
+  - claims: array of { text, evidence } — verifiable assertions
+  - action: { tool, args } binding the proposal to the specific call
+
+Example __pic structure:
+{
+  "intent": "Transfer funds for approved invoice",
+  "impact": "money",
+  "provenance": [{ "id": "user_request", "trust": "trusted" }],
+  "claims": [{ "text": "Invoice verified", "evidence": ["invoice_hash"] }],
+  "action": { "tool": "payments_send", "args": { "amount": 100 } }
+}
+
+Tool calls without valid __pic proposals will be BLOCKED for high-impact
+operations. Low-impact tools may proceed without __pic.`;
+
+/**
+ * Resolve plugin config from captured pluginConfig (closure from register()).
+ */
+function resolveConfig(pluginConfig: Record<string, unknown>): PICPluginConfig {
+    return {
+        bridge_url:
+            typeof pluginConfig.bridge_url === "string"
+                ? pluginConfig.bridge_url
+                : DEFAULT_CONFIG.bridge_url,
+        bridge_timeout_ms:
+            typeof pluginConfig.bridge_timeout_ms === "number"
+                ? pluginConfig.bridge_timeout_ms
+                : DEFAULT_CONFIG.bridge_timeout_ms,
+        log_level:
+            pluginConfig.log_level === "debug" || pluginConfig.log_level === "info" || pluginConfig.log_level === "warn"
+                ? pluginConfig.log_level
+                : DEFAULT_CONFIG.log_level,
+    };
+}
+
+/**
+ * Factory: creates the before_agent_start handler with captured plugin config.
+ */
+export function createPicInitHandler(
+    pluginConfig: Record<string, unknown>,
+): (event: { prompt: string; messages?: unknown[] }, ctx: Record<string, unknown>) => Promise<{ prependContext?: string }> {
+    return async function handler(
+        _event: { prompt: string; messages?: unknown[] },
+        _ctx: Record<string, unknown>,
+    ): Promise<{ prependContext?: string }> {
+        const config = resolveConfig(pluginConfig);
+
+        if (config.log_level === "debug") {
+            console.debug("[pic-init] Injected awareness message:", PIC_AWARENESS_MESSAGE);
+        }
+
+        // ── Early health check (best-effort, never blocks) ─────────────────
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), config.bridge_timeout_ms);
+
+        try {
+            const resp = await fetch(`${config.bridge_url}/health`, {
+                signal: controller.signal,
+            });
+
+            if (!resp.ok) {
+                console.warn(`[pic-init] PIC bridge health check failed: HTTP ${resp.status}`);
+            } else if (config.log_level === "debug") {
+                console.debug("[pic-init] PIC bridge is healthy");
+            }
+        } catch {
+            console.warn(
+                `[pic-init] PIC bridge unreachable at ${config.bridge_url} — ` +
+                "tool calls will be blocked (fail-closed) until the bridge is started.",
+            );
+        } finally {
+            clearTimeout(timeout);
+        }
+
+        if (config.log_level === "debug" || config.log_level === "info") {
+            console.log("[pic-init] PIC awareness injected into session");
+        }
+
+        return { prependContext: PIC_AWARENESS_MESSAGE };
+    };
+}

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+    "id": "pic-guard",
+    "name": "PIC Standard Guard",
+    "version": "0.6.1",
+    "description": "Provenance & Intent Contract verification for OpenClaw tool calls",
+    "configSchema": {
+        "type": "object",
+        "properties": {
+            "bridge_url": {
+                "type": "string",
+                "default": "http://127.0.0.1:7580",
+                "description": "PIC HTTP bridge endpoint URL"
+            },
+            "bridge_timeout_ms": {
+                "type": "integer",
+                "default": 500,
+                "minimum": 100,
+                "maximum": 5000,
+                "description": "HTTP timeout for bridge verification calls (milliseconds)"
+            },
+            "log_level": {
+                "type": "string",
+                "enum": [
+                    "debug",
+                    "info",
+                    "warn"
+                ],
+                "default": "info",
+                "description": "Logging verbosity level"
+            }
+        },
+        "additionalProperties": false
+    },
+    "uiHints": {
+        "bridge_url": {
+            "label": "Bridge URL",
+            "placeholder": "http://127.0.0.1:7580",
+            "description": "URL of the PIC HTTP bridge (pic-cli serve). Leave blank to use default localhost."
+        },
+        "bridge_timeout_ms": {
+            "label": "Timeout (ms)",
+            "inputType": "number",
+            "description": "Maximum time to wait for bridge response before blocking the tool call (fail-closed)."
+        },
+        "log_level": {
+            "label": "Log Level",
+            "description": "Controls verbosity: debug (all details), info (gate/audit events), warn (errors only)."
+        }
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "pic-guard",
+    "version": "0.6.1",
+    "description": "PIC Standard governance plugin for OpenClaw",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "prepublishOnly": "npm run build"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "files": [
+        "dist",
+        "hooks",
+        "config",
+        "openclaw.plugin.json"
+    ],
+    "openclaw": {
+        "extensions": [
+            "./dist/index.js"
+        ]
+    },
+    "keywords": [
+        "pic",
+        "provenance",
+        "intent",
+        "contracts",
+        "openclaw",
+        "plugin",
+        "ai-safety",
+        "tool-governance"
+    ],
+    "author": "Fabio Marcello Salvadori",
+    "license": "Apache-2.0",
+    "homepage": "https://github.com/madeinplutofabio/pic-standard/tree/main/integrations/openclaw",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/madeinplutofabio/pic-standard.git",
+        "directory": "integrations/openclaw"
+    },
+    "bugs": {
+        "url": "https://github.com/madeinplutofabio/pic-standard/issues"
+    },
+    "peerDependencies": {
+        "openclaw": ">=2026.2.1"
+    },
+    "devDependencies": {
+        "@types/node": "^20.19.32",
+        "typescript": "^5.9.3",
+        "vitest": "^1.6.1"
+    }
+}