@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/engine/engine.d.ts

@@ -1,109 +1,81 @@
 /**
  * Engine — the main facade that wires all components together.
  */
-import type { LLMConfig, StreamCallback, TerminalReason, TokenUsage } from "../types.js";
+import type { LLMConfig, StreamCallback } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
-import { type ApprovalBackend } from "../tool-system/permission.js";
+import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
 import { HookRegistry } from "../hooks/registry.js";
-import type { HookEventName } from "../hooks/events.js";
-import type { HookHandler } from "../hooks/registry.js";
+import { type GoalConfig, type GoalExtension } from "./goal.js";
 import { SessionManager } from "../session/session-manager.js";
-import type { CostStateStore } from "./cost-store.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
-import { type SettingsScope } from "../settings/manager.js";
+import type { CapabilityOverride } from "../settings/schema.js";
+import { type FeatureFlagName } from "../settings/feature-flags.js";
 import type { ToolContext } from "../tool-system/context.js";
-import { type SandboxConfig } from "../tool-system/sandbox/index.js";
-import { type AgentPresetName } from "../preset/index.js";
 import { ModelPool, type ModelEntry } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { EngineRuntime } from "./runtime.js";
-export interface EngineConfig {
-    llm: LLMConfig;
-    cwd?: string;
-    maxTurns?: number;
-    maxToolCallsPerTurn?: number;
-    permissionMode?: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
-    preset?: AgentPresetName;
-    enabledBuiltinTools?: string[];
-    disabledBuiltinTools?: string[];
-    customSystemPrompt?: string;
-    appendSystemPrompt?: string;
-    sessionStorageDir?: string;
-    maxContextTokens?: number;
-    approvalBackend?: ApprovalBackend;
-    hooks?: EngineHookConfig[];
-    askUser?: AskUserFn;
-    mcpServers?: Record<string, import("../types.js").MCPServerConfig>;
-    /**
-     * Optional opaque store for per-session cost/usage state. When provided,
-     * Engine calls `restore()` on session resume and `serialize()` at the end
-     * of each `run()` and stores the blob on the session. Without this the
-     * Engine doesn't persist cost state — it's a UI concern.
-     */
-    costStore?: CostStateStore;
-    /**
-     * True when the Engine runs in a no-UI / one-shot context (e.g. the `run`
-     * command). Currently controls InvestigationGuard soft-mode: in headless
-     * we never hard-block a tool call because there is no human to retry.
-     * Defaults to false.
-     */
-    headless?: boolean;
-    /**
-     * Sandbox configuration for shell-tool execution. When omitted, headless
-     * runs default to "auto" (Seatbelt on macOS / bwrap on Linux when
-     * available) and interactive runs default to "off" because a human is in
-     * the loop to approve commands.
-     */
-    sandbox?: SandboxConfig;
-    /**
-     * True when this Engine is itself a sub-agent (spawned by another
-     * Engine's Agent tool). Threaded into ToolContext so the Agent tool can
-     * refuse re-entry — defense in depth against the tool-list strip in
-     * spawn(): if a tool registry regression ever leaks Agent into a child's
-     * pool, the runtime check still blocks the call.
-     */
-    isSubAgent?: boolean;
-    /**
-     * Optional shared EngineRuntime providing pre-constructed shared resources
-     * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead
-     * of constructing its own. Existing callers that omit this field continue to
-     * work unchanged — T11 will migrate them.
-     */
-    runtime?: EngineRuntime;
-    /**
-     * Which disk config layers this Engine may read. Defaults to 'project' —
-     * the safe default: a library/SDK embedding never silently inherits the
-     * host user's personal ~/.code-shell config (keys, models, MCP, hooks); it
-     * only reads the project-level ${cwd}/.code-shell that travels with a repo.
-     * Host-terminal entrypoints (TUI/desktop/CLI) pass 'full' to restore the
-     * managed+user+project+local behavior. 'isolated' reads no disk at all.
-     * Subagents inherit the parent Engine's scope. See SettingsScope.
-     */
-    settingsScope?: SettingsScope;
-}
-export interface EngineHookConfig {
-    event: HookEventName;
-    handler: HookHandler;
-    priority?: number;
-    name?: string;
-}
-export interface EngineResult {
-    text: string;
-    reason: TerminalReason;
-    sessionId: string;
-    turnCount: number;
-    usage: TokenUsage;
-}
+/**
+ * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
+ * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
+ * compat flag off only drops the same-named .md (CLAUDE.md / AGENTS.md); the
+ * .claude/ subdir, *.local.md and rules/ are intentionally NOT linked.
+ * undefined (instructions omitted) means both stay on — backward compatible.
+ */
+export declare function compatFileNamesFrom(instructions?: {
+    compatClaude?: boolean;
+    compatCodex?: boolean;
+}): string[];
+export type { EngineConfig, EngineHookConfig, EngineResult } from "./types.js";
+import type { EngineConfig, EngineResult } from "./types.js";
+export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
- * - `modelKey` set + present in pool → that model's config (over parent base).
+ * - `modelKey` set + present in pool → that model's config (pure entry-derived
+ *   identity; the parent's llm is NOT consulted).
  * - otherwise (no key, no pool, or key miss) → the parent's llm unchanged.
  * Key miss is a soft fallback, NOT an error: a stale agent definition must not
  * crash the spawn.
+ *
+ * ClientDefaults (temperature/timeout/etc.) are inherited from the parent
+ * Engine directly via EngineConfig.clientDefaults — they do not flow through
+ * this helper because they're not part of LLMConfig anymore.
  */
 export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
-/** Load reusable sub-agent role definitions from <cwd>/.code-shell/agents. */
-export declare function loadAgentDefinitionsForCwd(cwd: string): AgentDefinitionRegistry;
+/**
+ * Load reusable sub-agent role definitions, merging:
+ *   1. project-level  <cwd>/.code-shell/agents/*.md   (ships built-ins)
+ *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
+ * Names in `disabledAgents` are filtered out so the LLM never sees them.
+ */
+/**
+ * Resolve the working directory for a run. Precedence:
+ *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
+ *
+ * The session-cwd tier is what stops a project-bound session from being
+ * resumed against the wrong directory: when a host omits options.cwd (e.g. its
+ * sidebar repo selection drifted to null), the session's own recorded cwd is
+ * recovered so the engine still loads THAT project's agents/settings/memory,
+ * not whatever process.cwd() happens to be. Pure so the precedence is testable
+ * without standing up an Engine.
+ */
+export declare function resolveRunCwd(args: {
+    optionCwd?: string;
+    sessionCwd?: string;
+    configCwd?: string;
+    processCwd: string;
+}): string;
+export declare function loadAgentDefinitionsForCwd(cwd: string, disabledAgents?: string[], disabledPlugins?: string[]): AgentDefinitionRegistry;
+/**
+ * #7: apply a project's per-turn builtin capability override to a tool list.
+ * A builtin marked `off` for the current cwd is HIDDEN from the turn's tool
+ * list (matching how skills/plugins/agents `off` apply mid-session). `on` /
+ * `inherit` / absent keep the tool — we can't re-add a tool the ctor-frozen
+ * registry omitted, but `on` for a tool already present is a no-op. Pure +
+ * exported so it's unit-testable without a full run() turn.
+ */
+export declare function applyBuiltinOverrideVisibility<T extends {
+    name: string;
+}>(tools: T[], override: Record<string, CapabilityOverride> | undefined): T[];
 /**
  * Compute a child Engine's tool scope.
  * - `allowlist` set → child enabled = allowlist minus nested-agent tools
@@ -117,21 +89,44 @@ export declare function resolveChildToolScope(allowlist: string[] | undefined, p
 };
 export declare class Engine {
     private config;
-    private readonly preset;
+    private preset;
     private toolRegistry;
     private hooks;
     private sessionManager;
     private mcpManager;
     private modelPool;
+    /**
+     * Handles for the settings-sourced hook handlers registered by
+     * registerSettingsHooks(), so reloadHooks() can unregister exactly those
+     * (and nothing else — plugin hooks, goal/builtin hooks are untouched) before
+     * re-registering from fresh settings. Without this, a reload would
+     * accumulate duplicate settings-hook handlers that all fire per event.
+     */
+    private settingsHookHandles;
+    /**
+     * Highest config-reload version applied so far. refreshRuntimeConfig drops
+     * any payload whose version is <= this, so out-of-order reload deliveries
+     * (multiple quick settings saves) can't let an older config clobber a newer
+     * one.
+     */
+    private lastAppliedConfigVersion;
     /** Memoized sub-agent role registry, keyed by the cwd it was loaded from. */
     private agentDefsCache?;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
+    private readonly sandboxCache;
     /** Active permission mode for this Engine instance. */
     permissionMode: NonNullable<EngineConfig["permissionMode"]>;
     /** True when permissionMode === "plan". */
     planMode: boolean;
     private settingsManager;
+    /**
+     * Cached auxiliary-task LLM client, keyed by the models[].key it was built
+     * from. Background calls (memory extraction, auto-dream) reuse it across
+     * runs so we don't redo the provider handshake every session. Invalidated
+     * implicitly: a changed auxModelKey produces a different cache key.
+     */
+    private auxClientCache?;
     private lastContextManager;
     private lastMessages;
     private lastSessionId;
@@ -152,10 +147,49 @@ export declare class Engine {
      * LLM response arrives.
      */
     private ctxOverheadBySid;
+    /**
+     * Step-gap steering queue (per sessionId, in-memory). Host pushes user
+     * messages here via enqueueSteer while a run is in flight; the turn loop
+     * drains it at each step boundary and splices them into the next LLM request
+     * WITHOUT aborting (the 不打断 path, vs cancel+resend). Pure memory, forgotten
+     * on process exit — same model as the credential session-allow set, so
+     * multiple Engines don't interfere and it stays cleanly extractable.
+     */
+    private steerQueueBySid;
     private activePermission;
+    /**
+     * The TurnLoop of the in-flight run(), exposed so extendGoalRun() can bump a
+     * running goal's turn/budget ceilings mid-run (TODO 3.1). Null when idle.
+     */
+    private activeTurnLoop;
+    /**
+     * The goal-stop hook of the in-flight goal run, exposed so clearGoal() can
+     * unregister it mid-run (the closure holds the now-cleared goal and would
+     * otherwise keep re-blocking the stop). Null when no goal run is active.
+     */
+    private activeGoalHook;
+    /**
+     * The in-flight run's session bundle, held so clearGoal() can wipe the goal
+     * on the SAME instance the run loop is persisting each turn — not a fresh
+     * detached copy from resume(). Without this, a mid-run 清除 clears disk, but
+     * the still-running loop's next saveState(bundle.state) resurrects the goal
+     * (bundle.state.activeGoal was never dropped). A never-completing goal run
+     * (judge keeps returning not_met → continueSession) stays live for a long
+     * time, so this write-back race is the norm, not an edge case, for such runs.
+     * Single-valued like activeTurnLoop — one top-level run per engine at a time.
+     * Null when idle; set at run start, cleared in run's finally.
+     */
+    private activeRunSession;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens(): number;
     private resolveMaxContextTokens;
+    /**
+     * Compaction thresholds from settings.context, clamped so they keep the
+     * required ordering floor < compact < summarize even if the user configures
+     * conflicting values (e.g. summarize below compact). Falls back to the
+     * ContextManager defaults when a field is absent.
+     */
+    private resolveContextRatios;
     /**
      * Emit a lifecycle hook with isSubAgent auto-merged into data so handlers
      * can skip noisy injections for spawned children. All Engine-side hook
@@ -171,22 +205,35 @@ export declare class Engine {
      * should register SDK-side handlers.
      */
     private registerSettingsHooks;
+    /**
+     * Re-apply settings.hooks onto the live HookRegistry after a settings
+     * change (config hot-reload layer 2). Surgical: removes ONLY the
+     * settings-sourced handlers this Engine previously registered (tracked in
+     * settingsHookHandles by identity) and re-runs registerSettingsHooks() from
+     * fresh disk settings. Plugin hooks (registered once at construction at
+     * priority 80) and goal/builtin/SDK-config hooks are never touched.
+     *
+     * The SettingsManager cache is invalidated first so the re-read reflects the
+     * latest settings.json on disk (mirrors freshSettings()'s load() semantics).
+     * Sub-agents never register settings hooks, so this is a no-op for them.
+     */
+    reloadHooks(): void;
     constructor(config: EngineConfig);
     /**
-     * Load models[] / providers[] from settings into the active ModelPool and
+     * Load modelConnections[] from settings into the active ModelPool and
      * resync this.config.llm with the matching entry. Called from the ctor and
      * from reloadModelPool() (e.g. after onboarding writes new entries to disk).
      */
     private populateModelPoolFromSettings;
     /**
      * Re-read settings and refresh the model pool. Used after onboarding /login
-     * writes new providers[] / models[] to disk so the running engine picks them
+     * writes new modelConnections[] to disk so the running engine picks them
      * up without a process restart. Existing pool entries are kept (re-registering
      * the same key overwrites them), so callers don't need to clear first.
      */
     reloadModelPool(): void;
     /**
-     * Auto-populate the model pool when settings.models[] is empty but
+     * Auto-populate the model pool when no modelConnections[] are configured but
      * the user has configured an API key. Detects the provider from the
      * key prefix / baseUrl and registers all its known models.
      */
@@ -195,13 +242,58 @@ export declare class Engine {
      * Register a custom tool (from product adapter) into the tool registry.
      * Must be called before run().
      */
-    registerCustomTool(definition: import("../types.js").RegisteredTool, executor: (args: Record<string, unknown>) => Promise<string>): void;
+    registerCustomTool(definition: import("../types.js").RegisteredTool, executor: BuiltinToolFn): void;
     /**
      * Inject the askUser handler after construction. Used by AgentServer
      * to wire its protocol-backed askUser into an Engine that was created
      * before the server existed (chicken-and-egg: server takes engine in ctor).
      */
     setAskUser(fn: AskUserFn | undefined): void;
+    /**
+     * Inject the browser automation bridge after construction (same chicken-and-egg
+     * as setAskUser: the desktop host builds the bridge — which drives a webview —
+     * after the Engine exists). Undefined → the browser_* tools degrade with a
+     * clear "no browser panel" error.
+     */
+    setBrowserBridge(bridge: import("../tool-system/browser-bridge.js").BrowserBridge | undefined): void;
+    /**
+     * Queue a user message to be spliced into the in-flight run for `sessionId`
+     * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
+     * resend). General-purpose: any host path (UI 引导, future agent coordination,
+     * external triggers) can call it. If no run is active for the session the
+     * message simply waits in the queue and is consumed when that session next
+     * runs (rare race; host normally only steers while busy). No-op on blank text.
+     *
+     * `id` is the host's stable queue-entry id. It rides through to the
+     * `steer_injected` event (so the host can match the injected bubble back to
+     * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
+     * entry. A blank id is tolerated but means the entry can't be revoked.
+     */
+    enqueueSteer(sessionId: string, text: string, id?: string): void;
+    /**
+     * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
+     * removed, false if it was already consumed by the turn loop (can't take it
+     * back — it has been spliced into the run).
+     */
+    unsteer(sessionId: string, id: string): boolean;
+    /** Drain + clear the steer queue for a session (turn loop consumes per step). */
+    private consumeSteer;
+    /** Wire the cookie→browser injection callback (InjectCredential tool). Same
+     *  post-construction injection model as setBrowserBridge. */
+    setInjectCredential(fn: import("../tool-system/context.js").InjectCredentialFn | undefined): void;
+    /**
+     * Whether this engine runs unattended (no interactive human). Used by the
+     * in-process AgentServer to decide whether to wire an interactive askUser.
+     */
+    isHeadless(): boolean;
+    /**
+     * Probe whether a session already exists on disk (its state/transcript dir is
+     * present). Used by the protocol server to distinguish "resume an existing
+     * session" from "silently create a fresh empty one" — e.g. a cron resume job
+     * whose target session the user deleted must fail loudly, not run its prompt
+     * against a blank session. A stat probe, not a load.
+     */
+    sessionExistsOnDisk(sessionId: string): boolean;
     /**
      * Run a task from start to finish.
      */
@@ -210,12 +302,37 @@ export declare class Engine {
         onStream?: StreamCallback;
         signal?: AbortSignal;
         sessionId?: string;
+        /**
+         * Goal mode for this run: the engine registers a GoalStopHook so the
+         * turn loop runs until the session model judges this goal met. Falls
+         * back to config.goal. Orthogonal to permissionMode. Accepts a raw
+         * string or a full GoalConfig; normalized once at the run boundary.
+         */
+        goal?: string | GoalConfig;
+        /**
+         * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
+         * background-job completion notification the server re-injects to wake an
+         * idle session) rather than the user's own input. The task is still sent
+         * to the model as a `role:"user"` message, but it is persisted with an
+         * `injected` flag so the disk reader skips rendering it as a user bubble
+         * on replay (matching the live UI, which shows only the assistant reply).
+         */
+        injected?: boolean;
     }): Promise<EngineResult>;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
      * task. Extracts durable memories from the transcript, saves a session
      * summary, and conditionally triggers auto-dream consolidation.
      */
+    /**
+     * Resolve the LLM client for background/auxiliary work (memory extraction,
+     * auto-dream). When settings.defaults.auxText names a valid pool model, build
+     * (and cache) a dedicated client for it so per-turn book-keeping runs on a cheap
+     * fast model instead of the expensive primary. Falls back to `fallback` (the
+     * active run's client) when unset, unknown, or on any build failure — aux
+     * work is best-effort and must never break a run.
+     */
+    private resolveAuxClient;
     private runMemoryPipeline;
     /**
      * Drive the auto-dream tool-call loop.
@@ -234,33 +351,31 @@ export declare class Engine {
      * bailed before the first LLM call (e.g. registry missing the tools).
      */
     private runDreamLoop;
-    /**
-     * Execute one memory tool call inside the dream loop. Enforces the two
-     * dream-loop invariants the prompt also states:
-     *   - Only the 4 memory tools are dispatchable.
-     *   - Save/Delete in "user" scope is refused (returned as a tool error)
-     *     because dream runs without an interactive permission backend.
-     */
-    private dispatchDreamTool;
     getToolRegistry(): ToolRegistry;
     /**
      * Switch the active model by pool key. Takes effect on the next run() call.
      * Returns the new model entry.
      *
-     * Persists settings.activeKey (and a legacy settings.model.* mirror) so the
+     * Persists settings.defaults.text (= the connection id / pool key) so the
      * next process startup defaults to the same model — without this, switches
      * only live in memory and every restart reverts to the previously persisted
-     * activeKey.
+     * defaults.text.
      */
     switchModel(key: string): ModelEntry;
+    /**
+     * Zero a session's cumulative token/cache usage on disk. Called on a model
+     * switch: a different model has its own prompt cache, so the accumulated
+     * cache-hit stats from the prior model are no longer meaningful. The next
+     * run's baseline (snapshotted from state.tokenUsage) then starts from zero.
+     */
+    resetSessionUsage(sessionId: string): void;
     /**
      * Write the active model selection to ~/.code-shell/settings.json.
      *
-     * We mirror into the legacy settings.model.* block (provider/name/apiKey/
-     * baseUrl) because boot paths in cli/main.ts, repl.ts, run.ts still read it.
-     * The mirror uses resolved llm values (not raw entry.*) so credentials that
-     * live on settings.providers[] flow through correctly — entry.apiKey is
-     * undefined when the entry resolves via providerCatalog.
+     * Persists settings.defaults.text = entry.key (the connection id == pool
+     * key). That is the single field the boot path reads to restore the active
+     * text model on the next startup (see ctor: settings.defaults.text → pool
+     * switch). No legacy activeKey/model.* mirror is written.
      */
     private persistActiveModel;
     /** Get the model pool. */
@@ -270,6 +385,42 @@ export declare class Engine {
     getHookRegistry(): HookRegistry;
     getSessionManager(): SessionManager;
     getConfig(): EngineConfig;
+    /**
+     * Config hot-reload "layer 2": merge a disk-default config patch into this
+     * ALREADY-RUNNING session's `this.config`, reload settings hooks, and
+     * incrementally connect any newly-added MCP servers. Applied at the next
+     * turn boundary — an in-flight turn is NOT interrupted: it keeps using the
+     * PromptComposer it was built with, and the next turn rebuilds the composer
+     * from the freshly-merged config (composer is rebuilt per-turn).
+     *
+     * `version` is a monotonic counter from the server: stale (<=last applied)
+     * payloads are dropped so out-of-order reload deliveries can't let an older
+     * config clobber a newer one (Q5).
+     *
+     * MCP: reconciles the shared MCP pool against the new disk-default server
+     * set. Added servers connect idempotently; removed/disabled servers are
+     * disconnected and their registered MCP tools are unregistered so plugin
+     * disable takes effect without an Electron restart.
+     *
+     * Preset (#2): a preset hot-reload re-resolves `this.preset` so the next-turn
+     * PromptComposer picks up the new preset's system prompt / behavior — that's
+     * the main user-visible preset effect and it IS hot. The toolRegistry's
+     * builtin tool SET, however, is ctor-frozen (and may be shared via runtime):
+     * it is NOT rebuilt here. So a preset change that alters the builtin tool set
+     * (e.g. general → terminal-coding adds LSP/Brief) only takes effect on the
+     * next session restart; we log a warning when that case is detected.
+     *
+     * disk-default-vs-slice caveat (#8): the patch carries pure DISK-default
+     * values (preset/customSystemPrompt/appendSystemPrompt/responseLanguage/
+     * userProfile — see diskDefaultsFrom). Spreading them here OVERRIDES any
+     * per-request slice override of the same field. This is correct for the
+     * desktop host today (its per-request slice only carries permissionMode+cwd,
+     * which are excluded from the disk patch). A future host that sets
+     * slice.preset (or the other prompt fields) per-request MUST exclude those
+     * from the reload patch — or track per-request overrides separately — or this
+     * reload will clobber them back to disk values.
+     */
+    refreshRuntimeConfig(patch: Partial<EngineConfig>, version: number): void;
     /**
      * Inject context into a session's transcript without triggering a LLM turn.
      * The injected content appears as an assistant message so the LLM can see it
@@ -279,6 +430,26 @@ export declare class Engine {
      * engine.run() call for this session picks up the injected content
      * instead of a stale snapshot from the previous run.
      */
+    /**
+     * Read a session's persisted active goal WITHOUT resuming it (cheap — reads
+     * only state.json via SessionManager.readActiveGoal). The desktop host calls
+     * this on session load to re-surface the goal block + its Cancel button: a
+     * persistent goal lives only in state.activeGoal and is never replayed from
+     * the transcript, so after a reload of an aborted goal run the UI would
+     * otherwise show nothing (the "goal 还在但页面不显示、取消不了" bug). Returns
+     * undefined when the session is unknown or has no active goal.
+     */
+    getGoal(sessionId: string): GoalConfig | undefined;
+    /**
+     * Clear a session's persisted active goal (CC `/goal clear`). Works whether
+     * the session is idle or its goal run is in flight: it wipes
+     * `state.activeGoal` (so the next bare send won't re-inherit it) and, if a
+     * goal hook is currently registered for this engine, unregisters it so an
+     * in-flight run can stop instead of being re-blocked by the now-cleared goal.
+     * Returns true if a goal was actually cleared. Idempotent — clearing a
+     * session with no active goal is a no-op returning false.
+     */
+    clearGoal(sessionId: string): boolean;
     injectContext(sessionId: string, content: string): void;
     /**
      * Force context compaction on the current session.
@@ -309,22 +480,138 @@ export declare class Engine {
      */
     setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
     getPermissionMode(): NonNullable<EngineConfig["permissionMode"]>;
+    /**
+     * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —
+     * 运行中续轮/加预算). No-op (returns null) when no run is active. Lets a user
+     * keep an unattended goal going past its original cap instead of restarting.
+     */
+    extendGoalRun(opts: GoalExtension): {
+        maxTurns: number;
+        tokenBudget?: number;
+        timeBudgetMs?: number;
+        maxStopBlocks: number;
+    } | null;
+    /**
+     * The effective permission rules for the current mode + cwd (TODO 5.1) —
+     * preset defaults + mode-derived + settings.permissions.rules, in the same
+     * order the classifier evaluates them. Exposed read-only so `/permissions`
+     * (and any UI) can list what's actually in force. Pure read; builds the same
+     * rule set buildPermissionConfig does, without constructing a backend.
+     */
+    getPermissionRules(): import("../types.js").PermissionRule[];
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
      * Also syncs permissionMode to keep both fields consistent.
      */
     setPlanMode(value: boolean): void;
+    /**
+     * Block until a background agent's state changes (finishes / its result is
+     * enqueued) or `signal` aborts. Resolves `true` if aborted, `false` on a
+     * change. The caller re-checks `hasRunningForSession` after each wake, so a
+     * spurious wake (another session's agent) just loops again.
+     *
+     * Subscribes to BOTH the registry AND the notification queue — and that's
+     * load-bearing, not belt-and-suspenders. A completing agent calls
+     * `markCompleted` (registry notify) and only THEN `enqueue` (queue notify),
+     * as two separate statements. If we woke on the registry notify alone, the
+     * loop could re-check, see no running agents, and `drainAll` BEFORE the
+     * result was enqueued — silently losing the last agent's output. Waking on
+     * the queue notify guarantees the item is already in the bucket. But a
+     * *cancelled* agent marks-but-never-enqueues (by design), so we also need
+     * the registry notify or a final cancel would hang the wait forever. Hence
+     * both. Subscribe-before-await closes the check/wait race either way.
+     */
+    private waitForBackgroundAgentChange;
+    /**
+     * Like waitForBackgroundAgentChange but with no abort signal and a hard
+     * timeout. Resolves `true` on a registry/queue change, `false` if `timeoutMs`
+     * elapses first. Used only by the headless abort-drain cleanup, where we want
+     * to catch a completing agent's just-about-to-enqueue notification without
+     * risking a permanent hang on an agent that never completes.
+     */
+    private waitForBackgroundAgentChangeOrTimeout;
     /**
      * Sub-agent role registry for the given cwd, memoized per-cwd so the
      * directory is read once rather than every turn. A new cwd (e.g. via
      * run({ cwd })) reloads.
      */
     private getAgentDefinitions;
+    /**
+     * Read settings.disabledAgents, folded with the project's
+     * capabilityOverrides.agents overlay for `cwd`. Unlike disabledSkills,
+     * sub-agents do NOT skip this — a disabled role must stay invisible
+     * everywhere. The overlay lets a project force-enable a globally-disabled
+     * role or force-disable a globally-enabled one (tri-state); read UNMERGED
+     * (getForScope) so inherit survives. No cwd / no overlay → baseline
+     * unchanged. Mirrors readDisabledLists (skills/plugins).
+     */
+    private readDisabledAgents;
+    /**
+     * Read the project's capabilityOverrides.builtin bucket for `cwd`, read
+     * UNMERGED (getForScope) so tri-state inherit survives. Sub-agents skip the
+     * overlay (minimal surface, same as readDisabledLists) — their builtin lists
+     * are already narrowed by resolveChildToolScope. No cwd / error → undefined,
+     * so the caller's baseline builtin lists pass through unchanged.
+     */
+    private readBuiltinOverride;
     /**
      * Build a base ToolContext for this Engine. Used by run() (which then
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
+    private resolveSandboxWithoutRuntime;
+    /**
+     * Build the shell env layered onto the Bash tool / background shells (see
+     * mergeShellEnv). Three user-configured sources, merged lowest → highest:
+     *
+     *   1. project `localEnvironment.env`  — the per-project "local environment"
+     *      panel (DATABASE_URL etc.); the floor, so a project's own panel values
+     *      can be overridden by an explicit top-level `env`.
+     *   2. global top-level `env`          — ~/.code-shell/settings.json; the
+     *      canonical home for API keys (OPENAI_API_KEY) a skill script reads —
+     *      configure once, every project's skills get it.
+     *   3. project top-level `env`         — .code-shell/settings.json; a project
+     *      that wants to override a global key wins.
+     *
+     * Each scope is read UNMERGED so the layering here is the single source of
+     * precedence (getForScope merges nothing). Returns undefined when no layer
+     * contributes a key, so the caller passes it through unchanged for projects
+     * that configure none.
+     *
+     * Sub-agents: a sub-agent is the user's OWN agent doing the user's work
+     * (mirrors Claude Code, where sub-agents inherit the parent environment), so
+     * it now reads the SAME env as the parent. The sub-agent branch is kept as an
+     * explicit seam (`filterSubagentEnv`) rather than removed — a future policy
+     * could narrow what a sub-agent sees (e.g. drop credential secrets) by
+     * changing that one hook; today it passes everything through unchanged.
+     * A no-cwd context still gets nothing (there is genuinely no project to read).
+     *
+     * None of these is filtered through the deny regex (mergeShellEnv): the user
+     * put them there deliberately. The allowlist/deny machinery only guards the
+     * host's process.env from a tainted model exfiltrating it via `env | curl`.
+     */
+    private readShellEnv;
+    /**
+     * Policy seam for what a sub-agent's shell sees. A sub-agent inherits the
+     * parent environment by default (mirrors Claude Code), so this is the
+     * identity function today. It exists so a future policy can narrow the set
+     * (e.g. strip credential `exposeAsEnv` secrets, or allowlist by name) in ONE
+     * place instead of scattering `isSubAgent` checks through readShellEnv.
+     */
+    private filterSubagentEnv;
+    /**
+     * Read the project's `localEnvironment.setupScripts` for this cwd (the raw
+     * per-platform map). Used by EnterWorktree to run setup once in a freshly
+     * created worktree. Returns undefined for sub-agents / no cwd (same minimal
+     * surface as readShellEnv). The platform selection + run live in
+     * git/worktree.ts; this only fetches the configured scripts.
+     */
+    readWorktreeSetupScripts(cwd?: string): {
+        default?: string;
+        macos?: string;
+        linux?: string;
+        windows?: string;
+    } | undefined;
     buildToolContext(): ToolContext;
     /**
      * Read settings.disabledSkills + settings.disabledPlugins in a single
@@ -338,4 +625,40 @@ export declare class Engine {
      * the same snapshot.
      */
     private readDisabledLists;
+    /**
+     * Public view of the folded disabled lists, for hosts that need the
+     * EFFECTIVE state (e.g. the protocol server's settings hot-reload rebuilds
+     * the plugin-MCP merge per session — a project-level "on" must override the
+     * global disabledPlugins there too).
+     */
+    getEffectiveDisabledLists(): {
+        disabledSkills: string[];
+        disabledPlugins: string[];
+    };
+    /**
+     * Public: resolve every known feature flag to its effective boolean (the
+     * settings overlay merged over the compiled-in defaults). Used by the
+     * `config` protocol query so the `/features` command can list flag state.
+     */
+    getFeatureFlags(): Record<FeatureFlagName, boolean>;
+    /**
+     * Read the merged `settings.featureFlags` overlay for this cwd. Project
+     * settings override user settings via the normal SettingsManager merge.
+     * Returns undefined (→ all defaults) on any read error or for sub-agents,
+     * so a flag check never throws and a child runs with default behavior.
+     */
+    private readFeatureFlags;
+    /**
+     * Read settings.memories ({ maxCount, maxAge, extractionModel, autoExtract }).
+     * Returns undefined on any error or when absent, so the memory pipeline
+     * falls back to its built-in defaults.
+     */
+    private readMemoriesConfig;
+    /**
+     * LLM client for memory extraction (TODO 8.1). Prefers
+     * settings.memories.extractionModel when it names a valid pool model;
+     * otherwise falls back to the aux client (which itself falls back to the
+     * passed primary). Build failures fall back too — extraction is best-effort.
+     */
+    private resolveExtractionClient;
 }