praxis-agent 0.13.0 → 0.15.0

package/README.md

@@ -94,8 +94,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   `/background` terminal handoff, unified `/status`/`/config`/`/usage` settings
   tabs, `/sandbox` mode/dependency/override/config controls, local cached
   `/release-notes`, Claude-compatible `/statusline` command execution and setup
-  agent, `/mcp`, `/memory` shared instruction and auto-memory access, and live
-  extension-reload controls,
+  agent, source-aligned `/init` project-instruction onboarding with its enhanced
+  skills/hooks flow, `/mcp`, `/memory` shared instruction and auto-memory
+  access, and live extension-reload controls,
   cursor/history composer, per-session model/effort/permission controls,
   context/status/skill/task dashboards, prompt stash and continuation shortcuts,
   filterable `@` file and agent references, composer undo, `Ctrl+G` external
@@ -136,7 +137,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   workspace-directory add/remove controls, path confinement, credential
   redaction, and sanitized child processes.
 - **Durable local work** — resumable sessions, full-history forks, file
-  checkpoints, tasks, foreground/background subagents, and top-level agents.
+  checkpoints, tasks, foreground/background subagents, top-level agents, and
+  Claude-compatible main-thread agent definitions with native prompt, model,
+  tool, memory, first-turn, and resume behavior.
 - **Claude-compatible ecosystem** — shared instructions with recursive `@`
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and transcript data.
@@ -184,8 +187,9 @@ for exact shared data, version boundaries, exclusions, and verification gates.
 
 Praxis targets one local OS user working across multiple repositories and
 sessions. It is CLI-only and provider-capability-aware. Organization, tenant,
-RBAC, billing, enterprise gateway, IDE, Chrome, Remote Control, Claude Desktop
-import, and hosted review-product surfaces are permanent non-goals.
+RBAC, subscription authentication and billing, enterprise gateway,
+IDE/Desktop/mobile clients, Remote Control, Claude Desktop import, and hosted
+review-product surfaces are permanent non-goals.
 
 ## Security and support
 

package/dist/application/session-service.d.ts

@@ -24,6 +24,7 @@ export interface ClaudeSessionServiceOptions {
     tools?: ToolRegistry;
     permissions?: PermissionResolver;
     permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
+    permissionMode?: ClaudePermissionMode;
     persistPermissionUpdates?: (updates: readonly PermissionUpdate[]) => void | Promise<void>;
     approveTool?: (call: ModelToolCall, originalCall?: ModelToolCall, decision?: PermissionDecision) => PermissionApproval | Promise<PermissionApproval>;
     approveRecovery?: (call: ModelToolCall) => boolean | Promise<boolean>;
@@ -43,6 +44,11 @@ export interface ClaudeSessionServiceOptions {
     enableDynamicWakeups?: boolean;
     enableWorkflows?: boolean;
     providerForModel?: (model: string) => ModelProvider;
+    providerForMainModel?: (model: string) => ModelProvider;
+    explicitModel?: boolean;
+    explicitSystemPrompt?: boolean;
+    agentInitialPromptHandledExternally?: boolean;
+    agentSystemPromptOverridesExplicit?: boolean;
     effort?: string;
     maxModelTurns?: number;
     betas?: readonly string[];
@@ -149,6 +155,7 @@ export declare class ClaudeSessionService {
     private readonly hostedSubagentsByRegistry;
     private readonly backgroundNotificationWrites;
     private readonly downloadedFileResourceSessions;
+    private activeProvider;
     private mcpClosePromise;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
@@ -221,6 +228,11 @@ export declare class ClaudeSessionService {
     private assertWritable;
     private sessionStatus;
     private provider;
+    model(): string | undefined;
+    private providerForAgent;
+    private resolveAgent;
+    private mainAgentSystemPrompt;
+    private assembledSystemMessages;
     private contextBudget;
     private append;
     private logicalTailUuid;

package/dist/application/session-service.js

@@ -22,7 +22,7 @@ import { ClaudeHookToolCoordinator } from '../hooks/claude-hook-tools.js';
 import { ClaudeTranscriptStore, } from '../persistence/claude-transcript-store.js';
 import { InMemoryTranscriptStore } from '../persistence/in-memory-transcript-store.js';
 import { ModelCompactor } from './model-compactor.js';
-import { ClaudeSubagentExecutor, StructuredOutputRegistry, } from './subagent-service.js';
+import { agentMemoryPrompt, ClaudeSubagentExecutor, StructuredOutputRegistry, } from './subagent-service.js';
 import { ScheduledPromptManager } from './scheduled-prompt-manager.js';
 import { ClaudeScheduledToolRegistry } from '../tools/claude-scheduled-tools.js';
 import { ClaudeTaskToolRegistry } from '../tools/claude-task-tools.js';
@@ -30,8 +30,29 @@ import { ClaudeWorkflowToolRegistry } from '../tools/claude-workflow-tools.js';
 import { WorkflowManager, } from './workflow-manager.js';
 import { SessionWorktreeManager } from './session-worktree.js';
 import { ClaudeWorktreeToolRegistry } from '../tools/claude-worktree-tools.js';
+import { FilteredToolRegistry } from '../tools/filtered-tool-registry.js';
 import { generateToolUseSummary } from './tool-use-summary.js';
 import { ClaudeUserMessageToolRegistry, CLAUDE_USER_MESSAGE_PROMPT, } from '../tools/claude-user-message.js';
+function agentPermissionMode(mode) {
+    return mode === undefined || mode === 'manual' ? 'default' : mode;
+}
+function agentToolName(rule) {
+    const opening = rule.indexOf('(');
+    return (opening < 0 ? rule : rule.slice(0, opening)).trim();
+}
+function mainAgentToolNames(tools, agent) {
+    const requested = agent.tools ? new Set(agent.tools.map(agentToolName)) : null;
+    if (requested && agent.memory) {
+        requested.add('Read');
+        requested.add('Edit');
+        requested.add('Write');
+    }
+    const disallowed = new Set(agent.disallowedTools?.map(agentToolName) ?? []);
+    return tools
+        .definitions()
+        .map(({ name }) => name)
+        .filter((name) => (!requested || requested.has(name)) && !disallowed.has(name));
+}
 const emptyToolRegistry = {
     definitions: () => [],
     prepare: async (call) => call,
@@ -97,6 +118,7 @@ export class ClaudeSessionService {
     hostedSubagentsByRegistry = new WeakMap();
     backgroundNotificationWrites = new Map();
     downloadedFileResourceSessions = new Set();
+    activeProvider;
     mcpClosePromise;
     runtimeCwd;
     constructor(options) {
@@ -127,6 +149,12 @@ export class ClaudeSessionService {
                         : {}),
                 })
                 : null;
+        const configuredAgent = options.agent
+            ? (options.extensions?.agent(options.agent) ?? null)
+            : null;
+        if (configuredAgent && options.provider) {
+            this.activeProvider = this.providerForAgent(configuredAgent);
+        }
     }
     nextScheduledPrompt(signal) {
         return this.scheduledPrompts?.next(signal) ?? Promise.resolve(null);
@@ -240,12 +268,15 @@ export class ClaudeSessionService {
                         permissionResolverForMode: this.options.permissionResolverForMode,
                     }
                     : {}),
+                parentPermissionMode: () => agentPermissionMode(this.options.interactiveTools?.mode(sessionId) ??
+                    this.options.permissionMode),
                 ...(this.options.subagentToolNames
                     ? { toolNames: this.options.subagentToolNames }
                     : {}),
                 ...(this.options.extensions
                     ? { extensions: this.options.extensions }
                     : {}),
+                ...(this.options.mcp ? { mcp: this.options.mcp } : {}),
                 ...(this.options.hooks ? { hooks: this.options.hooks } : {}),
                 ...(this.options.contextAssembler
                     ? { contextAssembler: this.options.contextAssembler }
@@ -501,7 +532,6 @@ export class ClaudeSessionService {
         return { agentId, name };
     }
     async promptSuggestion(sessionId, signal) {
-        const provider = this.provider();
         const loaded = this.options.sessionPersistence === false
             ? await this.turnStore(sessionId).withLease((lease) => lease.load())
             : {
@@ -513,20 +543,19 @@ export class ClaudeSessionService {
         const entries = loaded.value;
         this.restoreWorktree(entries.entries);
         const agentName = this.options.agent ?? getClaudeAgentSetting(entries.entries);
-        const agent = agentName ? this.options.extensions?.agent(agentName) : null;
+        const agent = this.resolveAgent(agentName);
+        const provider = this.providerForAgent(agent);
+        this.activeProvider = provider;
         const assembledContext = await this.options.contextAssembler?.assemble({
             cwd: this.activeCwd(),
         });
+        const agentSystem = await this.mainAgentSystemPrompt(agent);
+        const assembledSystemMessages = this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
         const contextMessages = [
-            ...(assembledContext?.systemMessages ?? []),
-            ...(agent
-                ? [
-                    {
-                        role: 'system',
-                        content: `# Agent definition: ${agent.name}\n\n${agent.body}`,
-                    },
-                ]
+            ...(agentSystem
+                ? [{ role: 'system', content: agentSystem }]
                 : []),
+            ...assembledSystemMessages,
         ];
         const messages = [
             ...contextMessages,
@@ -535,11 +564,16 @@ export class ClaudeSessionService {
                 { role: 'user', content: PROMPT_SUGGESTION_INSTRUCTION },
             ], assembledContext?.firstUserMessageContext),
         ];
+        const suggestionTools = agent && this.options.tools
+            ? new FilteredToolRegistry(this.options.tools, {
+                tools: mainAgentToolNames(this.options.tools, agent),
+            })
+            : this.options.tools;
         let suggestion = '';
         for await (const event of provider.complete({
             messages,
             ...(provider.capabilities.tools
-                ? { tools: this.options.tools?.definitions() ?? [] }
+                ? { tools: suggestionTools?.definitions() ?? [] }
                 : {}),
             ...(this.options.effort ? { effort: this.options.effort } : {}),
             ...(signal ? { signal } : {}),
@@ -1332,7 +1366,17 @@ export class ClaudeSessionService {
                     tail: appendResult.tail,
                 };
             }
-            const provider = this.provider();
+            const agentName = this.options.agent ?? getClaudeAgentSetting(snapshot.entries);
+            const agent = this.resolveAgent(agentName);
+            const provider = this.providerForAgent(agent);
+            this.activeProvider = provider;
+            const effectivePrompt = !requireExisting &&
+                !skipUserPrompt &&
+                !this.options.agentInitialPromptHandledExternally &&
+                shellCommand === undefined &&
+                agent?.initialPrompt
+                ? `${agent.initialPrompt}\n\n${prompt}`
+                : prompt;
             const initialPricing = this.options.pricing?.resolve(provider.model ?? 'praxis/provider');
             if (this.options.maxBudgetUsd !== undefined && !initialPricing) {
                 throw new Error(`Cannot enforce --max-budget-usd: no pricing is configured for model ${provider.model ?? 'praxis/provider'}`);
@@ -1450,12 +1494,15 @@ export class ClaudeSessionService {
                             permissionResolverForMode: this.options.permissionResolverForMode,
                         }
                         : {}),
+                    parentPermissionMode: () => agentPermissionMode(this.options.interactiveTools?.mode(sessionId) ??
+                        this.options.permissionMode),
                     ...(this.options.subagentToolNames
                         ? { toolNames: this.options.subagentToolNames }
                         : {}),
                     ...(this.options.extensions
                         ? { extensions: this.options.extensions }
                         : {}),
+                    ...(this.options.mcp ? { mcp: this.options.mcp } : {}),
                     ...(this.options.hooks ? { hooks: this.options.hooks } : {}),
                     ...(this.options.contextAssembler
                         ? { contextAssembler: this.options.contextAssembler }
@@ -1498,7 +1545,7 @@ export class ClaudeSessionService {
                     promptIdForCall: (callId) => currentPromptId ??
                         this.promptIdForToolCall(snapshot.entries, callId),
                     defaultModel: provider.model ?? 'praxis/provider',
-                    tokenBudget: workflowTokenTarget(prompt),
+                    tokenBudget: workflowTokenTarget(effectivePrompt),
                     enabled: true,
                 })
                 : agentTools;
@@ -1575,9 +1622,14 @@ export class ClaudeSessionService {
             const structuredCapture = this.options.structuredOutputSchema
                 ? { calls: 0, value: undefined }
                 : undefined;
-            const structuredTools = this.options.structuredOutputSchema && structuredCapture
-                ? new StructuredOutputRegistry(fileHistoryTools ?? this.options.tools ?? emptyToolRegistry, this.options.structuredOutputSchema, structuredCapture)
+            const agentScopedTools = agent && fileHistoryTools
+                ? new FilteredToolRegistry(fileHistoryTools, {
+                    tools: mainAgentToolNames(fileHistoryTools, agent),
+                })
                 : fileHistoryTools;
+            const structuredTools = this.options.structuredOutputSchema && structuredCapture
+                ? new StructuredOutputRegistry(agentScopedTools ?? this.options.tools ?? emptyToolRegistry, this.options.structuredOutputSchema, structuredCapture)
+                : agentScopedTools;
             const hookTools = this.options.hooks && structuredTools && turnPermissions
                 ? new ClaudeHookToolCoordinator({
                     tools: structuredTools,
@@ -1768,14 +1820,8 @@ export class ClaudeSessionService {
                     inputTokens: usage.inputTokens + (result.usage?.inputTokens ?? 0),
                     outputTokens: usage.outputTokens + (result.usage?.outputTokens ?? 0),
                 }), { inputTokens: 0, outputTokens: 0 });
-                const agentName = this.options.agent ?? getClaudeAgentSetting(snapshot.entries);
-                const agent = agentName
-                    ? this.options.extensions?.agent(agentName)
-                    : null;
-                if (agentName && !agent) {
-                    throw new Error(`Unknown Claude agent ${agentName}`);
-                }
                 if (this.options.agent &&
+                    agent &&
                     getClaudeAgentSetting(snapshot.entries) !== this.options.agent) {
                     const agentSetting = createClaudeAgentSettingEntry(sessionId, this.options.agent);
                     const settingTail = await this.append(lease, snapshot.tail, agentSetting);
@@ -1787,9 +1833,14 @@ export class ClaudeSessionService {
                 const assembledContext = await this.options.contextAssembler?.assemble({
                     cwd: this.activeCwd(),
                 });
+                const agentSystem = await this.mainAgentSystemPrompt(agent);
+                const assembledSystemMessages = this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
                 const planModeMessage = this.options.interactiveTools?.contextMessage(sessionId);
                 const contextMessages = [
-                    ...(assembledContext?.systemMessages ?? []),
+                    ...(agentSystem
+                        ? [{ role: 'system', content: agentSystem }]
+                        : []),
+                    ...assembledSystemMessages,
                     ...(planModeMessage
                         ? [{ role: 'system', content: planModeMessage }]
                         : []),
@@ -1801,14 +1852,6 @@ export class ClaudeSessionService {
                             },
                         ]
                         : []),
-                    ...(agent
-                        ? [
-                            {
-                                role: 'system',
-                                content: `# Agent definition: ${agent.name}\n\n${agent.body}`,
-                            },
-                        ]
-                        : []),
                     ...(this.options.structuredOutputSchema
                         ? [
                             {
@@ -1822,8 +1865,8 @@ export class ClaudeSessionService {
                     ? { userMessages: [] }
                     : shellCommand === undefined
                         ? this.options.extensions
-                            ? await this.options.extensions.expandPromptAsync(prompt, signal, toolResultDirectory)
-                            : { userMessages: [prompt] }
+                            ? await this.options.extensions.expandPromptAsync(effectivePrompt, signal, toolResultDirectory)
+                            : { userMessages: [effectivePrompt] }
                         : {
                             userMessages: [`<bash-input>${shellCommand}</bash-input>`],
                         };
@@ -1864,7 +1907,8 @@ export class ClaudeSessionService {
                         : {}),
                 }));
                 const agentMentionMessages = shellCommand === undefined && !skipUserPrompt
-                    ? (this.options.extensions?.agentMentionMessages(prompt) ?? [])
+                    ? (this.options.extensions?.agentMentionMessages(effectivePrompt) ??
+                        [])
                     : [];
                 const injectAgentMentionContext = (messages) => {
                     if (agentMentionMessages.length === 0)
@@ -1875,7 +1919,7 @@ export class ClaudeSessionService {
                         const message = messages[index];
                         if (message?.role === 'user' &&
                             typeof message.content === 'string' &&
-                            message.content.endsWith(prompt)) {
+                            message.content.endsWith(effectivePrompt)) {
                             insertionIndex = index;
                             foundPrompt = true;
                             break;
@@ -2073,7 +2117,7 @@ export class ClaudeSessionService {
                         ...hookSession,
                         hook_event_name: 'UserPromptSubmit',
                         prompt_id: currentPromptId ?? randomUUID(),
-                        prompt,
+                        prompt: effectivePrompt,
                     }, undefined, signal);
                     await recordHookOutcome(outcome);
                     if (outcome.blockedReason) {
@@ -2252,7 +2296,7 @@ export class ClaudeSessionService {
                 if (!skipUserPrompt) {
                     await this.append(lease, snapshot.tail, createClaudeLastPromptEntry({
                         sessionId,
-                        lastPrompt: prompt,
+                        lastPrompt: effectivePrompt,
                         leafUuid: finalLeafUuid,
                     }));
                 }
@@ -2865,6 +2909,42 @@ export class ClaudeSessionService {
         }
         return this.options.provider;
     }
+    model() {
+        return this.activeProvider?.model ?? this.options.provider?.model;
+    }
+    providerForAgent(agent) {
+        const inherited = this.provider();
+        const selectProvider = this.options.providerForMainModel ?? this.options.providerForModel;
+        if (this.options.explicitModel ||
+            !agent?.model ||
+            agent.model === 'inherit' ||
+            !selectProvider) {
+            return inherited;
+        }
+        return selectProvider(agent.model);
+    }
+    resolveAgent(name) {
+        if (!name)
+            return null;
+        return this.options.extensions?.agent(name) ?? null;
+    }
+    async mainAgentSystemPrompt(agent) {
+        if (!agent ||
+            (this.options.explicitSystemPrompt &&
+                !this.options.agentSystemPromptOverridesExplicit)) {
+            return null;
+        }
+        const memory = await agentMemoryPrompt(this.options.configRoot, this.activeCwd(), agent);
+        const system = memory ? `${agent.body}\n\n${memory}` : agent.body;
+        return system.trim() ? system : null;
+    }
+    assembledSystemMessages(agent, messages) {
+        return agent &&
+            this.options.explicitSystemPrompt &&
+            this.options.agentSystemPromptOverridesExplicit
+            ? messages.slice(1)
+            : messages;
+    }
     contextBudget(provider) {
         if (this.options.contextBudget)
             return this.options.contextBudget;

package/dist/application/subagent-service.d.ts

@@ -1,8 +1,9 @@
 import { type ClaudeSidechainPermissionMode } from '../compatibility/claude/sidechain.js';
 import { type ContextAssembler } from '../core/context.js';
 import { type ModelProvider, type ModelToolCall, type ModelToolDefinition, type ModelUsage, type PermissionResolver, type PermissionApproval, type PermissionDecision, type PermissionUpdate, type RuntimeEventSink, type ToolExecutionContext, type ToolExecutionResult, type ToolRegistry } from '../core/runtime.js';
-import { type ClaudeExtensionCatalog } from '../extensions/claude-extensions.js';
+import { type ClaudeAgentRuntimeDefinition, type ClaudeExtensionCatalog } from '../extensions/claude-extensions.js';
 import type { ClaudeHookRunner } from '../hooks/claude-hooks.js';
+import type { ClaudeMcpRuntime } from '../mcp/claude-mcp-tools.js';
 import { type BackgroundAgentSnapshot } from './background-agent-manager.js';
 export interface WorkflowAgentRunOptions {
     sessionId: string;
@@ -43,6 +44,7 @@ export declare class StructuredOutputRegistry implements ToolRegistry {
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
 }
+export declare function agentMemoryPrompt(configRoot: string, cwd: string, definition: ClaudeAgentRuntimeDefinition | null): Promise<string | null>;
 export interface ClaudeSubagentExecutorOptions {
     configRoot: string;
     cwd: string;
@@ -52,7 +54,9 @@ export interface ClaudeSubagentExecutorOptions {
     baseTools: ToolRegistry;
     permissions: PermissionResolver;
     permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
+    parentPermissionMode?: () => AgentPermissionMode;
     extensions?: ClaudeExtensionCatalog;
+    mcp?: ClaudeMcpRuntime;
     hooks?: ClaudeHookRunner;
     contextAssembler?: ContextAssembler;
     contextReserveTokens?: number;
@@ -80,6 +84,8 @@ export declare class ClaudeSubagentExecutor {
     backgroundSnapshots(): readonly BackgroundAgentSnapshot[];
     stopBackgroundTask(taskId: string): string;
     private cwd;
+    private agentDefinition;
+    private resolveAgentInput;
     registry(sessionId: string, depth: number, promptIdForCall: (callId: string) => string | null): ToolRegistry;
     definitions(): ModelToolDefinition;
     managementDefinitions(): readonly ModelToolDefinition[];