praxis-agent 0.28.0 → 0.29.0

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

@@ -208,6 +208,7 @@ export declare class ClaudeSessionService {
     private applyPermissionUpdates;
     close(): Promise<void>;
     transitionHookSession(sessionId: string, reason: Exclude<HookSessionEndReason, 'other'>): Promise<void>;
+    reloadContextResources(sessionId: string): void;
     createHostedToolRegistry(sessionId: string): ToolRegistry;
     run(prompt: string, signal?: AbortSignal, sessionId?: string, name?: string, images?: readonly ModelImage[], documents?: readonly ModelDocument[]): Promise<SessionRunResult>;
     runShell(command: string, signal?: AbortSignal, sessionId?: string, name?: string): Promise<SessionRunResult>;

package/dist/application/session-service.js

@@ -756,6 +756,16 @@ export class ClaudeSessionService {
     }
     async transitionHookSession(sessionId, reason) {
         await this.hookLifecycle.transition(sessionId, reason);
+        this.options.contextAssembler?.invalidate?.({
+            lifecycleId: sessionId,
+            reason: reason === 'resume' ? 'restore' : 'clear',
+        });
+    }
+    reloadContextResources(sessionId) {
+        this.options.contextAssembler?.invalidate?.({
+            lifecycleId: sessionId,
+            reason: 'resource-reload',
+        });
     }
     createHostedToolRegistry(sessionId) {
         const baseTools = this.options.tools;
@@ -996,6 +1006,7 @@ export class ClaudeSessionService {
         }
         const assembledContext = await this.options.contextAssembler?.assemble({
             cwd: this.activeCwd(),
+            lifecycleId: activeSessionId,
         });
         const messages = [
             ...(assembledContext?.systemMessages ?? []),
@@ -1106,13 +1117,18 @@ export class ClaudeSessionService {
         const agent = this.resolveAgent(agentName);
         const provider = this.providerForAgent(agent);
         this.activeProvider = provider;
+        const agentSystem = await this.mainAgentSystemPrompt(agent);
         const assembledContext = await this.options.contextAssembler?.assemble({
             cwd: this.activeCwd(),
+            lifecycleId: sessionId,
+            ...(agentSystem ? { mode: 'agent', baseSystemPrompt: agentSystem } : {}),
         });
-        const agentSystem = await this.mainAgentSystemPrompt(agent);
-        const assembledSystemMessages = this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
+        const hasPromptManifest = assembledContext?.promptSections !== undefined;
+        const assembledSystemMessages = hasPromptManifest
+            ? (assembledContext?.systemMessages ?? [])
+            : this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
         const contextMessages = [
-            ...(agentSystem
+            ...(!hasPromptManifest && agentSystem
                 ? [{ role: 'system', content: agentSystem }]
                 : []),
             ...assembledSystemMessages,
@@ -1410,12 +1426,22 @@ export class ClaudeSessionService {
             this.sessionCwds.set(sessionId, cwd);
             this.runtimeCwd = cwd;
             this.options.workspace?.setCwd(cwd);
+            this.options.contextAssembler?.invalidate?.({
+                lifecycleId: sessionId,
+                reason: 'cwd',
+            });
             return cwd;
         }
         this.runtimeCwd = cwd;
         this.options.workspace?.setCwd(cwd);
         if (sessionId)
             this.sessionCwds.set(sessionId, cwd);
+        if (sessionId) {
+            this.options.contextAssembler?.invalidate?.({
+                lifecycleId: sessionId,
+                reason: 'cwd',
+            });
+        }
         return cwd;
     }
     async recordCdUsage(sessionId) {
@@ -1791,6 +1817,10 @@ export class ClaudeSessionService {
         if (result.status === 'conflict') {
             throw new Error('Generated Claude fork session already exists');
         }
+        this.options.contextAssembler?.invalidate?.({
+            lifecycleId: sessionId,
+            reason: 'fork',
+        });
         return { sessionId, parentSessionId };
     }
     async ensureFork(parentSessionId, sessionId, checkpoint) {
@@ -1799,8 +1829,13 @@ export class ClaudeSessionService {
         const expected = await this.nativeForkEntries(parentSessionId, sessionId, checkpoint?.resumeSessionAt, checkpoint?.entryCount);
         const target = this.store(sessionId);
         const created = await target.create(expected);
-        if (created.status === 'created')
+        if (created.status === 'created') {
+            this.options.contextAssembler?.invalidate?.({
+                lifecycleId: sessionId,
+                reason: 'fork',
+            });
             return { sessionId, parentSessionId };
+        }
         const existing = await target.withLease((lease) => lease.load());
         if (existing.status === 'conflict') {
             throw new Error(`Claude transcript fork conflict: ${existing.reason}`);
@@ -1810,6 +1845,10 @@ export class ClaudeSessionService {
                 JSON.stringify(entry))) {
             throw new Error('Claude handoff target is not the expected native fork');
         }
+        this.options.contextAssembler?.invalidate?.({
+            lifecycleId: sessionId,
+            reason: 'fork',
+        });
         return { sessionId, parentSessionId };
     }
     async nativeForkEntries(parentSessionId, sessionId, resumeSessionAt, sourceEntryCount) {
@@ -2442,6 +2481,10 @@ export class ClaudeSessionService {
                     currentTurnToolCalls += 1;
                     const transition = this.worktreeManager?.consumeTransition(call.id);
                     if (transition) {
+                        this.options.contextAssembler?.invalidate?.({
+                            lifecycleId: sessionId,
+                            reason: 'worktree',
+                        });
                         const stateEntry = {
                             type: 'worktree-state',
                             worktreeSession: transition.state,
@@ -2584,29 +2627,83 @@ export class ClaudeSessionService {
                 let planModeMessage;
                 let sessionMemoryMessage = null;
                 let contextMessages = [];
+                let stableSystemMessageCount;
                 const refreshRuntimeContext = async () => {
-                    assembledContext = await this.options.contextAssembler?.assemble({
-                        cwd: this.activeCwd(),
-                    });
                     agentSystem = await this.mainAgentSystemPrompt(agent);
-                    const assembledSystemMessages = this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
                     planModeMessage =
                         this.options.interactiveTools?.contextMessage(sessionId);
                     sessionMemoryMessage = sessionMemory
                         ? this.sessionMemoryMessage(await sessionMemory.summary())
                         : null;
-                    contextMessages = [
+                    const additionalSections = [
+                        ...(planModeMessage
+                            ? [
+                                {
+                                    id: 'plan-mode',
+                                    placement: 'system',
+                                    stability: 'volatile',
+                                    content: planModeMessage,
+                                },
+                            ]
+                            : []),
+                        ...(sessionMemoryMessage
+                            ? [
+                                {
+                                    id: 'session-memory',
+                                    placement: 'system',
+                                    stability: 'volatile',
+                                    content: sessionMemoryMessage,
+                                },
+                            ]
+                            : []),
+                        ...(this.options.brief
+                            ? [
+                                {
+                                    id: 'brief-output',
+                                    placement: 'system',
+                                    stability: 'volatile',
+                                    content: CLAUDE_USER_MESSAGE_PROMPT,
+                                },
+                            ]
+                            : []),
+                        ...(this.options.structuredOutputSchema
+                            ? [
+                                {
+                                    id: 'structured-output',
+                                    placement: 'system',
+                                    stability: 'volatile',
+                                    content: 'You MUST call StructuredOutput exactly once at the end with a value matching the requested JSON Schema.',
+                                },
+                            ]
+                            : []),
+                    ];
+                    assembledContext = await this.options.contextAssembler?.assemble({
+                        cwd: this.activeCwd(),
+                        lifecycleId: sessionId,
                         ...(agentSystem
+                            ? { mode: 'agent', baseSystemPrompt: agentSystem }
+                            : {}),
+                        additionalSections,
+                    });
+                    const hasPromptManifest = assembledContext?.promptSections !== undefined;
+                    stableSystemMessageCount = hasPromptManifest
+                        ? assembledContext?.stableSystemSectionCount
+                        : undefined;
+                    const assembledSystemMessages = hasPromptManifest
+                        ? (assembledContext?.systemMessages ?? [])
+                        : this.assembledSystemMessages(agent, assembledContext?.systemMessages ?? []);
+                    contextMessages = [
+                        ...(!hasPromptManifest && agentSystem
                             ? [{ role: 'system', content: agentSystem }]
                             : []),
                         ...assembledSystemMessages,
-                        ...(planModeMessage
+                        ...(!hasPromptManifest && planModeMessage
                             ? [{ role: 'system', content: planModeMessage }]
                             : []),
-                        ...(sessionMemoryMessage
+                        ...(!hasPromptManifest && sessionMemoryMessage
                             ? [{ role: 'system', content: sessionMemoryMessage }]
                             : []),
-                        ...(this.options.brief
+                        ...(!hasPromptManifest && this.options.brief
                             ? [
                                 {
                                     role: 'system',
@@ -2614,7 +2711,7 @@ export class ClaudeSessionService {
                                 },
                             ]
                             : []),
-                        ...(this.options.structuredOutputSchema
+                        ...(!hasPromptManifest && this.options.structuredOutputSchema
                             ? [
                                 {
                                     role: 'system',
@@ -2915,6 +3012,10 @@ export class ClaudeSessionService {
                         if (outcome)
                             await recordHookOutcome(outcome);
                     }
+                    this.options.contextAssembler?.invalidate?.({
+                        lifecycleId: sessionId,
+                        reason: 'compact',
+                    });
                     await refreshRuntimeContext();
                     this.options.eventSink?.({
                         type: 'compact-boundary',
@@ -3086,6 +3187,9 @@ export class ClaudeSessionService {
                         ...contextMessages,
                         ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
                     ],
+                    ...(stableSystemMessageCount === undefined
+                        ? {}
+                        : { stableSystemMessageCount }),
                     cwd: this.activeCwd(),
                     toolResultDirectory,
                     observer,
@@ -3099,6 +3203,12 @@ export class ClaudeSessionService {
                         : {}),
                     reloadMessages: async () => {
                         await compactIfNeeded([], currentTurnUserMessages ?? []);
+                        if (stableSystemMessageCount === undefined) {
+                            delete runtimeRequest.stableSystemMessageCount;
+                        }
+                        else {
+                            runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
+                        }
                         return [
                             ...contextMessages,
                             ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
@@ -3213,6 +3323,12 @@ export class ClaudeSessionService {
                         ...contextMessages,
                         ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
                     ];
+                    if (stableSystemMessageCount === undefined) {
+                        delete runtimeRequest.stableSystemMessageCount;
+                    }
+                    else {
+                        runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
+                    }
                     try {
                         result = await attemptMainTurn();
                     }

package/dist/application/subagent-service.js

@@ -1493,10 +1493,16 @@ export class ClaudeSubagentExecutor {
             const assembleMessages = async () => {
                 const assembledContext = await this.options.contextAssembler?.assemble({
                     cwd,
+                    lifecycleId: options.agentId,
+                    mode: 'subagent',
+                    baseSystemPrompt: system,
                 });
+                const composedSubagentPolicy = assembledContext?.promptSections?.some((section) => section.id === 'subagent-policy');
                 const messages = [
                     ...(assembledContext?.systemMessages ?? []),
-                    { role: 'system', content: system },
+                    ...(composedSubagentPolicy
+                        ? []
+                        : [{ role: 'system', content: system }]),
                     ...injectFirstUserMessageContext(projectClaudeModelMessages(snapshot.entries), assembledContext?.firstUserMessageContext),
                     ...preloadedSkills,
                 ];

package/dist/cli-runtime.js

@@ -802,12 +802,6 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             ? {}
             : { permissionMode: interactivePermissionMode }),
     }, cwd);
-    const effectiveAppendSystemPrompt = [
-        runtimeSettingsPrompt,
-        cli.appendSystemPrompt,
-    ]
-        .filter((value) => value !== undefined)
-        .join('\n');
     const debug = cli.debug !== undefined || cli.debugFile !== undefined
         ? createCliDebugSink(eventSink, {
             cwd,
@@ -1175,6 +1169,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         });
         return filterDisabledMcpResources(candidates, await management.disabled());
     };
+    let contextAssembler;
     const mcpTools = await ClaudeMcpToolRegistry.connect({
         base: simpleMode
             ? localTools
@@ -1219,6 +1214,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         configRoot,
         onWarning: (message) => runtimeEventSink({ type: 'warning', message }),
         onPromptsChanged: (prompts) => extensions.setMcpPrompts(prompts),
+        onInstructionsChanged: () => contextAssembler?.invalidate({ reason: 'tool-pool' }),
         authenticateServer: async (name) => {
             const record = await new ClaudeMcpManagement({
                 dataPlane,
@@ -1374,6 +1370,54 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                 },
             })
             : undefined;
+        contextAssembler = new ClaudeContextAssembler({
+            loadResources: loadContextResources,
+            loadDynamicContext: (runtimeCwd = workspace.cwd()) => loadClaudeDynamicContext({
+                cwd: runtimeCwd,
+                ...(memoryDirectory ? { memoryDirectory } : {}),
+            }),
+            loadMcpInstructions: async () => mcpTools.instructions(),
+            loadSessionGuidance: async () => {
+                const toolNames = [
+                    ...new Set([
+                        ...filteredTools.definitions().map((definition) => definition.name),
+                        ...selectedTaskRuntimeTools,
+                        ...selectedScheduledTools,
+                        ...selectedWorkflowTools,
+                        ...selectedWorktreeTools,
+                        ...selectedInteractiveTools,
+                        ...(enableSubagents ? selectedAgentTools : []),
+                    ]),
+                ].sort();
+                const skillNames = extensions
+                    .modelInvocableSkills()
+                    .map((skill) => skill.name)
+                    .sort();
+                if (toolNames.length === 0 &&
+                    skillNames.length === 0 &&
+                    runtimeSettingsPrompt === undefined)
+                    return undefined;
+                return [
+                    '# Session capabilities',
+                    ...(toolNames.length > 0
+                        ? [`Enabled tools: ${toolNames.join(', ')}`]
+                        : []),
+                    ...(skillNames.length > 0
+                        ? [`Model-invocable skills: ${skillNames.join(', ')}`]
+                        : []),
+                    'Use a capability only when it directly helps complete the request, and follow its declared input contract.',
+                    ...(runtimeSettingsPrompt ? ['', runtimeSettingsPrompt] : []),
+                ].join('\n');
+            },
+            excludeDynamicSystemPromptSections: cli.excludeDynamicSystemPromptSections,
+            ...(cli.systemPrompt === undefined
+                ? {}
+                : { systemPrompt: cli.systemPrompt }),
+            ...(cli.appendSystemPrompt
+                ? { appendSystemPrompt: cli.appendSystemPrompt }
+                : {}),
+            ...(simpleMode ? { bare: true } : {}),
+        });
         const service = new ClaudeSessionService({
             ...options,
             provider: hostedToolProvider,
@@ -1409,20 +1453,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             ...(interactiveTools ? { interactiveTools } : {}),
             ...(hooks ? { hooks } : {}),
             ...(selectedMainAgent ? { agent: selectedMainAgent } : {}),
-            contextAssembler: new ClaudeContextAssembler({
-                loadResources: loadContextResources,
-                loadDynamicContext: (runtimeCwd = workspace.cwd()) => loadClaudeDynamicContext({
-                    cwd: runtimeCwd,
-                    ...(memoryDirectory ? { memoryDirectory } : {}),
-                }),
-                excludeDynamicSystemPromptSections: cli.excludeDynamicSystemPromptSections,
-                ...(cli.systemPrompt === undefined
-                    ? {}
-                    : { systemPrompt: cli.systemPrompt }),
-                ...(effectiveAppendSystemPrompt
-                    ? { appendSystemPrompt: effectiveAppendSystemPrompt }
-                    : {}),
-            }),
+            contextAssembler,
             conditionalRuleResolver: new ClaudeConditionalRuleResolver({
                 loadResources: loadContextResources,
             }),

package/dist/compatibility/claude/context.d.ts

@@ -1,12 +1,20 @@
-import type { AssembledContext, ContextAssembler } from '../../core/context.js';
+import type { AssembledContext, ContextAssembler, ContextAssemblyOptions, ContextInvalidationOptions } from '../../core/context.js';
 import { type ClaudeDynamicContextSections } from './dynamic-context.js';
 import type { ClaudeContextResources, ClaudeConditionalRule } from './shared-resources.js';
 export interface ClaudeContextAssemblerOptions {
     loadResources(cwd?: string): Promise<ClaudeContextResources>;
     loadDynamicContext?(cwd?: string): Promise<ClaudeDynamicContextSections>;
+    loadMcpInstructions?(): Promise<readonly ClaudeMcpInstruction[]>;
+    loadSessionGuidance?(): Promise<string | undefined>;
     excludeDynamicSystemPromptSections?: boolean;
     systemPrompt?: string;
     appendSystemPrompt?: string;
+    bare?: boolean;
+    now?(): Date;
+}
+export interface ClaudeMcpInstruction {
+    server: string;
+    instructions: string;
 }
 export type ClaudeConditionalRuleResolverOptions = ClaudeContextAssemblerOptions;
 export declare class ClaudeConditionalRuleResolver {
@@ -16,9 +24,16 @@ export declare class ClaudeConditionalRuleResolver {
 }
 export declare class ClaudeContextAssembler implements ContextAssembler {
     private readonly options;
+    private readonly composer;
+    private readonly snapshots;
     constructor(options: ClaudeContextAssemblerOptions);
-    assemble(options?: {
-        cwd?: string;
-    }): Promise<AssembledContext>;
+    assemble(options?: ContextAssemblyOptions): Promise<AssembledContext>;
+    invalidate(options: ContextInvalidationOptions): void;
+    private snapshot;
+    private loadResources;
+    private loadDynamicContext;
+    private loadMcpInstructions;
+    private loadSessionGuidance;
+    private currentDate;
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/compatibility/claude/context.js

@@ -1,4 +1,5 @@
 import { isAbsolute, matchesGlob, relative, resolve, sep } from 'node:path';
+import { PromptComposer, } from '../../core/prompt-composer.js';
 import { renderClaudeDynamicSystemContext, renderClaudeDynamicUserContext, } from './dynamic-context.js';
 function renderResources(title, resources) {
     const rendered = resources
@@ -40,22 +41,32 @@ export class ClaudeConditionalRuleResolver {
 }
 export class ClaudeContextAssembler {
     options;
+    composer = new PromptComposer();
+    snapshots = new Map();
     constructor(options) {
         this.options = options;
     }
     async assemble(options = {}) {
-        const resources = await this.options.loadResources(options.cwd);
+        const snapshot = this.snapshot(options);
+        const mode = options.mode ??
+            (this.options.systemPrompt !== undefined
+                ? 'custom'
+                : this.options.bare
+                    ? 'bare'
+                    : 'default');
+        const resources = mode === 'bare'
+            ? { instructions: [], conditionalRules: [], memoryIndex: null }
+            : await this.loadResources(snapshot, options.cwd);
         const sections = [
             renderResources('Instructions', resources.instructions),
             renderResources('Auto-memory', resources.memoryIndex ? [limitMemoryIndex(resources.memoryIndex)] : []),
         ].filter((section) => section !== null);
-        const messages = [];
-        if (this.options.systemPrompt !== undefined) {
-            messages.push({ role: 'system', content: this.options.systemPrompt });
-        }
+        const sessionSections = [];
         if (sections.length > 0) {
-            messages.push({
-                role: 'system',
+            sessionSections.push({
+                id: 'shared-resources',
+                placement: 'system',
+                stability: 'session',
                 content: `# Shared Claude context
 
 Instructions are ordered from broadest to most specific. Auto-memory is background context and does not override instructions.
@@ -63,36 +74,199 @@ Instructions are ordered from broadest to most specific. Auto-memory is backgrou
 ${sections.join('\n\n')}`,
             });
         }
-        let firstUserMessageContext;
-        if (this.options.systemPrompt === undefined &&
-            this.options.loadDynamicContext !== undefined) {
-            const dynamic = await this.options.loadDynamicContext(options.cwd);
+        const tailSections = [];
+        if (mode !== 'bare') {
+            sessionSections.push({
+                id: 'current-date',
+                placement: 'system',
+                stability: 'session',
+                content: `# Current date\n${this.currentDate(snapshot)}`,
+            });
+        }
+        if (mode !== 'bare') {
+            const guidance = await this.loadSessionGuidance(snapshot);
+            if (guidance?.trim()) {
+                sessionSections.push({
+                    id: 'session-guidance',
+                    placement: 'system',
+                    stability: 'session',
+                    content: guidance,
+                });
+            }
+            const mcpInstructions = await this.loadMcpInstructions(snapshot);
+            tailSections.push(...mcpInstructions
+                .filter(({ instructions }) => instructions.trim().length > 0)
+                .sort((left, right) => left.server.localeCompare(right.server))
+                .map(({ server, instructions }) => ({
+                id: `mcp-instructions:${server}`,
+                placement: 'system',
+                stability: 'volatile',
+                content: `# MCP server instructions: ${server}\n${instructions.trimEnd()}`,
+            })));
+        }
+        if (mode !== 'bare' && this.options.loadDynamicContext !== undefined) {
+            const dynamic = await this.loadDynamicContext(snapshot, options.cwd);
             if (this.options.excludeDynamicSystemPromptSections) {
                 if (dynamic.memory) {
-                    messages.push({ role: 'system', content: dynamic.memory });
+                    sessionSections.push({
+                        id: 'memory-mechanics',
+                        placement: 'system',
+                        stability: 'session',
+                        content: dynamic.memory,
+                    });
                 }
-                firstUserMessageContext = renderClaudeDynamicUserContext({
-                    environment: dynamic.environment,
-                    ...(dynamic.gitStatus ? { gitStatus: dynamic.gitStatus } : {}),
+                tailSections.push({
+                    id: 'relocated-runtime-context',
+                    placement: 'first-user',
+                    stability: 'session',
+                    content: renderClaudeDynamicUserContext({
+                        environment: dynamic.environment,
+                        ...(dynamic.gitStatus ? { gitStatus: dynamic.gitStatus } : {}),
+                    }),
                 });
             }
             else {
-                messages.push({
-                    role: 'system',
+                sessionSections.push({
+                    id: 'runtime-context',
+                    placement: 'system',
+                    stability: 'session',
                     content: renderClaudeDynamicSystemContext(dynamic),
                 });
             }
         }
-        if (this.options.appendSystemPrompt !== undefined) {
-            messages.push({
-                role: 'system',
-                content: this.options.appendSystemPrompt,
-            });
+        for (const section of options.additionalSections ?? []) {
+            const target = section.stability === 'volatile' || section.placement === 'first-user'
+                ? tailSections
+                : sessionSections;
+            target.push(section);
         }
+        const composition = this.composer.compose({
+            mode,
+            ...(options.baseSystemPrompt !== undefined
+                ? { baseSystemPrompt: options.baseSystemPrompt }
+                : this.options.systemPrompt !== undefined
+                    ? { baseSystemPrompt: this.options.systemPrompt }
+                    : {}),
+            ...(this.options.appendSystemPrompt !== undefined
+                ? { appendSystemPrompt: this.options.appendSystemPrompt }
+                : {}),
+            sessionSections,
+            tailSections,
+        });
         return {
-            systemMessages: messages,
-            ...(firstUserMessageContext ? { firstUserMessageContext } : {}),
+            systemMessages: composition.systemMessages,
+            promptSections: composition.sections,
+            stableSystemSectionCount: composition.stableSystemSectionCount,
+            ...(composition.firstUserMessageContext
+                ? { firstUserMessageContext: composition.firstUserMessageContext }
+                : {}),
         };
     }
+    invalidate(options) {
+        for (const [key, snapshot] of this.snapshots) {
+            if (options.lifecycleId !== undefined &&
+                snapshot.lifecycleId !== options.lifecycleId)
+                continue;
+            if (options.reason === 'resource-reload' ||
+                options.reason === 'compact') {
+                delete snapshot.resources;
+                continue;
+            }
+            if (options.reason === 'tool-pool') {
+                delete snapshot.mcpInstructions;
+                delete snapshot.sessionGuidance;
+                continue;
+            }
+            this.snapshots.delete(key);
+        }
+    }
+    snapshot(options) {
+        if (!options.lifecycleId)
+            return undefined;
+        const key = JSON.stringify([options.lifecycleId, options.cwd ?? null]);
+        let snapshot = this.snapshots.get(key);
+        if (!snapshot) {
+            snapshot = {
+                lifecycleId: options.lifecycleId,
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+            };
+            this.snapshots.set(key, snapshot);
+        }
+        return snapshot;
+    }
+    loadResources(snapshot, cwd) {
+        if (!snapshot)
+            return this.options.loadResources(cwd);
+        if (!snapshot.resources) {
+            const pending = this.options.loadResources(cwd);
+            snapshot.resources = pending;
+            void pending.catch(() => {
+                if (snapshot.resources === pending)
+                    delete snapshot.resources;
+            });
+        }
+        return snapshot.resources;
+    }
+    loadDynamicContext(snapshot, cwd) {
+        const load = this.options.loadDynamicContext;
+        if (!load)
+            throw new Error('Dynamic context loader is unavailable');
+        if (!snapshot)
+            return load(cwd);
+        if (!snapshot.dynamic) {
+            const pending = load(cwd);
+            snapshot.dynamic = pending;
+            void pending.catch(() => {
+                if (snapshot.dynamic === pending)
+                    delete snapshot.dynamic;
+            });
+        }
+        return snapshot.dynamic;
+    }
+    loadMcpInstructions(snapshot) {
+        const load = this.options.loadMcpInstructions;
+        if (!load)
+            return Promise.resolve([]);
+        if (!snapshot)
+            return load();
+        if (!snapshot.mcpInstructions) {
+            const pending = load();
+            snapshot.mcpInstructions = pending;
+            void pending.catch(() => {
+                if (snapshot.mcpInstructions === pending)
+                    delete snapshot.mcpInstructions;
+            });
+        }
+        return snapshot.mcpInstructions;
+    }
+    loadSessionGuidance(snapshot) {
+        const load = this.options.loadSessionGuidance;
+        if (!load)
+            return Promise.resolve(undefined);
+        if (!snapshot)
+            return load();
+        if (!snapshot.sessionGuidance) {
+            const pending = load();
+            snapshot.sessionGuidance = pending;
+            void pending.catch(() => {
+                if (snapshot.sessionGuidance === pending)
+                    delete snapshot.sessionGuidance;
+            });
+        }
+        return snapshot.sessionGuidance;
+    }
+    currentDate(snapshot) {
+        if (snapshot?.currentDate)
+            return snapshot.currentDate;
+        const now = (this.options.now ?? (() => new Date()))();
+        const date = [
+            String(now.getFullYear()).padStart(4, '0'),
+            String(now.getMonth() + 1).padStart(2, '0'),
+            String(now.getDate()).padStart(2, '0'),
+        ].join('-');
+        if (snapshot)
+            snapshot.currentDate = date;
+        return date;
+    }
 }
 //# sourceMappingURL=context.js.map

package/dist/core/context.d.ts

@@ -1,16 +1,29 @@
 import type { ModelMessage } from './runtime.js';
+import type { PromptCompositionMode, PromptSection } from './prompt-composer.js';
 export type SystemContextMessage = Extract<ModelMessage, {
     role: 'system';
 }>;
 export interface AssembledContext {
     systemMessages: readonly SystemContextMessage[];
     firstUserMessageContext?: string;
+    promptSections?: readonly PromptSection[];
+    stableSystemSectionCount?: number;
 }
 export interface ContextAssemblyOptions {
     cwd?: string;
+    lifecycleId?: string;
+    mode?: PromptCompositionMode;
+    baseSystemPrompt?: string;
+    additionalSections?: readonly PromptSection[];
+}
+export type ContextInvalidationReason = 'clear' | 'compact' | 'fork' | 'resource-reload' | 'restore' | 'tool-pool' | 'cwd' | 'worktree';
+export interface ContextInvalidationOptions {
+    lifecycleId?: string;
+    reason: ContextInvalidationReason;
 }
 export interface ContextAssembler {
     assemble(options?: ContextAssemblyOptions): Promise<AssembledContext>;
+    invalidate?(options: ContextInvalidationOptions): void;
 }
 export declare function injectFirstUserMessageContext(messages: readonly ModelMessage[], context: string | undefined): ModelMessage[];
 //# sourceMappingURL=context.d.ts.map

package/dist/core/prompt-composer.d.ts

@@ -0,0 +1,27 @@
+import type { SystemContextMessage } from './context.js';
+export type PromptSectionStability = 'static' | 'session' | 'volatile';
+export type PromptSectionPlacement = 'system' | 'first-user';
+export type PromptCompositionMode = 'default' | 'custom' | 'bare' | 'agent' | 'subagent';
+export interface PromptSection {
+    id: string;
+    content: string;
+    stability: PromptSectionStability;
+    placement: PromptSectionPlacement;
+}
+export interface PromptComposition {
+    sections: readonly PromptSection[];
+    systemMessages: readonly SystemContextMessage[];
+    firstUserMessageContext?: string;
+    stableSystemSectionCount: number;
+}
+export interface PromptCompositionOptions {
+    mode: PromptCompositionMode;
+    baseSystemPrompt?: string;
+    appendSystemPrompt?: string;
+    sessionSections?: readonly PromptSection[];
+    tailSections?: readonly PromptSection[];
+}
+export declare class PromptComposer {
+    compose(options: PromptCompositionOptions): PromptComposition;
+}
+//# sourceMappingURL=prompt-composer.d.ts.map

package/dist/core/prompt-composer.js

@@ -0,0 +1,99 @@
+const PRODUCT_POLICY = `# Praxis
+
+You are Praxis, a local CLI coding agent. Work until the user's request is genuinely handled or a concrete blocker requires their input.
+
+- Inspect relevant context before acting and use available tools deliberately.
+- Preserve user data, existing changes, and project-specific instructions.
+- Prefer focused, verifiable changes and report important outcomes clearly.
+- Use a scratch or work area when the runtime provides one; keep temporary artifacts out of the user's project.
+- Summarize or clear bulky intermediate results once their useful facts have been retained.
+- Treat the context window as bounded: preserve decisions and evidence before reducing detail.
+- Keep responses concise and use the user's language unless they request otherwise.`;
+function baseSection(mode, content) {
+    if (mode === 'bare')
+        return undefined;
+    if (mode === 'default') {
+        return {
+            id: 'product-policy',
+            content: PRODUCT_POLICY,
+            placement: 'system',
+            stability: 'static',
+        };
+    }
+    if (content === undefined || content.trim().length === 0) {
+        throw new Error(`${mode} prompt mode requires a base system prompt`);
+    }
+    return {
+        id: mode === 'custom'
+            ? 'custom-system'
+            : mode === 'agent'
+                ? 'agent-policy'
+                : 'subagent-policy',
+        content,
+        placement: 'system',
+        stability: 'session',
+    };
+}
+function normalizedSections(sections, group) {
+    return sections
+        .filter((section) => section.content.trim().length > 0)
+        .map((section) => {
+        if (!section.id.trim())
+            throw new Error('Prompt section id is required');
+        if (group === 'sessionSections' && section.stability === 'volatile') {
+            throw new Error('sessionSections cannot contain volatile prompt sections');
+        }
+        if (group === 'tailSections' &&
+            section.placement === 'system' &&
+            section.stability !== 'volatile') {
+            throw new Error('tailSections system entries must be volatile prompt sections');
+        }
+        return { ...section };
+    });
+}
+export class PromptComposer {
+    compose(options) {
+        const base = baseSection(options.mode, options.baseSystemPrompt);
+        const sessionSections = normalizedSections(options.sessionSections ?? [], 'sessionSections');
+        const append = options.appendSystemPrompt?.trim()
+            ? {
+                id: 'append-system',
+                content: options.appendSystemPrompt,
+                placement: 'system',
+                stability: 'session',
+            }
+            : undefined;
+        const tailSections = normalizedSections(options.tailSections ?? [], 'tailSections');
+        const sections = [
+            ...(base ? [base] : []),
+            ...sessionSections,
+            ...(append ? [append] : []),
+            ...tailSections,
+        ];
+        const identities = new Set();
+        for (const section of sections) {
+            if (identities.has(section.id)) {
+                throw new Error(`Duplicate prompt section ${section.id}`);
+            }
+            identities.add(section.id);
+        }
+        const systemSections = sections.filter((section) => section.placement === 'system');
+        const firstVolatileSystemIndex = systemSections.findIndex((section) => section.stability === 'volatile');
+        const firstUserMessageContext = sections
+            .filter((section) => section.placement === 'first-user')
+            .map((section) => section.content)
+            .join('\n\n');
+        return {
+            sections,
+            systemMessages: systemSections.map((section) => ({
+                role: 'system',
+                content: section.content,
+            })),
+            stableSystemSectionCount: firstVolatileSystemIndex < 0
+                ? systemSections.length
+                : firstVolatileSystemIndex,
+            ...(firstUserMessageContext ? { firstUserMessageContext } : {}),
+        };
+    }
+}
+//# sourceMappingURL=prompt-composer.js.map

package/dist/core/runtime.d.ts

@@ -119,6 +119,8 @@ export type ModelStreamEvent = {
 };
 export interface ModelRequest {
     messages: readonly ModelMessage[];
+    /** Number of leading system messages that form the stable prompt prefix. */
+    stableSystemMessageCount?: number;
     tools?: readonly ModelToolDefinition[];
     webSearch?: ModelWebSearch;
     signal?: AbortSignal;
@@ -450,6 +452,8 @@ export interface AgentRuntimeOptions {
 }
 export interface AgentRunRequest {
     messages: readonly ModelMessage[];
+    /** Number of leading system messages that form the stable prompt prefix. */
+    stableSystemMessageCount?: number;
     cwd?: string;
     toolResultDirectory?: string;
     observer?: AgentRunObserver;

package/dist/core/runtime.js

@@ -342,6 +342,11 @@ export class AgentRuntime {
                 this.emit({ type: 'state', state: 'awaiting-model' });
                 const providerRequest = {
                     messages: prepareProviderMessages(messages, this.provider.capabilities.images === true, this.provider.capabilities.documents === true),
+                    ...(request.stableSystemMessageCount === undefined
+                        ? {}
+                        : {
+                            stableSystemMessageCount: request.stableSystemMessageCount,
+                        }),
                 };
                 if (definitions.length > 0)
                     providerRequest.tools = definitions;

package/dist/mcp/claude-mcp-tools.d.ts

@@ -35,6 +35,7 @@ export interface ClaudeMcpRuntime {
     authenticate(name: string): Promise<void>;
     reload(): Promise<void>;
     tools(name: string): Promise<readonly ClaudeMcpToolInspection[]>;
+    instructions?(): readonly ClaudeMcpServerInstruction[];
     connectAgent?(options: {
         specs: readonly unknown[];
         base: ToolRegistry;
@@ -47,6 +48,10 @@ export interface ClaudeMcpRuntime {
     /** Release MCP transports and child processes owned by this runtime. */
     close?(): Promise<void>;
 }
+export interface ClaudeMcpServerInstruction {
+    server: string;
+    instructions: string;
+}
 export interface ClaudeMcpConfigurationStatus {
     name: string;
     path: string;
@@ -67,6 +72,7 @@ export interface ClaudeMcpToolRegistryOptions {
     signal?: AbortSignal;
     eventSink?: RuntimeEventSink;
     onPromptsChanged?: (prompts: readonly ClaudeMcpPromptDefinition[]) => void;
+    onInstructionsChanged?: (instructions: readonly ClaudeMcpServerInstruction[]) => void;
     authenticateServer?: (name: string) => Promise<void>;
     reloadResources?: () => Promise<readonly ClaudeJsonResource[]>;
     onElicitation?: (request: {
@@ -93,6 +99,7 @@ export declare class ClaudeMcpToolRegistry implements ToolRegistry, ClaudeMcpRun
     private readonly serverClients;
     private readonly reconnectableServers;
     private readonly serverCapabilities;
+    private readonly serverInstructions;
     private readonly reconnectingServers;
     private readonly promptOperations;
     private promptResultDirectoryPromise;
@@ -104,6 +111,7 @@ export declare class ClaudeMcpToolRegistry implements ToolRegistry, ClaudeMcpRun
     definitions(): readonly ModelToolDefinition[];
     schedulingPolicy(call: ModelToolCall): import("../core/runtime.js").ToolSchedulingPolicy;
     serverStatuses(): readonly ClaudeMcpServerStatus[];
+    instructions(): readonly ClaudeMcpServerInstruction[];
     inspect(): Promise<readonly ClaudeMcpServerStatus[]>;
     reconnect(name: string): Promise<void>;
     authenticate(name: string): Promise<void>;
@@ -137,6 +145,7 @@ export declare class ClaudeMcpToolRegistry implements ToolRegistry, ClaudeMcpRun
     private ensurePromptConnected;
     private reconnectServer;
     private publishPrompts;
+    private publishInstructions;
     private assertOpenGeneration;
     private trackPromptOperation;
     private promptResultDirectory;

package/dist/mcp/claude-mcp-tools.js

@@ -680,6 +680,7 @@ export class ClaudeMcpToolRegistry {
     serverClients = new Map();
     reconnectableServers = new Map();
     serverCapabilities = new Map();
+    serverInstructions = new Map();
     reconnectingServers = new Map();
     promptOperations = new Set();
     promptResultDirectoryPromise;
@@ -732,6 +733,11 @@ export class ClaudeMcpToolRegistry {
             status,
         }));
     }
+    instructions() {
+        return [...this.serverInstructions]
+            .map(([server, instructions]) => ({ server, instructions }))
+            .sort((left, right) => left.server.localeCompare(right.server));
+    }
     async inspect() {
         return this.runtimeStatuses();
     }
@@ -763,6 +769,7 @@ export class ClaudeMcpToolRegistry {
         this.statuses.clear();
         this.reconnectableServers.clear();
         this.serverCapabilities.clear();
+        this.serverInstructions.clear();
         const ambientSensitiveValues = sensitiveEnvironmentValues(process.env);
         const warn = (message) => this.options.onWarning?.(redactSensitiveText(message, ambientSensitiveValues));
         await this.configure(this.options.reloadResources
@@ -962,6 +969,7 @@ export class ClaudeMcpToolRegistry {
         await Promise.allSettled([...this.clients].map((client) => client.close()));
         this.clients.clear();
         this.serverClients.clear();
+        this.serverInstructions.clear();
         const directory = await this.promptResultDirectoryPromise?.catch(() => undefined);
         if (directory)
             await rm(directory, { recursive: true, force: true });
@@ -1052,7 +1060,9 @@ export class ClaudeMcpToolRegistry {
             if (this.closed || this.serverClients.get(serverName) !== client)
                 return;
             this.serverCapabilities.delete(serverName);
+            this.serverInstructions.delete(serverName);
             this.statuses.set(serverName, { name: serverName, status: 'failed' });
+            this.publishInstructions();
         };
         client.setRequestHandler(ElicitRequestSchema, async (request) => {
             if (!this.options.onElicitation)
@@ -1131,6 +1141,13 @@ export class ClaudeMcpToolRegistry {
                 ...(capabilities?.resources ? ['resources'] : []),
                 ...(capabilities?.prompts ? ['prompts'] : []),
             ]);
+            const serverInstruction = client.getInstructions()?.trim();
+            if (serverInstruction) {
+                this.serverInstructions.set(serverName, redactSensitiveText(serverInstruction, sensitiveValues));
+            }
+            else {
+                this.serverInstructions.delete(serverName);
+            }
             for (const [name, tool] of connectedTools)
                 this.connectedTools.set(name, tool);
             if (capabilities?.resources) {
@@ -1157,6 +1174,7 @@ export class ClaudeMcpToolRegistry {
                 status: 'connected',
                 statusDetail: 'connected',
             });
+            this.publishInstructions();
         }
         catch (error) {
             await client.close().catch(() => undefined);
@@ -1383,6 +1401,7 @@ export class ClaudeMcpToolRegistry {
         this.resourceServers.delete(serverName);
         this.promptServers.delete(serverName);
         this.serverCapabilities.delete(serverName);
+        this.serverInstructions.delete(serverName);
         await this.connectServer(serverName, reconnectable.config, reconnectable.sensitiveValues, expectedGeneration);
         if (this.statuses.get(serverName)?.status !== 'connected') {
             throw new Error(`MCP server ${serverName} could not reconnect`);
@@ -1393,6 +1412,10 @@ export class ClaudeMcpToolRegistry {
         if (!this.closed)
             this.options.onPromptsChanged?.(this.prompts());
     }
+    publishInstructions() {
+        if (!this.closed)
+            this.options.onInstructionsChanged?.(this.instructions());
+    }
     assertOpenGeneration(expectedGeneration) {
         if (this.closed || expectedGeneration !== this.generation) {
             throw new Error('MCP registry is closed');

package/dist/providers/anthropic-compatible.js

@@ -555,6 +555,20 @@ function serializeMessages(messages) {
     }
     return { system: system.join('\n\n'), messages: serialized };
 }
+function validateStableSystemPrefix(request) {
+    const count = request.stableSystemMessageCount;
+    if (count === undefined)
+        return;
+    const systemMessageCount = request.messages.filter((message) => message.role === 'system').length;
+    if (!Number.isSafeInteger(count) || count < 0 || count > systemMessageCount) {
+        throw new Error('Stable system message count must identify a valid system-message prefix');
+    }
+    if (request.messages
+        .slice(0, count)
+        .some((message) => message.role !== 'system')) {
+        throw new Error('Stable system message count must identify a valid system-message prefix');
+    }
+}
 export class AnthropicCompatibleProvider {
     options;
     capabilities;
@@ -609,6 +623,7 @@ export class AnthropicCompatibleProvider {
         this.maxErrorBodyBytes = options.maxErrorBodyBytes ?? 64 * 1024;
     }
     async *complete(request) {
+        validateStableSystemPrefix(request);
         if (request.webSearch && !this.capabilities.webSearch) {
             throw new Error('Provider does not support web search');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",