@compilr-dev/agents 0.5.6 → 0.5.8

package/dist/agent.d.ts

@@ -151,6 +151,10 @@ export type AgentEvent = {
     type: 'iteration_limit_extended';
     newMaxIterations: number;
     addedIterations: number;
+} | {
+    type: 'model_changed';
+    previousModel: string;
+    newModel: string;
 } | {
     type: 'llm_retry';
     attempt: number;
@@ -1128,6 +1132,17 @@ export declare class Agent {
      * Check if pins are enabled
      */
     hasPins(): boolean;
+    /**
+     * Get the current model ID for this agent.
+     */
+    getModel(): string;
+    /**
+     * Change the model for subsequent LLM calls. Same provider only.
+     * Takes effect on the next chat() call, not mid-stream.
+     *
+     * @param modelId - The new model ID (e.g., 'claude-opus-4-20250514')
+     */
+    setModel(modelId: string): void;
     /** @deprecated Use addPin() instead */
     addAnchor(input: AnchorInput): Anchor | undefined;
     /** @deprecated Use getPin() instead */

package/dist/agent.js

@@ -523,6 +523,27 @@ export class Agent {
     hasPins() {
         return this.pinManager !== undefined;
     }
+    // --- Model management -------------------------------------------------------
+    /**
+     * Get the current model ID for this agent.
+     */
+    getModel() {
+        return this.provider.getModel();
+    }
+    /**
+     * Change the model for subsequent LLM calls. Same provider only.
+     * Takes effect on the next chat() call, not mid-stream.
+     *
+     * @param modelId - The new model ID (e.g., 'claude-opus-4-20250514')
+     */
+    setModel(modelId) {
+        if (!modelId || typeof modelId !== 'string') {
+            throw new Error('modelId must be a non-empty string');
+        }
+        const previousModel = this.provider.getModel();
+        this.provider.setModel(modelId);
+        this.onEvent?.({ type: 'model_changed', previousModel, newModel: modelId });
+    }
     // --- Deprecated aliases (use pin methods instead) --------------------------
     /** @deprecated Use addPin() instead */
     addAnchor(input) {

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/dist/providers/claude.d.ts

@@ -72,13 +72,15 @@ export interface ClaudeProviderConfig {
 export declare class ClaudeProvider implements LLMProvider {
     readonly name = "claude";
     private readonly client;
-    private readonly defaultModel;
+    private defaultModel;
     private readonly defaultMaxTokens;
     private readonly enablePromptCaching;
     private readonly enableTokenEfficientTools;
     private readonly enableExtendedContext;
     private readonly estimateTokensFn;
     constructor(config: ClaudeProviderConfig);
+    getModel(): string;
+    setModel(modelId: string): void;
     /**
      * Send messages and stream the response
      */

package/dist/providers/claude.js

@@ -46,6 +46,12 @@ export class ClaudeProvider {
         this.estimateTokensFn =
             config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
+    getModel() {
+        return this.defaultModel;
+    }
+    setModel(modelId) {
+        this.defaultModel = modelId;
+    }
     /**
      * Send messages and stream the response
      */

package/dist/providers/gemini-native.d.ts

@@ -50,10 +50,12 @@ export interface GeminiNativeProviderConfig {
 export declare class GeminiNativeProvider implements LLMProvider {
     readonly name = "gemini";
     private readonly client;
-    private readonly defaultModel;
+    private defaultModel;
     private readonly defaultMaxTokens;
     private readonly estimateTokensFn;
     constructor(config: GeminiNativeProviderConfig);
+    getModel(): string;
+    setModel(modelId: string): void;
     /**
      * Send messages and stream the response
      */

package/dist/providers/gemini-native.js

@@ -45,6 +45,12 @@ export class GeminiNativeProvider {
         this.estimateTokensFn =
             config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
+    getModel() {
+        return this.defaultModel;
+    }
+    setModel(modelId) {
+        this.defaultModel = modelId;
+    }
     /**
      * Send messages and stream the response
      */

package/dist/providers/mock.d.ts

@@ -78,7 +78,10 @@ export declare class MockProvider implements LLMProvider {
     private readonly throwOnEmpty;
     private callCount;
     private readonly callHistory;
+    private mockModel;
     constructor(config?: MockProviderConfig);
+    getModel(): string;
+    setModel(modelId: string): void;
     /**
      * Add a response (text string or structured response with tool calls)
      */

package/dist/providers/mock.js

@@ -38,10 +38,17 @@ export class MockProvider {
     throwOnEmpty;
     callCount = 0;
     callHistory = [];
+    mockModel = 'mock-model';
     constructor(config = {}) {
         this.defaultDelay = config.defaultDelay ?? 0;
         this.throwOnEmpty = config.throwOnEmpty ?? true;
     }
+    getModel() {
+        return this.mockModel;
+    }
+    setModel(modelId) {
+        this.mockModel = modelId;
+    }
     /**
      * Add a response (text string or structured response with tool calls)
      */

package/dist/providers/openai-compatible.d.ts

@@ -121,11 +121,13 @@ export declare abstract class OpenAICompatibleProvider implements LLMProvider {
      */
     abstract readonly name: string;
     protected readonly baseUrl: string;
-    protected readonly defaultModel: string;
+    protected defaultModel: string;
     protected readonly defaultMaxTokens: number;
     protected readonly timeout: number;
     protected readonly estimateTokensFn: (text: string) => number;
     constructor(config: OpenAICompatibleConfig);
+    getModel(): string;
+    setModel(modelId: string): void;
     /**
      * Get authentication headers for API requests
      * @returns Headers object with auth credentials

package/dist/providers/openai-compatible.js

@@ -46,6 +46,12 @@ export class OpenAICompatibleProvider {
         this.estimateTokensFn =
             config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
+    getModel() {
+        return this.defaultModel;
+    }
+    setModel(modelId) {
+        this.defaultModel = modelId;
+    }
     /**
      * Extract cache statistics from response headers.
      * Override in subclasses for providers that return cache stats in headers (e.g., Fireworks).

package/dist/providers/types.d.ts

@@ -239,4 +239,15 @@ export interface LLMProvider {
      * Count tokens in messages (optional, provider-specific)
      */
     countTokens?(messages: Message[]): Promise<number>;
+    /**
+     * Get the current default model ID.
+     */
+    getModel(): string;
+    /**
+     * Change the default model for subsequent calls. Same provider only.
+     * Takes effect on the next chat() call, not mid-stream.
+     *
+     * @param modelId - The new model ID (e.g., 'claude-opus-4-20250514')
+     */
+    setModel(modelId: string): void;
 }

package/dist/rate-limit/provider-wrapper.d.ts

@@ -32,6 +32,8 @@ export declare class RateLimitedProvider implements LLMProvider {
     private readonly rateLimiter;
     private readonly retryConfig;
     constructor(provider: LLMProvider, config?: RateLimitRetryConfig);
+    getModel(): string;
+    setModel(modelId: string): void;
     /**
      * Get the rate limiter instance for statistics
      */

package/dist/rate-limit/provider-wrapper.js

@@ -38,6 +38,12 @@ export class RateLimitedProvider {
         this.rateLimiter = config.rateLimit ? createRateLimiter(config.rateLimit) : createRateLimiter();
         this.retryConfig = config.retry ?? {};
     }
+    getModel() {
+        return this.provider.getModel();
+    }
+    setModel(modelId) {
+        this.provider.setModel(modelId);
+    }
     /**
      * Get the rate limiter instance for statistics
      */

package/package.json

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