qlogicagent 0.5.2 → 0.6.0

package/dist/types/skills/memory/memory-store.d.ts

@@ -0,0 +1,86 @@
+export declare const MEMORY_ENTRY_DELIMITER = "\n\u00A7\n";
+export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
+export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
+export type MemoryStoreTarget = "memory" | "user";
+export interface MemoryStoreResult {
+    ok: boolean;
+    message: string;
+    target: MemoryStoreTarget;
+    entries: readonly string[];
+    entryCount: number;
+    usage: string;
+    errorCode?: string;
+}
+export interface MemoryStoreOptions {
+    memoryCharLimit?: number;
+    userCharLimit?: number;
+    /** When true, mutations automatically persist to ~/.qlogicagent/memory.json */
+    persistToDisk?: boolean;
+}
+export interface MemoryStoreSerialized {
+    memory: string;
+    user: string;
+}
+export declare class MemoryStore {
+    private memoryEntries;
+    private userEntries;
+    private frozenSnapshot;
+    private snapshotFrozen;
+    private saveTimer;
+    private readonly memoryCharLimit;
+    private readonly userCharLimit;
+    private readonly persistToDisk;
+    constructor(options?: MemoryStoreOptions);
+    /**
+     * Load from serialized form (e.g. from PG or filesystem).
+     * Deduplicates entries on load.
+     */
+    loadFromSerialized(data: Partial<MemoryStoreSerialized>): void;
+    /**
+     * Serialize current live state for persistence.
+     */
+    serialize(): MemoryStoreSerialized;
+    /**
+     * Load from disk (~/.qlogicagent/memory.json). No-op if file doesn't exist.
+     * Call this at startup when persistToDisk is enabled.
+     */
+    loadFromDisk(): Promise<void>;
+    /**
+     * Synchronous variant for use in sync constructors / init paths.
+     */
+    loadFromDiskSync(): void;
+    /**
+     * Schedule a debounced save to disk (500ms). Multiple rapid mutations
+     * coalesce into a single disk write.
+     */
+    private scheduleSave;
+    /** Flush any pending save immediately. Call before shutdown. */
+    flush(): Promise<void>;
+    /**
+     * Freeze current entries for system prompt injection.
+     * Call once at session start. After freezing, mutations update
+     * live state but NOT the system prompt block.
+     */
+    freezeSnapshot(): void;
+    /**
+     * Get frozen system prompt block for the given target.
+     * Returns empty string if no entries or not yet frozen.
+     */
+    getSystemPromptBlock(target: MemoryStoreTarget): string;
+    add(target: MemoryStoreTarget, content: string): MemoryStoreResult;
+    replace(target: MemoryStoreTarget, oldText: string, newContent: string): MemoryStoreResult;
+    remove(target: MemoryStoreTarget, oldText: string): MemoryStoreResult;
+    getEntries(target: MemoryStoreTarget): readonly string[];
+    getUsage(target: MemoryStoreTarget): {
+        used: number;
+        limit: number;
+        percent: number;
+    };
+    isEmpty(): boolean;
+    private entriesFor;
+    private charLimitFor;
+    private formatUsage;
+    private renderBlock;
+    private successResult;
+    private errorResult;
+}

package/dist/types/skills/memory/memory-tool.d.ts

@@ -0,0 +1,87 @@
+import type { MemoryProvider, MemorySearchResult } from "qlogicagent-runtime-contracts";
+import type { MemoryStore, MemoryStoreTarget } from "./memory-store.js";
+export interface MediaPreferencesSummary {
+    imageStyle?: string;
+    videoStyle?: string;
+    musicGenre?: string;
+    musicMood?: string;
+    primaryPurpose?: string;
+    colorPreference?: string;
+}
+export declare const MEMORY_TOOL_NAME: "memory";
+export declare const MEMORY_TOOL_MAX_CONTENT_LENGTH = 2000;
+export declare const MEMORY_TOOL_ACTIONS: readonly ["add", "replace", "remove", "search"];
+export type MemoryToolAction = (typeof MEMORY_TOOL_ACTIONS)[number];
+export declare const MEMORY_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: string[];
+            readonly description: string;
+        };
+        readonly target: {
+            readonly type: "string";
+            readonly enum: readonly ["memory", "user"];
+            readonly description: string;
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly old_text: {
+            readonly type: "string";
+            readonly description: "Required for 'replace' and 'remove'. A substring that uniquely identifies the note entry to modify.";
+        };
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Required for 'search'. Natural language query to find relevant memories.";
+        };
+        readonly category: {
+            readonly type: "string";
+            readonly enum: readonly ["profile", "facts", "media", "projects"];
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export declare const MEMORY_TOOL_DESCRIPTION: string;
+export declare const MEMORY_TOOL_LABEL = "Memory";
+export declare function isMemoryContentSafe(text: string): boolean;
+export interface MemoryToolParams {
+    action: MemoryToolAction;
+    target?: MemoryStoreTarget;
+    content?: string;
+    old_text?: string;
+    query?: string;
+    category?: "profile" | "facts" | "media" | "projects";
+}
+export interface MemoryToolResult {
+    ok: boolean;
+    message: string;
+    action: string;
+    /** For MD store operations: live entry count */
+    entryCount?: number;
+    /** For MD store operations: usage string */
+    usage?: string;
+    /** For search: qmemory results */
+    results?: MemorySearchResult[];
+    /** Indicates MD store was mutated (consumer should persist) */
+    storeModified?: boolean;
+    errorCode?: string;
+}
+export interface MemoryToolExecutorDeps {
+    /** QMemory provider for semantic search. */
+    provider: MemoryProvider;
+    /** Local MD memory store for notes. */
+    store?: MemoryStore;
+    userId: string;
+    sessionId?: string;
+    /** Query recalled facts/memories by natural language. */
+    queryGraph?: (query: string, userId: string) => string[];
+    /** Retrieve user profile summary. */
+    getProfileSummary?: (userId: string) => string | null;
+    /** Retrieve media preferences. */
+    getMediaPreferences?: (userId: string) => MediaPreferencesSummary | null;
+}
+export declare function executeMemoryTool(params: MemoryToolParams, deps: MemoryToolExecutorDeps): Promise<MemoryToolResult>;

package/dist/types/skills/memory/qmemory-adapter.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryIngestOptions, MemoryProvider } from "qlogicagent-runtime-contracts";
+/** A pre-extracted memory item ready to be stored (no LLM needed). */
+export interface ExtractedMemoryItem {
+    text: string;
+    category?: string;
+    importance?: number;
+    speaker?: string;
+    event_date?: string;
+    tags?: string[];
+}
+/** Configuration for the QMemory HTTP adapter. */
+export interface QMemoryAdapterConfig {
+    /** Base URL of the qmemory server (e.g. "http://localhost:18800"). */
+    baseUrl: string;
+    /** Optional API key for authentication. */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 5000). */
+    timeoutMs?: number;
+    /** Prefix prepended to userId for multi-tenant isolation. */
+    userIdPrefix?: string;
+}
+/** Health status returned by qmemory `/v1/health/`. */
+export interface QMemoryHealthStatus {
+    status: string;
+    version: string;
+    memoryCount: number;
+    dbSizeBytes: number;
+    embeddingModel: string;
+    uptimeSeconds: number;
+}
+/**
+ * Create a MemoryProvider backed by a QMemory HTTP server.
+ *
+ * Uses `qlogicagent-adapter-claw` for HTTP transport.
+ */
+export declare function createQMemoryAdapter(config: QMemoryAdapterConfig): MemoryProvider & {
+    health(): Promise<QMemoryHealthStatus>;
+    ingestExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<{
+        memoriesAdded: number;
+    }>;
+    feedback(memoryIds: string[], signal: string, sessionId?: string): Promise<void>;
+};

package/dist/types/skills/permissions/bash-classifier.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bash Classifier — CC yoloClassifier bash branch parity.
+ *
+ * Specialized classifier for shell/bash commands.
+ * CC decomposes each bash tool call into structured analysis:
+ *   1. Parse the command string
+ *   2. Check against known safe/dangerous command patterns
+ *   3. Check working directory context
+ *   4. If ambiguous, defer to the LLM classifier
+ *
+ * This is a pre-filter that runs BEFORE the general classifier,
+ * so commonly-used safe shell commands bypass the LLM entirely.
+ *
+ * Reference: claude-code src/utils/permissions/yoloClassifier.ts (bash branch)
+ */
+export interface BashClassifyResult {
+    decision: "allow" | "deny" | "defer";
+    reason: string;
+    /** Informational warning for destructive commands (CC parity). */
+    destructiveWarning?: string;
+}
+/**
+ * Classify a bash/shell command for safety.
+ *
+ * @param command - The shell command string
+ * @param cwd - Current working directory (for project context check)
+ * @param projectRoot - Project root directory
+ * @returns Classification result: allow / deny / defer (to LLM classifier)
+ */
+export declare function classifyBashCommand(command: string, cwd?: string, projectRoot?: string): BashClassifyResult;

package/dist/types/skills/permissions/classifier-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Classifier Cache — CC preToolUse approval cache parity.
+ *
+ * Caches already-judged tool use classification results to avoid
+ * redundant LLM classifier calls for identical tool invocations.
+ *
+ * CC pattern: The auto-mode classifier is expensive (2 LLM calls per tool).
+ * Caching results for identical (toolName + normalized args) combinations
+ * eliminates redundant classification within a session.
+ *
+ * Cache Key: `${toolName}::${normalizedArgs}`
+ *   - Args are sorted-key JSON for deterministic comparison
+ *   - Bash commands are normalized (whitespace collapse, env var strip)
+ *
+ * Cache is session-scoped (cleared on session end or mode change).
+ *
+ * Reference: claude-code src/utils/permissions/permissionCache.ts
+ */
+export interface CachedClassification {
+    shouldBlock: boolean;
+    reason: string;
+    /** Timestamp when this classification was made */
+    classifiedAt: number;
+    /** How many times this cache entry was reused */
+    hitCount: number;
+}
+export declare class ClassifierCache {
+    private cache;
+    /**
+     * Look up a cached classification result.
+     * Returns undefined if not cached or expired.
+     */
+    get(toolName: string, args: Record<string, unknown>): CachedClassification | undefined;
+    /**
+     * Store a classification result.
+     */
+    set(toolName: string, args: Record<string, unknown>, result: {
+        shouldBlock: boolean;
+        reason: string;
+    }): void;
+    /**
+     * Check if a tool+args combination is cached.
+     */
+    has(toolName: string, args: Record<string, unknown>): boolean;
+    /** Clear all cached classifications (called on mode change or session end) */
+    clear(): void;
+    /** Number of cached entries */
+    get size(): number;
+    /** Total cache hits across all entries */
+    get totalHits(): number;
+}

package/dist/types/skills/permissions/denial-tracking.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Denial Tracking — CC denialTracking.ts parity.
+ *
+ * Tracks consecutive and total classifier denials to determine
+ * when to fall back to interactive prompting.
+ *
+ * CC reference: src/utils/permissions/denialTracking.ts
+ *
+ * Integration:
+ *   - recordDenial() after each classifier block
+ *   - recordSuccess() after each classifier allow
+ *   - shouldFallbackToPrompting() before skipping approval dialog
+ */
+export interface DenialTrackingState {
+    consecutiveDenials: number;
+    totalDenials: number;
+}
+export declare const DENIAL_LIMITS: {
+    /** Max consecutive denials before falling back to prompting. */
+    readonly maxConsecutive: 3;
+    /** Max total denials in a session before forcing prompt mode. */
+    readonly maxTotal: 20;
+};
+export declare function createDenialTrackingState(): DenialTrackingState;
+/**
+ * Record a classifier denial. Increments both counters.
+ * Returns a new state object (immutable pattern).
+ */
+export declare function recordDenial(state: DenialTrackingState): DenialTrackingState;
+/**
+ * Record a classifier success. Resets consecutive counter only.
+ * Returns same reference if no change needed (optimization).
+ */
+export declare function recordSuccess(state: DenialTrackingState): DenialTrackingState;
+/**
+ * Check if the classifier should fall back to interactive prompting.
+ *
+ * CC pattern: After N consecutive denials or M total denials,
+ * the auto-classifier is likely miscalibrated — show the user
+ * the approval dialog instead.
+ */
+export declare function shouldFallbackToPrompting(state: DenialTrackingState): boolean;

package/dist/types/skills/permissions/hook-runner.d.ts

@@ -0,0 +1,85 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { ToolDefinition } from "../../agent/types.js";
+import { PermissionRuleEngine } from "./rule-engine.js";
+import type { PermissionUpdate, ApprovalRequest, ApprovalResponse } from "./types.js";
+import { type ClassifierLLMCall } from "./permission-classifier.js";
+import type { PermissionRole } from "../../orchestration/subagent/task-types.js";
+export interface PermissionCheckerDeps {
+    ruleEngine: PermissionRuleEngine;
+    hookRegistry: HookRegistry;
+    /**
+     * Callback to send an approval request to the host (Gateway/Electron).
+     * Must return a promise that resolves when the user responds.
+     * If the host does not support approval, this should reject or return denied.
+     */
+    onRequestApproval: (request: ApprovalRequest) => Promise<ApprovalResponse>;
+    /** Called when a persistent permission update is returned from the approval dialog */
+    onPermissionUpdate?: (update: PermissionUpdate) => void;
+    /** Called when a tool is denied (for logging/observability) */
+    onDenied?: (toolName: string, message: string) => void;
+    /**
+     * LLM call function for the auto-mode classifier (cc yoloClassifier pattern).
+     * If not provided, auto mode falls back to the approval dialog.
+     */
+    classifierLLMCall?: ClassifierLLMCall;
+    /**
+     * Recent conversation messages for classifier context.
+     * Called lazily when the classifier needs to run.
+     */
+    getRecentMessages?: () => import("../../agent/types.js").ChatMessage[];
+    /**
+     * Permission role context (CC: interactive/coordinator/worker).
+     * Determines how the checker behaves:
+     * - interactive: full approval dialog flow (default)
+     * - coordinator: auto-approve non-destructive ops, no user prompts
+     * - worker: classifier-only path, no approval dialog fallback
+     */
+    permissionRole?: PermissionRole;
+}
+export declare class PermissionChecker {
+    private readonly ruleEngine;
+    private readonly hookRegistry;
+    private readonly onRequestApproval;
+    private readonly onPermissionUpdate;
+    private readonly onDenied;
+    private readonly classifierLLMCall;
+    private readonly getRecentMessages;
+    private readonly permissionRole;
+    private readonly pendingApprovals;
+    private unregisterHook;
+    /** Tool meta cache — populated from ToolDefinition[] at agent creation */
+    private toolMetaCache;
+    /** Classifier result cache — avoids redundant LLM calls (CC permissionCache parity) */
+    private classifierCache;
+    /** Denial tracking state — CC denialTracking.ts parity */
+    private denialTracking;
+    constructor(deps: PermissionCheckerDeps);
+    /**
+     * Register the permission check hook on the HookRegistry.
+     * Returns an unregister function.
+     */
+    register(): () => void;
+    /**
+     * Resolve an incoming approval response (called by host RPC handler).
+     */
+    resolveApproval(response: ApprovalResponse): void;
+    /**
+     * Update tool metadata cache (call when tool list changes).
+     */
+    setToolMeta(tools: ToolDefinition[]): void;
+    get ruleEngineRef(): PermissionRuleEngine;
+    /** Fire permission.denied hook + onDenied callback */
+    private fireDenied;
+    private handleResult;
+    /**
+     * Worker/coordinator "ask" handler: classifier-only, no approval dialog.
+     * CC pattern: headless workers never prompt users.
+     */
+    private handleWorkerAsk;
+    private requestApproval;
+    /**
+     * Clear the classifier cache (CC parity: called on mode change / session end).
+     */
+    clearClassifierCache(): void;
+    private cancelAllPending;
+}

package/dist/types/skills/permissions/index.d.ts

@@ -0,0 +1,12 @@
+export { PermissionRuleEngine, parsePermissionConfig } from "./rule-engine.js";
+export { PermissionChecker } from "./hook-runner.js";
+export type { PermissionCheckerDeps } from "./hook-runner.js";
+export { classifyToolAction, isAutoModeAllowlistedTool, } from "./permission-classifier.js";
+export type { ClassifierLLMCall, ClassifierResult, } from "./permission-classifier.js";
+export { classifyBashCommand } from "./bash-classifier.js";
+export type { BashClassifyResult } from "./bash-classifier.js";
+export { ClassifierCache } from "./classifier-cache.js";
+export type { CachedClassification } from "./classifier-cache.js";
+export { watchSettings, loadInitialSettings } from "./settings-watcher.js";
+export type { SettingsFile, SettingsWatcherDeps } from "./settings-watcher.js";
+export type { PermissionMode, PermissionBehavior, PermissionResult, PermissionRuleEntry, PermissionConfig, PermissionUpdate, PermissionDecisionReason, ToolPermissionCheckInput, ApprovalRequest, ApprovalResponse, } from "./types.js";

package/dist/types/skills/permissions/permission-classifier.d.ts

@@ -0,0 +1,41 @@
+import type { ChatMessage } from "../../agent/types.js";
+export interface ClassifierResult {
+    shouldBlock: boolean;
+    reason: string;
+    stage: "allowlist" | "fast" | "thinking";
+    durationMs: number;
+}
+/**
+ * LLM call interface — injected by the host so the classifier
+ * doesn't depend on a specific LLM client.
+ */
+export interface ClassifierLLMCall {
+    (params: {
+        system: string;
+        messages: Array<{
+            role: "user" | "assistant";
+            content: string;
+        }>;
+        maxTokens: number;
+        temperature: number;
+        stop?: string[];
+        /** If true, host should cache the system prompt (cc cache_control). */
+        cacheSystemPrompt?: boolean;
+    }): Promise<{
+        text: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+    }>;
+}
+export declare function isAutoModeAllowlistedTool(toolName: string): boolean;
+/**
+ * Two-stage XML classifier for auto-mode permission decisions.
+ *
+ * Stage 1 (fast): Quick classification with minimal tokens.
+ * Stage 2 (thinking): Only if stage 1 blocks, do a more careful review.
+ *
+ * cc reference: classifyYoloAction() in yoloClassifier.ts
+ */
+export declare function classifyToolAction(toolName: string, toolArgs: Record<string, unknown>, recentMessages: ChatMessage[], llmCall: ClassifierLLMCall): Promise<ClassifierResult>;

package/dist/types/skills/permissions/rule-engine.d.ts

@@ -0,0 +1,41 @@
+import type { PermissionMode, PermissionBehavior, PermissionResult, PermissionRuleEntry, PermissionConfig, PermissionUpdate, ToolPermissionCheckInput } from "./types.js";
+export declare class PermissionRuleEngine {
+    private mode;
+    private rules;
+    private defaultBehavior;
+    private compiledPatterns;
+    constructor(config: PermissionConfig);
+    getMode(): PermissionMode;
+    setMode(mode: PermissionMode): void;
+    getRules(): readonly PermissionRuleEntry[];
+    getDefaultBehavior(): PermissionBehavior;
+    /** Replace all rules at once (for settings hot-reload). */
+    replaceRules(rules: PermissionRuleEntry[]): void;
+    /** Update the default behavior (for settings hot-reload). */
+    setDefaultBehavior(behavior: PermissionBehavior): void;
+    addRule(rule: PermissionRuleEntry): void;
+    /**
+     * Apply a persistent permission update (e.g. from approval dialog "always allow").
+     */
+    applyUpdate(update: PermissionUpdate): void;
+    /**
+     * 4-layer permission check (cc hasPermissionsToUseTool parity).
+     *
+     * Layer 0: Mode override
+     * Layer 1: Explicit rules (first match wins)
+     * Layer 2: Tool metadata (isReadOnly/isDangerous/requiresApproval)
+     * Layer 3: Default behavior
+     */
+    check(input: ToolPermissionCheckInput): PermissionResult;
+    private compileRules;
+}
+/**
+ * Parse permission config from Gateway-injected or local settings.
+ *
+ * Accepts cc-compatible format:
+ *   { mode?: "default", allow: [...], deny: [...], ask: [...], default?: "allow" }
+ *
+ * And extended rule format:
+ *   { rules: [{ pattern, behavior, reason, source }] }
+ */
+export declare function parsePermissionConfig(raw: unknown): PermissionConfig;

package/dist/types/skills/permissions/settings-watcher.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Settings Watcher — CC settings.json hot-reload parity.
+ *
+ * Watches the project-local settings file and reloads permission rules
+ * when it changes on disk. This allows users to adjust permission rules
+ * without restarting the agent session.
+ *
+ * Settings file location: `.qlogicagent/settings.json` in the project root
+ *
+ * Watched fields:
+ *   - permissionMode: PermissionMode
+ *   - permissionRules: PermissionRuleEntry[]
+ *   - defaultBehavior: PermissionBehavior
+ *
+ * CC reference: src/utils/settings/settings.ts (watchSettings, applySettings)
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { PermissionRuleEntry, PermissionMode, PermissionBehavior } from "./types.js";
+import { PermissionRuleEngine } from "./rule-engine.js";
+/** On-disk settings file schema */
+export interface SettingsFile {
+    permissionMode?: PermissionMode;
+    permissionRules?: PermissionRuleEntry[];
+    defaultBehavior?: PermissionBehavior;
+}
+export interface SettingsWatcherDeps {
+    /** Project root directory (where .qlogicagent/ lives) */
+    projectRoot: string;
+    /** Permission rule engine to update on changes */
+    ruleEngine: PermissionRuleEngine;
+    /** Hook registry for config.changed events */
+    hooks?: HookRegistry;
+    /** Logger */
+    log?: (msg: string) => void;
+}
+/**
+ * Watch the settings file for changes and hot-reload permission rules.
+ *
+ * Returns an unsubscribe function.
+ */
+export declare function watchSettings(deps: SettingsWatcherDeps): () => void;
+/**
+ * Load initial settings (non-watching).
+ * Call at session start to apply project settings before the watcher starts.
+ */
+export declare function loadInitialSettings(projectRoot: string, ruleEngine: PermissionRuleEngine): Promise<SettingsFile | null>;

package/dist/types/skills/permissions/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * User-configurable permission modes.
+ *
+ * cc reference:
+ *   'default'           → normal prompting
+ *   'bypassPermissions' → auto-accept all
+ *   'acceptEdits'       → auto-accept edits only
+ *   'dontAsk'           → auto-deny all
+ *   'plan'              → planning mode (pause execution)
+ *
+ * We keep the cc names for compatibility.
+ */
+export type PermissionMode = "default" | "bypassPermissions" | "acceptEdits" | "dontAsk" | "plan" | "auto";
+export declare const PERMISSION_MODES: readonly PermissionMode[];
+export type PermissionBehavior = "allow" | "deny" | "ask";
+export type PermissionDecisionReason = {
+    type: "rule";
+    rule: PermissionRuleEntry;
+} | {
+    type: "mode";
+    mode: PermissionMode;
+} | {
+    type: "hook";
+    hookName: string;
+    reason: string;
+} | {
+    type: "classifier";
+    classifier: string;
+    reason: string;
+} | {
+    type: "tool_check";
+    reason: string;
+} | {
+    type: "eligibility";
+    reasonCodes: string[];
+} | {
+    type: "sandbox";
+    reason: string;
+} | {
+    type: "other";
+    reason: string;
+};
+export interface PermissionAllowResult {
+    behavior: "allow";
+    updatedInput?: Record<string, unknown>;
+    decisionReason?: PermissionDecisionReason;
+}
+export interface PermissionAskResult {
+    behavior: "ask";
+    message: string;
+    toolName: string;
+    input?: Record<string, unknown>;
+    suggestions?: PermissionUpdate[];
+    decisionReason?: PermissionDecisionReason;
+}
+export interface PermissionDenyResult {
+    behavior: "deny";
+    message: string;
+    decisionReason: PermissionDecisionReason;
+}
+export type PermissionResult = PermissionAllowResult | PermissionAskResult | PermissionDenyResult;
+export interface PermissionUpdate {
+    /** Tool name or glob pattern */
+    pattern: string;
+    /** New rule to apply */
+    behavior: PermissionBehavior;
+    /** Human-readable description */
+    description?: string;
+}
+export interface PermissionRuleEntry {
+    /** Exact tool name or glob pattern */
+    pattern: string;
+    /** Action for matching tools */
+    behavior: PermissionBehavior;
+    /** Optional reason for logging/display */
+    reason?: string;
+    /** Source of this rule (config/user/plugin) */
+    source?: string;
+}
+export interface PermissionConfig {
+    /** Active permission mode */
+    mode: PermissionMode;
+    /** Rules evaluated in order; first match wins */
+    rules: PermissionRuleEntry[];
+    /** Default behavior when no rule matches */
+    defaultBehavior: PermissionBehavior;
+}
+export interface ToolPermissionCheckInput {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    /** Tool metadata from ToolDefinition.meta */
+    meta?: {
+        isReadOnly?: boolean;
+        isDangerous?: boolean;
+        requiresApproval?: boolean;
+        parallelSafe?: boolean;
+    };
+}
+export interface ApprovalRequest {
+    approvalId: string;
+    callId: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    message: string;
+    suggestions?: PermissionUpdate[];
+}
+export interface ApprovalResponse {
+    approvalId: string;
+    decision: "approved" | "denied";
+    updatedInput?: Record<string, unknown>;
+    /** Persistent rule to save */
+    permissionUpdate?: PermissionUpdate;
+}