praxis-agent 0.30.0 → 0.32.0

package/dist/compatibility/claude/context.js

@@ -1,5 +1,6 @@
 import { isAbsolute, matchesGlob, relative, resolve, sep } from 'node:path';
 import { PromptComposer, } from '../../core/prompt-composer.js';
+import { boundProjectMemoryIndex } from '../../core/project-memory.js';
 import { renderClaudeDynamicSystemContext, renderClaudeDynamicUserContext, } from './dynamic-context.js';
 function renderResources(title, resources) {
     const rendered = resources
@@ -12,7 +13,7 @@ function renderResources(title, resources) {
 function limitMemoryIndex(resource) {
     return {
         ...resource,
-        content: resource.content.split('\n').slice(0, 200).join('\n'),
+        content: boundProjectMemoryIndex(resource.content),
     };
 }
 export class ClaudeConditionalRuleResolver {
@@ -170,6 +171,8 @@ ${sections.join('\n\n')}`,
             if (options.reason === 'resource-reload' ||
                 options.reason === 'compact') {
                 delete snapshot.resources;
+                snapshot.resourceLoadReason =
+                    options.reason === 'compact' ? 'compact' : 'resource_reload';
                 continue;
             }
             if (options.reason === 'tool-pool') {
@@ -198,7 +201,18 @@ ${sections.join('\n\n')}`,
         if (!snapshot)
             return this.options.loadResources(cwd);
         if (!snapshot.resources) {
-            const pending = this.options.loadResources(cwd);
+            const reason = snapshot.resourceLoadReason ?? 'session_start';
+            delete snapshot.resourceLoadReason;
+            const pending = this.options
+                .loadResources(cwd)
+                .then(async (resources) => {
+                await this.options.onInstructionsLoaded?.(resources.instructions, {
+                    lifecycleId: snapshot.lifecycleId,
+                    ...(cwd === undefined ? {} : { cwd }),
+                    reason,
+                });
+                return resources;
+            });
             snapshot.resources = pending;
             void pending.catch(() => {
                 if (snapshot.resources === pending)

package/dist/compatibility/claude/dynamic-context.js

@@ -145,7 +145,8 @@ export async function loadClaudeDynamicContext(options) {
         ? [
             '# Memory',
             `Persistent project memory is stored at \`${options.memoryDirectory}\`.`,
-            'Use MEMORY.md as its concise index. Keep detailed durable facts in linked Markdown files, update existing entries instead of duplicating them, and do not store transient conversation state.',
+            'Use MEMORY.md as a concise index of one-line links. Keep detailed durable facts in linked Markdown topic files with name, description, and a type of user, feedback, project, or reference. Update existing entries instead of duplicating them.',
+            'Do not store codebase architecture, implementation patterns, git history, fix recipes, transient task or conversation state, or duplicates of repository instructions.',
         ].join('\n')
         : undefined;
     return {

package/dist/compatibility/claude/paths.js

@@ -1,26 +1,15 @@
 import { lstat, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { extname, resolve } from 'node:path';
+import { sanitizeProjectPath } from '../../platform/project-path-key.js';
 import { getDataOwnership } from './ownership.js';
 const MAX_SANITIZED_LENGTH = 200;
 const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function isClaudeSessionId(value) {
     return SESSION_ID_PATTERN.test(value);
 }
-function stablePathHash(value) {
-    let hash = 0;
-    for (let index = 0; index < value.length; index += 1) {
-        hash = Math.imul(hash, 31) + value.charCodeAt(index);
-        hash |= 0;
-    }
-    return Math.abs(hash);
-}
 export function sanitizeClaudeProjectPath(path) {
-    const sanitized = path.replace(/[^a-zA-Z0-9]/g, '-');
-    if (sanitized.length <= MAX_SANITIZED_LENGTH) {
-        return sanitized;
-    }
-    return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${stablePathHash(path).toString(36)}`;
+    return sanitizeProjectPath(path);
 }
 async function isDirectory(path) {
     try {

package/dist/compatibility/claude/shared-resources.d.ts

@@ -42,17 +42,17 @@ export interface LoadClaudeSharedResourcesOptions {
     homeDirectory?: string;
     claudeStatePath?: string;
     settingSources?: readonly ClaudeResourceScope[];
+    includeProjectMemory?: boolean;
 }
 export declare function resolveClaudeInstructionImports(resources: readonly ClaudeTextResource[], { homeDirectory }?: {
     homeDirectory?: string;
 }): Promise<ClaudeTextResource[]>;
-export declare function resolveClaudeProjectIdentity({ cwd, homeDirectory, }: {
+export declare function resolveClaudeProjectIdentity({ cwd, }: {
     cwd: string;
-    homeDirectory?: string;
 }): Promise<string>;
 export declare function loadClaudeSettings({ configRoot, cwd, settingSources, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeJsonResource[]>;
 export declare function resolveClaudeProjectMemoryDirectory({ configRoot, cwd, homeDirectory, }: LoadClaudeSharedResourcesOptions): Promise<string>;
 export declare function loadClaudeMcpResources({ configRoot, cwd, homeDirectory, claudeStatePath, settingSources, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeJsonResource[]>;
-export declare function loadClaudeContextResources({ configRoot, cwd, homeDirectory, settingSources, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeContextResources>;
-export declare function loadClaudeSharedResources({ configRoot, cwd, homeDirectory, claudeStatePath, settingSources, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeSharedResources>;
+export declare function loadClaudeContextResources({ configRoot, cwd, homeDirectory, settingSources, includeProjectMemory, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeContextResources>;
+export declare function loadClaudeSharedResources({ configRoot, cwd, homeDirectory, claudeStatePath, settingSources, includeProjectMemory, }: LoadClaudeSharedResourcesOptions): Promise<ClaudeSharedResources>;
 //# sourceMappingURL=shared-resources.d.ts.map

package/dist/compatibility/claude/shared-resources.js

@@ -2,6 +2,7 @@ import { readdir, readFile, realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { resolveProjectIdentity } from '../../platform/project-identity.js';
 import { sanitizeClaudeProjectPath } from './paths.js';
 function selectedScope(scope, settingSources) {
     return settingSources === undefined || settingSources.includes(scope);
@@ -255,32 +256,6 @@ async function findGitRoot(cwd) {
     }
     return current;
 }
-async function readOptionalRaw(path) {
-    try {
-        return await readFile(path, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return null;
-        throw error;
-    }
-}
-async function findMemoryIdentityRoot(gitRoot) {
-    const gitMarker = join(gitRoot, '.git');
-    const marker = await stat(gitMarker);
-    if (!marker.isFile())
-        return gitRoot;
-    const gitFile = await readFile(gitMarker, 'utf8');
-    const match = /^gitdir:\s*(.+)\s*$/m.exec(gitFile);
-    if (!match?.[1])
-        return gitRoot;
-    const gitDirectory = resolve(gitRoot, match[1]);
-    const commonDirectory = await readOptionalRaw(join(gitDirectory, 'commondir'));
-    if (!commonDirectory)
-        return gitRoot;
-    const commonGitDirectory = await canonicalPath(resolve(gitDirectory, commonDirectory.trim()));
-    return dirname(commonGitDirectory);
-}
 async function resolveProjectContext(cwd, homeDirectory) {
     const canonicalCwd = await canonicalPath(cwd);
     const gitRoot = await findGitRoot(canonicalCwd);
@@ -289,7 +264,7 @@ async function resolveProjectContext(cwd, homeDirectory) {
             directories: directoriesFromRoot(gitRoot, canonicalCwd),
             extensionDirectories: directoriesFromRoot(gitRoot, canonicalCwd),
             homeBoundary: null,
-            memoryIdentityRoot: await findMemoryIdentityRoot(gitRoot),
+            memoryIdentityRoot: await resolveProjectIdentity(gitRoot),
         };
     }
     const canonicalHome = await canonicalPath(homeDirectory);
@@ -303,8 +278,8 @@ async function resolveProjectContext(cwd, homeDirectory) {
         memoryIdentityRoot: canonicalCwd,
     };
 }
-export async function resolveClaudeProjectIdentity({ cwd, homeDirectory = homedir(), }) {
-    return (await resolveProjectContext(cwd, homeDirectory)).memoryIdentityRoot;
+export async function resolveClaudeProjectIdentity({ cwd, }) {
+    return resolveProjectIdentity(cwd);
 }
 async function loadProjectSettings(configRoot, cwd) {
     const userSettings = await readOptionalJson(join(configRoot, 'settings.json'), 'user');
@@ -411,13 +386,15 @@ async function loadProjectContextResources(projectDirectories, homeBoundary) {
 function present(value) {
     return value !== null;
 }
-async function loadResolvedClaudeContext(configRoot, projectDirectories, homeBoundary, memoryIdentityRoot) {
+async function loadResolvedClaudeContext(configRoot, projectDirectories, homeBoundary, memoryIdentityRoot, includeProjectMemory) {
     const projectMemoryDirectory = join(configRoot, 'projects', sanitizeClaudeProjectPath(memoryIdentityRoot), 'memory');
     const [globalInstruction, globalRules, projectContext, memoryIndex] = await Promise.all([
         readOptionalText(join(configRoot, 'CLAUDE.md'), 'user'),
         loadRuleResources(join(configRoot, 'rules'), 'user', projectDirectories.at(-1) ?? memoryIdentityRoot),
         loadProjectContextResources(projectDirectories, homeBoundary),
-        readOptionalText(join(projectMemoryDirectory, 'MEMORY.md'), 'project'),
+        includeProjectMemory
+            ? readOptionalText(join(projectMemoryDirectory, 'MEMORY.md'), 'project')
+            : Promise.resolve(null),
     ]);
     return {
         instructions: [
@@ -432,9 +409,9 @@ async function loadResolvedClaudeContext(configRoot, projectDirectories, homeBou
         memoryIndex,
     };
 }
-export async function loadClaudeContextResources({ configRoot, cwd, homeDirectory = homedir(), settingSources, }) {
+export async function loadClaudeContextResources({ configRoot, cwd, homeDirectory = homedir(), settingSources, includeProjectMemory = true, }) {
     const { directories, homeBoundary, memoryIdentityRoot } = await resolveProjectContext(cwd, homeDirectory);
-    const resources = await loadResolvedClaudeContext(configRoot, directories, homeBoundary, memoryIdentityRoot);
+    const resources = await loadResolvedClaudeContext(configRoot, directories, homeBoundary, memoryIdentityRoot, includeProjectMemory);
     const instructions = resources.instructions.filter((resource) => selectedScope(resource.scope, settingSources));
     return {
         instructions: await resolveClaudeInstructionImports(instructions, {
@@ -447,14 +424,16 @@ export async function loadClaudeContextResources({ configRoot, cwd, homeDirector
             : null,
     };
 }
-export async function loadClaudeSharedResources({ configRoot, cwd, homeDirectory = homedir(), claudeStatePath = join(configRoot, '.claude.json'), settingSources, }) {
+export async function loadClaudeSharedResources({ configRoot, cwd, homeDirectory = homedir(), claudeStatePath = join(configRoot, '.claude.json'), settingSources, includeProjectMemory = true, }) {
     const { directories: projectDirectories, extensionDirectories, homeBoundary, memoryIdentityRoot, } = await resolveProjectContext(cwd, homeDirectory);
     const projectMemoryDirectory = join(configRoot, 'projects', sanitizeClaudeProjectPath(memoryIdentityRoot), 'memory');
     const [globalInstruction, globalRules, projectInstructions, memory, skills, commands, agents, settings, mcp,] = await Promise.all([
         readOptionalText(join(configRoot, 'CLAUDE.md'), 'user'),
         loadAllRules(join(configRoot, 'rules'), 'user'),
         loadProjectInstructions(projectDirectories, homeBoundary),
-        findFiles(projectMemoryDirectory, (name) => name.endsWith('.md')).then((paths) => loadFiles(paths, 'project')),
+        includeProjectMemory
+            ? findFiles(projectMemoryDirectory, (name) => name.endsWith('.md')).then((paths) => loadFiles(paths, 'project'))
+            : Promise.resolve([]),
         loadScopedFiles(join(configRoot, 'skills'), extensionDirectories.map((path) => join(path, '.claude', 'skills')), (name) => name === 'SKILL.md'),
         loadScopedFiles(join(configRoot, 'commands'), extensionDirectories.map((path) => join(path, '.claude', 'commands')), (name) => name.endsWith('.md')),
         loadScopedFiles(join(configRoot, 'agents'), extensionDirectories.map((path) => join(path, '.claude', 'agents')), (name) => name.endsWith('.md')),

package/dist/core/context-budget.d.ts

@@ -1,4 +1,5 @@
 import type { ModelMessage, ModelToolDefinition, ModelUsage } from './runtime.js';
+import { ModelProviderError } from './runtime.js';
 export interface ContextBudgetOptions {
     contextWindowTokens: number;
     reserveTokens?: number;
@@ -76,15 +77,16 @@ export type ContextRecoveryStage = 'preflight' | 'microcompact' | 'auto-compact'
 export interface ContextRecoveryPlannerOptions {
     /** Number of reactive retries allowed before the planner reports `blocked`. */
     maxReactiveRetries?: number;
-    /** Consecutive failures that trip the circuit breaker to `blocked`. */
-    consecutiveFailureThreshold?: number;
 }
+export interface ContextRecoveryProgress {
+    beforeOccupancyTokens: number;
+    afterOccupancyTokens: number;
+}
+export declare function contextRecoveryMadeProgress(progress: ContextRecoveryProgress): boolean;
 export declare class ContextRecoveryPlanner {
     private readonly maxReactiveRetries;
-    private readonly consecutiveFailureThreshold;
     private currentStage;
     private reactiveRetriesUsed;
-    private consecutiveFailures;
     constructor(options?: ContextRecoveryPlannerOptions);
     get stage(): ContextRecoveryStage;
     get reactiveRetriesRemaining(): number;
@@ -93,14 +95,13 @@ export declare class ContextRecoveryPlanner {
     advance(): ContextRecoveryStage;
     /** Consume one reactive retry decision; reports `blocked` once the maximum
      *  reactive retries have been consumed. */
-    consumeReactiveRetry(): ContextRecoveryStage;
-    /** Record a failed recovery attempt; trips the circuit breaker to `blocked`
-     *  after `consecutiveFailureThreshold` consecutive failures. */
+    consumeReactiveRetry(progress: ContextRecoveryProgress): ContextRecoveryStage;
+    /** A failed reactive attempt exhausts the only selected context transition. */
     recordFailure(): ContextRecoveryStage;
     /** Record a successful recovery/model attempt; resets the planner. */
     recordSuccess(): ContextRecoveryStage;
 }
 /** True when a provider error signals that the request exceeded the model's
  *  context window and a reactive compaction retry is the relevant recovery. */
-export declare function isPromptTooLongError(error: unknown): boolean;
+export declare function isPromptTooLongError(error: unknown): error is ModelProviderError;
 //# sourceMappingURL=context-budget.d.ts.map

package/dist/core/context-budget.js

@@ -203,26 +203,24 @@ export class ContextBudget {
     }
 }
 const DEFAULT_MAX_REACTIVE_RETRIES = 1;
-const DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD = 3;
+export function contextRecoveryMadeProgress(progress) {
+    for (const [name, value] of Object.entries(progress)) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error(`${name} must be a nonnegative safe integer`);
+        }
+    }
+    return progress.afterOccupancyTokens < progress.beforeOccupancyTokens;
+}
 export class ContextRecoveryPlanner {
     maxReactiveRetries;
-    consecutiveFailureThreshold;
     currentStage = 'preflight';
     reactiveRetriesUsed = 0;
-    consecutiveFailures = 0;
     constructor(options = {}) {
         const maxReactiveRetries = options.maxReactiveRetries ?? DEFAULT_MAX_REACTIVE_RETRIES;
-        const consecutiveFailureThreshold = options.consecutiveFailureThreshold ??
-            DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD;
         if (!Number.isInteger(maxReactiveRetries) || maxReactiveRetries < 0) {
             throw new Error('maxReactiveRetries must be a nonnegative integer');
         }
-        if (!Number.isInteger(consecutiveFailureThreshold) ||
-            consecutiveFailureThreshold < 1) {
-            throw new Error('consecutiveFailureThreshold must be a positive integer');
-        }
         this.maxReactiveRetries = maxReactiveRetries;
-        this.consecutiveFailureThreshold = consecutiveFailureThreshold;
     }
     get stage() {
         return this.currentStage;
@@ -253,7 +251,11 @@ export class ContextRecoveryPlanner {
     }
     /** Consume one reactive retry decision; reports `blocked` once the maximum
      *  reactive retries have been consumed. */
-    consumeReactiveRetry() {
+    consumeReactiveRetry(progress) {
+        if (!contextRecoveryMadeProgress(progress)) {
+            this.currentStage = 'blocked';
+            return this.currentStage;
+        }
         this.reactiveRetriesUsed += 1;
         this.currentStage =
             this.reactiveRetriesUsed <= this.maxReactiveRetries
@@ -261,28 +263,21 @@ export class ContextRecoveryPlanner {
                 : 'blocked';
         return this.currentStage;
     }
-    /** Record a failed recovery attempt; trips the circuit breaker to `blocked`
-     *  after `consecutiveFailureThreshold` consecutive failures. */
+    /** A failed reactive attempt exhausts the only selected context transition. */
     recordFailure() {
-        this.consecutiveFailures += 1;
-        if (this.consecutiveFailures >= this.consecutiveFailureThreshold) {
-            this.currentStage = 'blocked';
-        }
+        this.currentStage = 'blocked';
         return this.currentStage;
     }
     /** Record a successful recovery/model attempt; resets the planner. */
     recordSuccess() {
-        this.consecutiveFailures = 0;
         this.reactiveRetriesUsed = 0;
         this.currentStage = 'preflight';
         return this.currentStage;
     }
 }
-const PROMPT_TOO_LONG_PATTERN = /context(?:[_\s-]?length|[_\s-]?window)|prompt(?:[_\s-]?is)?[_\s-]?too[_\s-]?long|too[_\s-]?many[_\s-]?tokens|maximum[_\s-]?context/iu;
 /** True when a provider error signals that the request exceeded the model's
  *  context window and a reactive compaction retry is the relevant recovery. */
 export function isPromptTooLongError(error) {
-    return (error instanceof ModelProviderError &&
-        PROMPT_TOO_LONG_PATTERN.test(error.message));
+    return error instanceof ModelProviderError && error.kind === 'prompt_too_long';
 }
 //# sourceMappingURL=context-budget.js.map

package/dist/core/project-memory.d.ts

@@ -0,0 +1,19 @@
+export declare const PROJECT_MEMORY_INDEX_MAX_LINES = 200;
+export declare const PROJECT_MEMORY_INDEX_MAX_BYTES: number;
+export type ProjectMemoryDataPlane = 'native' | 'claude';
+export interface ProjectMemoryPolicy {
+    enabled: boolean;
+    extraction: boolean;
+    recall: boolean;
+}
+export interface ResolveProjectMemoryPolicyOptions {
+    dataPlane: ProjectMemoryDataPlane;
+    settings: readonly {
+        value: unknown;
+    }[];
+    environment: Readonly<Record<string, string | undefined>>;
+}
+export declare function boundProjectMemoryText(source: string, maxLines: number, maxBytes: number): string;
+export declare function boundProjectMemoryIndex(source: string): string;
+export declare function resolveProjectMemoryPolicy({ dataPlane, settings, environment, }: ResolveProjectMemoryPolicyOptions): ProjectMemoryPolicy;
+//# sourceMappingURL=project-memory.d.ts.map

package/dist/core/project-memory.js

@@ -0,0 +1,58 @@
+export const PROJECT_MEMORY_INDEX_MAX_LINES = 200;
+export const PROJECT_MEMORY_INDEX_MAX_BYTES = 25 * 1024;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function utf8Prefix(source, maxBytes) {
+    const buffer = Buffer.from(source, 'utf8');
+    if (buffer.byteLength <= maxBytes)
+        return source;
+    for (let end = maxBytes; end >= Math.max(0, maxBytes - 4); end -= 1) {
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, end));
+        }
+        catch {
+            // Try the previous Unicode boundary.
+        }
+    }
+    return '';
+}
+export function boundProjectMemoryText(source, maxLines, maxBytes) {
+    return utf8Prefix(source.split(/\r?\n/u).slice(0, maxLines).join('\n'), maxBytes);
+}
+export function boundProjectMemoryIndex(source) {
+    return boundProjectMemoryText(source, PROJECT_MEMORY_INDEX_MAX_LINES, PROJECT_MEMORY_INDEX_MAX_BYTES);
+}
+function settingBoolean(settings, path) {
+    let selected;
+    for (const resource of settings) {
+        let value = resource.value;
+        for (const key of path)
+            value = record(value)?.[key];
+        if (typeof value === 'boolean')
+            selected = value;
+    }
+    return selected;
+}
+function enabledEnvironmentValue(value) {
+    return value === '1' || value?.toLowerCase() === 'true';
+}
+export function resolveProjectMemoryPolicy({ dataPlane, settings, environment, }) {
+    const disabledByEnvironment = enabledEnvironmentValue(dataPlane === 'claude'
+        ? environment.CLAUDE_CODE_DISABLE_AUTO_MEMORY
+        : environment.PRAXIS_DISABLE_AUTO_MEMORY);
+    const enabled = !disabledByEnvironment &&
+        (settingBoolean(settings, ['autoMemoryEnabled']) ?? true);
+    if (!enabled)
+        return { enabled: false, extraction: false, recall: false };
+    return {
+        enabled: true,
+        extraction: settingBoolean(settings, ['projectMemory', 'backgroundExtraction']) ??
+            enabledEnvironmentValue(environment.PRAXIS_PROJECT_MEMORY_EXTRACTION),
+        recall: settingBoolean(settings, ['projectMemory', 'selectiveRecall']) ??
+            enabledEnvironmentValue(environment.PRAXIS_PROJECT_MEMORY_RECALL),
+    };
+}
+//# sourceMappingURL=project-memory.js.map

package/dist/core/runtime.d.ts

@@ -181,6 +181,9 @@ export type RuntimeEvent = {
 } | {
     type: 'terminal';
     reason: ModelTerminalReason;
+} | {
+    type: 'model-attempt-discarded';
+    reason: ProviderErrorKind;
 } | {
     type: 'tool-call';
     call: ModelToolCall;
@@ -316,6 +319,7 @@ export interface ToolExecutionResult {
 }
 export interface ToolExecutionContext {
     cwd: string;
+    sessionId?: string;
     messages?: readonly ModelMessage[];
     signal?: AbortSignal;
     toolResultDirectory?: string;
@@ -404,6 +408,7 @@ export type PermissionDecision = {
 } | {
     behavior: 'deny';
     reason: string;
+    followUpUserMessages?: readonly string[];
     source?: PermissionDecisionSource;
 };
 export interface PermissionResolver {
@@ -452,6 +457,7 @@ export interface AgentRuntimeOptions {
 }
 export interface AgentRunRequest {
     messages: readonly ModelMessage[];
+    sessionId?: string;
     /** Number of leading system messages that form the stable prompt prefix. */
     stableSystemMessageCount?: number;
     cwd?: string;
@@ -472,10 +478,13 @@ export interface AgentRunRequest {
     effort?: string;
     thinking?: ModelThinkingConfig;
     collectMetrics?: boolean;
+    /** Provider failures whose presentation is owned by a caller recovery
+     *  boundary. `true` defers every typed provider failure for an owned retry. */
+    deferFailureKinds?: true | readonly ProviderErrorKind[];
     maxModelTurns?: number;
     betas?: readonly string[];
 }
-export interface AgentToolRecoveryRequest extends Pick<AgentRunRequest, 'approveTool' | 'cwd' | 'observer' | 'onPermissionUpdates' | 'permissionUpdates' | 'signal' | 'toolResultDirectory'> {
+export interface AgentToolRecoveryRequest extends Pick<AgentRunRequest, 'approveTool' | 'cwd' | 'observer' | 'onPermissionUpdates' | 'permissionUpdates' | 'signal' | 'sessionId' | 'toolResultDirectory'> {
     approveRecovery?: (call: ModelToolCall) => boolean | Promise<boolean>;
     messages?: readonly ModelMessage[];
 }

package/dist/core/runtime.js

@@ -255,6 +255,8 @@ export class AgentRuntime {
         this.options = options;
     }
     async run(request) {
+        const failurePresentationDeferred = (kind) => request.deferFailureKinds === true ||
+            request.deferFailureKinds?.includes(kind) === true;
         if (this.options.emitInitialContextState !== false) {
             this.emit({ type: 'state', state: 'assembling-context' });
         }
@@ -273,6 +275,8 @@ export class AgentRuntime {
         let durationToolMs = 0;
         let linesAdded = 0;
         let linesRemoved = 0;
+        let activeAttemptHasPresentation = false;
+        let activeAttemptDiscarded = false;
         const definitions = this.provider.capabilities.tools
             ? (this.options.tools?.definitions() ?? [])
             : [];
@@ -288,6 +292,8 @@ export class AgentRuntime {
         try {
             let modelTurns = 0;
             while (true) {
+                activeAttemptHasPresentation = false;
+                activeAttemptDiscarded = false;
                 if (request.signal?.aborted)
                     return this.cancel();
                 if (maxModelTurns !== undefined && modelTurns >= maxModelTurns) {
@@ -379,9 +385,10 @@ export class AgentRuntime {
                     }),
                     resultCompleted: (call, result) => this.presentToolResult(call, result),
                 });
-                const failScheduledTurn = async (error) => {
+                const failScheduledTurn = async (error, afterSettled) => {
                     toolScheduler.abort(error);
                     await toolScheduler.settle().catch(() => undefined);
+                    afterSettled?.();
                     throw error;
                 };
                 const apiStartedAt = request.collectMetrics ? performance.now() : 0;
@@ -418,6 +425,7 @@ export class AgentRuntime {
                             this.emit({ type: 'state', state: 'streaming' });
                         }
                         if (event.type === 'text-delta') {
+                            activeAttemptHasPresentation = true;
                             textBytes += Buffer.byteLength(event.delta);
                             if (textBytes > maxModelOutputBytes) {
                                 throw new Error(`Model output exceeded ${maxModelOutputBytes} bytes`);
@@ -427,6 +435,7 @@ export class AgentRuntime {
                         }
                         else if (event.type === 'thinking-delta' ||
                             event.type === 'thinking-signature-delta') {
+                            activeAttemptHasPresentation = true;
                             textBytes += Buffer.byteLength(event.delta);
                             if (textBytes > maxModelOutputBytes) {
                                 throw new Error(`Model output exceeded ${maxModelOutputBytes} bytes`);
@@ -434,10 +443,12 @@ export class AgentRuntime {
                             this.emit(event);
                         }
                         else if (event.type === 'thinking-stop') {
+                            activeAttemptHasPresentation = true;
                             thinkingBlocks.push(event.block);
                             this.emit(event);
                         }
                         else if (event.type === 'thinking-start') {
+                            activeAttemptHasPresentation = true;
                             const initialThinking = event.block.type === 'redacted_thinking'
                                 ? event.block.data
                                 : event.block.thinking;
@@ -462,10 +473,12 @@ export class AgentRuntime {
                             toolScheduler.schedule(event.call, resolveToolSchedulingPolicy(this.options.tools, event.call));
                         }
                         else if (event.type === 'terminal') {
+                            activeAttemptHasPresentation = true;
                             terminalReason = event.reason;
                             this.emit(event);
                         }
                         else {
+                            activeAttemptHasPresentation = true;
                             turnUsage = event.usage;
                             this.emit(event);
                         }
@@ -495,6 +508,18 @@ export class AgentRuntime {
                     terminalReason === undefined) {
                     return failScheduledTurn(new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true }));
                 }
+                if (terminalReason === 'prompt_too_long') {
+                    const discardAttempt = failurePresentationDeferred('prompt_too_long')
+                        ? () => {
+                            this.emit({
+                                type: 'model-attempt-discarded',
+                                reason: 'prompt_too_long',
+                            });
+                            activeAttemptDiscarded = true;
+                        }
+                        : undefined;
+                    await failScheduledTurn(new ModelProviderError('Provider reported that the active prompt exceeds its context window', { kind: 'prompt_too_long', retryable: false }), discardAttempt);
+                }
                 if (terminalReason === 'tool_use' && toolCalls.length === 0) {
                     return failScheduledTurn(new ModelProviderError('Provider reported tool_use without a completed tool call', { retryable: false }));
                 }
@@ -677,7 +702,18 @@ export class AgentRuntime {
                 return this.cancel();
             const message = error instanceof Error ? error.message : String(error);
             const retryable = error instanceof ModelProviderError ? error.retryable : false;
-            this.emit({ type: 'failed', message, retryable });
+            const kind = error instanceof ModelProviderError
+                ? modelProviderErrorKind(error)
+                : undefined;
+            const failureDeferred = kind !== undefined && failurePresentationDeferred(kind);
+            if (failureDeferred &&
+                activeAttemptHasPresentation &&
+                !activeAttemptDiscarded) {
+                this.emit({ type: 'model-attempt-discarded', reason: kind });
+            }
+            if (!failureDeferred) {
+                this.emit({ type: 'failed', message, retryable });
+            }
             throw error;
         }
     }
@@ -809,6 +845,8 @@ export class AgentRuntime {
             permissionPhase: 'request',
             permissionUpdates: request.permissionUpdates ?? [],
         };
+        if (request.sessionId)
+            context.sessionId = request.sessionId;
         if (request.signal)
             context.signal = request.signal;
         if (request.toolResultDirectory) {
@@ -890,7 +928,13 @@ export class AgentRuntime {
                     : decision.behavior === 'ask'
                         ? (decision.reason ?? 'Permission approval was not provided')
                         : 'Permission approval was not provided');
-            return { content: reason, isError: true };
+            return {
+                content: reason,
+                isError: true,
+                ...(decision.behavior === 'deny' && decision.followUpUserMessages
+                    ? { followUpUserMessages: decision.followUpUserMessages }
+                    : {}),
+            };
         }
         if (request.signal?.aborted) {
             throw request.signal.reason ?? new AgentRunCancelledError();

package/dist/hooks/claude-file-change-watcher.d.ts

@@ -0,0 +1,43 @@
+export type ClaudeFileChangeEvent = 'add' | 'change' | 'unlink';
+interface DirectoryWatcher {
+    close(): void;
+    on(event: 'error', listener: (error: Error) => void): DirectoryWatcher;
+    unref?(): void;
+}
+type WatchDirectory = (directory: string, listener: (filename: string | null) => void) => DirectoryWatcher;
+export interface ClaudeFileChangeWatcherOptions {
+    cwd: string;
+    staticPaths: readonly string[];
+    onFileChanged(filePath: string, event: ClaudeFileChangeEvent, signal: AbortSignal): Promise<readonly string[] | undefined>;
+    warn(message: string): void;
+    debounceMs?: number;
+    pathExists?(path: string): boolean;
+    watchDirectory?: WatchDirectory;
+}
+export declare class ClaudeFileChangeWatcher {
+    private readonly options;
+    private cwd;
+    private staticPaths;
+    private dynamicPaths;
+    private readonly watchers;
+    private readonly knownExistence;
+    private readonly pending;
+    private readonly inFlight;
+    private readonly debounceMs;
+    private readonly pathExists;
+    private readonly watchDirectory;
+    private generation;
+    private closed;
+    constructor(options: ClaudeFileChangeWatcherOptions);
+    updateForCwd(cwd: string, staticPaths: readonly string[], dynamicPaths: readonly string[]): void;
+    updateDynamicPaths(paths: readonly string[]): void;
+    close(timeoutMs?: number): Promise<void>;
+    private validDynamicPaths;
+    private targetPaths;
+    private rebuild;
+    private schedule;
+    private dispatch;
+    private clearResources;
+}
+export {};
+//# sourceMappingURL=claude-file-change-watcher.d.ts.map