@xenosystem/agent-sdk 0.10.32 → 0.10.33

package/dist/electron/index.d.cts

@@ -299,10 +299,42 @@ interface ToolPolicyProjection {
     approvalKey?: string;
     riskLevel?: "low" | "medium" | "high";
 }
+interface ToolAnnotationHints {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+interface ToolOrigin {
+    kind: "mcp";
+    server: string;
+    tool: string;
+}
+interface PermissionToolMetadata {
+    readOnly?: boolean;
+    annotations?: ToolAnnotationHints;
+    origin?: ToolOrigin;
+}
+interface PlanModeReadOnlyClaim {
+    toolName: string;
+    input: Record<string, unknown>;
+    source: "annotation" | "declaration";
+    origin?: ToolOrigin;
+    annotations?: ToolAnnotationHints;
+}
+interface PlanModeToolPolicy {
+    honourReadOnlyAnnotations?: boolean;
+    honourReadOnlyDeclarations?: boolean;
+    allowTools?: readonly string[];
+    validateReadOnlyClaim?: (claim: PlanModeReadOnlyClaim) => boolean | Promise<boolean>;
+}
 interface RegisteredTool {
     definition: ToolDefinition;
     execute: ToolExecutor;
     readOnly?: boolean;
+    annotations?: ToolAnnotationHints;
+    origin?: ToolOrigin;
     projectPolicyInput?: (input: Record<string, unknown>, context?: ToolPolicyProjectionContext) => ToolPolicyProjection | {
         error: ToolResult;
     };
@@ -677,18 +709,37 @@ interface PermissionCheckContext {
     ephemeralInputPreview?: string;
     onWaitStart?: () => void;
     onWaitEnd?: () => void;
+    tool?: PermissionToolMetadata;
+}
+interface DerivedPermissionEngineOptions {
+    mode?: "default" | "plan";
+    rules?: PermissionConfig["rules"];
 }
 declare class PermissionEngine {
-    private config;
+    protected config: PermissionConfig;
     private workingDirectory;
     private sessionAllowed;
     private sessionAllowedDirectories;
     private persistentAllowed;
     private persistentAllowedDirectories;
-    private promptFn?;
-    private decisionHook?;
+    protected promptFn?: PermissionPromptFn;
+    protected decisionHook?: PermissionDecisionHook;
+    protected planModeToolPolicy?: PlanModeToolPolicy;
     constructor(config?: Partial<PermissionConfig>, promptFn?: PermissionPromptFn, decisionHook?: PermissionDecisionHook);
     fork(promptFn?: PermissionPromptFn | undefined): PermissionEngine;
+    setPlanModeToolPolicy(policy: PlanModeToolPolicy | undefined): void;
+    get planModePolicy(): PlanModeToolPolicy | undefined;
+    deriveChild(options?: DerivedPermissionEngineOptions): PermissionEngine;
+    protected planModeVerdict(toolName: string, canonicalToolName: string, input: Record<string, unknown>, tool: PermissionToolMetadata | undefined): Promise<{
+        kind: "refuse";
+        reason: string;
+    } | {
+        kind: "admit";
+        reason: string;
+    } | {
+        kind: "defer";
+    }>;
+    private planModeReadOnlyAdmission;
     get mode(): PermissionConfig["mode"];
     setMode(mode: PermissionConfig["mode"]): void;
     setWorkingDirectory(cwd: string): void;
@@ -701,7 +752,10 @@ declare class PermissionEngine {
         reason: string;
     }>;
     private checkElevatedBash;
-    private finalizeDecision;
+    protected finalizeDecision(toolName: string, input: Record<string, unknown>, allowed: boolean, reason: string, traceId?: string, requesterLabel?: string): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
     classifyAutoPermission(toolName: string, input: Record<string, unknown>): AutoPermissionDecision;
     private contentDigest;
     private bashScopeSuffix;
@@ -715,7 +769,7 @@ declare class PermissionEngine {
     private promptUser;
     private getToolDetail;
     private getCommandPrefix;
-    private matchesRule;
+    protected matchesRule(ruleTool: string, pattern: string | undefined, toolName: string, input: Record<string, unknown>): boolean;
     private matchesBashPattern;
     private matchesWildcard;
     private isCredentialLikePath;

package/dist/electron/index.d.ts

@@ -299,10 +299,42 @@ interface ToolPolicyProjection {
     approvalKey?: string;
     riskLevel?: "low" | "medium" | "high";
 }
+interface ToolAnnotationHints {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+interface ToolOrigin {
+    kind: "mcp";
+    server: string;
+    tool: string;
+}
+interface PermissionToolMetadata {
+    readOnly?: boolean;
+    annotations?: ToolAnnotationHints;
+    origin?: ToolOrigin;
+}
+interface PlanModeReadOnlyClaim {
+    toolName: string;
+    input: Record<string, unknown>;
+    source: "annotation" | "declaration";
+    origin?: ToolOrigin;
+    annotations?: ToolAnnotationHints;
+}
+interface PlanModeToolPolicy {
+    honourReadOnlyAnnotations?: boolean;
+    honourReadOnlyDeclarations?: boolean;
+    allowTools?: readonly string[];
+    validateReadOnlyClaim?: (claim: PlanModeReadOnlyClaim) => boolean | Promise<boolean>;
+}
 interface RegisteredTool {
     definition: ToolDefinition;
     execute: ToolExecutor;
     readOnly?: boolean;
+    annotations?: ToolAnnotationHints;
+    origin?: ToolOrigin;
     projectPolicyInput?: (input: Record<string, unknown>, context?: ToolPolicyProjectionContext) => ToolPolicyProjection | {
         error: ToolResult;
     };
@@ -677,18 +709,37 @@ interface PermissionCheckContext {
     ephemeralInputPreview?: string;
     onWaitStart?: () => void;
     onWaitEnd?: () => void;
+    tool?: PermissionToolMetadata;
+}
+interface DerivedPermissionEngineOptions {
+    mode?: "default" | "plan";
+    rules?: PermissionConfig["rules"];
 }
 declare class PermissionEngine {
-    private config;
+    protected config: PermissionConfig;
     private workingDirectory;
     private sessionAllowed;
     private sessionAllowedDirectories;
     private persistentAllowed;
     private persistentAllowedDirectories;
-    private promptFn?;
-    private decisionHook?;
+    protected promptFn?: PermissionPromptFn;
+    protected decisionHook?: PermissionDecisionHook;
+    protected planModeToolPolicy?: PlanModeToolPolicy;
     constructor(config?: Partial<PermissionConfig>, promptFn?: PermissionPromptFn, decisionHook?: PermissionDecisionHook);
     fork(promptFn?: PermissionPromptFn | undefined): PermissionEngine;
+    setPlanModeToolPolicy(policy: PlanModeToolPolicy | undefined): void;
+    get planModePolicy(): PlanModeToolPolicy | undefined;
+    deriveChild(options?: DerivedPermissionEngineOptions): PermissionEngine;
+    protected planModeVerdict(toolName: string, canonicalToolName: string, input: Record<string, unknown>, tool: PermissionToolMetadata | undefined): Promise<{
+        kind: "refuse";
+        reason: string;
+    } | {
+        kind: "admit";
+        reason: string;
+    } | {
+        kind: "defer";
+    }>;
+    private planModeReadOnlyAdmission;
     get mode(): PermissionConfig["mode"];
     setMode(mode: PermissionConfig["mode"]): void;
     setWorkingDirectory(cwd: string): void;
@@ -701,7 +752,10 @@ declare class PermissionEngine {
         reason: string;
     }>;
     private checkElevatedBash;
-    private finalizeDecision;
+    protected finalizeDecision(toolName: string, input: Record<string, unknown>, allowed: boolean, reason: string, traceId?: string, requesterLabel?: string): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
     classifyAutoPermission(toolName: string, input: Record<string, unknown>): AutoPermissionDecision;
     private contentDigest;
     private bashScopeSuffix;
@@ -715,7 +769,7 @@ declare class PermissionEngine {
     private promptUser;
     private getToolDetail;
     private getCommandPrefix;
-    private matchesRule;
+    protected matchesRule(ruleTool: string, pattern: string | undefined, toolName: string, input: Record<string, unknown>): boolean;
     private matchesBashPattern;
     private matchesWildcard;
     private isCredentialLikePath;