@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/engine/run-tooling.js

@@ -0,0 +1,283 @@
+import { ToolExecutor } from "../tool-system/executor.js";
+import { InvestigationGuard } from "../tool-system/investigation-guard.js";
+import { TaskGuard } from "../tool-system/task-guard.js";
+import { PermissionClassifier, InteractiveApprovalBackend } from "../tool-system/permission.js";
+import { MCPManager } from "../tool-system/mcp-manager.js";
+import { buildMcpToolPolicies, isRegisteredMcpToolAllowed, } from "../tool-system/mcp-tool-policy.js";
+import { PLAN_MODE_ALLOWED_TOOLS } from "../tool-system/plan-mode-allowlist.js";
+import { isFeatureEnabled } from "../settings/feature-flags.js";
+import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
+/** engine.ts L1485-1522 —— ToolContext 组装(spawner、agentDefinitions、base 由调用方传入)。 */
+export function buildRunToolContext(args) {
+    const { options, profile, profileParams } = args;
+    let pendingRunYield;
+    // sessionId is filled in after the session bundle is resolved below
+    // (the session may be cold-started or resumed). Until then this is
+    // intentionally shaped as a mutable local; we treat it as immutable
+    // after the assignment.
+    const toolCtx = {
+        ...args.base,
+        approvalRouter: options?.approvalRouter ?? args.configApprovalRouter,
+        permissionMode: args.runPermissionMode,
+        planMode: args.runPlanMode,
+        subAgentSpawner: args.subAgentSpawner,
+        agentDefinitions: args.agentDefinitions,
+        // Stamp the resolved network policy onto the backend the tools see so
+        // Bash can surface "网络 deny" on its result. Shallow-copy (don't mutate
+        // the cached backend) — `wrap`/`hintForBlockedOutput` are plain function
+        // properties and survive the spread. Off keeps network undefined.
+        sandbox: args.sandbox,
+        cwd: args.cwd,
+        shellEnv: args.shellEnv,
+        // TodoWrite reads this to push task_update events independently
+        // of its return value, so the UI's pinned task panel refreshes
+        // immediately rather than after the LLM next surfaces the
+        // snapshot. wrappedOnStream snoops the same channel to keep
+        // latestTodos current for TaskGuard.
+        streamCallback: options?.onStream,
+        setCwd(nextCwd) {
+            toolCtx.cwd = nextCwd;
+        },
+        runYield: {
+            request(reason) {
+                pendingRunYield ??= reason;
+            },
+            peek() {
+                return pendingRunYield;
+            },
+            consume() {
+                const reason = pendingRunYield;
+                pendingRunYield = undefined;
+                return reason;
+            },
+        },
+    };
+    if (profile?.allowedToolNames) {
+        toolCtx.allowedToolNames = profile.allowedToolNames;
+    }
+    if (profile?.createRunServices) {
+        toolCtx.runScopedServices = profile.createRunServices({
+            profileParams,
+            reportResult: (key, value) => {
+                args.reportResult(key, value);
+            },
+        });
+    }
+    return toolCtx;
+}
+/** engine.ts L1876-1933 —— 权限分类器 + 审批监听 + ToolExecutor + guards。 */
+export function buildRunPermissionPipeline(args) {
+    const mode = args.mode;
+    const { rules: defaultRules, backend: approvalBackend } = args.permissionController.build(mode, args.cwd, args.approvalRouter);
+    const permission = new PermissionClassifier(defaultRules, mode, approvalBackend);
+    permission.setApprovalStateListener((waiting, toolName) => {
+        args.onApprovalPhase(waiting, toolName);
+    });
+    // Surface approval waits on the notification hook (fire-and-forget, like
+    // background-agent terminal states) so plugins / settings hooks can ping
+    // the user while a decision is pending.
+    permission.setApprovalEventListener((event) => {
+        args.emitNotificationHook({
+            kind: event.phase === "requested" ? "approval_requested" : "approval_resolved",
+            toolName: event.toolName,
+            riskLevel: event.riskLevel,
+            ...(event.approved !== undefined ? { approved: event.approved } : {}),
+            ...(event.sessionId ? { sessionId: event.sessionId } : {}),
+        });
+    });
+    args.permissionController.attach(permission, args.approvalRouter);
+    // If the backend is the interactive one, wire it for project-scope
+    // persistence: it needs cwd to find settings.local.json, and a callback
+    // to apply newly-saved rules to the live classifier so subsequent calls
+    // in this same session don't re-prompt. Headless/auto backends skip
+    // this — they don't prompt, so there are no project rules to persist.
+    if (approvalBackend instanceof InteractiveApprovalBackend) {
+        approvalBackend.setSessionContext(args.sessionId, {
+            cwd: args.cwd,
+            onProjectRules: (rules) => {
+                // Prepend the *full* accumulated list of session-saved project rules
+                // so user approvals win over defaults and earlier approvals aren't
+                // dropped when later ones come in.
+                permission.reconfigure(mode, approvalBackend, [...rules, ...defaultRules]);
+            },
+        });
+    }
+    const toolExecutor = new ToolExecutor(args.toolRegistry, permission, args.hooks);
+    const investigationGuard = new InvestigationGuard();
+    if (args.readOnlySession) {
+        investigationGuard.setPolicy("read-only-review");
+    }
+    else if (args.headless) {
+        investigationGuard.setSoftMode(true);
+    }
+    toolExecutor.setInvestigationGuard(investigationGuard);
+    toolExecutor.setTaskGuard(new TaskGuard(() => args.getLatestTodos()));
+    // Wire abort signal for cascading cancellation + per-Engine ToolContext
+    toolExecutor.setSignal(args.signal);
+    toolExecutor.setContext(args.toolCtx);
+    return { permission, toolExecutor };
+}
+/** engine.ts L1986-2003 —— MCP 连接(Runtime 池优先,回退 per-Engine)。 */
+export async function connectRunMcp(args) {
+    // Connect MCP servers (if configured and not already connected).
+    // B1: prefer the Runtime-owned MCPManager so all sessions in a
+    // worker share one set of connections. Falling back to a
+    // per-Engine instance keeps the null-runtime path (tests, ad-hoc
+    // scripts) working.
+    const mcpServers = args.mcpServers;
+    const mcpDisabled = args.mcpDisabled;
+    if (!mcpDisabled && Object.keys(mcpServers).length > 0 && !args.getManager()) {
+        if (args.runtimePool) {
+            args.setManager(args.runtimePool);
+        }
+        else {
+            args.setManager(new MCPManager(args.toolRegistry));
+        }
+        await args.getManager().connectAll(mcpServers, args.engineForConnect, (event) => {
+            // Fire-and-forget onto the notification hook: hosts/plugins learn
+            // about MCP availability changes without polling the pool.
+            args.emitNotificationHook({
+                kind: event.type,
+                server: event.server,
+                ...(event.error ? { error: event.error } : {}),
+            });
+        });
+    }
+}
+/**
+ * Build the availability-guard context for a tool surface.
+ *
+ * Extracted from {@link assembleRunToolDefs} so it is callable on its own. It
+ * matters that this has exactly one implementation: the executor SKIPS its
+ * visibility gate when `toolCtx.toolVisibility` is absent, so a caller that
+ * forgets to populate it doesn't just under-expose tools — it makes host-gated
+ * tools callable in contexts their guards were written to exclude.
+ *
+ * Optional keys are omitted rather than set to `undefined`: guards use
+ * `!== true` / `?? 0` style checks, and an empty `sessionMessageTargets` must not
+ * read as "the host authorized targets".
+ */
+export function buildToolVisibility(inputs) {
+    return {
+        cwd: inputs.cwd,
+        hasGoal: inputs.hasGoal,
+        ...(inputs.sessionId ? { sessionId: inputs.sessionId } : {}),
+        ...(inputs.settingsScope ? { settingsScope: inputs.settingsScope } : {}),
+        ...(inputs.host !== undefined ? { host: inputs.host } : {}),
+        ...(inputs.isSubAgent !== undefined ? { isSubAgent: inputs.isSubAgent } : {}),
+        ...(inputs.behaviorProfile !== undefined ? { behaviorProfile: inputs.behaviorProfile } : {}),
+        ...(inputs.sessionMessageTargets?.length
+            ? { sessionMessageTargets: inputs.sessionMessageTargets }
+            : {}),
+        ...(inputs.profileMeta ? { profileMeta: inputs.profileMeta } : {}),
+    };
+}
+/** engine.ts L2023-2145 —— builtin override / MCP 可见性 / feature flags / 动态 defs / plan-mode 过滤。
+ *  注意:本函数按原逻辑就地 mutate toolCtx(toolVisibility/disabledBuiltins/
+ *  allowedMcpServers/mcpToolPolicies)。 */
+export function assembleRunToolDefs(args) {
+    const { toolCtx } = args;
+    const guardCwd = args.guardCwd;
+    const toolVisibility = buildToolVisibility({
+        cwd: guardCwd,
+        hasGoal: args.hasRunnableGoal,
+        sessionId: toolCtx.sessionId,
+        settingsScope: args.settingsScope,
+        host: args.builtinToolHost,
+        isSubAgent: args.isSubAgent,
+        behaviorProfile: args.behaviorProfileId,
+        sessionMessageTargets: toolCtx.sessionMessages?.targets,
+        profileMeta: args.profileMeta,
+    });
+    toolCtx.toolVisibility = toolVisibility;
+    // #7: per-turn project builtin override. The toolRegistry's builtin tool
+    // SET is ctor-frozen (and may be shared via runtime), so a mid-session
+    // project override of a builtin can't rebuild the registry. But the tool
+    // LIST handed to the LLM is assembled fresh every turn, so we apply the
+    // override here: a builtin marked `off` for this cwd is HIDDEN from the
+    // turn's tool list (matching how skills/plugins/agents `off` apply
+    // mid-session via readDisabledLists). `on`/`inherit` keep whatever the
+    // registry already has — we can't re-add a tool the frozen registry omits,
+    // but `on` for a tool already present is a no-op (it stays). This makes a
+    // builtin toggle take effect on the NEXT message, like other capability
+    // kinds, without touching the registry.
+    const builtinOverride = args.builtinOverride;
+    // Turn `off` from a prompt-visibility filter into a real execution gate:
+    // collect the builtin tool names the override marks `off` and hand them to
+    // the executor (via the shared toolCtx the executor already holds a
+    // reference to, set at setContext above) so it rejects a call to a hidden
+    // builtin instead of running it from the still-populated registry.
+    if (builtinOverride) {
+        const registryNames = new Set(args.toolRegistry.getToolDefinitions().map((t) => t.name));
+        const disabledBuiltins = new Set(Object.keys(builtinOverride).filter((name) => builtinOverride[name] === "off" && registryNames.has(name)));
+        toolCtx.disabledBuiltins = disabledBuiltins;
+    }
+    // MCP tool exposure is per-SESSION even though the pool/registry are
+    // worker-shared (B1): a server connected by another project's session
+    // registers its tools into the SHARED registry, and without this filter
+    // they leaked into every session (e.g. chrome-devtools tools showing up
+    // in a project that never enabled the plugin). Keep an MCP tool only when
+    // its server is in THIS session's merged config.mcpServers — which
+    // already folds the project's capabilityOverrides. Gated on the config
+    // being present: engines without one (sub-agents, bare tests) have no
+    // MCP tools in their private registries anyway.
+    const allowedMcpServers = new Set(args.mcpDisabled
+        ? []
+        : Object.entries(args.mcpServers)
+            .filter(([, c]) => c.enabled !== false)
+            .map(([n]) => n));
+    toolCtx.allowedMcpServers = allowedMcpServers;
+    const mcpToolPolicies = buildMcpToolPolicies(args.mcpServers);
+    toolCtx.mcpToolPolicies = mcpToolPolicies;
+    const mcpVisible = (toolName) => {
+        const reg = args.toolRegistry.getTool(toolName);
+        return (reg?.source !== "mcp" ||
+            (allowedMcpServers.has(reg?.serverName ?? "") &&
+                isRegisteredMcpToolAllowed({
+                    source: "mcp",
+                    serverName: reg?.serverName,
+                    mcpToolName: reg?.mcpToolName,
+                }, mcpToolPolicies)));
+    };
+    // Feature-flag visibility: a builtin mapped in TOOL_FEATURE_FLAGS is
+    // hidden when its flag resolves to false (default-on flags only hide when
+    // explicitly disabled, so zero regression out of the box). Read once per
+    // turn so flipping a flag in settings takes effect on the NEXT message,
+    // like the other capability kinds.
+    const featureFlags = args.featureFlags;
+    const allToolDefs = args
+        .applyBuiltinOverrideVisibility(args.toolRegistry.getToolDefinitions(), builtinOverride)
+        .filter((t) => mcpVisible(t.name))
+        .filter((t) => {
+        const guard = args.toolGuards.get(t.name);
+        return guard ? guard(toolVisibility) : true;
+    })
+        .filter((t) => {
+        const flag = args.toolFeatureFlags.get(t.name);
+        return flag ? isFeatureEnabled(featureFlags, flag) : true;
+    })
+        // Dynamic per-engine bits the static defs can't carry: the Agent tool's
+        // agent_type enum + listing, and the image/video provider names. See
+        // applyDynamicToolDef — forwarding only the Agent description (dropping
+        // its rebuilt inputSchema) used to strip the agent_type enum, so the
+        // model omitted agent_type and configured roles never applied.
+        // A builtin's own exposure.rewriteDefinition (run-scoped rewrites like
+        // DelegateWork's closed workspace enum) applies first.
+        .map((t) => {
+        const rewrite = args.toolRewriters.get(t.name);
+        return applyDynamicToolDef(rewrite ? rewrite(t, toolVisibility) : t, toolCtx.agentDefinitions, guardCwd);
+    });
+    // In plan mode, only expose read-only/planning tools so the model won't
+    // attempt writes. Shared with executor.ts's execution gate via
+    // PLAN_MODE_ALLOWED_TOOLS so what the model SEES and what the executor
+    // RUNS can't drift apart. (Bash is in the set; the executor additionally
+    // gates Bash to read-only commands at call time.)
+    const profileAllowedToolNames = args.profileAllowedToolNames;
+    const profileToolDefs = profileAllowedToolNames
+        ? allToolDefs.filter((tool) => profileAllowedToolNames.has(tool.name))
+        : allToolDefs;
+    const toolDefs = args.runPlanMode
+        ? profileToolDefs.filter((t) => PLAN_MODE_ALLOWED_TOOLS.has(t.name))
+        : profileToolDefs;
+    return toolDefs;
+}

package/dist/engine/run-types.d.ts

@@ -0,0 +1,139 @@
+import type { SessionKind, StreamCallback, TokenUsage } from "../types.js";
+import type { InputAttachmentMeta } from "../types.js";
+import type { ApprovalRouter } from "../tool-system/permission.js";
+import type { GoalConfig } from "../goal/lifecycle.js";
+import type { EngineConfig, EngineResult } from "./types.js";
+import type { LiveChildState } from "../tool-system/builtin/agent-registry.js";
+import type { LegacyPetWorkspaceOption } from "../types.js";
+import type { SessionMessageTarget } from "../session/session-message.js";
+/**
+ * Open string id naming a registered {@link RunBehaviorProfile}. The literal
+ * "quickChatRestricted" (and, transitionally, "pet") remain valid values —
+ * the type is a string so hosts can register their own profiles.
+ */
+export type RunBehaviorMode = string;
+/**
+ * A named, domain-agnostic per-run behavior profile. Engine resolves at most
+ * one active profile per run (by behaviorMode or session kind) and applies
+ * its constraints generically — core carries no knowledge of what the
+ * profile is for. Product domains (e.g. the desktop Pet manager) define
+ * profile instances and register them via EngineConfig.behaviorProfiles or
+ * ExtensionModule.behaviorProfiles.
+ */
+export interface RunBehaviorProfile {
+    id: string;
+    /** Appended to the system prompt after config.appendSystemPrompt. */
+    systemPromptAppend?: string;
+    /** Hard tool allowlist for the run (model visibility + execution gate). */
+    allowedToolNames?: ReadonlySet<string>;
+    /** When set, the run's permission mode is locked to this value. */
+    forcePermissionMode?: NonNullable<EngineConfig["permissionMode"]>;
+    /** When true, per-run planMode requests are ignored. */
+    disablePlanMode?: boolean;
+    /** When true, MCP servers are neither connected nor exposed for the run. */
+    disableMcp?: boolean;
+    /**
+     * Wrapper tag for host-provided runtime context injected at the system
+     * prompt tail (e.g. "pet-world"). Injection happens only when both this tag
+     * and profileParams.runtimeContext (a string) are present.
+     */
+    runtimeContextTag?: string;
+    /** Heading line above the runtime-context block. */
+    runtimeContextHeading?: string;
+    /**
+     * Per-run services injected into ToolContext.runScopedServices for tools
+     * that share the profile's domain conventions. reportResult(key, value)
+     * surfaces structured run output under EngineResult.extensions[profile.id].
+     */
+    createRunServices?: (opts: {
+        profileParams: Readonly<Record<string, unknown>>;
+        reportResult: (key: string, value: unknown) => void;
+    }) => Record<string, unknown>;
+    /**
+     * Per-run metadata exposed to builtin availability guards / definition
+     * rewriters via ToolVisibilityContext.profileMeta.
+     */
+    buildVisibilityMeta?: (profileParams: Readonly<Record<string, unknown>>) => Record<string, unknown> | undefined;
+    /** Auto-activate this profile for these persisted session kinds. */
+    activateForSessionKinds?: readonly string[];
+}
+export declare const QUICK_CHAT_RESTRICTED_SYSTEM_PROMPT = "# Side Conversation Boundary\n\nThis is a side conversation, not the main-thread task execution environment.\n- Treat all content before this boundary as reference history only. Do not proactively continue any earlier plan, task, or modification.\n- Default to answering the user's question directly. Use lightweight read-only exploration only when needed.\n- Do not modify files, git state, configuration, or permissions unless the user explicitly asks after this boundary (for example, \"Allow you to modify files, please help me...\" or \"Please directly edit...\"). When explicitly requested, use the normally available tools subject to the current permission and approval mode.\n- Sub-agents are disabled for this side conversation. Do not create or invoke sub-agents.";
+/** The side-conversation restriction expressed as a generic behavior profile. */
+export declare const QUICK_CHAT_RESTRICTED_PROFILE: RunBehaviorProfile;
+export interface EngineRunOptions {
+    cwd?: string;
+    onStream?: StreamCallback;
+    signal?: AbortSignal;
+    sessionId?: string;
+    /** User-facing text persisted beside the full model-facing task. */
+    displayText?: string;
+    permissionMode?: NonNullable<EngineConfig["permissionMode"]>;
+    planMode?: boolean;
+    approvalRouter?: ApprovalRouter;
+    goal?: string | GoalConfig;
+    injected?: boolean;
+    clientMessageId?: string;
+    attachments?: InputAttachmentMeta[];
+    /** Named per-run behavior profile supplied by interactive product surfaces. */
+    behaviorMode?: RunBehaviorMode;
+    /**
+     * Generic per-run parameters consumed by the active behavior profile
+     * (createRunServices / buildVisibilityMeta / runtime-context injection).
+     * Never persisted; never part of `task`.
+     */
+    profileParams?: Record<string, unknown>;
+    /** Digital human bound to this Work Session; persisted on first use. */
+    workspaceProfile?: string;
+    /**
+     * Standing brief for this Session, injected as a system section every turn and
+     * persisted on first use (see SessionState.sessionBrief).
+     */
+    sessionBrief?: string;
+    /**
+     * Host-authorized Sessions in the same project that this run may message.
+     * The Engine validates the closed set against the source workspace
+     * before exposing it to the model.
+     */
+    sessionMessageTargets?: readonly SessionMessageTarget[];
+    /**
+     * @deprecated Compat alias for `profileParams.runtimeContext` — bounded host
+     * Pet world JSON; model-visible for this run, never persisted.
+     */
+    petRuntimeContext?: string;
+    /**
+     * @deprecated Compat alias for `profileParams.workspaces` — closed Workspace
+     * choices available to DelegateWork for this Pet turn.
+     */
+    petWorkspaces?: readonly LegacyPetWorkspaceOption[];
+    /** Durable classification requested only when creating a new session. */
+    kind?: SessionKind;
+    /** Trusted metadata for an interrupt redrive initiated by agent direction. */
+    agentDirection?: {
+        envelopeIds: string[];
+        correlationIds: string[];
+    };
+    /** Trusted child writer generation used to fence mailbox drains. */
+    runtimeGeneration?: number;
+    /** Trusted runtime-only progress events; never model/tool input. */
+    onAgentProgress?: (event: AgentRuntimeProgressEvent) => void;
+}
+export type AgentRuntimeProgressEvent = {
+    type: "phase";
+    phase: "starting" | "model" | "tool" | "waiting-permission" | "compacting" | "finalizing";
+    toolName?: string;
+} | {
+    type: "usage";
+    usage: TokenUsage;
+};
+export interface ChildEngineRuntime {
+    run(task: string, options?: EngineRunOptions): Promise<EngineResult>;
+    setAgentControlStateListener(listener: ((state: LiveChildState) => void) | undefined): void;
+    setAgentDirectionsDeliveredListener?(listener: ((envelopeIds: string[]) => void) | undefined): void;
+}
+export interface ChildEngineRunner {
+    createChild?(config: EngineConfig): ChildEngineRuntime;
+    runChild(config: EngineConfig, task: string, options: Pick<EngineRunOptions, "signal" | "onStream" | "sessionId">): Promise<Pick<EngineResult, "text" | "sessionId" | "usage">>;
+}
+export interface RunScopedDisposer {
+    dispose(): void | Promise<void>;
+}

package/dist/engine/run-types.js

@@ -0,0 +1,12 @@
+export const QUICK_CHAT_RESTRICTED_SYSTEM_PROMPT = `# Side Conversation Boundary
+
+This is a side conversation, not the main-thread task execution environment.
+- Treat all content before this boundary as reference history only. Do not proactively continue any earlier plan, task, or modification.
+- Default to answering the user's question directly. Use lightweight read-only exploration only when needed.
+- Do not modify files, git state, configuration, or permissions unless the user explicitly asks after this boundary (for example, "Allow you to modify files, please help me..." or "Please directly edit..."). When explicitly requested, use the normally available tools subject to the current permission and approval mode.
+- Sub-agents are disabled for this side conversation. Do not create or invoke sub-agents.`;
+/** The side-conversation restriction expressed as a generic behavior profile. */
+export const QUICK_CHAT_RESTRICTED_PROFILE = {
+    id: "quickChatRestricted",
+    systemPromptAppend: QUICK_CHAT_RESTRICTED_SYSTEM_PROMPT,
+};

package/dist/engine/run-workspace.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Run-workspace resolution — the pre-session phase of Engine.runExclusive:
+ * pins session kind, resolves the switchable work-Session profile binding,
+ * behavior profile / permission mode / plan mode, workspace resume (with its
+ * two early-return shapes), and the effective cwd. Pure of Engine — everything
+ * arrives via the args object (run-setup.ts / run-image-input.ts style).
+ */
+import type { SessionKind } from "../types.js";
+import type { SessionManager } from "../session/session-manager.js";
+import type { SettingsManager } from "../settings/manager.js";
+import type { EngineConfig, EngineResult } from "./types.js";
+import type { EngineRunOptions, RunBehaviorProfile } from "./run-types.js";
+import { type RunProfileState } from "./run-setup.js";
+/**
+ * Resolve the working directory for a run. Precedence for legacy sessions:
+ *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
+ * (Moved verbatim from engine.ts; engine.ts re-exports it for compatibility.)
+ */
+export declare function resolveRunCwd(args: {
+    optionCwd?: string;
+    sessionCwd?: string;
+    configCwd?: string;
+    processCwd: string;
+}): string;
+export interface RunWorkspaceResolution {
+    sessionKind: SessionKind;
+    sessionWorkspaceProfile: string | undefined;
+    profile: RunBehaviorProfile | undefined;
+    profileParams: Readonly<Record<string, unknown>>;
+    runPermissionMode: NonNullable<EngineConfig["permissionMode"]>;
+    runPlanMode: boolean;
+    cwd: string;
+    profileState: RunProfileState;
+}
+export type ResolveRunWorkspaceResult = {
+    ok: true;
+    resolution: RunWorkspaceResolution;
+} | {
+    ok: false;
+    result: EngineResult;
+};
+export declare function resolveRunWorkspace(args: {
+    options: EngineRunOptions | undefined;
+    sessionManager: Pick<SessionManager, "exists" | "readSessionKind" | "readSessionWorkspaceProfile" | "resolveSessionWorkspaceForResume" | "readSessionMainRoot">;
+    resolveBehaviorProfile: (sessionKind: string, behaviorMode: string | undefined) => RunBehaviorProfile | undefined;
+    configPermissionMode: EngineConfig["permissionMode"];
+    configCwd: string | undefined;
+    settings: SettingsManager;
+    processCwd: string;
+}): Promise<ResolveRunWorkspaceResult>;

package/dist/engine/run-workspace.js

@@ -0,0 +1,114 @@
+import { resolveRunProfileState } from "./run-setup.js";
+/**
+ * Resolve the working directory for a run. Precedence for legacy sessions:
+ *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
+ * (Moved verbatim from engine.ts; engine.ts re-exports it for compatibility.)
+ */
+export function resolveRunCwd(args) {
+    return args.optionCwd ?? args.sessionCwd ?? args.configCwd ?? args.processCwd;
+}
+export async function resolveRunWorkspace(args) {
+    const { options } = args;
+    const persistedSessionKind = options?.sessionId && args.sessionManager.exists(options.sessionId)
+        ? args.sessionManager.readSessionKind(options.sessionId)
+        : undefined;
+    if (persistedSessionKind !== undefined &&
+        options?.kind !== undefined &&
+        persistedSessionKind !== options.kind) {
+        throw new Error(`session kind mismatch: persisted ${persistedSessionKind}, requested ${options.kind}`);
+    }
+    const sessionKind = persistedSessionKind ?? options?.kind ?? "work";
+    const persistedWorkspaceProfile = options?.sessionId && args.sessionManager.exists(options.sessionId)
+        ? args.sessionManager.readSessionWorkspaceProfile(options.sessionId)
+        : undefined;
+    const sessionWorkspaceProfile = options?.workspaceProfile ?? persistedWorkspaceProfile;
+    if (sessionKind !== "work" && sessionWorkspaceProfile) {
+        throw new Error(`session kind ${sessionKind} cannot bind a workspace profile`);
+    }
+    const profile = args.resolveBehaviorProfile(sessionKind, options?.behaviorMode);
+    // Normalize per-run profile parameters. The legacy pet-named run options
+    // fold into the generic bag (runtimeContext / workspaces) so existing
+    // hosts keep working; an explicit profileParams entry wins on key clash.
+    const profileParams = {
+        ...(options?.petRuntimeContext !== undefined
+            ? { runtimeContext: options.petRuntimeContext }
+            : {}),
+        ...(options?.petWorkspaces !== undefined ? { workspaces: options.petWorkspaces } : {}),
+        ...(options?.profileParams ?? {}),
+    };
+    const planModeDisabled = profile?.disablePlanMode === true;
+    let runPermissionMode = profile?.forcePermissionMode ??
+        options?.permissionMode ??
+        args.configPermissionMode ??
+        "acceptEdits";
+    if (!planModeDisabled && options?.planMode === true) {
+        runPermissionMode = "plan";
+    }
+    else if (!planModeDisabled && options?.planMode === false && runPermissionMode === "plan") {
+        runPermissionMode = "acceptEdits";
+    }
+    const runPlanMode = runPermissionMode === "plan";
+    const workspaceResume = options?.sessionId && args.sessionManager.exists(options.sessionId)
+        ? await args.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
+        : undefined;
+    if (workspaceResume && !workspaceResume.ok) {
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: ${workspaceResume.message}`,
+                reason: "completed",
+                sessionId: options.sessionId,
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    if (workspaceResume?.ok &&
+        workspaceResume.reason === "worktree_missing_branch_gone" &&
+        workspaceResume.message) {
+        return {
+            ok: false,
+            result: {
+                text: workspaceResume.message,
+                reason: "completed",
+                sessionId: options.sessionId,
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    // Existing P1 sessions resolve cwd from SessionWorkspace, even if the host
+    // passes a stale cwd. Legacy sessions without workspace keep the historical
+    // explicit-cwd precedence for backward compatibility.
+    const workspaceCwd = workspaceResume?.ok && workspaceResume.reason !== "legacy" ? workspaceResume.cwd : undefined;
+    const sessionCwd = workspaceCwd === undefined && options?.cwd === undefined && options?.sessionId
+        ? workspaceResume?.ok
+            ? workspaceResume.cwd
+            : args.sessionManager.readSessionMainRoot(options.sessionId)
+        : undefined;
+    const cwd = workspaceCwd ??
+        resolveRunCwd({
+            optionCwd: options?.cwd,
+            sessionCwd,
+            configCwd: args.configCwd,
+            processCwd: args.processCwd,
+        });
+    const profileState = resolveRunProfileState({
+        sessionWorkspaceProfile,
+        cwd,
+        settings: args.settings,
+    });
+    return {
+        ok: true,
+        resolution: {
+            sessionKind,
+            sessionWorkspaceProfile,
+            profile,
+            profileParams,
+            runPermissionMode,
+            runPlanMode,
+            cwd,
+            profileState,
+        },
+    };
+}

package/dist/engine/steer-queue.d.ts

@@ -6,7 +6,7 @@
  * it. Pure + side-effect-free so it unit-tests without the Engine/TurnLoop
  * harness (same rationale as the renderer's queuedInput.ts).
  */
-import type { InputAttachmentMeta } from "../protocol/types.js";
+import type { InputAttachmentMeta } from "../types.js";
 export interface SteerItem {
     id: string;
     text: string;

package/dist/engine/subagent-spawner.d.ts

@@ -0,0 +1,32 @@
+import type { LLMConfig, StreamCallback } from "../types.js";
+import type { AgentPresetName } from "../preset/index.js";
+import type { ModelPool } from "../llm/model-pool.js";
+import type { SubAgentSpawner } from "../tool-system/context.js";
+import type { EngineConfig } from "./types.js";
+import type { ChildEngineRunner } from "./run-types.js";
+import { type SandboxConfig, type SandboxMode } from "../tool-system/sandbox/index.js";
+import type { MCPServerConfig } from "../types.js";
+export declare const NESTED_AGENT_TOOLS: string[];
+export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
+export declare function resolveChildToolScope(allowlist: string[] | undefined, parentDisabled: string[] | undefined, parentEnabled: string[] | undefined): {
+    enabled?: string[];
+    disabled: string[];
+};
+export declare function resolveChildSandbox(mode: SandboxMode | undefined, parent: SandboxConfig): SandboxConfig;
+export declare function resolveChildMcpServers(allowlist: string[] | undefined, parent: Record<string, MCPServerConfig> | undefined): Record<string, MCPServerConfig> | undefined;
+export declare function wrapChildStream(destination: StreamCallback | undefined, agentId: string): StreamCallback | undefined;
+export interface CreateSubAgentSpawnerDeps {
+    parentConfig: EngineConfig;
+    /** Fully resolved sandbox for this parent run, including settings layers. */
+    parentSandbox: SandboxConfig;
+    presetName: AgentPresetName;
+    cwd: string;
+    permissionMode: NonNullable<EngineConfig["permissionMode"]>;
+    modelPool?: ModelPool;
+    appendParentSubagent: (agentId: string, description: string) => void;
+    sessionExists: (sessionId: string) => boolean;
+    getSessionParentId?: (sessionId: string) => string | null | undefined;
+    childRunner: ChildEngineRunner;
+    parentStream?: StreamCallback;
+}
+export declare function createSubAgentSpawner(deps: CreateSubAgentSpawnerDeps): SubAgentSpawner;