praxis-agent 0.14.0 → 0.16.0

package/dist/cli.js

@@ -7,6 +7,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { ClaudeSessionService, } from './application/session-service.js';
+import { agentColorMessage, parseAgentColorInput, } from './compatibility/claude/agent-color.js';
 import { ClaudeConditionalRuleResolver, ClaudeContextAssembler, } from './compatibility/claude/context.js';
 import { loadClaudeDynamicContext } from './compatibility/claude/dynamic-context.js';
 import { createClaudePrSessionFilter, filterClaudePrLinkedSessions, } from './compatibility/claude/pr-links.js';
@@ -46,7 +47,7 @@ import { WorkspaceContext } from './application/session-worktree.js';
 import { launchTmuxWorktree } from './platform/tmux-worktree.js';
 import { claudeSandboxRuntime } from './sandbox/claude-sandbox-runtime.js';
 import { claudeSandboxTempDirectory, loadClaudeSandboxSettings, } from './sandbox/claude-sandbox-settings.js';
-import { createErrorResult, createSuccessResult, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
+import { createErrorResult, createSuccessResult, matchHeadlessColorCommand, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
 import { describeClaudePlugin, initClaudePlugin, installClaudePlugin, loadClaudePlugins, readPluginRegistry, setClaudePluginEnabled, uninstallClaudePlugin, updateClaudePlugin, validateClaudePlugin, } from './plugins/claude-plugin-runtime.js';
 import { addClaudeMarketplace, disableAllNativePlugins, installClaudeMarketplacePlugin, listClaudeMarketplaceAvailablePlugins, listNativePluginRecords, readClaudeKnownMarketplaces, removeClaudeMarketplace, setNativePluginEnabled, saveClaudePluginConfig, uninstallNativePlugin, updateClaudeMarketplace, updateNativePlugin, validateClaudeMarketplace, } from './plugins/claude-plugin-marketplace.js';
 import { executeClaudePluginEvalCommand, PLUGIN_EVAL_HELP, } from './plugins/claude-plugin-eval.js';
@@ -733,6 +734,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
     const runtimeEventSink = debug?.eventSink ?? eventSink;
     let provider;
     let providerForModel;
+    let providerForMainModel;
     const context = parseContextEnvironment(runtimeEnvironment);
     const apiKey = runtimeEnvironment.PRAXIS_API_KEY;
     const model = cli.model ?? runtimeEnvironment.PRAXIS_MODEL;
@@ -755,13 +757,18 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             throw new Error('Provider environment is unavailable');
         }
         providerForModel = createProviderForModel(apiKey, providerEnvironment, context, cli, controls);
-        const models = [model, ...(cli.fallbackModels ?? [])].filter((candidate, index, all) => all.indexOf(candidate) === index);
         const createProvider = providerForModel;
-        const providers = models.map((candidate) => createProvider(candidate));
-        provider =
-            providers.length > 1
+        providerForMainModel = (primaryModel) => {
+            const models = [primaryModel, ...(cli.fallbackModels ?? [])].filter((candidate, index, all) => all.indexOf(candidate) === index);
+            const providers = models.map((candidate) => createProvider(candidate));
+            const selected = providers[0];
+            if (!selected)
+                throw new Error('A primary model is required');
+            return providers.length > 1
                 ? new FallbackModelProvider({ providers })
-                : providers[0];
+                : selected;
+        };
+        provider = providerForMainModel(model);
     }
     const options = {
         configRoot,
@@ -769,6 +776,10 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         claudeVersion,
         eventSink: runtimeEventSink,
         sessionPersistence: cli.sessionPersistence,
+        explicitModel: interactiveModel !== undefined || controls.model !== undefined,
+        explicitSystemPrompt: cli.systemPrompt !== undefined,
+        agentInitialPromptHandledExternally: interactive,
+        agentSystemPromptOverridesExplicit: interactive,
         effort: cli.effort ?? 'high',
         ...(cli.maxTurns === undefined ? {} : { maxModelTurns: cli.maxTurns }),
         ...(cli.brief && !cli.disallowedTools.includes('SendUserMessage')
@@ -908,6 +919,15 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         }
     }
     settings.push(...pluginResources.settings);
+    const configuredAgent = [...settings]
+        .reverse()
+        .map((resource) => resource.value &&
+        typeof resource.value === 'object' &&
+        !Array.isArray(resource.value)
+        ? resource.value.agent
+        : undefined)
+        .find((value) => typeof value === 'string' && value.length > 0);
+    const selectedMainAgent = agent ?? configuredAgent;
     const resources = {
         ...loadedResources,
         commands: [...loadedResources.commands, ...pluginResources.commands],
@@ -1196,10 +1216,14 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             ...options,
             provider: hostedToolProvider,
             ...(providerForModel ? { providerForModel } : {}),
+            ...(providerForMainModel ? { providerForMainModel } : {}),
             tools: filteredTools,
             mcp: mcpTools,
             permissions,
             permissionResolverForMode,
+            permissionMode: cli.dangerouslySkipPermissions
+                ? 'bypassPermissions'
+                : cli.permissionMode,
             persistPermissionUpdates: (updates) => persistTuiPermissionUpdates({
                 cwd: workspace.cwd(),
                 configRoot,
@@ -1220,7 +1244,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                 : {}),
             ...(interactiveTools ? { interactiveTools } : {}),
             ...(hooks ? { hooks } : {}),
-            ...(agent ? { agent } : {}),
+            ...(selectedMainAgent ? { agent: selectedMainAgent } : {}),
             contextAssembler: new ClaudeContextAssembler({
                 loadResources: loadContextResources,
                 loadDynamicContext: (runtimeCwd = workspace.cwd()) => loadClaudeDynamicContext({
@@ -1320,6 +1344,8 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             retryRecentlyDenied: (sessionId, display, retrySignal) => service.retryRecentlyDenied(sessionId, display, retrySignal),
             answerSideQuestion: (sessionId, question, sideSignal, onDelta, permissionMode) => service.answerSideQuestion(sessionId, question, sideSignal, onDelta, permissionMode),
             recordBtwUsage: (sessionId, permissionMode) => service.recordBtwUsage(sessionId, permissionMode),
+            recordColorUsage: (sessionId, selection, display, permissionMode, options) => service.recordColorUsage(sessionId, selection, display, permissionMode, options),
+            agentColor: (sessionId) => service.readEffectiveAgentColor(sessionId),
             recordBackgroundUsage: (sessionId, permissionMode) => service.recordBackgroundUsage(sessionId, permissionMode),
             recordBackgroundLaunch: (sessionId) => service.recordBackgroundLaunch(sessionId),
             forkSideQuestion: (sessionId, question, sideSignal) => service.forkSideQuestion(sessionId, question, sideSignal),
@@ -1373,6 +1399,9 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             taskSnapshots: (sessionId) => service.taskSnapshots(sessionId),
             stopTask: (sessionId, taskId) => service.stopTask(sessionId, taskId),
             agentDefinitions: () => extensions.agentDefinitions(),
+            initialAgentPrompt: () => selectedMainAgent
+                ? extensions.agent(selectedMainAgent)?.initialPrompt
+                : undefined,
             inspect: (sessionId) => service.inspect(sessionId),
             export: (sessionId) => service.export(sessionId),
             transcript: (sessionId) => service.transcript(sessionId, pendingResumeSessionAt),
@@ -1407,7 +1436,10 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             runtimeInfo: () => ({
                 ...runtimeInfo,
                 cwd: workspace.cwd(),
-                model: provider?.model ?? process.env.PRAXIS_MODEL ?? 'unknown',
+                model: service.model() ??
+                    provider?.model ??
+                    runtimeEnvironment.PRAXIS_MODEL ??
+                    'unknown',
             }),
             promptSuggestion: (sessionId, suggestionSignal) => service.promptSuggestion(sessionId, suggestionSignal),
         };
@@ -3706,6 +3738,7 @@ async function execute(argv, io, dependencies, signal) {
     const pendingEvents = [];
     let streamIterator;
     let firstStreamMessage;
+    let streamInputExhausted = false;
     const queuedStreamUsers = [];
     const earlyControlResponses = new Map();
     let currentTurnAbort;
@@ -3905,6 +3938,19 @@ async function execute(argv, io, dependencies, signal) {
         }
         return 0;
     }
+    const headlessTurnReached = invocation.rewindFiles === undefined &&
+        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
+    if (streamIterator && headlessTurnReached) {
+        const first = await nextStreamUser();
+        if (first)
+            firstStreamMessage = first;
+        else
+            streamInputExhausted = true;
+    }
+    const firstHeadlessPrompt = firstStreamMessage?.prompt ?? headlessPrompt;
+    const firstTurnIsLocalColor = !invocation.disableSlashCommands &&
+        firstHeadlessPrompt !== undefined &&
+        matchHeadlessColorCommand(firstHeadlessPrompt) !== undefined;
     const service = await dependencies.createService({
         eventSink: outputFormat === 'stream-json' && !invocation.legacyJson
             ? (event) => {
@@ -3929,8 +3975,7 @@ async function execute(argv, io, dependencies, signal) {
                     }
                 }
                 : eventSink(io, outputFormat, invocation.legacyJson),
-        requireProvider: invocation.rewindFiles === undefined &&
-            !['fork', 'sessions', 'inspect', 'export'].includes(command ?? 'run'),
+        requireProvider: !streamInputExhausted && !firstTurnIsLocalColor && headlessTurnReached,
         ...(retryInterruptedTools ? { approveRecovery: () => true } : {}),
         ...(streamIterator ? { approveTool: approveStreamTool } : {}),
         ...(streamIterator ? { onElicitation: respondStreamElicitation } : {}),
@@ -4038,12 +4083,8 @@ async function execute(argv, io, dependencies, signal) {
         if (outputFormat === 'stream-json' && !invocation.legacyJson) {
             streamOutput = new StreamJsonOutput((value) => writeJson(io, value), runtimeInfo, activeSessionId, includePartialMessages, invocation.includeHookEvents);
         }
-        if (streamIterator) {
-            const first = await nextStreamUser();
-            if (!first)
-                return 0;
-            firstStreamMessage = first;
-        }
+        if (streamInputExhausted)
+            return 0;
         const initialPrompt = firstStreamMessage?.prompt ??
             promptFrom(command === 'resume'
                 ? args.slice(2)
@@ -4070,15 +4111,38 @@ async function execute(argv, io, dependencies, signal) {
                     streamOutput.replayUser(streamMessage.message);
             }
             let result;
+            let colorArgs;
             try {
-                result =
-                    existingSessionId !== undefined || !isFirstTurn
-                        ? runSignal
-                            ? await service.resume(activeSessionId, prompt, runSignal, undefined, streamMessage?.images, streamMessage?.documents)
-                            : await service.resume(activeSessionId, prompt, undefined, undefined, streamMessage?.images, streamMessage?.documents)
-                        : runSignal
-                            ? await service.run(prompt, runSignal, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents)
-                            : await service.run(prompt, undefined, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents);
+                colorArgs = invocation.disableSlashCommands
+                    ? undefined
+                    : matchHeadlessColorCommand(prompt);
+                if (colorArgs !== undefined) {
+                    if (!service.recordColorUsage) {
+                        throw new Error('Session color is unavailable.');
+                    }
+                    const selection = parseAgentColorInput(colorArgs);
+                    const localSessionId = await service.recordColorUsage(activeSessionId, selection, prompt, invocation.permissionMode, isFirstTurn && existingSessionId === undefined
+                        ? { createSession: true }
+                        : undefined);
+                    result = {
+                        sessionId: localSessionId,
+                        text: agentColorMessage(selection),
+                        usage: { inputTokens: 0, outputTokens: 0 },
+                        durationApiMs: 0,
+                        costUsd: 0,
+                        modelUsage: {},
+                    };
+                }
+                else {
+                    result =
+                        existingSessionId !== undefined || !isFirstTurn
+                            ? runSignal
+                                ? await service.resume(activeSessionId, prompt, runSignal, undefined, streamMessage?.images, streamMessage?.documents)
+                                : await service.resume(activeSessionId, prompt, undefined, undefined, streamMessage?.images, streamMessage?.documents)
+                            : runSignal
+                                ? await service.run(prompt, runSignal, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents)
+                                : await service.run(prompt, undefined, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents);
+                }
             }
             catch (error) {
                 if (isCancellation(error, turnAbort.signal)) {
@@ -4105,16 +4169,20 @@ async function execute(argv, io, dependencies, signal) {
                 return false;
             }
             activeSessionId = result.sessionId;
-            if (streamOutput)
+            if (streamOutput) {
+                if (colorArgs !== undefined) {
+                    streamOutput.syntheticAssistant(result.text);
+                }
                 streamOutput.result(result, startedAt);
+            }
             else if (outputFormat === 'json') {
                 const resultRuntimeInfo = service.runtimeInfo?.() ?? runtimeInfo;
-                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, Math.max(1, jsonModelTurns)));
+                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, colorArgs !== undefined ? 0 : Math.max(1, jsonModelTurns)));
             }
             else if (outputFormat !== 'text')
                 writeJson(io, { type: 'result', ...result });
             else
-                io.stdout('\n');
+                io.stdout(colorArgs !== undefined ? `${result.text}\n` : '\n');
             if (streamOutput && invocation.promptSuggestions) {
                 try {
                     const suggestion = await service.promptSuggestion?.(activeSessionId, runSignal);

package/dist/compatibility/claude/agent-color.d.ts

@@ -0,0 +1,25 @@
+import type { ClaudeTranscriptEntry } from './schema.js';
+export declare const AGENT_COLORS: readonly ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"];
+export type AgentColorName = (typeof AGENT_COLORS)[number];
+export declare const AGENT_COLOR_DEFAULT: "default";
+export type AgentColorValue = AgentColorName | typeof AGENT_COLOR_DEFAULT;
+export declare const AGENT_COLOR_VALUES: readonly AgentColorValue[];
+export declare const AGENT_COLOR_CHOICES: string;
+export declare const RESET_AGENT_COLOR_ALIASES: readonly ["default", "reset", "none", "gray", "grey"];
+export declare function isAgentColorName(value: unknown): value is AgentColorName;
+export declare function isAgentColorValue(value: unknown): value is AgentColorValue;
+export declare function normalizeAgentColorInput(input: string): string;
+export type AgentColorSelection = {
+    kind: 'color';
+    color: AgentColorName;
+} | {
+    kind: 'reset';
+} | {
+    kind: 'invalid';
+    input: string;
+};
+export declare function parseAgentColorInput(input: string): AgentColorSelection;
+export declare function randomAgentColor(): AgentColorName;
+export declare function agentColorMessage(selection: AgentColorSelection): string;
+export declare function getClaudeEffectiveAgentColor(entries: readonly ClaudeTranscriptEntry[], sessionId: string): AgentColorName | undefined;
+//# sourceMappingURL=agent-color.d.ts.map

package/dist/compatibility/claude/agent-color.js

@@ -0,0 +1,79 @@
+export const AGENT_COLORS = [
+    'red',
+    'blue',
+    'green',
+    'yellow',
+    'purple',
+    'orange',
+    'pink',
+    'cyan',
+];
+export const AGENT_COLOR_DEFAULT = 'default';
+export const AGENT_COLOR_VALUES = [
+    ...AGENT_COLORS,
+    AGENT_COLOR_DEFAULT,
+];
+export const AGENT_COLOR_CHOICES = `${AGENT_COLORS.join(', ')}, ${AGENT_COLOR_DEFAULT}`;
+export const RESET_AGENT_COLOR_ALIASES = [
+    AGENT_COLOR_DEFAULT,
+    'reset',
+    'none',
+    'gray',
+    'grey',
+];
+export function isAgentColorName(value) {
+    return (typeof value === 'string' &&
+        AGENT_COLORS.includes(value));
+}
+export function isAgentColorValue(value) {
+    return (typeof value === 'string' &&
+        AGENT_COLOR_VALUES.includes(value));
+}
+export function normalizeAgentColorInput(input) {
+    return input.trim().toLowerCase();
+}
+export function parseAgentColorInput(input) {
+    const normalized = normalizeAgentColorInput(input);
+    if (normalized === '') {
+        return { kind: 'color', color: randomAgentColor() };
+    }
+    if (RESET_AGENT_COLOR_ALIASES.includes(normalized)) {
+        return { kind: 'reset' };
+    }
+    if (isAgentColorName(normalized)) {
+        return { kind: 'color', color: normalized };
+    }
+    return { kind: 'invalid', input: normalized };
+}
+export function randomAgentColor() {
+    const index = Math.floor(Math.random() * AGENT_COLORS.length);
+    const color = AGENT_COLORS[index];
+    if (color === undefined)
+        throw new Error('AGENT_COLORS must not be empty');
+    return color;
+}
+export function agentColorMessage(selection) {
+    switch (selection.kind) {
+        case 'color':
+            return `Session color set to: ${selection.color}`;
+        case 'reset':
+            return 'Session color reset to default';
+        case 'invalid':
+            return `Invalid color "${selection.input}". Available colors: ${AGENT_COLOR_CHOICES}`;
+    }
+}
+export function getClaudeEffectiveAgentColor(entries, sessionId) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type !== 'agent-color' || entry.sessionId !== sessionId) {
+            continue;
+        }
+        const color = entry.agentColor;
+        if (color === AGENT_COLOR_DEFAULT)
+            return undefined;
+        if (isAgentColorName(color))
+            return color;
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent-color.js.map

package/dist/compatibility/claude/fork.js

@@ -152,6 +152,7 @@ function validateNativeHistory(entries) {
     return undefined;
 }
 export function createClaudeNativeFork({ source, sourceSessionId, sessionId, resumeSessionAt, }) {
+    const agentColors = [];
     const titles = [];
     const modes = [];
     const permissionModes = [];
@@ -204,7 +205,9 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
             throw new Error('Claude fork source entry has the wrong sessionId');
         }
         const copied = copyClaudeEntryWithSessionId(entry, sessionId);
-        if (entry.type === 'ai-title')
+        if (entry.type === 'agent-color')
+            agentColors.push(copied);
+        else if (entry.type === 'ai-title')
             titles.push(copied);
         else if (entry.type === 'mode')
             modes.push(copied);
@@ -232,6 +235,7 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
         lastPrompt = undefined;
     }
     return [
+        ...agentColors.slice(-1),
         ...titles.slice(-1),
         ...modes.slice(-1),
         ...permissionModes.slice(-1),

package/dist/compatibility/claude/schema.js

@@ -1,5 +1,7 @@
+import { isAgentColorValue } from './agent-color.js';
 const SUPPORTED_VERSION = '2.1.208';
 const APPENDABLE_ENTRY_TYPES = new Set([
+    'agent-color',
     'agent-name',
     'agent-setting',
     'assistant',
@@ -17,6 +19,7 @@ const APPENDABLE_ENTRY_TYPES = new Set([
     'worktree-state',
 ]);
 const FORKABLE_ENTRY_TYPES = new Set([
+    'agent-color',
     'agent-name',
     'agent-setting',
     'ai-title',
@@ -717,6 +720,13 @@ function validateAppendableEntry(entry) {
         }
         return;
     }
+    if (entry.type === 'agent-color') {
+        if (!isAgentColorValue(entry.agentColor) ||
+            !isNonEmptyString(entry.sessionId)) {
+            throw new Error('Claude agent-color entry has invalid metadata');
+        }
+        return;
+    }
     if (entry.type === 'agent-name') {
         if (!isNonEmptyString(entry.agentName) ||
             !isNonEmptyString(entry.sessionId)) {
@@ -868,7 +878,9 @@ function validateSidechainEntry(entry) {
     }
 }
 function validateForkableEntry(entry) {
-    if (entry.type === 'custom-title' || entry.type === 'agent-name') {
+    if (entry.type === 'custom-title' ||
+        entry.type === 'agent-name' ||
+        entry.type === 'agent-color') {
         validateAppendableEntry(entry);
         return;
     }

package/dist/extensions/claude-extensions.d.ts

@@ -23,6 +23,24 @@ export interface ClaudeAgentDefinition {
     name: string;
     description: string;
 }
+export type ClaudeAgentEffort = 'low' | 'medium' | 'high' | 'max' | number;
+export type ClaudeAgentPermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan';
+export interface ClaudeAgentRuntimeDefinition extends ClaudeExtensionDefinition {
+    kind: 'agent';
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
+    model?: string;
+    effort?: ClaudeAgentEffort;
+    permissionMode?: ClaudeAgentPermissionMode;
+    maxTurns?: number;
+    skills?: readonly string[];
+    initialPrompt?: string;
+    memory?: 'user' | 'project' | 'local';
+    background?: boolean;
+    isolation?: 'worktree';
+    mcpServers?: readonly unknown[];
+    hooks?: Readonly<Record<string, unknown>>;
+}
 export interface ClaudePromptExpansion {
     userMessages: readonly string[];
     messages?: readonly ClaudePromptExpansionMessage[];
@@ -50,7 +68,7 @@ export declare class ClaudeExtensionCatalog {
     slashCommandDefinitions(): readonly ClaudeSlashCommandDefinition[];
     skill(name: string): ClaudeExtensionDefinition | null;
     modelInvocableSkills(): readonly ClaudeExtensionDefinition[];
-    agent(name: string): ClaudeExtensionDefinition | null;
+    agent(name: string): ClaudeAgentRuntimeDefinition | null;
     agentNames(): readonly string[];
     agentDefinitions(): readonly ClaudeAgentDefinition[];
     agentMentionMessages(prompt: string): readonly string[];

package/dist/extensions/claude-extensions.js

@@ -122,6 +122,123 @@ function parseFrontmatter(resource) {
         body: lines.slice(closingIndex + 1).join('\n'),
     };
 }
+function parseAgentList(value) {
+    if (value === undefined)
+        return undefined;
+    const values = typeof value === 'string'
+        ? [value]
+        : Array.isArray(value)
+            ? value.filter((item) => typeof item === 'string')
+            : [];
+    const parsed = [];
+    for (const value of values) {
+        let current = '';
+        let depth = 0;
+        for (const character of value) {
+            if (character === '(')
+                depth += 1;
+            if (character === ')' && depth > 0)
+                depth -= 1;
+            if (depth === 0 && (character === ',' || /\s/u.test(character))) {
+                if (current.trim())
+                    parsed.push(current.trim());
+                current = '';
+            }
+            else {
+                current += character;
+            }
+        }
+        if (current.trim())
+            parsed.push(current.trim());
+    }
+    return parsed;
+}
+function parseAgentEffort(value) {
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? value : undefined;
+    }
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (['low', 'medium', 'high', 'max'].includes(normalized)) {
+        return normalized;
+    }
+    if (!/^[+-]?\d+$/u.test(normalized))
+        return undefined;
+    const numeric = Number(normalized);
+    return Number.isInteger(numeric) ? numeric : undefined;
+}
+function parsePositiveInteger(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+    }
+    if (typeof value !== 'string' || !/^[1-9]\d*$/u.test(value)) {
+        return undefined;
+    }
+    const numeric = Number(value);
+    return Number.isSafeInteger(numeric) ? numeric : undefined;
+}
+function parseAgentDefinition(resource) {
+    const definition = parseDefinition('agent', resource);
+    const { metadata } = parseFrontmatter(resource);
+    const parsedTools = parseAgentList(metadata.tools);
+    const tools = parsedTools?.includes('*') ? undefined : parsedTools;
+    const disallowedTools = parseAgentList(metadata.disallowedTools);
+    const skills = parseAgentList(metadata.skills);
+    const model = typeof metadata.model === 'string' && metadata.model.trim()
+        ? metadata.model.trim().toLowerCase() === 'inherit'
+            ? 'inherit'
+            : metadata.model.trim()
+        : undefined;
+    const effort = parseAgentEffort(metadata.effort);
+    const permissionMode = [
+        'acceptEdits',
+        'auto',
+        'bypassPermissions',
+        'default',
+        'dontAsk',
+        'plan',
+    ].includes(String(metadata.permissionMode))
+        ? metadata.permissionMode
+        : undefined;
+    const maxTurns = parsePositiveInteger(metadata.maxTurns);
+    const initialPrompt = typeof metadata.initialPrompt === 'string' && metadata.initialPrompt.trim()
+        ? metadata.initialPrompt
+        : undefined;
+    const memory = ['user', 'project', 'local'].includes(String(metadata.memory))
+        ? metadata.memory
+        : undefined;
+    const background = metadata.background === true || metadata.background === 'true'
+        ? true
+        : undefined;
+    const isolation = metadata.isolation === 'worktree' ? 'worktree' : undefined;
+    const mcpServers = Array.isArray(metadata.mcpServers) && metadata.mcpServers.length > 0
+        ? [...metadata.mcpServers]
+        : undefined;
+    const hooks = typeof metadata.hooks === 'object' &&
+        metadata.hooks !== null &&
+        !Array.isArray(metadata.hooks) &&
+        Object.keys(metadata.hooks).length > 0
+        ? { ...metadata.hooks }
+        : undefined;
+    return {
+        ...definition,
+        kind: 'agent',
+        ...(tools === undefined ? {} : { tools }),
+        ...(disallowedTools === undefined ? {} : { disallowedTools }),
+        ...(model === undefined ? {} : { model }),
+        ...(effort === undefined ? {} : { effort }),
+        ...(permissionMode === undefined ? {} : { permissionMode }),
+        ...(maxTurns === undefined ? {} : { maxTurns }),
+        ...(skills?.length ? { skills } : {}),
+        ...(initialPrompt === undefined ? {} : { initialPrompt }),
+        ...(memory === undefined ? {} : { memory }),
+        ...(background === undefined ? {} : { background }),
+        ...(isolation === undefined ? {} : { isolation }),
+        ...(mcpServers === undefined ? {} : { mcpServers }),
+        ...(hooks === undefined ? {} : { hooks }),
+    };
+}
 export function validateClaudeExtensions(resources) {
     for (const resource of resources) {
         const lines = resource.content.split(/\r?\n/);
@@ -216,6 +333,14 @@ function indexed(kind, resources) {
     }
     return definitions;
 }
+function indexedAgents(resources) {
+    const definitions = new Map();
+    for (const resource of resources) {
+        const definition = parseAgentDefinition(resource);
+        definitions.set(definition.name, definition);
+    }
+    return definitions;
+}
 function substituteArguments(body, argumentsText) {
     const values = argumentsText.length === 0 ? [] : argumentsText.split(/\s+/);
     return body.replace(/\$(ARGUMENTS|\d+)/g, (_, key) => key === 'ARGUMENTS' ? argumentsText : (values[Number(key)] ?? ''));
@@ -251,7 +376,7 @@ export class ClaudeExtensionCatalog {
             : indexed('skill', resources.skills);
         this.agents = new Map([
             ['statusline-setup', BUILTIN_STATUSLINE_AGENT],
-            ...indexed('agent', resources.agents),
+            ...indexedAgents(resources.agents),
         ]);
     }
     setMcpPrompts(prompts) {

package/dist/hooks/claude-hooks.d.ts

@@ -1,6 +1,6 @@
 import type { ClaudeJsonResource } from '../compatibility/claude/shared-resources.js';
 import type { PermissionBehavior } from '../core/runtime.js';
-export type ClaudeHookEventName = 'Setup' | 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PostToolUse' | 'PostToolUseFailure' | 'Stop' | 'SessionEnd';
+export type ClaudeHookEventName = 'Setup' | 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PostToolUse' | 'PostToolUseFailure' | 'Stop' | 'SubagentStop' | 'SessionEnd';
 export interface ClaudeHookInput extends Record<string, unknown> {
     session_id: string;
     transcript_path: string;
@@ -79,7 +79,9 @@ export declare class ClaudeHookRunner {
     private readonly maxTimeoutMs;
     private readonly executeCommand;
     private readonly onEvent;
+    private readonly cwd;
     constructor(options: ClaudeHookRunnerOptions);
+    withAdditionalSettings(settings: readonly ClaudeJsonResource[]): ClaudeHookRunner;
     run(input: ClaudeHookInput, matcherValue?: string, signal?: AbortSignal): Promise<ClaudeHookOutcome>;
     private runCommand;
 }

package/dist/hooks/claude-hooks.js

@@ -7,12 +7,14 @@ const KILL_GRACE_MS = 250;
 const HOOK_EVENTS = [
     'Setup',
     'SessionStart',
+    'SubagentStart',
     'UserPromptSubmit',
     'PreToolUse',
     'PermissionRequest',
     'PostToolUse',
     'PostToolUseFailure',
     'Stop',
+    'SubagentStop',
     'SessionEnd',
 ];
 function isRecord(value) {
@@ -137,12 +139,24 @@ export class ClaudeHookRunner {
     maxTimeoutMs;
     executeCommand;
     onEvent;
+    cwd;
     constructor(options) {
         this.settings = options.settings;
         this.maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
         this.maxTimeoutMs = options.maxTimeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.executeCommand = options.executeCommand ?? this.runCommand.bind(this);
         this.onEvent = options.onEvent;
+        this.cwd = options.cwd;
+    }
+    withAdditionalSettings(settings) {
+        return new ClaudeHookRunner({
+            settings: [...this.settings, ...settings],
+            maxOutputBytes: this.maxOutputBytes,
+            maxTimeoutMs: this.maxTimeoutMs,
+            executeCommand: this.executeCommand,
+            ...(this.onEvent ? { onEvent: this.onEvent } : {}),
+            cwd: this.cwd,
+        });
     }
     async run(input, matcherValue, signal) {
         if (signal?.aborted)