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

package/dist/session/transcript.d.ts

@@ -10,10 +10,34 @@ export declare class Transcript {
     getFilePath(): string;
     constructor(filePath: string);
     append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
-    appendMessage(role: string, content: string | ContentBlock[]): TranscriptEvent;
+    /**
+     * Append a chat message to the transcript.
+     *
+     * `injected` marks a synthetic system-reminder turn (e.g. a background-job
+     * completion notification) that is submitted to the model as `role:"user"`
+     * but is NOT the user's own input. The disk reader uses this flag to skip
+     * rendering it as a user bubble on replay (matching the live UI, which never
+     * shows it as a bubble — only the assistant's reply). Real user input and
+     * step-gap steering messages are left unmarked so they render normally.
+     */
+    appendMessage(role: string, content: string | ContentBlock[], opts?: {
+        injected?: boolean;
+    }): TranscriptEvent;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
     appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
+     *  Written at spawn time so replay can rebuild the sub-agent's card from
+     *  sessions/<agentId>/ — agentId === the sub-agent's session id. */
+    appendSubagent(agentId: string, name: string | undefined, description: string): TranscriptEvent;
     appendTurnBoundary(): TranscriptEvent;
+    /**
+     * Mark the in-flight turn as user-interrupted (Stop). Persisted so a resume
+     * rebuilds the renderer's "stopped" marker (foldTranscript) — otherwise the
+     * interrupted turn folds behind the process-card header on reload.
+     * Idempotent: a no-op if the last event is already a turn_stopped (the loop
+     * can hit more than one abort return for a single Stop).
+     */
+    appendTurnStopped(): TranscriptEvent | undefined;
     appendSummary(summary: string, compactedRange: {
         fromTurn: number;
         toTurn: number;

package/dist/session/transcript.js

@@ -29,8 +29,22 @@ export class Transcript {
         this.flush(event);
         return event;
     }
-    appendMessage(role, content) {
-        return this.append("message", { role, content });
+    /**
+     * Append a chat message to the transcript.
+     *
+     * `injected` marks a synthetic system-reminder turn (e.g. a background-job
+     * completion notification) that is submitted to the model as `role:"user"`
+     * but is NOT the user's own input. The disk reader uses this flag to skip
+     * rendering it as a user bubble on replay (matching the live UI, which never
+     * shows it as a bubble — only the assistant's reply). Real user input and
+     * step-gap steering messages are left unmarked so they render normally.
+     */
+    appendMessage(role, content, opts) {
+        return this.append("message", {
+            role,
+            content,
+            ...(opts?.injected ? { injected: true } : {}),
+        });
     }
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
@@ -38,10 +52,29 @@ export class Transcript {
     appendToolResult(toolCallId, toolName, result, error) {
         return this.append("tool_result", { toolCallId, toolName, result, error });
     }
+    /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
+     *  Written at spawn time so replay can rebuild the sub-agent's card from
+     *  sessions/<agentId>/ — agentId === the sub-agent's session id. */
+    appendSubagent(agentId, name, description) {
+        return this.append("subagent", { agentId, name, description });
+    }
     appendTurnBoundary() {
         this.currentTurn++;
         return this.append("turn_boundary", { turnNumber: this.currentTurn });
     }
+    /**
+     * Mark the in-flight turn as user-interrupted (Stop). Persisted so a resume
+     * rebuilds the renderer's "stopped" marker (foldTranscript) — otherwise the
+     * interrupted turn folds behind the process-card header on reload.
+     * Idempotent: a no-op if the last event is already a turn_stopped (the loop
+     * can hit more than one abort return for a single Stop).
+     */
+    appendTurnStopped() {
+        const last = this.events[this.events.length - 1];
+        if (last && last.type === "turn_stopped")
+            return undefined;
+        return this.append("turn_stopped", {});
+    }
     appendSummary(summary, compactedRange) {
         return this.append("summary", {
             summary,

package/dist/session/undo-target.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure selection of the "most recent file modification" to undo, given a
+ * FileHistory snapshot list. Kept fs-free so the "what does /undo target"
+ * decision is unit-testable and shared between the TUI command and any future
+ * desktop entry point.
+ *
+ * A snapshot is the *pre-modification* backup of a file (see file-history.ts:
+ * saveSnapshot runs before Write/Edit/ApplyPatch). So the newest snapshot's
+ * backup is the content to restore for a single-step undo: it is the state the
+ * file had immediately before the last edit.
+ */
+import type { FileSnapshot, RedoRecord } from "./file-history.js";
+/**
+ * The snapshot for the most recent modification. Returns the entry with the
+ * greatest `timestamp`; on a tie (same-millisecond snapshots of different
+ * files) the LAST such entry in array order wins — saveSnapshot pushes in
+ * chronological order, so the last pushed is the most recently recorded, which
+ * is the stable, predictable choice. Returns null for an empty history.
+ */
+export declare function latestUndoTarget(snapshots: FileSnapshot[]): FileSnapshot | null;
+/**
+ * For "/undo all": each tracked file's EARLIEST snapshot — its content before
+ * the *first* AI edit this session. Restoring all of these reverts the whole
+ * session's file changes (vs. latestUndoTarget, which is the single last step).
+ *
+ * Returns one snapshot per file path, ordered by that file's first-edit time
+ * (oldest first) so a preview reads chronologically. On a same-millisecond tie
+ * for a given file, the FIRST array entry wins (earliest recorded).
+ */
+export declare function earliestSnapshotsPerFile(snapshots: FileSnapshot[]): FileSnapshot[];
+/**
+ * For turn-level "/undo": the snapshots needed to revert just the MOST RECENT
+ * conversation turn (one user message = one turn, see SessionState.turnSeq).
+ *
+ * The latest turn = the greatest `turnSeq` present. A turn boundary is defined
+ * by turnSeq, NOT wall-clock — a clock skew must not move the boundary. Within
+ * that turn, each touched file is restored to its EARLIEST snapshot of the turn
+ * (its content before the *first* edit that turn), so re-editing a file twice
+ * in one turn still reverts to the pre-turn baseline — and edits from *earlier*
+ * turns are left intact (that's the whole point vs. earliestSnapshotsPerFile,
+ * which spans the whole session).
+ *
+ * Backward compatibility: snapshots written before this feature have no
+ * `turnSeq`. They share the `undefined` bucket. `undefined` sorts as the
+ * smallest "turn", so any real (tagged) turn supersedes the legacy bucket; a
+ * history that is ALL-legacy degrades to whole-session behaviour (each file's
+ * earliest) rather than throwing.
+ *
+ * Returns one snapshot per file, ordered by that file's first-edit time within
+ * the turn (oldest first) so a preview reads chronologically. Empty → [].
+ */
+export declare function latestTurnUndoTargets(snapshots: FileSnapshot[]): FileSnapshot[];
+/**
+ * For "/redo": the RedoRecord[] of the MOST RECENT undone turn — the turn that
+ * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
+ * undone state (i.e. nothing newer happened since the undo). Otherwise [].
+ *
+ * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
+ * exists only for a turn that was undone and not yet redone). R is redoable iff
+ * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
+ * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
+ * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
+ * is the sole evidence and is honoured as long as nothing newer superseded it.
+ *
+ * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
+ */
+export declare function latestRedoTargets(redoRecords: RedoRecord[], snapshots: FileSnapshot[]): RedoRecord[];

package/dist/session/undo-target.js

@@ -0,0 +1,144 @@
+/**
+ * Pure selection of the "most recent file modification" to undo, given a
+ * FileHistory snapshot list. Kept fs-free so the "what does /undo target"
+ * decision is unit-testable and shared between the TUI command and any future
+ * desktop entry point.
+ *
+ * A snapshot is the *pre-modification* backup of a file (see file-history.ts:
+ * saveSnapshot runs before Write/Edit/ApplyPatch). So the newest snapshot's
+ * backup is the content to restore for a single-step undo: it is the state the
+ * file had immediately before the last edit.
+ */
+/**
+ * The snapshot for the most recent modification. Returns the entry with the
+ * greatest `timestamp`; on a tie (same-millisecond snapshots of different
+ * files) the LAST such entry in array order wins — saveSnapshot pushes in
+ * chronological order, so the last pushed is the most recently recorded, which
+ * is the stable, predictable choice. Returns null for an empty history.
+ */
+export function latestUndoTarget(snapshots) {
+    let best = null;
+    for (const s of snapshots) {
+        // `>=` so a later array entry with an equal timestamp supersedes an
+        // earlier one (last-pushed wins on a tie).
+        if (best === null || s.timestamp >= best.timestamp)
+            best = s;
+    }
+    return best;
+}
+/**
+ * For "/undo all": each tracked file's EARLIEST snapshot — its content before
+ * the *first* AI edit this session. Restoring all of these reverts the whole
+ * session's file changes (vs. latestUndoTarget, which is the single last step).
+ *
+ * Returns one snapshot per file path, ordered by that file's first-edit time
+ * (oldest first) so a preview reads chronologically. On a same-millisecond tie
+ * for a given file, the FIRST array entry wins (earliest recorded).
+ */
+export function earliestSnapshotsPerFile(snapshots) {
+    const earliest = new Map();
+    for (const s of snapshots) {
+        // Undone snapshots belong to a reverted turn: their content is no longer on
+        // disk and they are not the session baseline, so skip them — otherwise an
+        // undone (earlier) snapshot could win the baseline and `/undo all` would
+        // restore stale content.
+        if (s.undone)
+            continue;
+        const cur = earliest.get(s.filePath);
+        // strict `<` so the first-seen entry wins on a tie (earliest recorded).
+        if (!cur || s.timestamp < cur.timestamp)
+            earliest.set(s.filePath, s);
+    }
+    return [...earliest.values()].sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+ * For turn-level "/undo": the snapshots needed to revert just the MOST RECENT
+ * conversation turn (one user message = one turn, see SessionState.turnSeq).
+ *
+ * The latest turn = the greatest `turnSeq` present. A turn boundary is defined
+ * by turnSeq, NOT wall-clock — a clock skew must not move the boundary. Within
+ * that turn, each touched file is restored to its EARLIEST snapshot of the turn
+ * (its content before the *first* edit that turn), so re-editing a file twice
+ * in one turn still reverts to the pre-turn baseline — and edits from *earlier*
+ * turns are left intact (that's the whole point vs. earliestSnapshotsPerFile,
+ * which spans the whole session).
+ *
+ * Backward compatibility: snapshots written before this feature have no
+ * `turnSeq`. They share the `undefined` bucket. `undefined` sorts as the
+ * smallest "turn", so any real (tagged) turn supersedes the legacy bucket; a
+ * history that is ALL-legacy degrades to whole-session behaviour (each file's
+ * earliest) rather than throwing.
+ *
+ * Returns one snapshot per file, ordered by that file's first-edit time within
+ * the turn (oldest first) so a preview reads chronologically. Empty → [].
+ */
+export function latestTurnUndoTargets(snapshots) {
+    if (snapshots.length === 0)
+        return [];
+    // Find the latest turn, SKIPPING undone turns: once a turn is undone (marked,
+    // not deleted) its snapshots stay on disk for redo but must not be re-selected
+    // by undo — so the next /undo peels the prior live turn ("onion" behaviour).
+    // undefined (legacy) is treated as the smallest turn so it loses to any tagged
+    // turn; a key of `-Infinity` models that ordering.
+    const turnKey = (s) => s.turnSeq ?? -Infinity;
+    let maxTurn = -Infinity;
+    let found = false;
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        const k = turnKey(s);
+        if (k > maxTurn)
+            maxTurn = k;
+        found = true;
+    }
+    if (!found)
+        return [];
+    // Within the latest live turn, each file's earliest snapshot = its pre-turn
+    // state. Undone snapshots are skipped here too (defensive: they share neither
+    // the selected turn nor the baseline).
+    const earliest = new Map();
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        if (turnKey(s) !== maxTurn)
+            continue;
+        const cur = earliest.get(s.filePath);
+        // strict `<` so the first-seen entry wins on a same-ms tie (earliest).
+        if (!cur || s.timestamp < cur.timestamp)
+            earliest.set(s.filePath, s);
+    }
+    return [...earliest.values()].sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+ * For "/redo": the RedoRecord[] of the MOST RECENT undone turn — the turn that
+ * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
+ * undone state (i.e. nothing newer happened since the undo). Otherwise [].
+ *
+ * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
+ * exists only for a turn that was undone and not yet redone). R is redoable iff
+ * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
+ * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
+ * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
+ * is the sole evidence and is honoured as long as nothing newer superseded it.
+ *
+ * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
+ */
+export function latestRedoTargets(redoRecords, snapshots) {
+    if (redoRecords.length === 0)
+        return [];
+    let maxRedoTurn = -Infinity;
+    for (const r of redoRecords) {
+        if (r.turnSeq > maxRedoTurn)
+            maxRedoTurn = r.turnSeq;
+    }
+    // If any LIVE snapshot belongs to a strictly newer turn, the redo turn is no
+    // longer the latest undone state → not redoable.
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        const k = s.turnSeq ?? -Infinity;
+        if (k > maxRedoTurn)
+            return [];
+    }
+    return redoRecords.filter((r) => r.turnSeq === maxRedoTurn);
+}

package/dist/settings/disk-defaults.d.ts

@@ -1,5 +1,5 @@
 import type { ValidatedSettings } from "./schema.js";
-import type { EngineConfig } from "../engine/engine.js";
+import type { EngineConfig } from "../engine/types.js";
 /**
  * The subset of EngineConfig the config hot-reload ("layer 2") pushes onto an
  * already-running session's `this.config`. These are the "disk-default" fields:
@@ -32,4 +32,11 @@ export type DiskDefaultPatch = Pick<EngineConfig, "preset" | "customSystemPrompt
  * config (no divergence). It reuses `personalizationFrom` for the three
  * personalization fields rather than duplicating the mapping.
  */
-export declare function diskDefaultsFrom(settings: ValidatedSettings): DiskDefaultPatch;
+export declare function diskDefaultsFrom(settings: ValidatedSettings, 
+/**
+ * EFFECTIVE disabled plugins for the target session — the caller should
+ * pass `engine.getEffectiveDisabledLists().disabledPlugins` so the merge
+ * honors project capabilityOverrides (能力总览 project "on" overrides the
+ * global list). Omitted → falls back to the raw global list (legacy).
+ */
+effectiveDisabledPlugins?: string[]): DiskDefaultPatch;

package/dist/settings/disk-defaults.js

@@ -9,7 +9,14 @@ import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
  * config (no divergence). It reuses `personalizationFrom` for the three
  * personalization fields rather than duplicating the mapping.
  */
-export function diskDefaultsFrom(settings) {
+export function diskDefaultsFrom(settings, 
+/**
+ * EFFECTIVE disabled plugins for the target session — the caller should
+ * pass `engine.getEffectiveDisabledLists().disabledPlugins` so the merge
+ * honors project capabilityOverrides (能力总览 project "on" overrides the
+ * global list). Omitted → falls back to the raw global list (legacy).
+ */
+effectiveDisabledPlugins) {
     const agent = settings.agent ?? {};
     return {
         preset: agent.preset,
@@ -19,6 +26,8 @@ export function diskDefaultsFrom(settings) {
         // Same merge engineFactory uses: user-configured servers + enabled
         // plugins' servers. Plugin servers a disabled plugin would contribute are
         // skipped, matching new-session construction.
-        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, settings.disabledPlugins ?? []),
+        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, effectiveDisabledPlugins ??
+            settings.disabledPlugins ??
+            [], settings.mcpServerOverrides ?? {}),
     };
 }

package/dist/settings/feature-flags.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Feature Flags — a small, central on/off registry for opt-in or
+ * experimental behavior.
+ *
+ * Design goals:
+ *   - One source of truth for flag NAMES + their DEFAULT state, so a flag
+ *     can't be checked under a typo (the known set is a const).
+ *   - Settings-driven: `settings.featureFlags` is a `{ [name]: boolean }`
+ *     overlay over the defaults. Project settings override user settings the
+ *     same way every other settings field does (the SettingsManager merge),
+ *     so a flag can be flipped per-workspace.
+ *   - Forgiving read: `isFeatureEnabled` falls back to the default when a
+ *     flag is absent from settings, and ignores unknown flag names from
+ *     settings (forward-compat with older binaries).
+ *
+ * This is the knob layer only — each consumer still has to CHECK its flag.
+ * The `/features` command (CLI) reads/writes this same map.
+ */
+/** Canonical flag names. Add new flags here so checks stay typo-safe. */
+export declare const FEATURE_FLAGS: {
+    /** Web search tool availability (also gated by a configured provider). */
+    readonly web_search: {
+        readonly default: true;
+        readonly description: "Enable the WebSearch tool";
+    };
+    /** The Bash/shell tool. Off → the model cannot run shell commands. */
+    readonly shell_tool: {
+        readonly default: true;
+        readonly description: "Enable the Bash/shell tool";
+    };
+    /** Fast-output mode for supported models. */
+    readonly fast_mode: {
+        readonly default: false;
+        readonly description: "Faster streaming output on supported models";
+    };
+    /** Undo system (file-operation backups + /undo). */
+    readonly undo: {
+        readonly default: false;
+        readonly description: "Per-session file undo (/undo)";
+    };
+    /** Shell snapshot: capture full stdout/stderr of commands. */
+    readonly shell_snapshot: {
+        readonly default: false;
+        readonly description: "Capture full command stdout/stderr snapshots";
+    };
+};
+export type FeatureFlagName = keyof typeof FEATURE_FLAGS;
+/** The settings overlay shape: a partial map of known flags → boolean. */
+export type FeatureFlagOverrides = Partial<Record<FeatureFlagName, boolean>>;
+/** All known flag names, for iteration (e.g. the /features listing). */
+export declare function featureFlagNames(): FeatureFlagName[];
+/** True when `name` is a recognized flag (narrows an arbitrary string). */
+export declare function isKnownFeatureFlag(name: string): name is FeatureFlagName;
+/**
+ * Resolve a flag's effective state: the settings overlay value when present
+ * and boolean, else the flag's compiled-in default. Unknown names → false
+ * (a check for a flag that doesn't exist is never "enabled").
+ */
+export declare function isFeatureEnabled(overrides: FeatureFlagOverrides | undefined, name: FeatureFlagName): boolean;
+/**
+ * Resolve the full effective flag map (defaults merged with overrides).
+ * Used by `/features` to show the current state of every flag.
+ */
+export declare function resolveFeatureFlags(overrides: FeatureFlagOverrides | undefined): Record<FeatureFlagName, boolean>;

package/dist/settings/feature-flags.js

@@ -0,0 +1,61 @@
+/**
+ * Feature Flags — a small, central on/off registry for opt-in or
+ * experimental behavior.
+ *
+ * Design goals:
+ *   - One source of truth for flag NAMES + their DEFAULT state, so a flag
+ *     can't be checked under a typo (the known set is a const).
+ *   - Settings-driven: `settings.featureFlags` is a `{ [name]: boolean }`
+ *     overlay over the defaults. Project settings override user settings the
+ *     same way every other settings field does (the SettingsManager merge),
+ *     so a flag can be flipped per-workspace.
+ *   - Forgiving read: `isFeatureEnabled` falls back to the default when a
+ *     flag is absent from settings, and ignores unknown flag names from
+ *     settings (forward-compat with older binaries).
+ *
+ * This is the knob layer only — each consumer still has to CHECK its flag.
+ * The `/features` command (CLI) reads/writes this same map.
+ */
+/** Canonical flag names. Add new flags here so checks stay typo-safe. */
+export const FEATURE_FLAGS = {
+    /** Web search tool availability (also gated by a configured provider). */
+    web_search: { default: true, description: "Enable the WebSearch tool" },
+    /** The Bash/shell tool. Off → the model cannot run shell commands. */
+    shell_tool: { default: true, description: "Enable the Bash/shell tool" },
+    /** Fast-output mode for supported models. */
+    fast_mode: { default: false, description: "Faster streaming output on supported models" },
+    /** Undo system (file-operation backups + /undo). */
+    undo: { default: false, description: "Per-session file undo (/undo)" },
+    /** Shell snapshot: capture full stdout/stderr of commands. */
+    shell_snapshot: { default: false, description: "Capture full command stdout/stderr snapshots" },
+};
+/** All known flag names, for iteration (e.g. the /features listing). */
+export function featureFlagNames() {
+    return Object.keys(FEATURE_FLAGS);
+}
+/** True when `name` is a recognized flag (narrows an arbitrary string). */
+export function isKnownFeatureFlag(name) {
+    return Object.prototype.hasOwnProperty.call(FEATURE_FLAGS, name);
+}
+/**
+ * Resolve a flag's effective state: the settings overlay value when present
+ * and boolean, else the flag's compiled-in default. Unknown names → false
+ * (a check for a flag that doesn't exist is never "enabled").
+ */
+export function isFeatureEnabled(overrides, name) {
+    const override = overrides?.[name];
+    if (typeof override === "boolean")
+        return override;
+    return FEATURE_FLAGS[name].default;
+}
+/**
+ * Resolve the full effective flag map (defaults merged with overrides).
+ * Used by `/features` to show the current state of every flag.
+ */
+export function resolveFeatureFlags(overrides) {
+    const out = {};
+    for (const name of featureFlagNames()) {
+        out[name] = isFeatureEnabled(overrides, name);
+    }
+    return out;
+}

package/dist/settings/manager.d.ts

@@ -12,7 +12,38 @@ import { type ValidatedSettings } from "./schema.js";
  * `process.env.HOME` mutations.
  */
 export declare function userHome(): string;
+/**
+ * True if `key` (a dotted path like "permissions.rules" or just "env") targets a
+ * protected trust-root field. Matches on the FIRST segment so nested writes
+ * ("permissions.defaultMode", "env.FOO") are caught too.
+ */
+export declare function isProtectedSettingKey(key: string): boolean;
+/**
+ * The fixed cwd used for "no-repo" pure-chat conversations (a chat not bound to
+ * any code project). Same location as desktop's `resolveNoRepoCwd`
+ * (`join(homedir(), ".code-shell", "no-repo")`), but built from {@link userHome}
+ * so tests can isolate it by overriding `$HOME`. The engine compares
+ * `config.cwd === noRepoDir()` to flip skill/plugin filtering to whitelist mode.
+ */
+export declare function noRepoDir(): string;
 export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+/**
+ * Top-level settings fields that can influence code execution and are therefore
+ * stripped from an UNTRUSTED project's disk layers (project + local) before
+ * merge. A repo commits these into its `.code-shell/settings.json`, so an
+ * untrusted clone must not have them take effect:
+ *   - permissions  — `rules` can self-authorize (allow Bash …); `defaultMode`
+ *                     can set bypassPermissions.
+ *   - env          — injected into Bash child env unfiltered (BASH_ENV,
+ *                     LD_PRELOAD, PATH → arbitrary code on next command).
+ *   - localEnvironment — same, as the env floor.
+ *   - hooks        — arbitrary commands on lifecycle events.
+ *   - mcpServers   — auto-connect to attacker-controlled MCP servers.
+ * Only project-scoped layers are filtered; user/managed/flag are trusted.
+ * Mirrors Claude Code's TRUSTED_SETTING_SOURCES model (project sources excluded
+ * from dangerous env application until trust is granted).
+ */
+export declare const DANGEROUS_PROJECT_FIELDS: readonly ["permissions", "env", "localEnvironment", "hooks", "mcpServers"];
 /**
  * Which disk layers a SettingsManager is allowed to read.
  *   'full'     — managed + user (~/.code-shell) + project + local (host terminal entrypoints)
@@ -26,13 +57,49 @@ export type SettingsScope = "isolated" | "project" | "full";
 export declare class SettingsManager {
     private readonly cwd;
     private readonly scope;
+    /**
+     * Workspace trust for the project directory. When false, dangerous fields
+     * committed into the project's own `.code-shell/settings.{json,local.json}`
+     * ({@link DANGEROUS_PROJECT_FIELDS}) are stripped before merge, so a cloned
+     * malicious repo can't self-authorize permission rules, inject `env`
+     * (BASH_ENV/LD_PRELOAD/…), register hooks, or connect MCP servers. Safe
+     * fields (model choice, UI prefs, …) still merge. The user/managed/flag
+     * layers are never gated — the user put those there deliberately.
+     *
+     * Defaults to `true` so existing embedders/tests keep their behavior; the
+     * host (desktop) passes the real trust decision from its trust-store.
+     */
+    private readonly projectTrusted;
     private sources;
     private merged;
-    constructor(cwd?: string, scope?: SettingsScope);
+    constructor(cwd?: string, scope?: SettingsScope, 
+    /**
+     * Workspace trust for the project directory. When false, dangerous fields
+     * committed into the project's own `.code-shell/settings.{json,local.json}`
+     * ({@link DANGEROUS_PROJECT_FIELDS}) are stripped before merge, so a cloned
+     * malicious repo can't self-authorize permission rules, inject `env`
+     * (BASH_ENV/LD_PRELOAD/…), register hooks, or connect MCP servers. Safe
+     * fields (model choice, UI prefs, …) still merge. The user/managed/flag
+     * layers are never gated — the user put those there deliberately.
+     *
+     * Defaults to `true` so existing embedders/tests keep their behavior; the
+     * host (desktop) passes the real trust decision from its trust-store.
+     */
+    projectTrusted?: boolean);
     /**
      * Load settings from all sources.
      */
     load(flagOverrides?: Record<string, unknown>): ValidatedSettings;
+    /**
+     * Run the version-based migrations (migrate-config.ts MIGRATIONS) against a
+     * single physical settings file. Best-effort: any read/parse/write error
+     * falls through silently and the original source data is used as-is.
+     * Writes back (with a .bak, like the models[] migration above) ONLY when a
+     * step changed actual content — the configVersion stamp alone doesn't
+     * justify touching the file. On write-back the in-memory source is updated
+     * so this load() already sees the migrated shape.
+     */
+    private applyConfigMigration;
     /**
      * Get current effective settings.
      */