praxis-agent 0.14.0 → 0.16.0

package/dist/application/subagent-service.js

@@ -1,5 +1,5 @@
 import { randomBytes, randomUUID } from 'node:crypto';
-import { readdir, stat } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { resolveClaudePaths } from '../compatibility/claude/paths.js';
@@ -103,6 +103,155 @@ class RestrictedToolRegistry {
         return this.base.execute(call, context);
     }
 }
+const AGENT_UNAVAILABLE_TOOLS = new Set([
+    'Agent',
+    'Task',
+    'TaskOutput',
+    'TaskStop',
+    'ExitPlanMode',
+    'EnterPlanMode',
+    'AskUserQuestion',
+    'Workflow',
+]);
+const BACKGROUND_AGENT_TOOLS = new Set([
+    'Read',
+    'WebSearch',
+    'TodoWrite',
+    'Grep',
+    'WebFetch',
+    'Glob',
+    'Bash',
+    'Edit',
+    'Write',
+    'NotebookEdit',
+    'Skill',
+    'StructuredOutput',
+    'ToolSearch',
+    'EnterWorktree',
+    'ExitWorktree',
+]);
+function agentToolRuleName(rule) {
+    const opening = rule.indexOf('(');
+    return (opening < 0 ? rule : rule.slice(0, opening)).trim();
+}
+function enabledAgentToolNames(base, definition, background, additiveTools = new Set()) {
+    const requested = definition?.tools
+        ? new Set(definition.tools.map(agentToolRuleName))
+        : null;
+    if (requested && definition?.memory) {
+        requested.add('Read');
+        requested.add('Edit');
+        requested.add('Write');
+    }
+    const disallowed = new Set(definition?.disallowedTools?.map(agentToolRuleName) ?? []);
+    return base
+        .definitions()
+        .map(({ name }) => name)
+        .filter((name) => {
+        if (additiveTools.has(name))
+            return true;
+        if (AGENT_UNAVAILABLE_TOOLS.has(name))
+            return false;
+        if (background &&
+            !name.startsWith('mcp__') &&
+            !BACKGROUND_AGENT_TOOLS.has(name)) {
+            return false;
+        }
+        if (requested && !requested.has(name))
+            return false;
+        return !disallowed.has(name);
+    });
+}
+function agentMemoryDirectory(configRoot, cwd, agentType, scope) {
+    const directoryName = agentType.replaceAll(':', '-');
+    if (scope === 'user') {
+        return join(configRoot, 'agent-memory', directoryName);
+    }
+    return join(cwd, '.claude', scope === 'project' ? 'agent-memory' : 'agent-memory-local', directoryName);
+}
+export async function agentMemoryPrompt(configRoot, cwd, definition) {
+    if (!definition?.memory)
+        return null;
+    const directory = agentMemoryDirectory(configRoot, cwd, definition.name, definition.memory);
+    await mkdir(directory, { recursive: true }).catch(() => undefined);
+    let source = '';
+    try {
+        source = await readFile(join(directory, 'MEMORY.md'), 'utf8');
+    }
+    catch {
+        source = '';
+    }
+    const lines = source.trim().split('\n');
+    const truncated = lines.slice(0, 200).join('\n').slice(0, 25_000);
+    const scopeGuidance = definition.memory === 'user'
+        ? 'Keep entries general enough to apply across projects.'
+        : definition.memory === 'project'
+            ? 'Keep entries specific to this project and suitable for version control.'
+            : 'Keep entries specific to this project and machine; this scope is not version controlled.';
+    return [
+        '# Persistent Agent Memory',
+        '',
+        `Use the file-based memory directory at \`${directory}\`. The directory already exists.`,
+        'Keep MEMORY.md as a concise index and store detailed durable knowledge in linked Markdown files. Update existing entries instead of duplicating them, and do not save transient task state.',
+        scopeGuidance,
+        '',
+        '## MEMORY.md',
+        '',
+        truncated || 'The memory index is currently empty.',
+    ].join('\n');
+}
+function agentSkillMessages(catalog, definition) {
+    if (!catalog || !definition?.skills?.length)
+        return [];
+    const available = catalog.modelInvocableSkills();
+    const prefix = definition.name.split(':')[0];
+    return definition.skills.flatMap((requested) => {
+        const skill = available.find(({ name }) => name === requested) ??
+            available.find(({ name }) => name === `${prefix}:${requested}`) ??
+            available.find(({ name }) => name.endsWith(`:${requested}`));
+        if (!skill)
+            return [];
+        const content = catalog.renderSkill(skill.name, '');
+        if (content === null)
+            return [];
+        return [
+            {
+                role: 'user',
+                content: [
+                    `<command-message>${skill.name}</command-message>`,
+                    `<command-name>${skill.name}</command-name>`,
+                    '<skill-format>true</skill-format>',
+                    '',
+                    content,
+                ].join('\n'),
+            },
+        ];
+    });
+}
+function agentHookSettings(definition) {
+    if (!definition?.hooks)
+        return [];
+    const { Stop, SubagentStop, ...hooks } = definition.hooks;
+    const stopHooks = Stop === undefined
+        ? SubagentStop
+        : SubagentStop === undefined
+            ? Stop
+            : Array.isArray(Stop) && Array.isArray(SubagentStop)
+                ? [...SubagentStop, ...Stop]
+                : Stop;
+    return [
+        {
+            path: definition.path,
+            scope: definition.scope,
+            value: {
+                hooks: {
+                    ...hooks,
+                    ...(stopHooks === undefined ? {} : { SubagentStop: stopHooks }),
+                },
+            },
+        },
+    ];
+}
 function parseAgentInput(call) {
     const allowed = new Set([
         'description',
@@ -180,7 +329,7 @@ function parseAgentInput(call) {
             ? {}
             : { permissionMode: permissionMode }),
         ...(isolation === undefined ? {} : { isolation }),
-        runInBackground: call.input.run_in_background !== false,
+        runInBackground: call.input.run_in_background === true,
     };
 }
 export class ClaudeSubagentExecutor {
@@ -209,6 +358,35 @@ export class ClaudeSubagentExecutor {
     cwd() {
         return this.options.cwdProvider?.() ?? this.options.cwd;
     }
+    agentDefinition(input) {
+        return this.options.extensions?.agent(input.subagentType) ?? null;
+    }
+    resolveAgentInput(input) {
+        const definition = this.agentDefinition(input);
+        const environmentModel = process.env.CLAUDE_CODE_SUBAGENT_MODEL?.trim();
+        const configuredModel = definition?.model && definition.model !== 'inherit'
+            ? definition.model
+            : undefined;
+        const model = environmentModel || input.model || configuredModel;
+        const parentPermissionMode = this.options.parentPermissionMode?.();
+        const definitionCanOverridePermissionMode = ![
+            'acceptEdits',
+            'auto',
+            'bypassPermissions',
+        ].includes(parentPermissionMode ?? 'default');
+        const permissionMode = input.permissionMode ??
+            (definitionCanOverridePermissionMode
+                ? definition?.permissionMode
+                : parentPermissionMode);
+        const isolation = input.isolation ?? definition?.isolation;
+        return {
+            ...input,
+            ...(model ? { model } : {}),
+            ...(permissionMode ? { permissionMode } : {}),
+            ...(isolation ? { isolation } : {}),
+            runInBackground: input.runInBackground || definition?.background === true,
+        };
+    }
     registry(sessionId, depth, promptIdForCall) {
         return new ClaudeSubagentToolRegistry(this.options.baseTools, this, sessionId, depth, promptIdForCall);
     }
@@ -328,7 +506,7 @@ export class ClaudeSubagentExecutor {
     prepare(call, depth) {
         if (!this.isEnabled('Agent'))
             throw new Error('Tool Agent is unavailable');
-        const input = parseAgentInput(call);
+        const input = this.resolveAgentInput(parseAgentInput(call));
         if (input.runInBackground && this.options.persistence === 'memory') {
             throw new Error('Background agents require session persistence');
         }
@@ -367,7 +545,7 @@ export class ClaudeSubagentExecutor {
         if (this.calls > maxCalls) {
             throw new Error(`Agent call count exceeded ${maxCalls}`);
         }
-        const input = parseAgentInput(call);
+        const input = this.resolveAgentInput(parseAgentInput(call));
         const spawnDepth = depth + 1;
         const agentId = `a${randomBytes(8).toString('hex')}`;
         const paths = resolveClaudePaths({
@@ -959,33 +1137,52 @@ export class ClaudeSubagentExecutor {
                 await append(toClaudeSidechainEntry(entry, options.agentId, options.input.subagentType));
             }
         };
+        const customAgent = this.agentDefinition(options.input);
         const hookSession = {
             session_id: String(options.root.sessionId),
             transcript_path: options.transcriptPath,
             cwd,
             permission_mode: options.input.permissionMode ?? 'default',
         };
+        const scopedHookSettings = agentHookSettings(customAgent);
+        const scopedHooks = scopedHookSettings.length > 0
+            ? this.options.hooks?.withAdditionalSettings(scopedHookSettings)
+            : this.options.hooks;
         const nestedTools = this.registry(String(options.root.sessionId), options.spawnDepth, () => options.promptId);
-        const builtInStatusLineAgent = this.options.extensions?.agent(options.input.subagentType)?.path ===
-            BUILTIN_STATUSLINE_AGENT_PATH;
+        const agentMcp = customAgent?.mcpServers?.length
+            ? await this.options.mcp?.connectAgent?.({
+                specs: customAgent.mcpServers,
+                base: nestedTools,
+                cwd,
+                ...(options.signal ? { signal: options.signal } : {}),
+            })
+            : null;
+        const agentToolBase = agentMcp?.tools ?? nestedTools;
+        const inheritedToolNames = new Set(nestedTools.definitions().map(({ name }) => name));
+        const additiveAgentToolNames = new Set(agentToolBase
+            .definitions()
+            .map(({ name }) => name)
+            .filter((name) => !inheritedToolNames.has(name)));
+        const agentScopedTools = new RestrictedToolRegistry(agentToolBase, enabledAgentToolNames(agentToolBase, customAgent, options.input.runInBackground, additiveAgentToolNames));
+        const builtInStatusLineAgent = customAgent?.path === BUILTIN_STATUSLINE_AGENT_PATH;
         const scopedTools = builtInStatusLineAgent
-            ? new RestrictedToolRegistry(nestedTools, ['Read', 'Edit'])
-            : nestedTools;
+            ? new RestrictedToolRegistry(agentScopedTools, ['Read', 'Edit'])
+            : agentScopedTools;
         const agentTools = options.outputSchema
             ? new StructuredOutputRegistry(builtInStatusLineAgent
                 ? new RestrictedToolRegistry(structuredOnlyTools, ['Read', 'Edit'])
                 : structuredOnlyTools, options.outputSchema, options.structuredOutput)
             : scopedTools;
-        const runtimeTools = this.options.hooks
+        const runtimeTools = scopedHooks
             ? new ClaudeHookToolCoordinator({
                 tools: agentTools,
                 permissions,
-                hooks: this.options.hooks,
+                hooks: scopedHooks,
                 session: hookSession,
                 recordOutcome: recordHookOutcome,
             })
             : agentTools;
-        const runtimePermissions = this.options.hooks
+        const runtimePermissions = scopedHooks
             ? runtimeTools
             : permissions;
         const emit = (event) => {
@@ -1032,7 +1229,7 @@ export class ClaudeSubagentExecutor {
         const runtime = new AgentRuntime(options.provider, emit, {
             tools: runtimeTools,
             permissions: runtimePermissions,
-            maxModelTurns: 16,
+            maxModelTurns: customAgent?.maxTurns ?? 16,
             maxModelOutputBytes: this.options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
             maxToolCallsPerTurn: 32,
             maxToolInputBytes: 1024 * 1024,
@@ -1104,36 +1301,31 @@ export class ClaudeSubagentExecutor {
             prompt: options.input.prompt,
         });
         try {
-            if (this.options.hooks) {
-                const start = await this.options.hooks.run({
+            if (scopedHooks) {
+                const start = await scopedHooks.run({
                     ...hookSession,
-                    hook_event_name: 'SessionStart',
-                    source: 'startup',
-                }, 'startup', options.signal);
+                    hook_event_name: 'SubagentStart',
+                    agent_id: options.agentId,
+                    agent_type: options.input.subagentType,
+                }, options.input.subagentType, options.signal);
                 await recordHookOutcome(start);
                 if (start.blockedReason) {
-                    throw new Error(`SessionStart hook error: ${start.blockedReason}`);
-                }
-                const prompt = await this.options.hooks.run({
-                    ...hookSession,
-                    hook_event_name: 'UserPromptSubmit',
-                    prompt_id: options.promptId,
-                    prompt: options.input.prompt,
-                }, undefined, options.signal);
-                await recordHookOutcome(prompt);
-                if (prompt.blockedReason) {
-                    throw new Error(`UserPromptSubmit hook error: ${prompt.blockedReason}`);
+                    throw new Error(`SubagentStart hook error: ${start.blockedReason}`);
                 }
             }
-            const customAgent = this.options.extensions?.agent(options.input.subagentType);
             const baseSystem = options.input.subagentType === 'general-purpose'
                 ? 'You are a general-purpose subagent. Complete the isolated task and return a concise result.'
                 : options.input.subagentType === 'workflow-subagent'
                     ? 'You are a workflow subagent. Complete the isolated task. Your final text is the raw return value consumed by the workflow, not a user-facing message.'
                     : `# Agent definition: ${options.input.subagentType}\n\n${customAgent?.body ?? ''}`;
-            const system = options.outputSchema
-                ? `${baseSystem}\n\nYou MUST call StructuredOutput exactly once at the end with a value matching its schema.`
+            const memoryPrompt = await agentMemoryPrompt(this.options.configRoot, cwd, customAgent);
+            const agentSystem = memoryPrompt
+                ? `${baseSystem}\n\n${memoryPrompt}`
                 : baseSystem;
+            const system = options.outputSchema
+                ? `${agentSystem}\n\nYou MUST call StructuredOutput exactly once at the end with a value matching its schema.`
+                : agentSystem;
+            const preloadedSkills = agentSkillMessages(this.options.extensions, customAgent);
             let stopHookActive = false;
             const contextBudget = options.provider.capabilities.contextWindowTokens
                 ? new ContextBudget({
@@ -1154,17 +1346,20 @@ export class ClaudeSubagentExecutor {
                     ...(assembledContext?.systemMessages ?? []),
                     { role: 'system', content: system },
                     ...injectFirstUserMessageContext(projectClaudeModelMessages(snapshot.entries), assembledContext?.firstUserMessageContext),
+                    ...preloadedSkills,
                 ];
                 if (contextBudget) {
                     contextBudget.assertFits(contextBudget.evaluate(messages, definitions));
                 }
                 return messages;
             };
+            const configuredEffort = typeof customAgent?.effort === 'string' ? customAgent.effort : undefined;
+            const effectiveEffort = options.effort ?? configuredEffort;
             const result = await runtime.run({
                 messages: await assembleMessages(),
                 reloadMessages: assembleMessages,
                 cwd,
-                ...(options.effort ? { effort: options.effort } : {}),
+                ...(effectiveEffort ? { effort: effectiveEffort } : {}),
                 toolResultDirectory: options.toolResultDirectory,
                 observer,
                 ...(this.options.approveTool
@@ -1174,21 +1369,24 @@ export class ClaudeSubagentExecutor {
                 ...(this.options.onPermissionUpdates
                     ? { onPermissionUpdates: this.options.onPermissionUpdates }
                     : {}),
-                ...(this.options.hooks || this.options.backgroundTaskNotifications
+                ...(scopedHooks || this.options.backgroundTaskNotifications
                     ? {
                         onStop: async (text) => {
                             const messages = [];
-                            const outcome = await this.options.hooks?.run({
+                            const outcome = await scopedHooks?.run({
                                 ...hookSession,
-                                hook_event_name: 'Stop',
+                                hook_event_name: 'SubagentStop',
                                 stop_hook_active: stopHookActive,
+                                agent_id: options.agentId,
+                                agent_transcript_path: options.transcriptPath,
+                                agent_type: options.input.subagentType,
                                 last_assistant_message: text,
-                            }, undefined, options.signal);
+                            }, options.input.subagentType, options.signal);
                             if (outcome) {
                                 await recordHookOutcome(outcome);
                                 if (outcome.blockedReason) {
                                     stopHookActive = true;
-                                    messages.push(`Stop hook error: ${outcome.blockedReason}`);
+                                    messages.push(`SubagentStop hook error: ${outcome.blockedReason}`);
                                 }
                             }
                             const background = await this.background.notifications({
@@ -1251,25 +1449,12 @@ export class ClaudeSubagentExecutor {
             throw error;
         }
         finally {
-            try {
-                const outcome = await this.options.hooks?.run({
-                    ...hookSession,
-                    hook_event_name: 'SessionEnd',
-                    reason: 'other',
-                }, 'other');
-                for (const execution of outcome?.executions.filter((value) => value.exitCode !== 0) ?? []) {
-                    this.options.eventSink?.({
-                        type: 'warning',
-                        message: `Subagent SessionEnd hook failed: ${execution.stderr.trim() || execution.stdout.trim() || `exit code ${execution.exitCode}`}`,
-                    });
-                }
-            }
-            catch (error) {
+            await agentMcp?.close().catch((error) => {
                 this.options.eventSink?.({
                     type: 'warning',
-                    message: `Subagent SessionEnd hook failed: ${error instanceof Error ? error.message : String(error)}`,
+                    message: `Agent MCP cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
                 });
-            }
+            });
         }
     }
 }

package/dist/cli/interactive.d.ts

@@ -8,6 +8,8 @@ import { type TuiMemoryFiles } from './tui/memory-files.js';
 import { type TuiDiffSnapshot } from './tui/git-diff.js';
 import { type TuiPermissionBehavior, type TuiPermissionRule } from './tui/permission-settings.js';
 import { type RecentlyDeniedStore } from './tui/recently-denied.js';
+import { type AgentColorSelection } from '../compatibility/claude/agent-color.js';
+import type { AgentColorName } from '../compatibility/claude/agent-color.js';
 import type { ClaudeResourceScope } from '../compatibility/claude/shared-resources.js';
 import type { TuiHookConfiguration } from './tui/hook-settings.js';
 import { type TuiSlashCommand } from './tui/slash-commands.js';
@@ -41,6 +43,8 @@ interface InteractiveSessionCommands {
     retryRecentlyDenied?(sessionId: string, display: string, signal?: AbortSignal): Promise<SessionRunResult>;
     answerSideQuestion?(sessionId: string | undefined, question: string, signal?: AbortSignal, onDelta?: (delta: string) => void, permissionMode?: ClaudePermissionMode): Promise<SideQuestionResult>;
     recordBtwUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
+    recordColorUsage?(sessionId: string | undefined, selection: AgentColorSelection, display: string, permissionMode?: ClaudePermissionMode): Promise<string>;
+    agentColor?(sessionId: string): Promise<AgentColorName | undefined>;
     recordBackgroundUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
     recordBackgroundLaunch?(sessionId: string): Promise<SessionForkCheckpoint>;
     forkSideQuestion?(sessionId: string, question: string, signal?: AbortSignal): Promise<SideQuestionForkResult>;
@@ -58,6 +62,7 @@ interface InteractiveSessionCommands {
     slashCommands?(): readonly TuiSlashCommand[];
     agentDefinitions?(): readonly TuiAgentEntry[];
     runtimeInfo?(): CliRuntimeInfo;
+    initialAgentPrompt?(): string | undefined;
     setPermissionMode?(sessionId: string, mode: ClaudePermissionMode): Promise<void>;
     nextScheduledPrompt?(signal?: AbortSignal): Promise<{
         id: string;
@@ -110,6 +115,7 @@ interface InteractiveAppProps {
     initialSessions: readonly SessionSummary[];
     initialPrompt?: string;
     initialHistory?: readonly TranscriptItem[];
+    initialSessionColor?: AgentColorName;
     signal?: AbortSignal;
     onCancel?: () => void;
     onTurnChange?: (turn: Promise<void> | null) => void;
@@ -178,7 +184,7 @@ interface InteractiveAppProps {
     releaseNotesLoader?: (configRoot: string) => Promise<string>;
     settingSources?: readonly ClaudeResourceScope[];
 }
-export declare function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
+export declare function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory, initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
 export declare function runInteractive(options: {
     factory: InteractiveServiceFactory;
     initialPrompt?: string;