actoviq-agent-sdk 0.3.0 → 0.4.0

package/dist/src/runtime/agentClient.js

@@ -1,7 +1,12 @@
 import path from 'node:path';
+import { execFile as execFileCallback } from 'node:child_process';
+import { mkdir, readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { z } from 'zod';
 import { createActoviqBuddyApi } from '../buddy/actoviqBuddy.js';
 import { createActoviqComputerUseMcpServer, createActoviqComputerUseTools, } from '../computer/actoviqComputerUse.js';
 import { resolveRuntimeConfig } from '../config/resolveRuntimeConfig.js';
+import { resolveActoviqModelReference } from '../config/modelTiers.js';
 import { mergeActoviqHooks, normalizeActoviqHookMessages, resolveActoviqPostRunHooks, resolveActoviqSessionStartHooks, } from '../hooks/actoviqHooks.js';
 import { createActoviqMemoryApi } from '../memory/actoviqMemory.js';
 import { appendMessagesToTranscript } from '../memory/actoviqTranscriptLogger.js';
@@ -14,11 +19,16 @@ import { SessionStore } from '../storage/sessionStore.js';
 import { TeammateStore } from '../storage/teammateStore.js';
 import { ActoviqSwarmApi } from '../swarm/actoviqSwarm.js';
 import { createActoviqFileTools } from '../tools/actoviqFileTools.js';
+import { createGitWorktreeWorkspace, } from '../workspace/actoviqWorkspace.js';
 import { ActoviqAgentsApi, createActoviqTaskTool, summarizeActoviqAgentDefinition, } from './actoviqAgents.js';
+import { getDefaultActoviqAgents } from './defaultActoviqAgents.js';
+import { loadActoviqAgentDefinitions } from './actoviqAgentDefinitions.js';
 import { ActoviqSkillsApi, loadActoviqSkillDefinitions, resolveActoviqSkillPrompt, summarizeActoviqSkillDefinition, } from './actoviqSkills.js';
 import { ActoviqBackgroundTaskManager, ActoviqBackgroundTasksApi, } from './actoviqBackgroundTasks.js';
 import { ActoviqContextApi, ActoviqSlashCommandsApi, } from './actoviqSlashCommands.js';
-import { compactActoviqSession, getPersistedActoviqCompactHistory, getPersistedActoviqCompactState, isActoviqPromptTooLongError, } from './actoviqCompact.js';
+import { compactActoviqSession, getPersistedActoviqCompactHistory, getPersistedActoviqCompactState, isActoviqPromptTooLongError, recordActoviqLoopCompactionsOnSession, trackRecentFile, trackRecentSkill, } from './actoviqCompact.js';
+import { ACTOVIQ_SESSION_PERMISSION_STATE_KEY, getPersistedActoviqSessionPermissionState, serializeActoviqSessionPermissionState, } from './actoviqSessionPermissions.js';
+const RECENT_FILE_TOOL_NAMES = new Set(['Read', 'Write', 'Edit', 'NotebookEdit']);
 import { ActoviqToolsApi, buildActoviqCleanToolCatalog, resolveActoviqCleanToolMetadata, } from './actoviqToolCatalog.js';
 import { WorkflowApi } from '../workflow/workflowBuilder.js';
 import { SessionManager } from './sessionManager.js';
@@ -29,6 +39,7 @@ import { createOpenaiModelApi } from '../provider/openai-model-api.js';
 import { AgentRunStream } from './asyncQueue.js';
 import { executeConversation } from './conversationEngine.js';
 import { asError, createId, deepClone, isRecord, nowIso, truncateText } from './helpers.js';
+import { tool } from './tools.js';
 import { buildInvokedSkillMessages, buildRelevantMemoryMessages, extractTextFromContent, } from './messageUtils.js';
 import { AgentSession } from './agentSession.js';
 const RELEVANT_MEMORY_SESSION_STATE_KEY = '__actoviqRelevantMemoryState';
@@ -38,6 +49,7 @@ const RELEVANT_MEMORY_MAX_SESSION_BYTES = 60 * 1024;
 const DEFAULT_SESSION_MEMORY_MAX_TOKENS = 4_096;
 const DEFAULT_DREAM_MAX_TOKENS = 4_096;
 const MAX_REACTIVE_COMPACT_ATTEMPTS = 3;
+const execFile = promisify(execFileCallback);
 const SESSION_MEMORY_SYSTEM_PROMPT = `You maintain the persistent session-memory markdown file for an ongoing engineering conversation.
 
 Return only the full updated markdown document.
@@ -72,6 +84,13 @@ function cloneAgentDefinition(definition) {
         hooks: cloneHooks(definition.hooks),
         tools: definition.tools ? [...definition.tools] : undefined,
         mcpServers: definition.mcpServers ? deepClone(definition.mcpServers) : undefined,
+        allowedTools: definition.allowedTools ? [...definition.allowedTools] : undefined,
+        disallowedTools: definition.disallowedTools ? [...definition.disallowedTools] : undefined,
+        allowedAgents: definition.allowedAgents ? [...definition.allowedAgents] : undefined,
+        skills: definition.skills ? [...definition.skills] : undefined,
+        requiredMcpServers: definition.requiredMcpServers
+            ? [...definition.requiredMcpServers]
+            : undefined,
     };
 }
 function cloneSkillDefinition(definition) {
@@ -101,6 +120,17 @@ export class AgentSessionsApi {
     get(sessionId) {
         return this.resumeSession(sessionId);
     }
+    resume(sessionId, options = {}) {
+        return this.resumeSession(sessionId, options);
+    }
+    async continueMostRecent(options = {}) {
+        const sessions = await this.store.list();
+        const mostRecent = sessions.find(session => session.status !== 'closed') ?? sessions[0];
+        if (!mostRecent) {
+            throw new Error('No stored sessions are available to resume.');
+        }
+        return this.resumeSession(mostRecent.id, options);
+    }
     delete(sessionId) {
         return this.store.delete(sessionId);
     }
@@ -172,12 +202,41 @@ function getAgentContinuityState(metadata) {
                         count: typeof record.count === 'number' ? record.count : 1,
                         lastInvokedAt: record.lastInvokedAt,
                         lastDescription: typeof record.lastDescription === 'string' ? record.lastDescription : undefined,
+                        lastRunId: typeof record.lastRunId === 'string' ? record.lastRunId : undefined,
+                        lastSessionId: typeof record.lastSessionId === 'string' ? record.lastSessionId : undefined,
+                        lastStatus: record.lastStatus === 'completed' ||
+                            record.lastStatus === 'async_launched' ||
+                            record.lastStatus === 'failed' ||
+                            record.lastStatus === 'cancelled'
+                            ? record.lastStatus
+                            : undefined,
+                        lastTaskId: typeof record.lastTaskId === 'string' ? record.lastTaskId : undefined,
+                        lastTextSummary: typeof record.lastTextSummary === 'string' ? record.lastTextSummary : undefined,
+                        runIds: readStringArray(record.runIds),
+                        sessionIds: readStringArray(record.sessionIds),
+                        taskIds: readStringArray(record.taskIds),
+                        totalRequestCount: typeof record.totalRequestCount === 'number'
+                            ? record.totalRequestCount
+                            : undefined,
+                        totalToolCallCount: typeof record.totalToolCallCount === 'number'
+                            ? record.totalToolCallCount
+                            : undefined,
+                        totalToolErrorCount: typeof record.totalToolErrorCount === 'number'
+                            ? record.totalToolErrorCount
+                            : undefined,
                     },
                 ];
             })
             : [],
     };
 }
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const values = value.filter((entry) => typeof entry === 'string');
+    return values.length > 0 ? values : undefined;
+}
 function mergeDelegatedAgents(existing, pending) {
     const merged = new Map(existing.map(record => [record.name, { ...record }]));
     for (const record of pending) {
@@ -188,15 +247,53 @@ function mergeDelegatedAgents(existing, pending) {
                 count: 1,
                 lastInvokedAt: record.invokedAt,
                 lastDescription: record.description,
+                lastRunId: record.runId,
+                lastSessionId: record.sessionId,
+                lastStatus: record.status,
+                lastTaskId: record.taskId,
+                lastTextSummary: record.textSummary,
+                runIds: record.runId ? [record.runId] : undefined,
+                sessionIds: record.sessionId ? [record.sessionId] : undefined,
+                taskIds: record.taskId ? [record.taskId] : undefined,
+                totalRequestCount: record.requestCount,
+                totalToolCallCount: record.toolCallCount,
+                totalToolErrorCount: record.toolErrorCount,
             });
             continue;
         }
         current.count += 1;
         current.lastInvokedAt = record.invokedAt;
         current.lastDescription = record.description ?? current.lastDescription;
+        current.lastRunId = record.runId ?? current.lastRunId;
+        current.lastSessionId = record.sessionId ?? current.lastSessionId;
+        current.lastStatus = record.status ?? current.lastStatus;
+        current.lastTaskId = record.taskId ?? current.lastTaskId;
+        current.lastTextSummary = record.textSummary ?? current.lastTextSummary;
+        current.runIds = appendUnique(current.runIds, record.runId);
+        current.sessionIds = appendUnique(current.sessionIds, record.sessionId);
+        current.taskIds = appendUnique(current.taskIds, record.taskId);
+        current.totalRequestCount = sumOptional(current.totalRequestCount, record.requestCount);
+        current.totalToolCallCount = sumOptional(current.totalToolCallCount, record.toolCallCount);
+        current.totalToolErrorCount = sumOptional(current.totalToolErrorCount, record.toolErrorCount);
     }
     return [...merged.values()].sort((left, right) => right.lastInvokedAt.localeCompare(left.lastInvokedAt));
 }
+function appendUnique(existing, value) {
+    if (!value) {
+        return existing;
+    }
+    const next = existing ? [...existing] : [];
+    if (!next.includes(value)) {
+        next.push(value);
+    }
+    return next;
+}
+function sumOptional(current, next) {
+    if (next === undefined) {
+        return current;
+    }
+    return (current ?? 0) + next;
+}
 function getInvokedSkillState(metadata) {
     const raw = metadata?.[INVOKED_SKILLS_STATE_KEY];
     if (!Array.isArray(raw)) {
@@ -257,6 +354,8 @@ export class ActoviqAgentClient {
     defaultTools;
     defaultMcpServers;
     hooks;
+    maxSubagentDepth;
+    maxSubagentFanout;
     sessions;
     agents;
     skills;
@@ -273,13 +372,15 @@ export class ActoviqAgentClient {
     agentDefinitions;
     skillDefinitions;
     pendingDelegations = new Map();
+    pendingRuntimeNotifications = new Map();
+    subagentInputQueues = new Map();
     sessionRuntimeOverrides = new Map();
     backgroundTaskManager;
     defaultPermissionMode;
     defaultPermissions;
     defaultClassifier;
     defaultApprover;
-    constructor(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, hooks, agentDefinitions = [], skillDefinitions = [], defaultPermissionMode, defaultPermissions, defaultClassifier, defaultApprover, sessionManagerConfig) {
+    constructor(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, hooks, agentDefinitions = [], skillDefinitions = [], defaultPermissionMode, defaultPermissions, defaultClassifier, defaultApprover, sessionManagerConfig, maxSubagentDepth = 1, maxSubagentFanout = 8) {
         this.config = config;
         this.store = store;
         this.backgroundTaskStore = backgroundTaskStore;
@@ -290,8 +391,10 @@ export class ActoviqAgentClient {
         this.defaultTools = defaultTools;
         this.defaultMcpServers = defaultMcpServers;
         this.hooks = hooks;
+        this.maxSubagentDepth = maxSubagentDepth;
+        this.maxSubagentFanout = maxSubagentFanout;
         this.sessionManager = new SessionManager(this.store, sessionManagerConfig);
-        this.sessions = new AgentSessionsApi(this.store, (sessionId) => this.resumeSession(sessionId), this.sessionManager);
+        this.sessions = new AgentSessionsApi(this.store, (sessionId, options) => this.resumeSession(sessionId, options), this.sessionManager);
         this.agentDefinitions = new Map(agentDefinitions.map(definition => [definition.name, cloneAgentDefinition(definition)]));
         this.skillDefinitions = new Map(skillDefinitions.map(definition => [definition.name, cloneSkillDefinition(definition)]));
         this.backgroundTaskManager = new ActoviqBackgroundTaskManager(this.backgroundTaskStore);
@@ -356,9 +459,23 @@ export class ActoviqAgentClient {
             resumeSession: (sessionId) => this.resumeSession(sessionId),
             getBackgroundTask: (taskId) => this.backgroundTaskManager.get(taskId),
         }, this.teammateStore, this.mailboxStore);
-        if (!this.defaultTools.some(tool => tool.name === 'Task')) {
+        const existingDelegationTool = this.defaultTools.find(tool => tool.name === 'Agent' || tool.name === 'Task');
+        if (!existingDelegationTool) {
             this.defaultTools.unshift(this.createTaskTool());
         }
+        else if (existingDelegationTool.name === 'Task') {
+            existingDelegationTool.aliases = [
+                ...new Set([...(existingDelegationTool.aliases ?? []), 'Agent']),
+            ];
+        }
+        this.replaceDefaultTool(this.createSendMessageTool());
+        this.replaceDefaultTool(this.createBackgroundTaskListTool());
+        this.replaceDefaultTool(this.createBackgroundTaskGetTool());
+        this.replaceDefaultTool(this.createBackgroundTaskStopTool());
+        this.replaceDefaultTool(this.createBackgroundTaskOutputTool());
+        if (this.listSkillDefinitions().length > 0) {
+            this.replaceDefaultTool(this.createSkillRegistryTool());
+        }
     }
     async listToolMetadata(options) {
         return resolveActoviqCleanToolMetadata({
@@ -373,7 +490,7 @@ export class ActoviqAgentClient {
     }
     /** Resolve a tool definition by name from the default tool registry. */
     getTool(name) {
-        return this.defaultTools.find(t => t.name === name);
+        return this.defaultTools.find(t => t.name === name || t.aliases?.includes(name));
     }
     async getToolCatalog(options) {
         return buildActoviqCleanToolCatalog(await this.listToolMetadata(options));
@@ -419,6 +536,13 @@ export class ActoviqAgentClient {
             disableDefaultSkills: options.disableDefaultSkills,
             loadDefaultSkillDirectories: options.loadDefaultSkillDirectories,
         });
+        const loadedAgents = await loadActoviqAgentDefinitions({
+            homeDir: config.homeDir,
+            workDir: config.workDir,
+            agentDirectories: options.agentDirectories,
+            loadDefaultAgentDirectories: options.loadDefaultAgentDirectories,
+        });
+        const agentDefinitions = mergeAgentDefinitions(options.disableDefaultAgents === true ? [] : getDefaultActoviqAgents(), loadedAgents, options.agents ?? []);
         const defaultTools = [...(options.tools ?? [])];
         const defaultMcpServers = [...(options.mcpServers ?? [])];
         if (options.computerUse) {
@@ -430,7 +554,9 @@ export class ActoviqAgentClient {
                 defaultTools.push(...createActoviqComputerUseTools(computerUseOptions));
             }
         }
-        return new ActoviqAgentClient(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, options.hooks, options.agents ?? [], [...loadedSkills, ...(options.skills ?? [])], options.permissionMode, options.permissions, options.classifier, options.approver, options.sessionManager);
+        const client = new ActoviqAgentClient(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, options.hooks, agentDefinitions, [...loadedSkills, ...(options.skills ?? [])], options.permissionMode, options.permissions, options.classifier, options.approver, options.sessionManager, options.maxSubagentDepth, options.maxSubagentFanout);
+        await client.backgroundTaskManager.reconcileInterruptedTasks();
+        return client;
     }
     async run(input, options = {}) {
         const runId = createId();
@@ -491,23 +617,74 @@ export class ActoviqAgentClient {
         return race(tasks, options);
     }
     async createSession(options = {}) {
+        const model = this.resolveModel(options.model);
         const stored = await this.store.create({
+            id: options.id,
             title: options.title,
             systemPrompt: options.systemPrompt ?? this.config.systemPrompt,
-            model: options.model ?? this.config.model,
+            model,
             tags: options.tags,
             metadata: {
-                __actoviqWorkDir: this.config.workDir,
                 ...(options.metadata ?? {}),
+                __actoviqWorkDir: this.config.workDir,
+                ...(options.permissionMode || options.permissions
+                    ? {
+                        [ACTOVIQ_SESSION_PERMISSION_STATE_KEY]: serializeActoviqSessionPermissionState({
+                            mode: options.permissionMode,
+                            permissions: clonePermissionRules(options.permissions) ?? [],
+                        }),
+                    }
+                    : {}),
             },
             initialMessages: options.initialMessages,
         });
         return this.hydrateSession(stored);
     }
-    async resumeSession(sessionId) {
-        const stored = await this.store.load(sessionId);
+    async resumeSession(sessionId, options = {}) {
+        const loaded = options.fork
+            ? await this.store.fork(sessionId, {
+                title: options.title,
+                tags: options.tags,
+                metadata: options.metadata,
+            })
+            : await this.store.load(sessionId);
+        const stored = deepClone(loaded);
+        if (options.model) {
+            stored.model = this.resolveModel(options.model);
+        }
+        if (options.permissionMode !== undefined || options.permissions !== undefined) {
+            const currentPermissionState = getPersistedActoviqSessionPermissionState(stored.metadata);
+            stored.metadata[ACTOVIQ_SESSION_PERMISSION_STATE_KEY] =
+                serializeActoviqSessionPermissionState({
+                    mode: options.permissionMode ?? currentPermissionState.mode,
+                    permissions: options.permissions !== undefined
+                        ? clonePermissionRules(options.permissions) ?? []
+                        : currentPermissionState.permissions,
+                });
+        }
+        if (!options.fork) {
+            if (options.title?.trim()) {
+                stored.title = options.title.trim();
+                stored.titleSource = 'manual';
+            }
+            if (options.tags) {
+                stored.tags = [...options.tags];
+            }
+            if (options.metadata) {
+                stored.metadata = { ...stored.metadata, ...options.metadata };
+            }
+        }
+        stored.status = 'active';
+        stored.lastActiveAt = nowIso();
+        stored.updatedAt = stored.lastActiveAt;
+        await this.store.save(stored);
         return this.hydrateSession(stored);
     }
+    resolveModel(model) {
+        return model
+            ? resolveActoviqModelReference(model, this.config.modelTiers).model
+            : this.config.model;
+    }
     async compactSessionById(sessionId, options = {}) {
         const session = await this.resumeSession(sessionId);
         return this.compactSessionForSession(session, options);
@@ -529,7 +706,28 @@ export class ActoviqAgentClient {
         return this.dream.maybeAutoDream(options);
     }
     async close() {
-        await this.mcpManager.closeAll();
+        const errors = [];
+        try {
+            await this.backgroundTaskManager.cancelAll();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            this.sessionManager.dispose();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await this.mcpManager.closeAll();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'Errors occurred while closing the agent SDK.');
+        }
     }
     listAgentDefinitions() {
         return [...this.agentDefinitions.values()].map(summarizeActoviqAgentDefinition);
@@ -553,6 +751,8 @@ export class ActoviqAgentClient {
                 ...(definition.metadata ?? {}),
                 ...(options.metadata ?? {}),
                 __actoviqAgentDefinition: definition.name,
+                __actoviqAgentMemory: definition.memory,
+                __actoviqAgentSource: definition.source,
                 [AGENT_CONTINUITY_STATE_KEY]: {
                     currentAgent: definition.name,
                     delegatedAgents: [],
@@ -588,16 +788,223 @@ export class ActoviqAgentClient {
     createTaskTool(options = {}) {
         return createActoviqTaskTool({
             ...options,
+            listAgentDefinitions: () => this.listAgentDefinitions(),
             getAgentDefinition: (agent) => this.getAgentDefinition(agent),
-            runAgent: (agent, prompt, runOptions) => this.runWithAgent(agent, prompt, runOptions),
-            onDelegated: ({ subagentType, description, parentSessionId, parentRunId }) => {
+            runAgent: (agent, prompt, runOptions, delegation) => this.runDelegatedAgentTask(agent, prompt, runOptions, delegation),
+            maxDepth: this.maxSubagentDepth,
+            maxFanout: this.maxSubagentFanout,
+            onDelegated: ({ subagentType, description, parentSessionId, parentRunId, runId, sessionId, status, taskId, requestCount, toolCallCount, toolErrorCount, textSummary, }) => {
                 this.recordPendingDelegation(parentSessionId ?? parentRunId, {
                     name: subagentType,
                     description,
                     invokedAt: nowIso(),
+                    runId,
+                    sessionId,
+                    status,
+                    taskId,
+                    requestCount,
+                    toolCallCount,
+                    toolErrorCount,
+                    textSummary,
                 });
             },
-            launchBackgroundAgent: (agent, prompt, backgroundOptions, runOptions) => this.launchBackgroundAgentTask(agent, prompt, backgroundOptions, runOptions),
+            launchBackgroundAgent: (agent, prompt, backgroundOptions, runOptions, delegation) => this.launchBackgroundAgentTask(agent, prompt, backgroundOptions, runOptions, delegation),
+        });
+    }
+    replaceDefaultTool(replacement) {
+        const existingIndex = this.defaultTools.findIndex(tool => tool.name === replacement.name);
+        if (existingIndex >= 0) {
+            this.defaultTools.splice(existingIndex, 1, replacement);
+            return;
+        }
+        this.defaultTools.push(replacement);
+    }
+    createSendMessageTool() {
+        return tool({
+            name: 'SendMessage',
+            description: 'Send a follow-up message to a running or previously completed agent by agent id, task id, session id, or assigned name. Running agents receive it at the next tool boundary; stopped agents resume in the background with full session context.',
+            inputSchema: z.strictObject({
+                to: z.string().min(1).describe('Agent id, task id, session id, or assigned name'),
+                message: z.union([z.string(), z.record(z.string(), z.unknown())]),
+                summary: z.string().optional(),
+            }),
+            isConcurrencySafe: () => true,
+        }, async ({ to, message, summary }, context) => {
+            const text = typeof message === 'string'
+                ? message
+                : JSON.stringify(message);
+            const routed = await this.routeMessageToAgent(to.trim(), text, {
+                parentRunId: context.runId,
+                parentSessionId: context.sessionId,
+                runOptions: {
+                    permissionMode: context.permissionMode,
+                    permissions: context.permissions,
+                    classifier: context.classifier,
+                    approver: context.approver,
+                    hooks: context.hooks,
+                    effort: context.effort,
+                    metadata: context.metadata,
+                },
+            });
+            return {
+                ...routed,
+                summary,
+            };
+        });
+    }
+    /**
+     * Model-facing Skill tool backed by the real skill registry. Loads the
+     * resolved skill content into the conversation as the tool result
+     * (progressive disclosure), instead of the former no-op stub.
+     */
+    createSkillRegistryTool() {
+        return tool({
+            name: 'Skill',
+            description: 'Load a registered skill by name. The skill content (workflow, checklist, or domain knowledge) is returned so you can follow it for the current task.',
+            inputSchema: z.strictObject({
+                skill: z.string().describe('The name of the skill to load'),
+                args: z.string().optional().describe('Optional arguments for the skill'),
+            }),
+            isReadOnly: () => true,
+            prompt: () => {
+                const names = this.listSkillDefinitions()
+                    .filter((definition) => definition.disableModelInvocation !== true)
+                    .map((definition) => definition.description
+                    ? `- ${definition.name}: ${definition.description}`
+                    : `- ${definition.name}`);
+                if (names.length === 0) {
+                    return '';
+                }
+                return [
+                    'Use the Skill tool to load a registered skill when the task matches its description.',
+                    'Available skills:',
+                    ...names,
+                ].join('\n');
+            },
+        }, async ({ skill, args }, context) => {
+            const definition = this.getSkillDefinition(skill);
+            if (!definition || definition.disableModelInvocation === true) {
+                const available = this.listSkillDefinitions()
+                    .filter((entry) => entry.disableModelInvocation !== true)
+                    .map((entry) => entry.name)
+                    .join(', ');
+                throw new Error(`No skill named "${skill}" is registered.${available ? ` Available skills: ${available}.` : ''}`);
+            }
+            const resolved = await resolveActoviqSkillPrompt(definition, args ?? '', {
+                args: args ?? '',
+                workDir: this.config.workDir,
+                homeDir: this.config.homeDir,
+                sessionId: context.sessionId,
+                userId: this.config.userId,
+            });
+            const content = extractTextFromContent(resolved.content);
+            return [
+                `Loaded skill "${definition.name}".`,
+                '',
+                '<skill-content>',
+                content,
+                '</skill-content>',
+                '',
+                'Apply this skill to the current task now.',
+            ].join('\n');
+        });
+    }
+    createBackgroundTaskListTool() {
+        return tool({
+            name: 'TaskList',
+            description: 'List background subagent tasks for the current SDK runtime.',
+            inputSchema: z.strictObject({}),
+            isReadOnly: () => true,
+            serialize: (output) => {
+                if (output.tasks.length === 0) {
+                    return 'No background tasks.';
+                }
+                return output.tasks
+                    .map(task => [
+                    `Task id: ${task.id}`,
+                    `Status: ${task.status}`,
+                    `Subagent: ${task.subagentType}`,
+                    `Description: ${task.description}`,
+                    task.runId ? `Run id: ${task.runId}` : undefined,
+                    task.sessionId ? `Session id: ${task.sessionId}` : undefined,
+                    task.completedAt ? `Completed at: ${task.completedAt}` : undefined,
+                ].filter(Boolean).join('\n'))
+                    .join('\n\n');
+            },
+        }, async () => ({
+            tasks: await this.backgroundTaskManager.list(),
+        }));
+    }
+    createBackgroundTaskGetTool() {
+        return tool({
+            name: 'TaskGet',
+            description: 'Retrieve background subagent task status by ID.',
+            inputSchema: z.strictObject({
+                taskId: z.string().optional().describe('The ID of the task to get'),
+                task_id: z.string().optional().describe('The ID of the task to get'),
+            }).superRefine((input, ctx) => {
+                if (!resolveTaskId(input)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['task_id'],
+                        message: 'Provide `task_id` or `taskId`.',
+                    });
+                }
+            }),
+            isReadOnly: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async (input) => {
+            const taskId = resolveTaskId(input);
+            if (!taskId) {
+                throw new Error('TaskGet requires `task_id` or `taskId`.');
+            }
+            const task = await this.backgroundTaskManager.get(taskId);
+            if (!task) {
+                throw new Error(`No background task with id "${taskId}" exists.`);
+            }
+            return task;
+        });
+    }
+    createBackgroundTaskStopTool() {
+        return tool({
+            name: 'TaskStop',
+            description: 'Stop a running background subagent task.',
+            inputSchema: z.strictObject({
+                task_id: z.string().describe('The ID of the task to stop'),
+            }),
+            isConcurrencySafe: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async ({ task_id }) => {
+            const task = await this.backgroundTaskManager.cancel(task_id);
+            if (!task) {
+                throw new Error(`No background task with id "${task_id}" exists.`);
+            }
+            return task;
+        });
+    }
+    createBackgroundTaskOutputTool() {
+        return tool({
+            name: 'TaskOutput',
+            description: 'Retrieve output from a completed or running background subagent task.',
+            inputSchema: z.strictObject({
+                task_id: z.string().describe('The ID of the task to get output for'),
+                block: z.boolean().optional().describe('Wait for task to complete before returning'),
+                timeout: z.number().int().positive().optional().describe('Max wait time in milliseconds'),
+            }),
+            isReadOnly: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async ({ task_id, block, timeout }, context) => {
+            if (block) {
+                return this.backgroundTaskManager.wait(task_id, {
+                    timeoutMs: timeout,
+                    signal: context.signal,
+                });
+            }
+            const task = await this.backgroundTaskManager.get(task_id);
+            if (!task) {
+                throw new Error(`No background task with id "${task_id}" exists.`);
+            }
+            return task;
         });
     }
     async prepareSkillExecution(skillName, args, options, sessionId) {
@@ -651,12 +1058,30 @@ export class ActoviqAgentClient {
         return session.send(execution.prompt, execution.options);
     }
     async forwardStreamResult(stream, emit) {
+        const errors = [];
         const pump = (async () => {
-            for await (const event of stream) {
-                emit(event);
+            try {
+                for await (const event of stream) {
+                    emit(event);
+                }
+            }
+            catch (error) {
+                errors.push(error);
             }
         })();
-        const [result] = await Promise.all([stream.result, pump]);
+        let result;
+        try {
+            [result] = await Promise.all([stream.result, pump]);
+        }
+        catch (error) {
+            if (errors.length > 0) {
+                throw new AggregateError([error, ...errors], 'Stream result and event pump both failed.');
+            }
+            throw error;
+        }
+        if (errors.length > 0) {
+            throw errors[0];
+        }
         return result;
     }
     getSessionRuntimeOverrides(sessionId) {
@@ -703,14 +1128,19 @@ export class ActoviqAgentClient {
         }
         this.sessionRuntimeOverrides.set(sessionId, next);
     }
-    setSessionRuntimePermissionContext(sessionId, context) {
+    async setSessionRuntimePermissionContext(session, context) {
+        const sessionId = session.id;
         const current = this.sessionRuntimeOverrides.get(sessionId) ?? {};
+        const stored = session.snapshot();
+        const persisted = getPersistedActoviqSessionPermissionState(stored.metadata);
         const next = {
             ...current,
-            permissionMode: context.mode,
-            permissions: clonePermissionRules(context.permissions),
-            classifier: context.classifier,
-            approver: context.approver,
+            permissionMode: context.mode ?? current.permissionMode ?? persisted.mode,
+            permissions: context.permissions !== undefined
+                ? clonePermissionRules(context.permissions)
+                : current.permissions ?? persisted.permissions,
+            classifier: context.classifier ?? current.classifier,
+            approver: context.approver ?? current.approver,
         };
         if (isHooksEmpty(next.hooks) &&
             !next.permissionMode &&
@@ -718,27 +1148,42 @@ export class ActoviqAgentClient {
             !next.classifier &&
             !next.approver) {
             this.sessionRuntimeOverrides.delete(sessionId);
-            return;
         }
-        this.sessionRuntimeOverrides.set(sessionId, next);
+        else {
+            this.sessionRuntimeOverrides.set(sessionId, next);
+        }
+        stored.metadata[ACTOVIQ_SESSION_PERMISSION_STATE_KEY] =
+            serializeActoviqSessionPermissionState({
+                mode: next.permissionMode,
+                permissions: clonePermissionRules(next.permissions) ?? [],
+            });
+        stored.updatedAt = nowIso();
+        await this.store.save(stored);
+        return stored;
     }
-    clearSessionRuntimePermissionContext(sessionId) {
+    async clearSessionRuntimePermissionContext(session) {
+        const sessionId = session.id;
         const current = this.sessionRuntimeOverrides.get(sessionId);
-        if (!current) {
-            return;
-        }
-        const next = {
-            ...current,
-            permissionMode: undefined,
-            permissions: undefined,
-            classifier: undefined,
-            approver: undefined,
-        };
-        if (isHooksEmpty(next.hooks)) {
-            this.sessionRuntimeOverrides.delete(sessionId);
-            return;
+        if (current) {
+            const next = {
+                ...current,
+                permissionMode: undefined,
+                permissions: undefined,
+                classifier: undefined,
+                approver: undefined,
+            };
+            if (isHooksEmpty(next.hooks)) {
+                this.sessionRuntimeOverrides.delete(sessionId);
+            }
+            else {
+                this.sessionRuntimeOverrides.set(sessionId, next);
+            }
         }
-        this.sessionRuntimeOverrides.set(sessionId, next);
+        const stored = session.snapshot();
+        delete stored.metadata[ACTOVIQ_SESSION_PERMISSION_STATE_KEY];
+        stored.updatedAt = nowIso();
+        await this.store.save(stored);
+        return stored;
     }
     applySessionRuntimeOverrides(sessionId, options) {
         const overrides = this.getSessionRuntimeOverrides(sessionId);
@@ -755,6 +1200,16 @@ export class ActoviqAgentClient {
         };
     }
     hydrateSession(stored) {
+        const persistedPermissionState = getPersistedActoviqSessionPermissionState(stored.metadata);
+        if (persistedPermissionState.mode ||
+            persistedPermissionState.permissions.length > 0) {
+            const current = this.sessionRuntimeOverrides.get(stored.id) ?? {};
+            this.sessionRuntimeOverrides.set(stored.id, {
+                ...current,
+                permissionMode: current.permissionMode ?? persistedPermissionState.mode,
+                permissions: current.permissions ?? persistedPermissionState.permissions,
+            });
+        }
         return new AgentSession({
             runSession: (session, input, options) => this.runOnSession(session, input, options),
             streamSession: (session, input, options) => this.streamOnSession(session, input, options),
@@ -775,8 +1230,9 @@ export class ActoviqAgentClient {
             getAgentContinuity: (session) => this.getAgentContinuityForSession(session),
             setRuntimeHooks: (session, hooks) => this.setSessionRuntimeHooks(session.id, hooks),
             clearRuntimeHooks: (session) => this.clearSessionRuntimeHooks(session.id),
-            setRuntimePermissionContext: (session, context) => this.setSessionRuntimePermissionContext(session.id, context),
-            clearRuntimePermissionContext: (session) => this.clearSessionRuntimePermissionContext(session.id),
+            setModel: (session, model) => this.setSessionModel(session, model),
+            setRuntimePermissionContext: (session, context) => this.setSessionRuntimePermissionContext(session, context),
+            clearRuntimePermissionContext: (session) => this.clearSessionRuntimePermissionContext(session),
             hydrate: (next) => this.hydrateSession(next),
             saveCheckpoint: (_session, label) => this.store.saveCheckpoint(stored.id, label),
             restoreCheckpoint: (session, checkpointId) => this.restoreCheckpointToSession(session, checkpointId),
@@ -784,6 +1240,13 @@ export class ActoviqAgentClient {
             deleteCheckpoint: (_session, checkpointId) => this.store.deleteCheckpoint(stored.id, checkpointId),
         }, this.store, stored);
     }
+    async setSessionModel(session, model) {
+        const next = session.snapshot();
+        next.model = this.resolveModel(model);
+        next.updatedAt = nowIso();
+        await this.store.save(next);
+        return next;
+    }
     async restoreCheckpointToSession(session, checkpointId) {
         const checkpoint = await this.store.loadCheckpoint(session.id, checkpointId);
         session.replace(checkpoint.snapshot);
@@ -886,13 +1349,30 @@ export class ActoviqAgentClient {
             ...(augmentations?.metadata ?? {}),
             ...(options.metadata ?? {}),
         };
-        const mergedTools = mergeUniqueByName(options.__actoviqUseDefaultTools === false ? [] : this.defaultTools, options.tools ?? []);
+        const workDir = options.__actoviqWorkDir ?? options.workDir ?? this.config.workDir;
+        const mergedTools = filterAgentTools(mergeUniqueByName(options.__actoviqUseDefaultTools === false ? [] : this.defaultTools, options.tools ?? []), options.__actoviqAllowedTools, options.__actoviqDisallowedTools);
         // Collect tool prompts for system prompt assembly
         const toolPromptParts = await collectToolPrompts(mergedTools, {
-            workDir: this.config.workDir,
+            workDir,
             permissionMode: options.permissionMode ?? this.defaultPermissionMode,
         });
         const systemPrompt = await this.resolveSystemPrompt(options, session, [...(augmentations?.systemPromptParts ?? []), ...toolPromptParts]);
+        const runtimeConfig = options.__actoviqMaxToolIterations || workDir !== this.config.workDir
+            ? {
+                ...this.config,
+                workDir,
+                ...(options.__actoviqMaxToolIterations
+                    ? { maxToolIterations: options.__actoviqMaxToolIterations }
+                    : {}),
+            }
+            : this.config;
+        const notificationKey = session?.id ?? runId;
+        const drainQueuedInputs = notificationKey || options.drainQueuedInputs
+            ? () => [
+                ...(options.drainQueuedInputs?.() ?? []),
+                ...this.drainRuntimeNotifications(notificationKey),
+            ]
+            : undefined;
         return executeConversation({
             runId,
             input,
@@ -902,9 +1382,10 @@ export class ActoviqAgentClient {
             systemPrompt,
             tools: mergedTools,
             mcpServers: mergeUniqueByName(options.__actoviqUseDefaultMcpServers === false ? [] : this.defaultMcpServers, options.mcpServers ?? []),
-            model: options.model ?? session?.model ?? this.config.model,
+            model: this.resolveModel(options.model ?? session?.model),
             maxTokens: options.maxTokens,
             temperature: options.temperature,
+            effort: options.effort,
             toolChoice: options.toolChoice,
             userId: options.userId ?? this.config.userId,
             metadata,
@@ -915,11 +1396,12 @@ export class ActoviqAgentClient {
             approver: options.approver ?? this.defaultApprover,
             canUseTool: options.canUseTool,
             hooks: augmentations?.hooks,
+            drainQueuedInputs,
             streaming,
             emit,
             skipRunStartedEvent,
             modelApi: this.modelApi,
-            config: this.config,
+            config: runtimeConfig,
             mcpManager: this.mcpManager,
         }).then(result => ({
             ...result,
@@ -979,11 +1461,32 @@ export class ActoviqAgentClient {
         return promptParts.join('\n\n');
     }
     async prepareRunAugmentations(runId, input, options, session) {
+        const internalOptions = options;
         const promptText = typeof input === 'string' ? input : extractTextFromContent(input);
         const memoryContext = await this.prepareRelevantMemoryContext(input, session);
         const invokedSkillContext = this.prepareInvokedSkillContext(session);
+        const notificationMessages = session
+            ? (await this.collectPendingTaskNotifications(session.id)).map(text => ({
+                role: 'user',
+                content: text,
+            }))
+            : [];
+        const initialPromptMessages = internalOptions.__actoviqInitialPrompt
+            ? [{
+                    role: 'user',
+                    content: internalOptions.__actoviqInitialPrompt,
+                }]
+            : [];
+        const agentMemoryMessages = session
+            ? await this.prepareAgentMemoryMessages(session, internalOptions)
+            : [];
+        const preloadedSkillMessages = await this.preparePreloadedAgentSkillMessages(internalOptions.__actoviqPreloadedSkills, session?.id, internalOptions.__actoviqWorkDir ?? internalOptions.workDir ?? this.config.workDir);
         const hooks = mergeActoviqHooks(this.hooks, options.hooks);
         const prefixedMessages = [
+            ...notificationMessages,
+            ...initialPromptMessages,
+            ...agentMemoryMessages,
+            ...preloadedSkillMessages,
             ...invokedSkillContext.prefixedMessages,
             ...memoryContext.prefixedMessages,
         ];
@@ -996,7 +1499,7 @@ export class ActoviqAgentClient {
                 promptText,
                 sessionId: session?.id,
                 session: session ? deepClone(session) : undefined,
-                workDir: this.config.workDir,
+                workDir: internalOptions.__actoviqWorkDir ?? internalOptions.workDir ?? this.config.workDir,
                 options,
             });
             if (!result) {
@@ -1019,6 +1522,70 @@ export class ActoviqAgentClient {
             metadata,
         };
     }
+    async preparePreloadedAgentSkillMessages(skillNames, sessionId, workDir) {
+        if (!skillNames?.length) {
+            return [];
+        }
+        const messages = [];
+        for (const skillName of skillNames) {
+            const definition = this.getSkillDefinition(skillName);
+            if (!definition) {
+                messages.push({
+                    role: 'user',
+                    content: `<agent_skill_warning>Skill "${skillName}" was requested by the agent definition but is not registered.</agent_skill_warning>`,
+                });
+                continue;
+            }
+            const resolved = await resolveActoviqSkillPrompt(definition, '', {
+                args: '',
+                workDir,
+                homeDir: this.config.homeDir,
+                sessionId,
+                userId: this.config.userId,
+            });
+            messages.push({
+                role: 'user',
+                content: [
+                    `<agent_skill name="${skillName}">`,
+                    extractTextFromContent(resolved.content),
+                    '</agent_skill>',
+                ].join('\n'),
+            });
+        }
+        return messages;
+    }
+    async prepareAgentMemoryMessages(session, options) {
+        const scope = session.metadata.__actoviqAgentMemory;
+        const agentName = session.metadata.__actoviqAgentDefinition;
+        if ((scope !== 'user' && scope !== 'project' && scope !== 'local') ||
+            typeof agentName !== 'string') {
+            return [];
+        }
+        const workDir = options.__actoviqWorkDir ?? options.workDir ?? this.config.workDir;
+        const root = scope === 'user'
+            ? path.join(this.config.homeDir, 'agent-memory', agentName)
+            : scope === 'project'
+                ? path.join(workDir, '.actoviq', 'agent-memory', agentName)
+                : path.join(workDir, '.actoviq', 'agent-memory-local', agentName);
+        const memoryPath = path.join(root, 'MEMORY.md');
+        await mkdir(root, { recursive: true });
+        let content = '';
+        try {
+            content = await readFile(memoryPath, 'utf8');
+        }
+        catch {
+            // A new agent memory starts empty and can be updated by normal file tools.
+        }
+        return [{
+                role: 'user',
+                content: [
+                    `<agent_memory scope="${scope}" path="${memoryPath}">`,
+                    content.trim() || '(empty)',
+                    '</agent_memory>',
+                    `Persist durable lessons for future ${agentName} runs by updating ${memoryPath}.`,
+                ].join('\n'),
+            }];
+    }
     async applyPostRunHooks(runId, input, options, result, session) {
         const promptText = typeof input === 'string' ? input : extractTextFromContent(input);
         const hooks = mergeActoviqHooks(this.hooks, options.hooks);
@@ -1031,7 +1598,9 @@ export class ActoviqAgentClient {
                 promptText,
                 sessionId: session?.id,
                 session: session ? deepClone(session) : undefined,
-                workDir: this.config.workDir,
+                workDir: options.__actoviqWorkDir ??
+                    options.workDir ??
+                    this.config.workDir,
                 options,
                 result,
             });
@@ -1057,6 +1626,27 @@ export class ActoviqAgentClient {
         existing.push(record);
         this.pendingDelegations.set(key, existing);
     }
+    updatePendingDelegation(key, task) {
+        const records = this.pendingDelegations.get(key);
+        const record = records?.find(candidate => candidate.taskId === task.id);
+        if (!record) {
+            return;
+        }
+        record.runId = task.runId ?? record.runId;
+        record.sessionId = task.sessionId ?? record.sessionId;
+        record.status =
+            task.status === 'completed'
+                ? 'completed'
+                : task.status === 'failed'
+                    ? 'failed'
+                    : task.status === 'cancelled'
+                        ? 'cancelled'
+                        : record.status;
+        record.requestCount = task.requestCount ?? record.requestCount;
+        record.toolCallCount = task.toolCallCount ?? record.toolCallCount;
+        record.toolErrorCount = task.toolErrorCount ?? record.toolErrorCount;
+        record.textSummary = task.text ?? task.partialText ?? record.textSummary;
+    }
     consumePendingDelegations(key) {
         if (!key) {
             return [];
@@ -1157,6 +1747,9 @@ export class ActoviqAgentClient {
             latestBoundary,
             compactCount: Math.max(compactState.compactCount, persistedCompactState.compactCount),
             microcompactCount: Math.max(compactState.microcompactCount, persistedCompactState.microcompactCount),
+            consecutiveCompactFailures: persistedCompactState.consecutiveFailures,
+            lastCompactFailureAt: persistedCompactState.lastFailureAt,
+            lastCompactError: persistedCompactState.lastError,
             hasCompacted: compactState.hasCompacted ||
                 persistedCompactState.compactCount + persistedCompactState.microcompactCount > 0,
             summaryMessage: compactState.summaryMessage ?? persistedCompactState.lastSummaryMessage,
@@ -1185,12 +1778,16 @@ export class ActoviqAgentClient {
         }, {
             workDir: this.config.workDir,
             systemPrompt: snapshot.systemPrompt ?? this.config.systemPrompt,
-            model: options.model ?? snapshot.model ?? this.config.model,
+            model: this.resolveModel(options.model ?? snapshot.model),
             modelApi: this.modelApi,
             compactConfig: this.config.compact,
             runtimeState: this.getSessionMemoryRuntimeState(snapshot),
         });
-        if (reactive.session === snapshot) {
+        if (!reactive.result.compacted) {
+            if (reactive.session !== snapshot) {
+                await this.store.save(reactive.session);
+                session.replace(reactive.session);
+            }
             return undefined;
         }
         await this.store.save(reactive.session);
@@ -1208,48 +1805,239 @@ export class ActoviqAgentClient {
             result: reactive.result,
         };
     }
-    async launchBackgroundAgentTask(agent, prompt, options, runOptions = {}) {
+    async runDelegatedAgentTask(agent, prompt, runOptions = {}, delegation = { description: prompt }) {
         const definition = this.requireAgentDefinition(agent);
-        const session = await this.createAgentSession(agent, {
-            title: `${definition.name}: ${truncateText(prompt, 80)}`,
+        const prepared = await this.prepareDelegatedWorkspace(definition, delegation);
+        try {
+            const session = await this.createAgentSession(agent, {
+                title: `${delegation.name ?? definition.name}: ${truncateText(delegation.description, 80)}`,
+                metadata: {
+                    __actoviqAgentName: delegation.name,
+                    __actoviqAgentWorkDir: prepared.workDir,
+                    __actoviqAgentWorktreePath: prepared.workspace?.path,
+                    __actoviqAgentWorktreeBranch: prepared.workspace?.metadata.branch,
+                },
+            });
+            const result = await session.send(prompt, this.prepareDelegatedRunOptions(runOptions, prepared.workDir, session.id));
+            const retained = await this.finalizeDelegatedWorkspace(prepared.workspace);
+            return {
+                result,
+                sessionId: session.id,
+                worktreePath: retained ? prepared.workspace?.path : undefined,
+                worktreeBranch: retained ? prepared.workspace?.metadata.branch : undefined,
+            };
+        }
+        catch (error) {
+            await this.finalizeDelegatedWorkspace(prepared.workspace);
+            throw error;
+        }
+    }
+    async routeMessageToAgent(address, message, context) {
+        const tasks = await this.backgroundTaskManager.list();
+        const task = tasks.find(candidate => candidate.id === address ||
+            candidate.sessionId === address ||
+            candidate.agentName === address);
+        if (task?.sessionId && (task.status === 'queued' || task.status === 'running')) {
+            const queue = this.subagentInputQueues.get(task.sessionId) ?? [];
+            queue.push(message);
+            this.subagentInputQueues.set(task.sessionId, queue);
+            await this.backgroundTaskManager.updateProgress(task.id, {
+                queuedMessageCount: queue.length,
+                progressSummary: `Queued follow-up message for ${task.agentName ?? task.subagentType}.`,
+            });
+            return {
+                status: 'queued',
+                taskId: task.id,
+                agentId: task.sessionId,
+                agentName: task.agentName,
+            };
+        }
+        const sessionId = task?.sessionId ?? address;
+        let session;
+        try {
+            session = await this.resumeSession(sessionId);
+        }
+        catch {
+            throw new Error(`No addressable agent found for "${address}".`);
+        }
+        const agentName = typeof session.metadata.__actoviqAgentDefinition === 'string'
+            ? session.metadata.__actoviqAgentDefinition
+            : task?.subagentType;
+        if (!agentName) {
+            throw new Error(`Session "${sessionId}" is not an agent session.`);
+        }
+        const resumed = await this.launchBackgroundOnSession(session, agentName, message, {
+            parentRunId: context.parentRunId,
+            parentSessionId: context.parentSessionId,
+        }, context.runOptions, {
+            description: `Continue ${task?.agentName ?? agentName}`,
+            name: task?.agentName,
+            cwd: typeof session.metadata.__actoviqAgentWorkDir === 'string'
+                ? session.metadata.__actoviqAgentWorkDir
+                : undefined,
+        }, task?.id);
+        return {
+            status: 'resumed',
+            taskId: resumed.id,
+            agentId: session.id,
+            agentName: task?.agentName,
+        };
+    }
+    async prepareDelegatedWorkspace(definition, delegation) {
+        if (delegation.cwd) {
+            return { workDir: path.resolve(delegation.cwd) };
+        }
+        if ((delegation.isolation ?? definition.isolation) !== 'worktree') {
+            return { workDir: path.resolve(definition.cwd ?? this.config.workDir) };
+        }
+        const branch = `actoviq-agent-${createId().slice(0, 8)}`;
+        const workspace = await createGitWorktreeWorkspace({
+            repositoryPath: this.config.workDir,
+            name: delegation.name
+                ? `actoviq-${sanitizeWorkspaceName(delegation.name)}-${createId().slice(0, 6)}`
+                : undefined,
+            branch,
             metadata: {
-                __actoviqBackgroundParentRunId: options.parentRunId,
-                __actoviqBackgroundParentSessionId: options.parentSessionId,
+                agent: definition.name,
             },
         });
-        if (runOptions.hooks) {
-            session.setHooks(runOptions.hooks);
+        return { workDir: workspace.path, workspace };
+    }
+    prepareDelegatedRunOptions(runOptions, workDir, sessionId) {
+        return {
+            ...runOptions,
+            workDir,
+            tools: [
+                ...createActoviqFileTools({ cwd: workDir }),
+                ...(runOptions.tools ?? []),
+            ],
+            drainQueuedInputs: () => [
+                ...(runOptions.drainQueuedInputs?.() ?? []),
+                ...this.drainSubagentInputs(sessionId),
+            ],
+        };
+    }
+    async finalizeDelegatedWorkspace(workspace) {
+        if (!workspace) {
+            return false;
         }
-        if (runOptions.permissionMode ||
-            runOptions.permissions ||
-            runOptions.classifier ||
-            runOptions.approver) {
-            session.setPermissionContext({
-                mode: runOptions.permissionMode,
-                permissions: runOptions.permissions,
-                classifier: runOptions.classifier,
-                approver: runOptions.approver,
-            });
+        const dirty = await isGitWorkspaceDirty(workspace.path);
+        if (!dirty) {
+            await workspace.dispose();
+            return false;
         }
-        return this.backgroundTaskManager.launch({
-            subagentType: definition.name,
-            description: prompt,
-            workDir: this.config.workDir,
-            parentRunId: options.parentRunId,
-            parentSessionId: options.parentSessionId,
-            onRun: async (signal) => {
-                const result = await session.send(prompt, { signal });
-                return {
-                    runId: result.runId,
-                    sessionId: session.id,
-                    model: result.model,
-                    text: result.text,
-                    toolCallCount: result.toolCalls.length,
-                };
-            },
+        return true;
+    }
+    drainSubagentInputs(sessionId) {
+        const queued = this.subagentInputQueues.get(sessionId) ?? [];
+        this.subagentInputQueues.delete(sessionId);
+        return queued;
+    }
+    async collectPendingTaskNotifications(parentSessionId) {
+        this.pendingRuntimeNotifications.delete(parentSessionId);
+        const notifications = [];
+        for (const task of await this.backgroundTaskManager.list()) {
+            if (task.parentSessionId !== parentSessionId ||
+                task.notificationDeliveredAt ||
+                (task.status !== 'completed' &&
+                    task.status !== 'failed' &&
+                    task.status !== 'cancelled')) {
+                continue;
+            }
+            notifications.push(formatTaskNotification(task));
+            await this.markTaskNotificationDelivered(task.id);
+        }
+        return notifications;
+    }
+    enqueueTaskNotification(task) {
+        const notificationKey = task.parentSessionId ?? task.parentRunId;
+        if (!notificationKey || task.notificationDeliveredAt) {
+            return;
+        }
+        const queue = this.pendingRuntimeNotifications.get(notificationKey) ?? [];
+        if (!queue.some(entry => entry.taskId === task.id)) {
+            queue.push({ taskId: task.id, text: formatTaskNotification(task) });
+            this.pendingRuntimeNotifications.set(notificationKey, queue);
+        }
+    }
+    drainRuntimeNotifications(sessionId) {
+        const queued = this.pendingRuntimeNotifications.get(sessionId) ?? [];
+        this.pendingRuntimeNotifications.delete(sessionId);
+        for (const entry of queued) {
+            void this.markTaskNotificationDelivered(entry.taskId);
+        }
+        return queued.map(entry => entry.text);
+    }
+    async markTaskNotificationDelivered(taskId) {
+        const task = await this.backgroundTaskManager.get(taskId);
+        if (!task || task.notificationDeliveredAt) {
+            return;
+        }
+        await this.backgroundTaskStore.save({
+            ...task,
+            notificationDeliveredAt: nowIso(),
+            updatedAt: nowIso(),
         });
     }
-    async launchBackgroundOnSession(session, agent, prompt, options, runOptions = {}) {
+    async launchBackgroundAgentTask(agent, prompt, options, runOptions = {}, delegation = { description: prompt }) {
+        const definition = this.requireAgentDefinition(agent);
+        const prepared = await this.prepareDelegatedWorkspace(definition, delegation);
+        try {
+            const session = await this.createAgentSession(agent, {
+                title: `${delegation.name ?? definition.name}: ${truncateText(delegation.description, 80)}`,
+                metadata: {
+                    __actoviqBackgroundParentRunId: options.parentRunId,
+                    __actoviqBackgroundParentSessionId: options.parentSessionId,
+                    __actoviqAgentName: delegation.name,
+                    __actoviqAgentWorkDir: prepared.workDir,
+                    __actoviqAgentWorktreePath: prepared.workspace?.path,
+                    __actoviqAgentWorktreeBranch: prepared.workspace?.metadata.branch,
+                },
+            });
+            if (runOptions.hooks) {
+                session.setHooks(runOptions.hooks);
+            }
+            if (runOptions.permissionMode ||
+                runOptions.permissions ||
+                runOptions.classifier ||
+                runOptions.approver) {
+                await session.setPermissionContext({
+                    mode: runOptions.permissionMode,
+                    permissions: runOptions.permissions,
+                    classifier: runOptions.classifier,
+                    approver: runOptions.approver,
+                });
+            }
+            return this.backgroundTaskManager.launch({
+                subagentType: definition.name,
+                description: delegation.description,
+                workDir: prepared.workDir,
+                parentRunId: options.parentRunId,
+                parentSessionId: options.parentSessionId,
+                sessionId: session.id,
+                agentName: delegation.name,
+                worktreePath: prepared.workspace?.path,
+                worktreeBranch: prepared.workspace?.metadata.branch,
+                onRun: (signal, updateProgress) => this.runBackgroundAgentSession({
+                    session,
+                    prompt,
+                    signal,
+                    updateProgress,
+                    runOptions: this.prepareDelegatedRunOptions(runOptions, prepared.workDir, session.id),
+                    workspace: prepared.workspace,
+                }),
+                onSettled: task => {
+                    this.updatePendingDelegation(options.parentSessionId ?? options.parentRunId, task);
+                    this.enqueueTaskNotification(task);
+                },
+            });
+        }
+        catch (error) {
+            await this.finalizeDelegatedWorkspace(prepared.workspace);
+            throw error;
+        }
+    }
+    async launchBackgroundOnSession(session, agent, prompt, options, runOptions = {}, delegation = { description: prompt }, resumedFromTaskId) {
         const definition = this.requireAgentDefinition(agent);
         if (runOptions.hooks) {
             session.setHooks(runOptions.hooks);
@@ -1258,7 +2046,7 @@ export class ActoviqAgentClient {
             runOptions.permissions ||
             runOptions.classifier ||
             runOptions.approver) {
-            session.setPermissionContext({
+            await session.setPermissionContext({
                 mode: runOptions.permissionMode,
                 permissions: runOptions.permissions,
                 classifier: runOptions.classifier,
@@ -1267,32 +2055,82 @@ export class ActoviqAgentClient {
         }
         return this.backgroundTaskManager.launch({
             subagentType: definition.name,
-            description: prompt,
-            workDir: this.config.workDir,
+            description: delegation.description,
+            workDir: delegation.cwd ?? this.config.workDir,
             parentRunId: options.parentRunId,
             parentSessionId: options.parentSessionId ?? session.id,
-            onRun: async (signal) => {
-                const result = await session.send(prompt, { signal });
-                return {
-                    runId: result.runId,
-                    sessionId: session.id,
-                    model: result.model,
-                    text: result.text,
-                    toolCallCount: result.toolCalls.length,
-                };
+            sessionId: session.id,
+            agentName: delegation.name,
+            resumedFromTaskId,
+            onRun: (signal, updateProgress) => this.runBackgroundAgentSession({
+                session,
+                prompt,
+                signal,
+                updateProgress,
+                runOptions: this.prepareDelegatedRunOptions(runOptions, delegation.cwd ?? this.config.workDir, session.id),
+            }),
+            onSettled: task => {
+                this.updatePendingDelegation(options.parentSessionId ?? options.parentRunId, task);
+                this.enqueueTaskNotification(task);
             },
         });
     }
+    async runBackgroundAgentSession(args) {
+        try {
+            await args.updateProgress({
+                progressSummary: 'Agent is running.',
+            });
+            const result = await args.session.send(args.prompt, {
+                ...args.runOptions,
+                signal: args.signal,
+            });
+            await args.updateProgress({
+                partialText: result.text,
+                requestCount: result.requests.length,
+                toolCallCount: result.toolCalls.length,
+                toolErrorCount: result.toolCalls.filter(call => call.isError).length,
+                currentIteration: result.requests.at(-1)?.iteration,
+                currentToolName: undefined,
+                progressSummary: 'Agent completed.',
+            });
+            const retainedWorktree = await this.finalizeDelegatedWorkspace(args.workspace);
+            return {
+                runId: result.runId,
+                sessionId: args.session.id,
+                model: result.model,
+                text: result.text,
+                toolCallCount: result.toolCalls.length,
+                toolErrorCount: result.toolCalls.filter(call => call.isError).length,
+                requestCount: result.requests.length,
+                retainedWorktree,
+                worktreePath: retainedWorktree ? args.workspace?.path : undefined,
+                worktreeBranch: retainedWorktree ? args.workspace?.metadata.branch : undefined,
+            };
+        }
+        catch (error) {
+            await args.updateProgress({
+                progressSummary: args.signal.aborted
+                    ? 'Agent stopped before completion.'
+                    : 'Agent failed before completion.',
+            });
+            await this.finalizeDelegatedWorkspace(args.workspace);
+            throw error;
+        }
+        finally {
+            this.subagentInputQueues.delete(args.session.id);
+        }
+    }
     async compactSessionForSession(session, options = {}) {
         const snapshot = session.snapshot();
         const { session: compactedSession, result } = await compactActoviqSession(snapshot, {
             ...options,
+            model: options.model ? this.resolveModel(options.model) : undefined,
             force: options.force ?? true,
             trigger: 'manual',
         }, {
             workDir: this.config.workDir,
             systemPrompt: snapshot.systemPrompt ?? this.config.systemPrompt,
-            model: snapshot.model ?? this.config.model,
+            model: this.resolveModel(snapshot.model),
             modelApi: this.modelApi,
             compactConfig: this.config.compact,
             runtimeState: this.getSessionMemoryRuntimeState(snapshot),
@@ -1313,7 +2151,7 @@ export class ActoviqAgentClient {
                 systemPrompt: await this.buildDreamSystemPrompt(),
                 tools: createActoviqFileTools({ cwd: this.config.workDir }),
                 mcpServers: [],
-                model: request.model ?? this.config.model,
+                model: this.resolveModel(request.model),
                 maxTokens: request.maxTokens ?? DEFAULT_DREAM_MAX_TOKENS,
                 userId: this.config.userId,
                 metadata: {
@@ -1527,7 +2365,7 @@ export class ActoviqAgentClient {
         const stored = session.snapshot();
         const extraction = await this.performSessionMemoryExtraction(stored, {
             force: options.force ?? true,
-            model: options.model ?? stored.model ?? this.config.model,
+            model: this.resolveModel(options.model ?? stored.model),
             systemPrompt: stored.systemPrompt ?? this.config.systemPrompt,
             trigger: 'manual',
             maxTokens: options.maxTokens,
@@ -1549,6 +2387,9 @@ export class ActoviqAgentClient {
             ...(options.metadata ?? {}),
             ...(hookOutcome.sessionMetadata ?? {}),
         };
+        if (result.loopCompactions?.length) {
+            recordActoviqLoopCompactionsOnSession(next, result.loopCompactions);
+        }
         const runtimeState = this.getSessionMemoryRuntimeState(next);
         if (runtimeState.pendingPostCompaction) {
             runtimeState.pendingPostCompaction = false;
@@ -1575,6 +2416,30 @@ export class ActoviqAgentClient {
             next.metadata[INVOKED_SKILLS_STATE_KEY] = invokedSkills;
             result.invokedSkills = invokedSkills;
         }
+        // Track recently touched files and skills so post-compact context
+        // reminders can point the model back to its working set.
+        for (const call of result.toolCalls) {
+            if (call.isError) {
+                continue;
+            }
+            const callInput = call.input;
+            if (RECENT_FILE_TOOL_NAMES.has(call.publicName)) {
+                const filePath = typeof callInput?.file_path === 'string'
+                    ? callInput.file_path
+                    : typeof callInput?.notebook_path === 'string'
+                        ? callInput.notebook_path
+                        : undefined;
+                if (filePath) {
+                    trackRecentFile(next, filePath);
+                }
+            }
+            if (call.publicName === 'Skill' && typeof callInput?.skill === 'string') {
+                trackRecentSkill(next, callInput.skill);
+            }
+        }
+        for (const record of result.invokedSkills ?? []) {
+            trackRecentSkill(next, record.name);
+        }
         const previousRelevantMemoryState = getRelevantMemorySessionState(next.metadata);
         const surfacedPaths = new Set(previousRelevantMemoryState.surfacedPaths);
         let totalBytes = previousRelevantMemoryState.totalBytes;
@@ -1618,7 +2483,7 @@ export class ActoviqAgentClient {
             await appendMessagesToTranscript(paths.projectStateDir, session.id, this.config.workDir, newMessages);
         }
         const extraction = await this.performSessionMemoryExtraction(next, {
-            model: options.model ?? next.model ?? this.config.model,
+            model: this.resolveModel(options.model ?? next.model),
             systemPrompt: next.systemPrompt ?? this.config.systemPrompt,
             trigger: 'auto',
             maxTokens: Math.min(options.maxTokens ?? this.config.maxTokens, DEFAULT_SESSION_MEMORY_MAX_TOKENS),
@@ -1628,7 +2493,7 @@ export class ActoviqAgentClient {
         const compacted = await compactActoviqSession(next, { trigger: 'auto' }, {
             workDir: this.config.workDir,
             systemPrompt: next.systemPrompt ?? this.config.systemPrompt,
-            model: options.model ?? next.model ?? this.config.model,
+            model: this.resolveModel(options.model ?? next.model),
             modelApi: this.modelApi,
             compactConfig: this.config.compact,
             runtimeState: extraction.state,
@@ -1674,10 +2539,22 @@ export class ActoviqAgentClient {
         return this.mergeAgentRunOptions(this.requireAgentDefinition(agentName), options);
     }
     mergeAgentRunOptions(definition, options) {
+        const availableMcpServers = new Set([
+            ...this.defaultMcpServers.map(server => server.name),
+            ...(definition.mcpServers ?? []).map(server => server.name),
+            ...(options.mcpServers ?? []).map(server => server.name),
+        ]);
+        const missingMcpServers = (definition.requiredMcpServers ?? []).filter(server => !availableMcpServers.has(server));
+        if (missingMcpServers.length > 0) {
+            throw new Error(`Agent "${definition.name}" requires unavailable MCP servers: ${missingMcpServers.join(', ')}.`);
+        }
+        const nestedAgentDenylist = definition.allowNestedAgents === true ? [] : ['Agent', 'Task'];
         return {
             ...options,
             systemPrompt: joinPromptParts(definition.systemPrompt, options.systemPrompt),
             model: options.model ?? definition.model,
+            effort: options.effort ?? definition.effort,
+            permissionMode: options.permissionMode ?? definition.permissionMode,
             metadata: {
                 ...(definition.metadata ?? {}),
                 ...(options.metadata ?? {}),
@@ -1688,6 +2565,19 @@ export class ActoviqAgentClient {
             mcpServers: [...(definition.mcpServers ?? []), ...(options.mcpServers ?? [])],
             __actoviqUseDefaultTools: definition.inheritDefaultTools !== false,
             __actoviqUseDefaultMcpServers: definition.inheritDefaultMcpServers !== false,
+            __actoviqMaxToolIterations: definition.maxToolIterations ?? definition.maxTurns,
+            __actoviqAllowedTools: definition.allowedTools
+                ? [...definition.allowedTools]
+                : undefined,
+            __actoviqDisallowedTools: [
+                ...(definition.disallowedTools ?? []),
+                ...nestedAgentDenylist,
+            ],
+            __actoviqPreloadedSkills: definition.skills
+                ? [...definition.skills]
+                : undefined,
+            __actoviqWorkDir: options.workDir ?? definition.cwd,
+            __actoviqInitialPrompt: definition.initialPrompt,
         };
     }
     mergeSkillRunOptions(definition, options) {
@@ -1719,6 +2609,35 @@ export class ActoviqAgentClient {
 export async function createAgentSdk(options = {}) {
     return ActoviqAgentClient.create(options);
 }
+function resolveTaskId(input) {
+    return [input.task_id, input.taskId]
+        .map(value => value?.trim())
+        .find((value) => Boolean(value));
+}
+function serializeBackgroundTaskOutput(task) {
+    return [
+        `Task id: ${task.id}`,
+        `Status: ${task.status}`,
+        `Subagent: ${task.subagentType}`,
+        task.agentName ? `Agent name: ${task.agentName}` : undefined,
+        task.runId ? `Run id: ${task.runId}` : undefined,
+        task.sessionId ? `Session id: ${task.sessionId}` : undefined,
+        task.model ? `Model: ${task.model}` : undefined,
+        typeof task.toolCallCount === 'number' ? `Tool calls: ${task.toolCallCount}` : undefined,
+        typeof task.toolErrorCount === 'number' ? `Tool errors: ${task.toolErrorCount}` : undefined,
+        typeof task.requestCount === 'number' ? `Requests: ${task.requestCount}` : undefined,
+        task.currentToolName ? `Current tool: ${task.currentToolName}` : undefined,
+        task.progressSummary ? `Progress: ${task.progressSummary}` : undefined,
+        task.worktreePath ? `Worktree: ${task.worktreePath}` : undefined,
+        task.worktreeBranch ? `Branch: ${task.worktreeBranch}` : undefined,
+        task.error ? `Error:\n${task.error}` : undefined,
+        task.text
+            ? `Output:\n${task.text}`
+            : task.partialText
+                ? `Partial output:\n${task.partialText}`
+                : 'Output: <not available yet>',
+    ].filter(Boolean).join('\n');
+}
 function joinPromptParts(...parts) {
     const normalized = parts.filter((value) => typeof value === 'string' && value.trim().length > 0);
     if (normalized.length === 0) {
@@ -1726,6 +2645,99 @@ function joinPromptParts(...parts) {
     }
     return normalized.join('\n\n');
 }
+function mergeAgentDefinitions(...groups) {
+    const merged = new Map();
+    for (const group of groups) {
+        for (const definition of group) {
+            merged.set(definition.name, cloneAgentDefinition(definition));
+        }
+    }
+    return [...merged.values()];
+}
+function filterAgentTools(tools, allowedTools, disallowedTools) {
+    const allowed = allowedTools?.length ? new Set(allowedTools) : undefined;
+    const denied = new Set(disallowedTools ?? []);
+    return tools.filter(toolDefinition => {
+        const names = [toolDefinition.name, ...(toolDefinition.aliases ?? [])];
+        if (names.some(name => denied.has(name))) {
+            return false;
+        }
+        return !allowed || names.some(name => allowed.has(name));
+    });
+}
+function formatTaskNotification(task) {
+    const result = task.status === 'completed'
+        ? task.text ?? task.partialText ?? ''
+        : task.partialText ?? '';
+    return [
+        '<task_notification>',
+        `<task_id>${escapeXml(task.id)}</task_id>`,
+        task.sessionId ? `<agent_id>${escapeXml(task.sessionId)}</agent_id>` : undefined,
+        task.agentName ? `<agent_name>${escapeXml(task.agentName)}</agent_name>` : undefined,
+        `<status>${task.status}</status>`,
+        `<summary>${escapeXml(task.status === 'completed'
+            ? `Agent "${task.agentName ?? task.subagentType}" completed.`
+            : `Agent "${task.agentName ?? task.subagentType}" ${task.status}.`)}</summary>`,
+        result ? `<result>${escapeXml(result)}</result>` : undefined,
+        task.error ? `<error>${escapeXml(task.error)}</error>` : undefined,
+        `<usage><requests>${task.requestCount ?? 0}</requests><tool_uses>${task.toolCallCount ?? 0}</tool_uses><tool_errors>${task.toolErrorCount ?? 0}</tool_errors></usage>`,
+        task.retainedWorktree && task.worktreePath
+            ? `<worktree><path>${escapeXml(task.worktreePath)}</path>${task.worktreeBranch ? `<branch>${escapeXml(task.worktreeBranch)}</branch>` : ''}</worktree>`
+            : undefined,
+        '</task_notification>',
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/gu, '&amp;')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;');
+}
+function sanitizeWorkspaceName(value) {
+    return value
+        .trim()
+        .replace(/[^A-Za-z0-9_-]+/gu, '-')
+        .replace(/^-+|-+$/gu, '')
+        .slice(0, 40) || 'agent';
+}
+async function isGitWorkspaceDirty(workDir) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10_000);
+        try {
+            const { stdout } = await new Promise((resolve, reject) => {
+                const child = execFileCallback('git', ['-C', workDir, 'status', '--porcelain'], {
+                    windowsHide: true,
+                    signal: controller.signal,
+                });
+                child.on('error', reject);
+                let stdout = '';
+                let stderr = '';
+                child.stdout?.on('data', (data) => { stdout += data.toString(); });
+                child.stderr?.on('data', (data) => { stderr += data.toString(); });
+                child.on('close', (code) => {
+                    if (code === 0) {
+                        resolve({ stdout, stderr });
+                    }
+                    else {
+                        reject(new Error(`git status exited with code ${code}: ${stderr}`));
+                    }
+                });
+            });
+            return stdout.trim().length > 0;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // If git is unavailable, timed out, or the repo is broken,
+        // conservatively treat as not dirty to avoid leaking worktrees.
+        return false;
+    }
+}
 function mergeUniqueByName(defaults, overrides) {
     const merged = new Map();
     for (const item of defaults) {