@compilr-dev/agents 0.5.6 → 0.5.7

package/dist/index.d.ts

@@ -52,7 +52,7 @@ export type { Guardrail, GuardrailInput, GuardrailAction, GuardrailResult, Guard
 export { MCPClient, MCPManager, mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, normalizeServerConfig, MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError, } from './mcp/index.js';
 export type { MCPTransport, MCPConnectionStatus, MCPStdioOptions, MCPHttpOptions, MCPClientConfig, MCPServerConfig, MCPToolDefinition, MCPContentBlock, MCPToolResult, MCPClientEventType, MCPClientEvent, MCPClientEventHandler, MCPManagerOptions, MCPToolConversionOptions, } from './mcp/index.js';
 export { PermissionManager } from './permissions/index.js';
-export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './permissions/index.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PermissionHandlerResponse, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './permissions/index.js';
 export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './memory/index.js';
 export type { LLMProviderName, MemoryFile, ProjectMemory, FilePattern, CombineStrategy, ProjectMemoryOptions, ProjectMemoryEventType, ProjectMemoryEvent, ProjectMemoryEventHandler, MemoryDiscoveryResult, ProviderPatterns, } from './memory/index.js';
 export { UsageTracker, createUsageTracker } from './costs/index.js';

package/dist/permissions/index.d.ts

@@ -2,4 +2,4 @@
  * Permissions module - Tool-level permission management
  */
 export { PermissionManager } from './manager.js';
-export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './types.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PermissionHandlerResponse, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './types.js';

package/dist/permissions/manager.js

@@ -226,8 +226,8 @@ export class PermissionManager {
                     return { allowed: true, level, askedUser: false, rule };
                 }
                 // Ask for permission
-                const allowed = await this.askPermission(toolName, input, level, rule);
-                if (allowed) {
+                const askResult = await this.askPermission(toolName, input, level, rule);
+                if (askResult.allowed) {
                     this.sessionGrants.add(toolName);
                     this.emit({ type: 'permission:session_granted', toolName, level, input, rule });
                 }
@@ -235,11 +235,11 @@ export class PermissionManager {
                     this.emit({ type: 'permission:denied', toolName, level, input, rule });
                 }
                 return {
-                    allowed,
+                    allowed: askResult.allowed,
                     level,
                     askedUser: true,
                     rule,
-                    reason: allowed ? undefined : 'User denied permission',
+                    reason: askResult.allowed ? undefined : (askResult.reason ?? 'User denied permission'),
                 };
             }
             case 'once': {
@@ -249,19 +249,19 @@ export class PermissionManager {
                     return { allowed: true, level, askedUser: false, rule };
                 }
                 // Ask for permission each time (unless session-granted above)
-                const allowed = await this.askPermission(toolName, input, level, rule);
-                if (allowed) {
+                const askResult = await this.askPermission(toolName, input, level, rule);
+                if (askResult.allowed) {
                     this.emit({ type: 'permission:granted', toolName, level, input, rule });
                 }
                 else {
                     this.emit({ type: 'permission:denied', toolName, level, input, rule });
                 }
                 return {
-                    allowed,
+                    allowed: askResult.allowed,
                     level,
                     askedUser: true,
                     rule,
-                    reason: allowed ? undefined : 'User denied permission',
+                    reason: askResult.allowed ? undefined : (askResult.reason ?? 'User denied permission'),
                 };
             }
         }
@@ -281,7 +281,7 @@ export class PermissionManager {
     async askPermission(toolName, input, level, rule) {
         // If no handler, default to allow
         if (!this.handler) {
-            return true;
+            return { allowed: true };
         }
         const preview = this.previewGenerator(toolName, input);
         const request = {
@@ -292,7 +292,12 @@ export class PermissionManager {
             preview,
         };
         this.emit({ type: 'permission:asked', toolName, level, input, rule });
-        return this.handler(request);
+        const response = await this.handler(request);
+        // Normalize legacy boolean responses (backward compat)
+        if (typeof response === 'boolean') {
+            return { allowed: response };
+        }
+        return response;
     }
     /**
      * Grant session-level permission for a tool

package/dist/permissions/types.d.ts

@@ -84,25 +84,52 @@ export interface PermissionCheckResult {
      */
     reason?: string;
 }
+/**
+ * Response shape from a permission handler.
+ *
+ * Either a plain boolean (legacy — backward compatible) OR a structured
+ * object that can carry an optional reason. The reason is delivered to
+ * the agent inline with the tool's permission-denied error so the agent
+ * sees the user's context immediately, in the same turn.
+ *
+ * @example
+ * ```typescript
+ * // Legacy (still supported):
+ * return true;
+ * return false;
+ *
+ * // With reason:
+ * return { allowed: false, reason: 'Use project_document_add instead' };
+ * return { allowed: true };
+ * ```
+ */
+export type PermissionHandlerResponse = boolean | {
+    allowed: boolean;
+    reason?: string;
+};
 /**
  * Handler called when permission is needed
  *
  * @param request - Information about the permission request
- * @returns true to allow execution, false to deny
+ * @returns true to allow / false to deny — or { allowed, reason? } to
+ *          carry context (especially useful when denying with a message)
  *
  * @example
  * ```typescript
  * const handler: PermissionHandler = async (request) => {
  *   // Show UI prompt to user
- *   const allowed = await showConfirmDialog(
+ *   const result = await showConfirmDialog(
  *     `Allow ${request.toolName}?`,
  *     request.description
  *   );
- *   return allowed;
+ *   if (!result.allowed && result.message) {
+ *     return { allowed: false, reason: result.message };
+ *   }
+ *   return result.allowed;
  * };
  * ```
  */
-export type PermissionHandler = (request: PermissionRequest) => boolean | Promise<boolean>;
+export type PermissionHandler = (request: PermissionRequest) => PermissionHandlerResponse | Promise<PermissionHandlerResponse>;
 /**
  * Preview generator for permission requests
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",