salmon-loop 0.2.3 → 0.2.16

package/dist/core/streaming/stream-assembler.js

@@ -2,12 +2,15 @@ import { getExitCode } from '../runtime/exit-codes.js';
 import { normalizeStopReason } from './normalized-events.js';
 export class StreamAssembler {
     clock;
+    deferToolRequestsUntilExecutionInput;
     streams = new Map();
     canonicalTextStreams = new Set();
     canonicalClosedTextStreams = new Set();
     toolCallStates = new Map();
     constructor(options = {}) {
         this.clock = options.clock ?? (() => new Date());
+        this.deferToolRequestsUntilExecutionInput =
+            options.deferToolRequestsUntilExecutionInput ?? false;
     }
     push(event) {
         if (event.type === 'llm.responses.event') {
@@ -27,33 +30,42 @@ export class StreamAssembler {
                 return [];
             }
             this.canonicalTextStreams.delete(event.streamId);
-            return this.handleTextEnd(event.streamId, event.timestamp, event.finishReason);
+            return [
+                ...this.flushPendingToolRequests(event.streamId),
+                ...this.handleTextEnd(event.streamId, event.timestamp, event.finishReason),
+            ];
         }
         if (event.type === 'tool.call.start') {
             const out = [];
             const st = this.getToolCallState(event.callId);
             if (!st.requestStarted) {
                 st.requestStarted = true;
-                out.push({
+                st.request = {
                     type: 'normalized.tool_request_start',
                     callId: event.callId,
                     toolName: event.toolName,
                     phase: event.phase,
                     round: event.round,
+                    ...(event.input === undefined ? {} : { input: event.input }),
                     timestamp: event.timestamp,
-                });
+                };
             }
+            else if (event.input !== undefined && st.request && st.request.input === undefined) {
+                st.request = { ...st.request, input: event.input };
+            }
+            out.push(...this.emitPendingToolRequest(st));
             if (!st.requestEnded) {
                 st.requestEnded = true;
-                out.push({
+                st.requestEnd = {
                     type: 'normalized.tool_request_end',
                     callId: event.callId,
                     toolName: event.toolName,
                     phase: event.phase,
                     round: event.round,
                     timestamp: event.timestamp,
-                });
+                };
             }
+            out.push(...this.emitPendingToolRequestEnd(st));
             if (st.executionStarted)
                 return out;
             st.executionStarted = true;
@@ -73,26 +85,28 @@ export class StreamAssembler {
             const st = this.getToolCallState(event.callId);
             if (!st.requestStarted) {
                 st.requestStarted = true;
-                out.push({
+                st.request = {
                     type: 'normalized.tool_request_start',
                     callId: event.callId,
                     toolName: event.toolName,
                     phase: event.phase,
                     round: event.round,
                     timestamp: event.timestamp,
-                });
+                };
             }
+            out.push(...this.emitPendingToolRequest(st));
             if (!st.requestEnded) {
                 st.requestEnded = true;
-                out.push({
+                st.requestEnd = {
                     type: 'normalized.tool_request_end',
                     callId: event.callId,
                     toolName: event.toolName,
                     phase: event.phase,
                     round: event.round,
                     timestamp: event.timestamp,
-                });
+                };
             }
+            out.push(...this.emitPendingToolRequestEnd(st));
             out.push({
                 type: 'normalized.tool_call_end',
                 callId: event.callId,
@@ -211,7 +225,10 @@ export class StreamAssembler {
                 return [];
             this.canonicalClosedTextStreams.add(event.streamId);
             this.canonicalTextStreams.delete(event.streamId);
-            return this.handleTextEnd(event.streamId, event.timestamp, undefined);
+            return [
+                ...this.flushPendingToolRequests(event.streamId),
+                ...this.handleTextEnd(event.streamId, event.timestamp, undefined),
+            ];
         }
         if (isOutputItemAddedMessageEvent(event.event) ||
             isContentPartAddedOutputTextEvent(event.event)) {
@@ -223,7 +240,10 @@ export class StreamAssembler {
                 return [];
             this.canonicalClosedTextStreams.add(event.streamId);
             this.canonicalTextStreams.delete(event.streamId);
-            return this.handleTextEnd(event.streamId, event.timestamp, undefined);
+            return [
+                ...this.flushPendingToolRequests(event.streamId),
+                ...this.handleTextEnd(event.streamId, event.timestamp, undefined),
+            ];
         }
         if (isOutputItemAddedFunctionCallEvent(event.event)) {
             if (!event.phase || typeof event.round !== 'number')
@@ -231,38 +251,38 @@ export class StreamAssembler {
             const callId = event.event.item.call_id;
             const toolName = event.event.item.name;
             const st = this.getToolCallState(callId);
+            st.streamId ??= event.streamId;
             if (st.requestStarted)
                 return [];
             st.requestStarted = true;
-            return [
-                {
-                    type: 'normalized.tool_request_start',
-                    callId,
-                    toolName,
-                    phase: event.phase,
-                    round: event.round,
-                    timestamp: event.timestamp,
-                },
-            ];
+            st.request = {
+                type: 'normalized.tool_request_start',
+                callId,
+                toolName,
+                phase: event.phase,
+                round: event.round,
+                timestamp: event.timestamp,
+            };
+            return this.deferToolRequestsUntilExecutionInput ? [] : this.emitPendingToolRequest(st);
         }
         if (isOutputItemDoneFunctionCallEvent(event.event)) {
             if (!event.phase || typeof event.round !== 'number')
                 return [];
             const callId = event.event.item.call_id;
             const st = this.getToolCallState(callId);
+            st.streamId ??= event.streamId;
             if (st.requestEnded)
                 return [];
             st.requestEnded = true;
-            return [
-                {
-                    type: 'normalized.tool_request_end',
-                    callId,
-                    toolName: event.event.item.name,
-                    phase: event.phase,
-                    round: event.round,
-                    timestamp: event.timestamp,
-                },
-            ];
+            st.requestEnd = {
+                type: 'normalized.tool_request_end',
+                callId,
+                toolName: event.event.item.name,
+                phase: event.phase,
+                round: event.round,
+                timestamp: event.timestamp,
+            };
+            return this.emitPendingToolRequestEnd(st);
         }
         return [];
     }
@@ -274,10 +294,34 @@ export class StreamAssembler {
             requestStarted: false,
             requestEnded: false,
             executionStarted: false,
+            emittedRequest: false,
+            emittedRequestEnd: false,
         };
         this.toolCallStates.set(callId, created);
         return created;
     }
+    emitPendingToolRequest(st) {
+        if (st.emittedRequest || !st.request)
+            return [];
+        st.emittedRequest = true;
+        return [st.request];
+    }
+    emitPendingToolRequestEnd(st) {
+        if (st.emittedRequestEnd || !st.requestEnd || !st.emittedRequest)
+            return [];
+        st.emittedRequestEnd = true;
+        return [st.requestEnd];
+    }
+    flushPendingToolRequests(streamId) {
+        const out = [];
+        for (const st of this.toolCallStates.values()) {
+            if (st.streamId !== streamId)
+                continue;
+            out.push(...this.emitPendingToolRequest(st));
+            out.push(...this.emitPendingToolRequestEnd(st));
+        }
+        return out;
+    }
 }
 function isOutputTextDeltaEvent(event) {
     return (event.type === 'response.output_text.delta' &&

package/dist/core/sub-agent/context-snapshot.js

@@ -0,0 +1,156 @@
+import { normalizeToolResultReplacementState, } from '../session/replacement-state.js';
+import { SUB_AGENT_CONTEXT_SNAPSHOT_VERSION, SUB_AGENT_CONTEXT_SNAPSHOT_FIELD_SEMANTICS, } from './types.js';
+function deepClone(value) {
+    if (typeof structuredClone === 'function') {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+function cloneArtifactHandle(artifact) {
+    if (!artifact)
+        return undefined;
+    return {
+        handle: artifact.handle,
+        mimeType: artifact.mimeType,
+        sha256: artifact.sha256,
+        size: artifact.size,
+    };
+}
+function cloneConversationContext(messages) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return undefined;
+    return messages.map((message) => {
+        const cloned = {
+            role: message.role,
+            content: message.content,
+        };
+        if (message.name !== undefined)
+            cloned.name = message.name;
+        if (message.reasoning_content !== undefined)
+            cloned.reasoning_content = message.reasoning_content;
+        if (message.tool_call_id !== undefined)
+            cloned.tool_call_id = message.tool_call_id;
+        if (Array.isArray(message.tool_calls)) {
+            cloned.tool_calls = deepClone(message.tool_calls);
+        }
+        return cloned;
+    });
+}
+function cloneToolCallingAudit(entries) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        return undefined;
+    return entries.map((entry) => deepClone(entry));
+}
+function cloneArtifactHints(hints) {
+    if (!hints)
+        return undefined;
+    const verifyArtifact = cloneArtifactHandle(hints.verifyArtifact);
+    const subAgentPatchArtifacts = hints.subAgentPatchArtifacts?.map((artifact) => cloneArtifactHandle(artifact));
+    const subAgentAuditArtifacts = hints.subAgentAuditArtifacts?.map((artifact) => cloneArtifactHandle(artifact));
+    const recentReadArtifacts = hints.recentReadArtifacts?.map((item) => ({
+        path: item.path,
+        artifact: cloneArtifactHandle(item.artifact),
+    }));
+    const toolResultPreviewArtifacts = hints.toolResultPreviewArtifacts?.map((item) => ({
+        label: item.label,
+        artifact: cloneArtifactHandle(item.artifact),
+    }));
+    if (!verifyArtifact &&
+        !subAgentPatchArtifacts?.length &&
+        !subAgentAuditArtifacts?.length &&
+        !recentReadArtifacts?.length &&
+        !toolResultPreviewArtifacts?.length) {
+        return undefined;
+    }
+    return {
+        verifyArtifact,
+        subAgentPatchArtifacts,
+        subAgentAuditArtifacts,
+        recentReadArtifacts,
+        toolResultPreviewArtifacts,
+    };
+}
+function cloneReplacementState(state) {
+    const normalized = normalizeToolResultReplacementState(state);
+    if (!normalized)
+        return undefined;
+    return {
+        schemaVersion: normalized.schemaVersion,
+        entries: Object.fromEntries(Object.entries(normalized.entries).map(([key, value]) => [
+            key,
+            {
+                toolResultId: value.toolResultId,
+                decision: value.decision,
+                preview: value.preview,
+                frozenAt: value.frozenAt,
+                sourceArtifactHandle: value.sourceArtifactHandle,
+                identityVersion: value.identityVersion,
+                hashAlgorithm: value.hashAlgorithm,
+            },
+        ])),
+    };
+}
+function hasAnySnapshotData(snapshot) {
+    return Boolean(snapshot.conversationContext ||
+        snapshot.artifactHints ||
+        snapshot.toolCallingAudit ||
+        snapshot.replacementState ||
+        snapshot.planRuntime ||
+        snapshot.cacheSharing);
+}
+function normalizeSnapshotVersion(snapshot) {
+    const version = snapshot.version ?? SUB_AGENT_CONTEXT_SNAPSHOT_VERSION;
+    if (version !== SUB_AGENT_CONTEXT_SNAPSHOT_VERSION) {
+        throw new Error(`Unsupported sub-agent context snapshot version: ${version}`);
+    }
+    return version;
+}
+function assertSupportedSnapshotFields(snapshot) {
+    const supportedFields = new Set([
+        'version',
+        ...Object.keys(SUB_AGENT_CONTEXT_SNAPSHOT_FIELD_SEMANTICS),
+    ]);
+    const unknownFields = Object.keys(snapshot).filter((key) => !supportedFields.has(key));
+    if (unknownFields.length > 0) {
+        throw new Error(`Unsupported sub-agent context snapshot fields: ${unknownFields.sort().join(', ')}`);
+    }
+}
+/**
+ * Applies the Stage 5 protocol:
+ * - mutable runtime state is cloned by default
+ * - session infrastructure metadata remains shared by reference
+ */
+export function cloneSubAgentContextSnapshot(snapshot) {
+    if (!snapshot)
+        return undefined;
+    assertSupportedSnapshotFields(snapshot);
+    const version = normalizeSnapshotVersion(snapshot);
+    const cloned = {
+        version,
+        conversationContext: cloneConversationContext(snapshot.conversationContext),
+        artifactHints: cloneArtifactHints(snapshot.artifactHints),
+        toolCallingAudit: cloneToolCallingAudit(snapshot.toolCallingAudit),
+        replacementState: cloneReplacementState(snapshot.replacementState),
+        planRuntime: snapshot.planRuntime,
+        cacheSharing: snapshot.cacheSharing,
+    };
+    if (!hasAnySnapshotData(cloned)) {
+        return undefined;
+    }
+    return cloned;
+}
+export function mergeSubAgentContextSnapshot(requestSnapshot, runtimeSnapshot) {
+    const normalizedRequestVersion = requestSnapshot && normalizeSnapshotVersion(requestSnapshot);
+    const normalizedRuntimeVersion = runtimeSnapshot && normalizeSnapshotVersion(runtimeSnapshot);
+    const merged = {
+        version: normalizedRuntimeVersion ?? normalizedRequestVersion ?? SUB_AGENT_CONTEXT_SNAPSHOT_VERSION,
+        conversationContext: runtimeSnapshot?.conversationContext ?? requestSnapshot?.conversationContext,
+        artifactHints: runtimeSnapshot?.artifactHints ?? requestSnapshot?.artifactHints,
+        toolCallingAudit: runtimeSnapshot?.toolCallingAudit ?? requestSnapshot?.toolCallingAudit,
+        replacementState: runtimeSnapshot?.replacementState ?? requestSnapshot?.replacementState,
+        planRuntime: runtimeSnapshot?.planRuntime ?? requestSnapshot?.planRuntime,
+        cacheSharing: runtimeSnapshot?.cacheSharing ?? requestSnapshot?.cacheSharing,
+    };
+    return cloneSubAgentContextSnapshot(merged);
+}
+//# sourceMappingURL=context-snapshot.js.map

package/dist/core/sub-agent/core/loop.js

@@ -25,7 +25,7 @@ export class SmallfryLoop {
      * Run the recursive loop based on the stratagem.
      */
     async execute(initCtx) {
-        getLogger().info(`[SmallfryLoop] ${text.smallfry.status.working} (${this.profile.name})`);
+        getLogger().debug(`[SmallfryLoop] ${text.smallfry.status.working} (${this.profile.name})`);
         let pipeline = Pipeline.of(initCtx);
         // Dynamic Phase Injection based on Stratagem
         pipeline = pipeline.step('PREFLIGHT', runPreflight);

package/dist/core/sub-agent/core/manager.js

@@ -3,11 +3,15 @@ import { text } from '../../../locales/index.js';
 import { createFileSystemAdapter } from '../../adapters/fs/index.js';
 import * as fs from '../../adapters/fs/node-fs.js';
 import { GitAdapter } from '../../adapters/git/git-adapter.js';
+import { recordAuditEvent } from '../../observability/audit-trail.js';
 import { getLogger } from '../../observability/logger.js';
 import { FileStateResolver } from '../../strata/layers/file-state-resolver.js';
 import { RuntimeEnvironment } from '../../strata/runtime/environment.js';
 import { ErrorType } from '../../types/index.js';
 import { ArtifactStore } from '../artifacts/store.js';
+import { cloneSubAgentContextSnapshot } from '../context-snapshot.js';
+import { isReadOnlySubAgentContext, resolveSubAgentDryRun } from '../dispatch-policy.js';
+import { validateSharedPrefixConsistency } from '../prefix-consistency.js';
 import { getSubAgentRegistry } from '../registry.js';
 import { SmallfryLoop } from './loop.js';
 /**
@@ -33,12 +37,39 @@ export class SubAgentManager {
      * Spawns a new sub-agent and monitors its execution.
      */
     async execute(request) {
-        const profile = this.deps.registry.get(request.agent_ref);
+        const normalizedRequest = request.session_target === 'shared'
+            ? (() => {
+                const consistency = validateSharedPrefixConsistency({
+                    requestSnapshot: request.contextSnapshot,
+                    runtimeSnapshot: this.ctx.contextSnapshot,
+                });
+                if (consistency.compatible)
+                    return request;
+                recordAuditEvent('sub_agent.shared.prefix_consistency_failed', {
+                    metric: 'shared_fallback_rate',
+                    fallbackMode: 'isolated',
+                    reason: consistency.reason,
+                    expected: consistency.expected,
+                    actual: consistency.actual,
+                }, {
+                    source: 'smallfry',
+                    severity: 'medium',
+                    scope: 'session',
+                    phase: this.ctx.phase,
+                });
+                return {
+                    ...request,
+                    session_target: 'isolated',
+                    contextSnapshot: undefined,
+                };
+            })()
+            : request;
+        const profile = this.deps.registry.get(normalizedRequest.agent_ref);
         if (!profile) {
-            return this.fail(request.agent_ref, text.smallfry.errors.profileNotFound(request.agent_ref), 'LOOP_FAILED');
+            return this.fail(normalizedRequest.agent_ref, text.smallfry.errors.profileNotFound(normalizedRequest.agent_ref), 'LOOP_FAILED');
         }
         const agentId = `smallfry-${randomBytes(4).toString('hex')}`;
-        const currentDepth = request.recursionDepth || 0;
+        const currentDepth = normalizedRequest.recursionDepth || 0;
         const MAX_RECURSION_DEPTH = 2;
         if (currentDepth >= MAX_RECURSION_DEPTH) {
             const msg = text.smallfry.errors.recursionLimitExceeded(currentDepth, MAX_RECURSION_DEPTH);
@@ -47,7 +78,7 @@ export class SubAgentManager {
         }
         this.activeAgents.set(agentId, { profile, status: 'hiring' });
         this.controller.registerAgent(agentId, profile, 'hiring');
-        getLogger().info(`[SubAgentManager] ${text.smallfry.status.spawning} (ID: ${agentId}, Role: ${profile.role})`);
+        getLogger().debug(`[SubAgentManager] ${text.smallfry.status.spawning} (ID: ${agentId}, Role: ${profile.role})`);
         const llm = this.ctx.llm;
         if (!llm) {
             const msg = text.smallfry.errors.dispatchMissingRuntimeLlm;
@@ -59,7 +90,12 @@ export class SubAgentManager {
             if (this.controller.isStopRequested(agentId)) {
                 throw new Error('Stop requested before launching Smallfry');
             }
-            const runtimeEnv = await this.setupIsolatedEnvironment(request, llm, agentId);
+            const effectiveDryRun = resolveSubAgentDryRun({
+                parentDryRun: this.ctx.dryRun,
+                flowMode: this.ctx.flowMode,
+                phase: this.ctx.phase,
+            });
+            const runtimeEnv = await this.setupIsolatedEnvironment(normalizedRequest, llm, agentId, effectiveDryRun);
             try {
                 const workspace = runtimeEnv.workspace;
                 const activePath = workspace.workPath;
@@ -68,21 +104,23 @@ export class SubAgentManager {
                 const flowMode = 'patch';
                 const fsAdapter = createFileSystemAdapter(flowMode);
                 // 2. Construct InitCtx for the smallfry
-                const initCtx = {
+                const initCtx = this.applyContextSnapshot(normalizedRequest.contextSnapshot, {
                     workspace: {
                         workPath: activePath,
                         baseRepoPath: workspace.baseRepoPath,
                         strategy: workspace.strategy,
                     },
                     options: {
-                        instruction: request.task,
+                        instruction: normalizedRequest.task,
                         repoPath: activePath,
-                        dryRun: this.ctx.dryRun,
-                        contextFiles: request.contextFiles || [],
+                        dryRun: effectiveDryRun,
+                        contextFiles: normalizedRequest.contextFiles || [],
                         llm,
                         recursionDepth: currentDepth + 1, // Increment depth for child
-                        allowedToolNames: this.filterAllowedTools(profile.allowedTools),
-                        timeoutMs: request.timeout_seconds ? request.timeout_seconds * 1000 : profile.timeoutMs,
+                        allowedToolNames: this.filterAllowedTools(profile.allowedTools, this.ctx.phase),
+                        timeoutMs: normalizedRequest.timeout_seconds
+                            ? normalizedRequest.timeout_seconds * 1000
+                            : profile.timeoutMs,
                     },
                     mode: flowMode,
                     fs: fsAdapter,
@@ -100,7 +138,7 @@ export class SubAgentManager {
                     },
                     fileStateResolver: resolver,
                     shadowInitialRef: runtimeEnv?.initialSnapshotHash || 'HEAD',
-                };
+                });
                 // 3. Launch the "Little Fry"
                 const subLoop = new SmallfryLoop(profile);
                 const result = await subLoop.execute(initCtx);
@@ -133,6 +171,23 @@ export class SubAgentManager {
     async spawn(request) {
         return this.execute(request);
     }
+    applyContextSnapshot(snapshot, initCtx) {
+        const normalized = cloneSubAgentContextSnapshot(snapshot);
+        if (!normalized)
+            return initCtx;
+        return {
+            ...initCtx,
+            cacheSharing: normalized.cacheSharing ?? initCtx.cacheSharing,
+            planRuntime: normalized.planRuntime ?? initCtx.planRuntime,
+            toolCallingAudit: normalized.toolCallingAudit ?? initCtx.toolCallingAudit,
+            replacementState: normalized.replacementState ?? initCtx.replacementState,
+            artifactHints: normalized.artifactHints ?? initCtx.artifactHints,
+            options: {
+                ...initCtx.options,
+                conversationContext: normalized.conversationContext ?? initCtx.options.conversationContext,
+            },
+        };
+    }
     updateStatus(id, status) {
         const entry = this.activeAgents.get(id);
         if (entry) {
@@ -154,13 +209,29 @@ export class SubAgentManager {
             errorType: ErrorType.UNKNOWN,
         };
     }
-    async setupIsolatedEnvironment(request, llm, agentId) {
+    async setupIsolatedEnvironment(request, llm, agentId, effectiveDryRun) {
+        if (isReadOnlySubAgentContext({
+            flowMode: this.ctx.flowMode,
+            phase: this.ctx.phase,
+        }) &&
+            request.session_target !== 'isolated') {
+            recordAuditEvent('sub_agent.dispatch.read_only_forced_isolated', {
+                requestedSessionTarget: request.session_target,
+                effectiveSessionTarget: 'isolated',
+            }, {
+                source: 'smallfry',
+                severity: 'low',
+                scope: 'session',
+                phase: this.ctx.phase,
+            });
+        }
         const baseRepoPath = this.ctx.persistenceRoot || this.ctx.repoRoot;
         const options = {
             instruction: request.task,
             repoPath: baseRepoPath,
             llm,
-            dryRun: this.ctx.dryRun,
+            // CRITICAL SAFETY: read-only model phases force sub-agent dryRun.
+            dryRun: effectiveDryRun,
             verify: undefined,
             strategy: 'worktree',
             contextFiles: request.contextFiles,
@@ -187,15 +258,20 @@ export class SubAgentManager {
     }
     async persistArtifacts(agentId, result) {
         const patch = result.finalPatch;
-        if (!patch || typeof patch !== 'string')
-            return result;
+        const { finalPatch: _ignored, ...rest } = result;
+        const auditArtifact = await this.persistAuditArtifact(rest.auditPath);
+        if (!patch || typeof patch !== 'string') {
+            return {
+                ...rest,
+                auditPath: auditArtifact?.handle ?? rest.auditPath,
+                auditArtifact: auditArtifact ?? rest.auditArtifact,
+            };
+        }
         const saved = await this.deps.artifactStore.saveText({
             content: patch,
             mimeType: 'text/x-diff',
             fileExt: 'patch',
         });
-        const { finalPatch: _ignored, ...rest } = result;
-        const auditArtifact = await this.persistAuditArtifact(rest.auditPath);
         return {
             ...rest,
             auditPath: auditArtifact?.handle ?? rest.auditPath,
@@ -203,7 +279,7 @@ export class SubAgentManager {
             patchArtifact: saved,
         };
     }
-    filterAllowedTools(allowed) {
+    filterAllowedTools(allowed, phase) {
         const safeReadOnlyTools = new Set([
             'agent_dispatch',
             'code.search',
@@ -213,7 +289,30 @@ export class SubAgentManager {
             'git.cat',
             'artifact.read',
         ]);
-        return allowed.filter((name) => safeReadOnlyTools.has(name));
+        const readOnlyPlanTools = new Set(['plan.init', 'plan.read', 'plan.update']);
+        const readOnlyPhase = isReadOnlySubAgentContext({
+            flowMode: this.ctx.flowMode,
+            phase,
+        });
+        if (!readOnlyPhase) {
+            return allowed;
+        }
+        const filtered = allowed.filter((name) => safeReadOnlyTools.has(name) || (readOnlyPhase && readOnlyPlanTools.has(name)));
+        if (readOnlyPhase) {
+            const removed = allowed.filter((name) => !filtered.includes(name));
+            if (removed.length > 0) {
+                recordAuditEvent('sub_agent.dispatch.read_only_tool_guard_filtered', {
+                    removedTools: removed,
+                    retainedTools: filtered,
+                }, {
+                    source: 'smallfry',
+                    severity: 'medium',
+                    scope: 'session',
+                    phase,
+                });
+            }
+        }
+        return filtered;
     }
     async persistAuditArtifact(auditPath) {
         if (!auditPath || typeof auditPath !== 'string')

package/dist/core/sub-agent/dispatch-policy.js

@@ -0,0 +1,29 @@
+import { resolveExecutionProfile } from '../runtime/execution-profile.js';
+import { Phase } from '../types/runtime.js';
+const READ_ONLY_MODEL_PHASE_SET = new Set([Phase.EXPLORE, Phase.PLAN, Phase.PATCH]);
+/**
+ * Read-only model phases in which sub-agent dispatch must never cause workspace mutation.
+ */
+export function isReadOnlyModelPhase(phase) {
+    return phase !== undefined && READ_ONLY_MODEL_PHASE_SET.has(phase);
+}
+export function isReadOnlySubAgentContext({ flowMode, phase }) {
+    if (!flowMode) {
+        return isReadOnlyModelPhase(phase);
+    }
+    const profile = resolveExecutionProfile(flowMode);
+    if (profile.driver === 'agent') {
+        return false;
+    }
+    return isReadOnlyModelPhase(phase);
+}
+/**
+ * In read-only model phases, sub-agent execution must run in dry-run mode regardless of parent value.
+ */
+export function resolveSubAgentDryRun({ parentDryRun, flowMode, phase, }) {
+    if (isReadOnlySubAgentContext({ flowMode, phase })) {
+        return true;
+    }
+    return parentDryRun;
+}
+//# sourceMappingURL=dispatch-policy.js.map