qlogicagent 0.5.0 → 0.5.3

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/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: `.openclaw/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 .openclaw/ 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;
+}

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

@@ -0,0 +1,2 @@
+export { PluginLoader, type PluginLoaderConfig } from "./plugin-loader.js";
+export { PLUGIN_HOOK_MAP, type PluginApi, type PluginHookPhase, type PluginModule, type LoadedPlugin, } from "./plugin-api.js";

package/dist/types/skills/plugins/plugin-api.d.ts

@@ -0,0 +1,38 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { HookPoint, HookHandler } from "../../contracts/hooks.js";
+import type { WorkspaceSkill } from "../skill-types.js";
+export type PluginHookPhase = "preToolUse" | "postToolUse" | "onTurnStart" | "onTurnEnd" | "onSessionEnd";
+/** Map plugin hook phases to internal HookPoint names */
+export declare const PLUGIN_HOOK_MAP: Record<PluginHookPhase, HookPoint>;
+export interface PluginApi {
+    /** Register a tool that will be available to the LLM. */
+    registerTool(tool: PortableTool): void;
+    /** Register a hook at a specific lifecycle phase. */
+    registerHook(phase: PluginHookPhase, handler: HookHandler<any>): void;
+    /** Register a skill (Markdown instructions + metadata). */
+    registerSkill(skill: WorkspaceSkill): void;
+    /** Get plugin-scoped configuration (from openclaw/plugins/name/config.json). */
+    getConfig(): Record<string, unknown>;
+    /**
+     * Set an activation check function. When it returns false, the plugin's
+     * tools and hooks are temporarily deactivated. Results are cached for
+     * `ttlMs` (default: 60 000) to avoid expensive re-checks.
+     */
+    setActivationCheck(checkFn: () => boolean | Promise<boolean>, ttlMs?: number): void;
+    /** Plugin's own name (directory name). */
+    readonly pluginName: string;
+}
+/**
+ * Every plugin must export a `register` function.
+ * Called once during plugin loading.
+ */
+export interface PluginModule {
+    register(api: PluginApi): void | Promise<void>;
+}
+export interface LoadedPlugin {
+    name: string;
+    directory: string;
+    toolCount: number;
+    hookCount: number;
+    skillCount: number;
+}

package/dist/types/skills/plugins/plugin-loader.d.ts

@@ -0,0 +1,45 @@
+import type { ToolRegistry } from "../tool-registry.js";
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { WorkspaceSkill } from "../skill-types.js";
+import { type LoadedPlugin } from "./plugin-api.js";
+export interface PluginLoaderConfig {
+    /** Directories to scan for plugins (order = priority) */
+    pluginDirs: string[];
+    /** ToolRegistry to inject plugin tools into */
+    toolRegistry: ToolRegistry;
+    /** HookRegistry to wire plugin hooks into */
+    hookRegistry: HookRegistry;
+    /** Logger */
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export declare class PluginLoader {
+    private config;
+    private loaded;
+    private pluginSkills;
+    private activations;
+    private log;
+    constructor(config: PluginLoaderConfig);
+    /**
+     * Discover and load all plugins from configured directories.
+     * Returns the list of successfully loaded plugins.
+     */
+    loadAll(): Promise<LoadedPlugin[]>;
+    /**
+     * Get all skills registered by plugins.
+     */
+    getPluginSkills(): WorkspaceSkill[];
+    /**
+     * Get list of all loaded plugins.
+     */
+    getLoaded(): LoadedPlugin[];
+    /**
+     * Re-check activation for plugins whose TTL has expired.
+     * Call this before tool resolution or periodically in the agent loop.
+     * Only re-runs check functions when the cache has expired.
+     */
+    refreshActivations(): Promise<void>;
+    private loadPlugin;
+}

package/dist/types/skills/plugins/plugin-marketplace.d.ts

@@ -0,0 +1,61 @@
+export interface MarketplaceSource {
+    /** Source type */
+    type: "npm" | "git" | "url";
+    /** Package name (npm), git URL, or zip URL */
+    specifier: string;
+    /** Optional version constraint (npm only) */
+    version?: string;
+}
+export interface MarketplaceConfig {
+    /** Enabled plugins from marketplace */
+    enabledPlugins: MarketplaceSource[];
+    /**
+     * Enterprise policy: only allow plugins matching these names.
+     * If set, any plugin not in the allowlist is blocked.
+     */
+    allowlist?: string[];
+    /**
+     * Enterprise policy: block these plugin names.
+     */
+    blocklist?: string[];
+}
+export interface MarketplaceCatalogEntry {
+    /** Plugin name */
+    name: string;
+    /** Installed version */
+    version: string;
+    /** Source that provided this plugin */
+    source: MarketplaceSource;
+    /** Local install path */
+    installPath: string;
+    /** Install timestamp */
+    installedAt: string;
+}
+export interface InstalledPluginsManifest {
+    version: 1;
+    plugins: MarketplaceCatalogEntry[];
+}
+export interface MarketplaceLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+/**
+ * Load plugins from cache only (no network). Fast startup path.
+ * CC parity: loadAllPluginsCacheOnly()
+ */
+export declare function loadCachedPlugins(): string[];
+/**
+ * Install/update marketplace plugins and return their local paths.
+ * CC parity: loadAllPluginsWithDynamic()
+ */
+export declare function installMarketplacePlugins(config: MarketplaceConfig, log: MarketplaceLogger): Promise<string[]>;
+/**
+ * Get the marketplace config from user settings.
+ * Reads ~/.openclaw/marketplace.json
+ */
+export declare function loadMarketplaceConfig(): MarketplaceConfig | null;
+/**
+ * Combine local plugin dirs + marketplace plugin dirs for PluginLoader.
+ * CC parity: loadAllPlugins() merges session + marketplace + builtin.
+ */
+export declare function resolveAllPluginDirs(localDirs: string[], log: MarketplaceLogger): Promise<string[]>;

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

@@ -0,0 +1,71 @@
+/**
+ * Content block returned by tool execution.
+ * Compatible with OpenAI / Anthropic content array format.
+ */
+export interface ToolContentBlock {
+    type: "text" | "image";
+    text?: string;
+    /** base64-encoded image data (only when type === "image") */
+    data?: string;
+    mimeType?: string;
+}
+/**
+ * Result of executing a portable tool.
+ */
+export interface PortableToolResult {
+    content: ToolContentBlock[];
+    /** Arbitrary structured metadata for the calling runtime. */
+    details?: Record<string, unknown>;
+}
+/**
+ * A runtime-agnostic tool definition.
+ *
+ * @typeParam TParams The expected parameter shape (for TypeScript consumers).
+ */
+export interface PortableTool<TParams = Record<string, unknown>> {
+    /** Unique tool name (e.g. "think", "todo", "memory_query"). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** Tool description shown to the LLM. */
+    description: string;
+    /** JSON Schema object describing the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /**
+     * When true, the tool should NOT appear in the default tool list.
+     * The host injects it only for complex tasks (e.g. multi-step reasoning)
+     * or when explicitly activated via tool_search.
+     * This saves context tokens in simple conversations.
+     */
+    shouldDefer?: boolean;
+    /**
+     * Whether the tool can safely run concurrently with other tools.
+     * When true, the runtime may execute this tool in parallel with others.
+     * Default: false (sequential execution assumed).
+     */
+    isConcurrencySafe?: boolean;
+    /**
+     * Whether the tool only reads state and never mutates anything.
+     * Read-only tools can skip confirmation prompts in strict permission modes.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Brief keyword hint for tool_search to match against
+     * (e.g. "return the final response as structured JSON").
+     */
+    searchHint?: string;
+    /**
+     * Maximum allowed content size in characters for the tool result.
+     * The runtime should truncate/reject results exceeding this.
+     */
+    maxResultSizeChars?: number;
+    /**
+     * Execute the tool.
+     *
+     * @param toolCallId - Unique ID for this tool invocation (for tracing).
+     * @param params     - Parsed parameters matching the JSON Schema.
+     * @param signal     - Optional abort signal.
+     * @returns Tool result with content blocks + optional details.
+     */
+    execute(toolCallId: string, params: TParams, signal?: AbortSignal): Promise<PortableToolResult>;
+}