dsh-perm-gate 0.2.0

package/lib/evaluate.js

@@ -0,0 +1,94 @@
+/**
+ * First-match decision for dsh-perm-gate. Given a tool call + its command/path
+ * candidate strings, evaluate the deny-first rule chain and return the first
+ * matching action (or `defaultAction`). Pure — no I/O.
+ */
+import { normalizeWorkspacePath } from './path.js';
+import { extractPathCandidates, extractUrlCandidates, } from './rule.js';
+import { decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
+const SHELL_TOOLS = new Set(['bash', 'pwsh', 'sh', 'cmd', 'powershell']);
+/** Whether one compiled rule matches the given call context. */
+export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
+    if (!rule.enabled)
+        return false;
+    // tools dimension: any glob matches.
+    if (rule.tools.length > 0 && !rule.tools.some((t) => t.re.test(ctx.tool)))
+        return false;
+    const ci = ctx.caseInsensitive ?? false;
+    // command dimension: at least one decomposed simple command satisfies some command spec.
+    if (rule.command.length > 0) {
+        if (commands.length === 0)
+            return false;
+        let ok = false;
+        for (const spec of rule.command) {
+            for (const cmd of commands) {
+                if (!spec.word.re.test(cmd.command))
+                    continue;
+                if (spec.flag === 'recursive' && !isRecursiveDeletion(cmd))
+                    continue;
+                if (spec.flag === 'force' && !isForceDeletion(cmd))
+                    continue;
+                ok = true;
+                break;
+            }
+            if (ok)
+                break;
+        }
+        if (!ok)
+            return false;
+    }
+    // args dimension: any token matches any args glob.
+    if (rule.args.length > 0) {
+        const tokens = [];
+        for (const cmd of commands)
+            tokens.push(...cmd.args, ...cmd.redirects);
+        tokens.push(...pathCands, ...urlCands);
+        if (!tokens.some((tok) => rule.args.some((g) => g.re.test(tok))))
+            return false;
+    }
+    // paths dimension: any workspace-relative path candidate matches any path glob.
+    if (rule.paths.length > 0) {
+        const rel = pathCands
+            .map((p) => normalizeWorkspacePath(ctx.cwd, p, ci))
+            .filter((p) => p.length > 0);
+        if (rel.length === 0)
+            return false;
+        if (!rel.some((p) => rule.paths.some((g) => g.re.test(p))))
+            return false;
+    }
+    return true;
+}
+/** Compute the deterministic first-match decision (P2 chain). */
+export function decideRules(ruleset, ctx) {
+    const commands = ctx.commandText !== undefined && SHELL_TOOLS.has(ctx.tool)
+        ? decomposeSafe(ctx.commandText)
+        : [];
+    const pathCands = extractPathCandidates(ctx.args);
+    const urlCands = extractUrlCandidates(ctx.args);
+    const scan = (list, _action) => {
+        for (const rule of list) {
+            if (ruleMatches(rule, ctx, commands, pathCands, urlCands)) {
+                return { action: rule.action, reason: rule.reason, ruleIndex: rule.index };
+            }
+        }
+        return undefined;
+    };
+    const deny = scan(ruleset.deny, 'deny');
+    if (deny !== undefined)
+        return deny;
+    const allow = scan(ruleset.allow, 'allow');
+    if (allow !== undefined)
+        return allow;
+    const ask = scan(ruleset.ask, 'ask');
+    if (ask !== undefined)
+        return ask;
+    return { action: ruleset.defaultAction, reason: `no rule matched; default action`, ruleIndex: undefined };
+}
+function decomposeSafe(text) {
+    try {
+        return decomposeShellCommand(text).commands;
+    }
+    catch {
+        return [];
+    }
+}

package/lib/events.d.ts

@@ -0,0 +1,56 @@
+/** One gate decision event. `kind` drives the client notice strip styling. */
+export interface GateEvent {
+    /** Monotonic id (resumed from the file across restarts). */
+    readonly id: number;
+    readonly ts: string;
+    readonly sessionId: string;
+    readonly tool: string;
+    /** auto = allowed (rule/grant/llm), ask = routed to the human, deny = vetoed, learned = confirmation settled. */
+    readonly kind: 'auto' | 'ask' | 'deny' | 'learned';
+    /** Risk category when an LLM verdict contributed to the decision. */
+    readonly risk?: string;
+    /** Truncated decision reason. */
+    readonly reason: string;
+}
+export interface GateEventInput {
+    readonly sessionId?: string;
+    readonly tool: string;
+    readonly kind: GateEvent['kind'];
+    readonly risk?: string;
+    readonly reason: string;
+}
+export declare class EventLog {
+    /** JSONL path; `undefined` disables event recording entirely. */
+    private readonly filePath;
+    private readonly now;
+    private seq;
+    constructor(
+    /** JSONL path; `undefined` disables event recording entirely. */
+    filePath: string | undefined, now?: () => number);
+    /** Append one event; returns it, or undefined when recording is disabled/failed. */
+    append(input: GateEventInput): GateEvent | undefined;
+    /** Events with `id > since`, optionally filtered to one session. */
+    query({ sessionId, since }?: {
+        sessionId?: string;
+        since?: number;
+    }): GateEvent[];
+    private nextId;
+}
+/**
+ * The minimal face of the DSH `webServer` service this plugin uses
+ * (typed locally — never value-imported; provided by the dsh runtime).
+ */
+export interface WebServerLike {
+    register(route: {
+        kind: 'exact';
+        path: string;
+        handler: (req: unknown, res: unknown) => unknown;
+    }): () => void;
+}
+export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
+/**
+ * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
+ * service. Returns whether the route was registered (false when the service is
+ * unavailable — the host keeps running, only the HTTP API is missing).
+ */
+export declare function registerEventsRoute(server: unknown, log: EventLog): boolean;

package/lib/events.js

@@ -0,0 +1,129 @@
+/**
+ * Gate decision events for dsh-perm-gate: a JSONL audit feed the browser half
+ * polls so every automatic allow / ask / deny is visible in the conversation UI.
+ *
+ * Pure append-only logging: every I/O error is swallowed (events are best-effort
+ * and must never influence gating), and the id sequence resumes from the file on
+ * first use so restarts never reuse an id the client has already seen.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const REASON_MAX = 200;
+export class EventLog {
+    filePath;
+    now;
+    seq = -1; // lazily restored from the file on first append
+    constructor(
+    /** JSONL path; `undefined` disables event recording entirely. */
+    filePath, now = Date.now) {
+        this.filePath = filePath;
+        this.now = now;
+    }
+    /** Append one event; returns it, or undefined when recording is disabled/failed. */
+    append(input) {
+        if (this.filePath === undefined)
+            return undefined;
+        try {
+            const id = this.nextId();
+            const ev = {
+                id,
+                ts: new Date(this.now()).toISOString(),
+                sessionId: input.sessionId ?? '',
+                tool: input.tool,
+                kind: input.kind,
+                ...(input.risk === undefined ? {} : { risk: input.risk }),
+                reason: String(input.reason).slice(0, REASON_MAX),
+            };
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            appendFileSync(this.filePath, JSON.stringify(ev) + '\n', 'utf8');
+            return ev;
+        }
+        catch {
+            return undefined; // best-effort only
+        }
+    }
+    /** Events with `id > since`, optionally filtered to one session. */
+    query({ sessionId, since } = {}) {
+        if (this.filePath === undefined)
+            return [];
+        let text;
+        try {
+            text = readFileSync(this.filePath, 'utf8');
+        }
+        catch {
+            return []; // no events yet
+        }
+        const out = [];
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (typeof ev.id !== 'number')
+                    continue;
+                if (since !== undefined && ev.id <= since)
+                    continue;
+                if (sessionId !== undefined && sessionId !== '' && ev.sessionId !== sessionId)
+                    continue;
+                out.push(ev);
+            }
+            catch {
+                // corrupted line: skip
+            }
+        }
+        return out;
+    }
+    nextId() {
+        if (this.seq < 0) {
+            this.seq = 0;
+            for (const ev of this.query()) {
+                if (ev.id > this.seq)
+                    this.seq = ev.id;
+            }
+        }
+        this.seq += 1;
+        return this.seq;
+    }
+}
+export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
+/**
+ * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
+ * service. Returns whether the route was registered (false when the service is
+ * unavailable — the host keeps running, only the HTTP API is missing).
+ */
+export function registerEventsRoute(server, log) {
+    if (typeof server !== 'object' || server === null)
+        return false;
+    const candidate = server;
+    if (typeof candidate.register !== 'function')
+        return false;
+    candidate.register({
+        kind: 'exact',
+        path: EVENTS_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET' && req.method !== 'HEAD') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            let sessionId;
+            let since;
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                sessionId = url.searchParams.get('sessionId') ?? undefined;
+                const raw = url.searchParams.get('since');
+                if (raw !== null && raw !== '')
+                    since = Number.parseInt(raw, 10) || 0;
+            }
+            catch {
+                // unparseable URL: answer with the unfiltered tail
+            }
+            const events = log.query({ sessionId, since });
+            res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
+            res.end(JSON.stringify({ events }));
+        },
+    });
+    return true;
+}

package/lib/grant.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Session-scoped grants for dsh-perm-gate: a bounded, precise grant that lets a
+ * specific tool+call through once (or N times) within a TTL. Grants are keyed
+ * by a canonical fingerprint of the call so re-running with a DIFFERENT target
+ * never reuses authority.
+ */
+export type GrantDecision = 'allow' | 'no-match';
+export interface GrantSpec {
+    readonly tool: string;
+    /** Canonical fingerprint of the call (see {@link canonicalizeCall}). */
+    readonly fingerprint: string;
+    readonly decidedBy: 'human' | 'approval' | 'grant-chain';
+    readonly sessionId: string;
+    readonly parentAuthorized: boolean;
+    readonly ttlMs: number;
+    readonly maxUses: number;
+    readonly expiresAt: number;
+}
+export declare class GrantExpiredError extends Error {
+    constructor();
+}
+/**
+ * Canonicalize a tool call into a stable-but-precise fingerprint.
+ * Object keys are sorted and pure-value secrets are redacted by length, while
+ * meaningful fields that change authority (host, path, command word) are kept.
+ * Two calls that are cosmetic-equivalent (`{a:1,b:2}` vs `{b:2,a:1}`, or
+ * whitespace differences in a command) share a fingerprint; a call that targets
+ * a different path or host does NOT.
+ */
+export declare function canonicalizeCall(tool: string, args: Record<string, unknown>): string;
+/** A live grant with remaining uses; encapsulates expiry consumption. */
+export declare class SessionGrant {
+    readonly spec: GrantSpec;
+    private readonly now;
+    private uses;
+    constructor(spec: GrantSpec, now?: () => number);
+    get expiresAt(): number;
+    get remaining(): number;
+    ready(): boolean;
+    /** Consume one use if within TTL/maxUses; throws on expiry. otherwise returns false. */
+    tryConsume(now?: number): boolean;
+}
+/** Session-scoped grant registry. */
+export declare class GrantRegistry {
+    private readonly sessionId;
+    private readonly now;
+    private readonly grants;
+    constructor(sessionId: string, now?: () => number);
+    get size(): number;
+    /** Mint a precise grant. Self-minting restrictions are enforced by the decision engine, not here. */
+    mint(spec: Omit<GrantSpec, 'sessionId' | 'expiresAt'>): SessionGrant;
+    /**
+     * Resolve an allow for a call. Requires the grant's session to be a descendant
+     * of (or equal to) the caller. Returns 'allow' after consuming a use.
+     */
+    decide(tool: string, args: Record<string, unknown>): GrantDecision;
+    private prune;
+}
+/** Constructor helper: grant spec expiry is derived from ttlMs. */
+export declare function withExpiry(spec: Omit<GrantSpec, 'expiresAt'>, now?: () => number): GrantSpec;

package/lib/grant.js

@@ -0,0 +1,121 @@
+export class GrantExpiredError extends Error {
+    constructor() {
+        super('grant expired');
+        this.name = 'GrantExpiredError';
+    }
+}
+/**
+ * Canonicalize a tool call into a stable-but-precise fingerprint.
+ * Object keys are sorted and pure-value secrets are redacted by length, while
+ * meaningful fields that change authority (host, path, command word) are kept.
+ * Two calls that are cosmetic-equivalent (`{a:1,b:2}` vs `{b:2,a:1}`, or
+ * whitespace differences in a command) share a fingerprint; a call that targets
+ * a different path or host does NOT.
+ */
+export function canonicalizeCall(tool, args) {
+    const sortable = sortKeys(args);
+    return `${tool}:${stableStringify(sortable)}`;
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.slice(0, 50).map(sortKeys);
+    if (typeof v === 'object' && v !== null) {
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = sortKeys(v[k]);
+        return out;
+    }
+    return v;
+}
+function stableStringify(v) {
+    if (typeof v === 'string')
+        return JSON.stringify(v.replace(/\s+/g, ' '));
+    if (typeof v !== 'object' || v === null)
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    return `{${Object.keys(v).map((k) => JSON.stringify(k) + ':' + stableStringify(v[k])).join(',')}}`;
+}
+/** A live grant with remaining uses; encapsulates expiry consumption. */
+export class SessionGrant {
+    spec;
+    now;
+    uses = 0;
+    constructor(spec, now = Date.now) {
+        this.spec = spec;
+        this.now = now;
+    }
+    get expiresAt() {
+        return this.spec.expiresAt;
+    }
+    get remaining() {
+        return this.spec.maxUses - this.uses;
+    }
+    ready() {
+        return this.remaining > 0;
+    }
+    /** Consume one use if within TTL/maxUses; throws on expiry. otherwise returns false. */
+    tryConsume(now) {
+        const at = now ?? this.now();
+        if (at >= this.spec.expiresAt)
+            throw new GrantExpiredError();
+        if (this.uses >= this.spec.maxUses)
+            return false;
+        this.uses += 1;
+        return true;
+    }
+}
+/** Session-scoped grant registry. */
+export class GrantRegistry {
+    sessionId;
+    now;
+    grants = [];
+    constructor(sessionId, now = Date.now) {
+        this.sessionId = sessionId;
+        this.now = now;
+    }
+    get size() {
+        return this.grants.length;
+    }
+    /** Mint a precise grant. Self-minting restrictions are enforced by the decision engine, not here. */
+    mint(spec) {
+        const now = this.now();
+        const full = { ...spec, sessionId: this.sessionId, expiresAt: now + spec.ttlMs };
+        const grant = new SessionGrant(full, this.now);
+        this.prune();
+        this.grants.push(grant);
+        return grant;
+    }
+    /**
+     * Resolve an allow for a call. Requires the grant's session to be a descendant
+     * of (or equal to) the caller. Returns 'allow' after consuming a use.
+     */
+    decide(tool, args) {
+        const fp = canonicalizeCall(tool, args);
+        this.prune();
+        for (const g of this.grants) {
+            if (g.spec.fingerprint !== fp)
+                continue;
+            try {
+                if (g.tryConsume())
+                    return 'allow';
+            }
+            catch {
+                return 'no-match';
+            }
+        }
+        return 'no-match';
+    }
+    prune() {
+        const at = this.now();
+        for (let i = this.grants.length - 1; i >= 0; i -= 1) {
+            const g = this.grants[i];
+            if (at >= g.spec.expiresAt || g.remaining <= 0)
+                this.grants.splice(i, 1);
+        }
+    }
+}
+/** Constructor helper: grant spec expiry is derived from ttlMs. */
+export function withExpiry(spec, now = Date.now) {
+    return { ...spec, expiresAt: now() + spec.ttlMs };
+}

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * dsh-perm-gate — DSH cordis function plugin.
+ *
+ * Function-plugin contract: exports `name` / `inject` / `Config` / `apply`
+ * with NO default export (the DSH Loader unwraps `exports.default ?? exports`,
+ * and a stray default would discard the metadata).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+import { PermGateRuntime } from './runtime.js';
+export declare const name = "dsh-perm-gate";
+/** The `tools` service drives `tools/pre-execute`/`tools/result`; it is supplied by dsh-tools. */
+export declare const inject: string[];
+export { Config };
+/** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
+export declare const PERMISSIVE_NAMESPACE = "dsh-perm-gate";
+export declare function apply(ctx: Context, config?: Record<string, unknown>): PermGateRuntime;

package/lib/index.js

@@ -0,0 +1,140 @@
+import { join } from 'node:path';
+import { Config, resolvePermissiveStrategies } from './config.js';
+import { registerEventsRoute } from './events.js';
+import { PermGateRuntime } from './runtime.js';
+export const name = 'dsh-perm-gate';
+/** The `tools` service drives `tools/pre-execute`/`tools/result`; it is supplied by dsh-tools. */
+export const inject = ['tools'];
+export { Config };
+/** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
+export const PERMISSIVE_NAMESPACE = 'dsh-perm-gate';
+/**
+ * Inline equivalent of the official `installSettingsSection` helper: register
+ * the namespace through the `settings` service, layer the composition entry as
+ * `base`, and keep the runtime source live so the UI card applies immediately.
+ * `onScope` receives the live scope after registration (for seeding/syncing
+ * host-owned fields like the allowlist).
+ */
+function installSettingsSection(ctx, ns, schema, entry, hooks) {
+    ;
+    ctx.inject(['settings'], (sctx) => {
+        const scope = sctx.settings.register(ns, schema, { base: entry });
+        hooks.setSource(() => scope.get());
+        hooks.onChange();
+        hooks.onScope?.(scope);
+        sctx.effect(() => () => {
+            hooks.setSource(() => entry);
+            hooks.onChange();
+        });
+        scope.watch(() => hooks.onChange());
+    });
+}
+/** Column a settings-scope value into the typed live face. */
+function asSurface(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function apply(ctx, config = {}) {
+    // Runtime-adjustable config: the composition entry is the base; the settings
+    // namespace layers on top and `current()` always reads the active section.
+    let current = () => config;
+    // Plugin-owned data files live under $DSH_HOME (node_modules may be read-only);
+    // a missing dshHome degrades both stores to in-memory.
+    const dataDir = typeof config.dshHome === 'string' && config.dshHome !== '' ? join(config.dshHome, 'perm-gate') : undefined;
+    const runtime = new PermGateRuntime({
+        ...config,
+        // Read the Permissive tier live so the UI card's switches take effect on
+        // the next tool call (no reload). Falls back to the composition entry.
+        readPermissive: () => {
+            const c = current();
+            return {
+                enabled: c.permissive ?? false,
+                strategies: resolvePermissiveStrategies(c.permissiveStrategies),
+            };
+        },
+        // Read the llmAssist receiver (endpoint/model/secret/timeout) live from the
+        // same namespace, so editing the settings card applies to the next tool call.
+        readClassifyConfig: () => {
+            const c = current();
+            return {
+                endpoint: c.classifierEndpoint,
+                model: c.classifierModel,
+                apiKey: c.classifierApiKey,
+                timeoutMs: c.riskTimeoutMs ?? 20_000,
+            };
+        },
+        // Read the verdict-learning switch and threshold live.
+        readRiskLearning: () => {
+            const c = current();
+            return {
+                enabled: c.riskLearning ?? false,
+                threshold: c.riskThreshold ?? 3,
+            };
+        },
+        learningFile: typeof config.learningFile === 'string' && config.learningFile !== ''
+            ? config.learningFile
+            : (dataDir !== undefined ? join(dataDir, 'learning.json') : undefined),
+        eventsFile: typeof config.eventsFile === 'string' && config.eventsFile !== ''
+            ? config.eventsFile
+            : (dataDir !== undefined ? join(dataDir, 'events.jsonl') : undefined),
+    });
+    installSettingsSection(ctx, PERMISSIVE_NAMESPACE, Config, config, {
+        setSource: (source) => {
+            current = source;
+        },
+        onChange: () => { },
+        onScope: (scope) => {
+            // Seed the editable whitelist from the rules file only when the namespace
+            // carries no override yet, so the card shows the current allow patterns.
+            const surface = asSurface(scope.get());
+            if (surface !== undefined && !Array.isArray(surface.allowlist)) {
+                const patterns = runtime.allowlist();
+                if (patterns.length > 0)
+                    void scope.set('allowlist', patterns.slice());
+            }
+            // Card edits -> namespace -> rulesFile (mirror + reload).
+            scope.watch(() => {
+                const next = asSurface(scope.get());
+                if (next !== undefined && Array.isArray(next.allowlist)) {
+                    runtime.setAllowlist(next.allowlist.filter((x) => typeof x === 'string'));
+                }
+            });
+        },
+    });
+    // Event feed HTTP API (best effort): the dsh webServer service exposes the
+    // JSONL decision events to the browser half; without it events stay on disk.
+    try {
+        const webServer = ctx.get('webServer');
+        if (webServer !== undefined && runtime.eventLog !== undefined) {
+            registerEventsRoute(webServer, runtime.eventLog);
+        }
+    }
+    catch {
+        // webServer unavailable: the feed remains disk-only
+    }
+    const listener = async (exec, next) => {
+        const decision = runtime.decideExecution(exec);
+        if (decision === undefined)
+            return next();
+        // llmAssist: refine an `ask` with the risk grader before the human seam.
+        // undefined = auto-allowed (risk-safe / learned) → proceed.
+        if (decision.kind === 'ask') {
+            const refined = await runtime.refineAsk(exec, decision);
+            if (refined === undefined)
+                return next();
+            return refined;
+        }
+        return decision;
+    };
+    // `tools/pre-execute` / `tools/result` are dsh-tools events, not part of
+    // cordis core's typed `Events`, so they are registered through the string overload.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const host = ctx;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    host.on('tools/pre-execute', listener);
+    // Settle verdict-learning candidates: a result for a registered ask means the
+    // human approved it and it executed — one confirmation recorded.
+    host.on('tools/result', ((exec) => { runtime.settleExecution(exec); }));
+    return runtime;
+}

package/lib/learning.d.ts

@@ -0,0 +1,58 @@
+/** One confirmed operation sample: fingerprint plus a short human-readable context. */
+export interface LearningSample {
+    readonly fp: string;
+    readonly ctx: string;
+    readonly at: number;
+}
+/** The persisted document shape (version 1). */
+export interface LearningDoc {
+    version: 1;
+    /** key (`tool|category`) → human confirmation count. */
+    confirmed: Record<string, number>;
+    /** key → the most recent confirmed samples (bounded). */
+    samples: Record<string, LearningSample[]>;
+}
+export interface RiskLearningOptions {
+    /** Confirmations required before an exact-sample re-run may auto-allow. A getter reads the live setting. Default 3. */
+    readonly threshold?: number | (() => number);
+    /** Samples retained per key (oldest evicted). Default 10. */
+    readonly maxSamples?: number;
+    readonly now?: () => number;
+}
+/**
+ * Derive a stable, precise operation fingerprint from structured arguments:
+ * shell calls → `word|target-basename`; file-arg tools → the target basename;
+ * everything else → the tool name alone. Two calls share a fingerprint only
+ * when they perform the same kind of write against the same-named target.
+ */
+export declare function operationFingerprint(tool: string, args: Record<string, unknown>, commandText?: string): string;
+/** The learning key for one call: `tool|category` (only neutral learns today). */
+export declare function learnKey(tool: string, category: string): string;
+export declare class RiskLearning {
+    /** Persistence path; `undefined` keeps state in memory only. */
+    private readonly filePath;
+    private readonly options;
+    private doc;
+    private loaded;
+    constructor(
+    /** Persistence path; `undefined` keeps state in memory only. */
+    filePath: string | undefined, options?: RiskLearningOptions);
+    private get threshold();
+    private load;
+    private persist;
+    /** Human confirmations recorded so far for one key. */
+    count(key: string): number;
+    /** Whether one key already holds a confirmed sample with this fingerprint. */
+    hasSample(key: string, fp: string): boolean;
+    /**
+     * The learning gate: auto-allow only when the key reached the threshold AND
+     * this exact fingerprint was among the human-confirmed samples.
+     */
+    shouldAutoAllow(key: string, fp: string): boolean;
+    /** Record one human confirmation: bump the count and store the sample (bounded). */
+    confirm(key: string, fp: string, ctx: string): void;
+    /** Drop all learning state (counts and samples) and persist the empty doc. */
+    reset(): void;
+    /** Read-only deep view (for tests and diagnostics). */
+    snapshot(): LearningDoc;
+}