chainlesschain 0.162.162 → 0.162.163

package/src/lib/settings-loader.cjs

@@ -415,11 +415,53 @@ function readBooleanSetting(key, opts = {}) {
   return value;
 }
 
+/**
+ * Read a string-array setting across the layered `.claude/settings.json` files
+ * plus managed settings. Unlike {@link readBooleanSetting} (last-layer wins),
+ * arrays UNION across layers (mirroring how `env`/`sandbox` accumulate in
+ * {@link loadSettingsConfig}) — a user-scope and a project-scope layer can each
+ * contribute entries. Non-array values and non-string members are ignored.
+ * Returns a de-duplicated array, or `undefined` when no layer sets it.
+ *
+ * @param {string} key  settings key or dotted path (e.g. "instructionExcludes")
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {string} [opts.settingsFile]
+ * @param {(msg:string)=>void} [opts.onWarn]
+ * @returns {string[]|undefined}
+ */
+function readStringArraySetting(key, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const parts = String(key).split(".");
+  const collected = [];
+  let sawAny = false;
+  const absorb = (data) => {
+    let node = data;
+    for (const p of parts) {
+      node = node && typeof node === "object" ? node[p] : undefined;
+    }
+    if (Array.isArray(node)) {
+      sawAny = true;
+      for (const item of node) {
+        if (typeof item === "string" && item.trim()) collected.push(item);
+      }
+    }
+  };
+  for (const file of settingsPaths(cwd, opts.settingsFile)) {
+    absorb(readSettingsFile(file, { onWarn: opts.onWarn }));
+  }
+  const managed = loadManagedSettings(opts);
+  if (managed.settings) absorb(managed.settings);
+  if (!sawAny) return undefined;
+  return [...new Set(collected)];
+}
+
 module.exports = {
   loadSettings,
   loadSettingsConfig,
   readSettingsFile,
   readBooleanSetting,
+  readStringArraySetting,
   settingsPaths,
   managedSettingsPath,
   loadManagedSettings,

package/src/lib/side-effect-ledger-store.js

@@ -0,0 +1,88 @@
+/**
+ * Persist the side-effect ledger ([[side-effect-ledger.js]]) as a tamper-evident
+ * chained session event so a worker that crashed mid `git push` / `file-write` /
+ * `package-install` can rebuild its ledger on recovery and reconcile WITHOUT
+ * repeating a side-effect it already issued.
+ *
+ * Same shape as [[turn-binding-store.js]]: each persist writes the FULL ledger
+ * snapshot (newest wins), all I/O is delegated to the canonical session store
+ * via `_deps` so the module stays pure-testable.
+ */
+
+import {
+  appendEvent as storeAppendEvent,
+  readEvents as storeReadEvents,
+} from "../harness/jsonl-session-store.js";
+import {
+  SideEffectLedger,
+  reconcileSideEffects,
+} from "./side-effect-ledger.js";
+
+/** Event type carrying a full SideEffectLedger snapshot. */
+export const SIDE_EFFECT_LEDGER_EVENT = "side_effect_ledger";
+
+export const _deps = {
+  appendEvent: storeAppendEvent,
+  readEvents: storeReadEvents,
+};
+
+/**
+ * Append the current ledger as a chained event. Best-effort — a persistence
+ * failure must not crash the operation it is guarding.
+ *
+ * @param {string} sessionId
+ * @param {SideEffectLedger|object} ledger
+ * @returns {boolean}
+ */
+export function persistSideEffectLedger(sessionId, ledger) {
+  if (!sessionId || !ledger) return false;
+  const snapshot =
+    ledger instanceof SideEffectLedger ? ledger.toJSON() : ledger;
+  if (!snapshot || !Array.isArray(snapshot.ops)) return false;
+  try {
+    _deps.appendEvent(sessionId, SIDE_EFFECT_LEDGER_EVENT, snapshot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rebuild the ledger from the LATEST persisted snapshot, or an empty ledger when
+ * the session never persisted one (or on read error).
+ *
+ * @param {string} sessionId
+ * @param {{clock?:Function}} [opts]
+ * @returns {SideEffectLedger}
+ */
+export function loadSideEffectLedger(sessionId, opts = {}) {
+  let events = [];
+  try {
+    events = _deps.readEvents(sessionId) || [];
+  } catch {
+    return new SideEffectLedger(opts);
+  }
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i];
+    if (
+      e &&
+      e.type === SIDE_EFFECT_LEDGER_EVENT &&
+      e.data &&
+      Array.isArray(e.data.ops)
+    ) {
+      return SideEffectLedger.fromJSON(e.data, opts);
+    }
+  }
+  return new SideEffectLedger(opts);
+}
+
+/**
+ * Load + reconcile in one step: the recovery entry point. Returns the plan a
+ * restarting worker uses to decide, per op, redo / inspect / skip.
+ *
+ * @param {string} sessionId
+ * @returns {{plans:Array, redo:string[], inspect:string[], skip:string[]}}
+ */
+export function reconcileSessionSideEffects(sessionId) {
+  return reconcileSideEffects(loadSideEffectLedger(sessionId));
+}

package/src/lib/side-effect-ledger.js

@@ -0,0 +1,296 @@
+/**
+ * Side-effect ledger — crash-safe accounting of irreversible actions so a
+ * recovered worker never repeats a side-effect it already issued (P0
+ * state-machine slice: CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12
+ * §"后台 Agent 状态机" — "副作用台账（prepared→started→committed|failed|unknown）
+ * 与崩溃恢复重放").
+ *
+ * The gap's acceptance is concrete: kill the worker/supervisor mid `file-write`,
+ * `git push`, or `package-install`, and after recovery the effect must not be
+ * applied twice. The classic bug is a blind retry — the process died AFTER
+ * `git push` reached the remote but BEFORE it recorded success, so a naive
+ * "resume the turn" pushes again.
+ *
+ * The fix is a two-phase record around every side-effect:
+ *
+ *   prepare(opId)  →  start(opId)  →  commit(opId) | fail(opId) | unknown(opId)
+ *
+ * and an HONEST recovery planner. The invariant: a `started`-but-not-settled op
+ * is INDETERMINATE — we cannot know if the effect landed — so unless the op is
+ * explicitly idempotent it must be INSPECTED by a human/verifier, never blindly
+ * redone. `prepared`-but-never-`started` ops are safe to redo (no effect issued
+ * yet); `committed` ops are skipped; cleanly `failed` ops redo only when the
+ * caller vouched they roll back atomically.
+ *
+ * Everything here is PURE (no timers, no I/O): the ledger is in-memory +
+ * serializable so a caller persists it alongside the session record. I/O lives
+ * in [[side-effect-ledger-store.js]].
+ */
+
+/** Lifecycle states of one side-effecting operation. */
+export const SIDE_EFFECT_STATE = Object.freeze({
+  PREPARED: "prepared", // intent recorded; nothing issued yet
+  STARTED: "started", // effect issued; outcome not yet known
+  COMMITTED: "committed", // effect confirmed applied
+  FAILED: "failed", // effect confirmed NOT applied (clean failure)
+  UNKNOWN: "unknown", // outcome indeterminate (e.g. crash mid-flight)
+});
+
+/** Recovery actions the reconciler emits for each unsettled op. */
+export const RECOVERY_ACTION = Object.freeze({
+  SKIP: "skip", // already committed — do nothing
+  REDO: "redo", // safe to run again (no effect issued, or idempotent)
+  INSPECT: "inspect", // indeterminate — verify before any repeat
+});
+
+/**
+ * Default idempotency for well-known side-effect kinds. Only actions that are
+ * naturally safe to re-run without duplicating an external effect are `true`.
+ * `file-write` is idempotent ONLY when a pre-write checkpoint exists (the write
+ * can be re-applied from the same source over a restored tree); a raw append
+ * has no such guarantee, so the default is conservative `false`.
+ */
+const KIND_IDEMPOTENT = new Map([
+  ["git-push", false],
+  ["package-install", false],
+  ["network-mutation", false],
+  ["payment", false],
+  ["file-write", false],
+  ["file-write-checkpointed", true],
+  ["read", true],
+  ["compute", true],
+]);
+
+/** Whether a kind is idempotent by default (unknown kinds → conservative false). */
+export function kindIsIdempotent(kind) {
+  return KIND_IDEMPOTENT.get(String(kind || "")) === true;
+}
+
+function nowFrom(clock) {
+  return typeof clock === "function" ? Number(clock()) || 0 : 0;
+}
+
+/**
+ * The in-memory, serializable ledger. A caller records the two-phase lifecycle
+ * around each side-effect and, after a crash, hands the rebuilt ledger to
+ * `reconcileSideEffects` for a recovery plan.
+ *
+ * Timestamps are optional and only stamped when a `clock` is injected — keeping
+ * the ledger deterministic in tests (no `Date.now()`).
+ */
+export class SideEffectLedger {
+  constructor({ clock } = {}) {
+    this._ops = new Map();
+    this._order = [];
+    this._clock = clock || null;
+  }
+
+  _rec(opId) {
+    return this._ops.get(String(opId)) || null;
+  }
+
+  /**
+   * Record intent to perform a side-effect. Idempotent on opId (re-preparing an
+   * existing op is a no-op, so a retry loop can't reset a committed op).
+   *
+   * @param {string} opId  stable id (survives restart — e.g. `${turnId}:${seq}`)
+   * @param {{kind?:string, key?:string, idempotent?:boolean, meta?:object}} [info]
+   */
+  prepare(opId, info = {}) {
+    const id = String(opId);
+    if (this._ops.has(id)) return this;
+    const kind = info.kind == null ? null : String(info.kind);
+    this._ops.set(id, {
+      opId: id,
+      kind,
+      key: info.key == null ? null : String(info.key),
+      idempotent:
+        typeof info.idempotent === "boolean"
+          ? info.idempotent
+          : kindIsIdempotent(kind),
+      state: SIDE_EFFECT_STATE.PREPARED,
+      reason: null,
+      meta: info.meta && typeof info.meta === "object" ? { ...info.meta } : {},
+      preparedAt: nowFrom(this._clock),
+      settledAt: null,
+    });
+    this._order.push(id);
+    return this;
+  }
+
+  /** Mark the effect as ISSUED (outcome not yet known). Only from `prepared`. */
+  start(opId) {
+    return this._advance(opId, SIDE_EFFECT_STATE.STARTED, [
+      SIDE_EFFECT_STATE.PREPARED,
+    ]);
+  }
+
+  /** Confirm the effect applied. Only from `started`. */
+  commit(opId) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.COMMITTED,
+      [SIDE_EFFECT_STATE.STARTED],
+      { settle: true },
+    );
+  }
+
+  /** Confirm the effect did NOT apply (clean failure). Only from `started`. */
+  fail(opId, reason) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.FAILED,
+      [SIDE_EFFECT_STATE.STARTED],
+      { settle: true, reason },
+    );
+  }
+
+  /**
+   * Explicitly mark an op's outcome indeterminate. Accepts `prepared`/`started`
+   * (a recovery pass sweeping unsettled ops), never overrides a settled op.
+   */
+  unknown(opId, reason) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.UNKNOWN,
+      [SIDE_EFFECT_STATE.PREPARED, SIDE_EFFECT_STATE.STARTED],
+      { settle: true, reason },
+    );
+  }
+
+  _advance(opId, next, allowedFrom, { settle = false, reason } = {}) {
+    const rec = this._rec(opId);
+    if (!rec) return this;
+    if (!allowedFrom.includes(rec.state)) return this; // illegal transition → ignore
+    rec.state = next;
+    if (reason != null) rec.reason = String(reason);
+    if (settle) rec.settledAt = nowFrom(this._clock);
+    return this;
+  }
+
+  get(opId) {
+    const rec = this._rec(opId);
+    return rec ? { ...rec, meta: { ...rec.meta } } : null;
+  }
+
+  list() {
+    return this._order.map((id) => this.get(id));
+  }
+
+  /** Ops that never reached a terminal state — the recovery surface. */
+  unsettled() {
+    return this.list().filter(
+      (o) =>
+        o.state === SIDE_EFFECT_STATE.PREPARED ||
+        o.state === SIDE_EFFECT_STATE.STARTED,
+    );
+  }
+
+  toJSON() {
+    return { ops: this._order.map((id) => this.get(id)) };
+  }
+
+  static fromJSON(json, { clock } = {}) {
+    const ledger = new SideEffectLedger({ clock });
+    for (const o of json?.ops || []) {
+      if (!o || o.opId == null) continue;
+      const id = String(o.opId);
+      if (ledger._ops.has(id)) continue;
+      ledger._ops.set(id, {
+        opId: id,
+        kind: o.kind == null ? null : String(o.kind),
+        key: o.key == null ? null : String(o.key),
+        idempotent: o.idempotent === true,
+        state: Object.values(SIDE_EFFECT_STATE).includes(o.state)
+          ? o.state
+          : SIDE_EFFECT_STATE.UNKNOWN,
+        reason: o.reason == null ? null : String(o.reason),
+        meta: o.meta && typeof o.meta === "object" ? { ...o.meta } : {},
+        preparedAt: Number(o.preparedAt) || 0,
+        settledAt: o.settledAt == null ? null : Number(o.settledAt) || 0,
+      });
+      ledger._order.push(id);
+    }
+    return ledger;
+  }
+}
+
+/**
+ * Plan recovery for one op record (from SideEffectLedger.get()/list()). HONEST:
+ * an indeterminate `started` op is INSPECT unless it is explicitly idempotent.
+ *
+ * @param {object} op
+ * @returns {{opId:string, action:string, reason:string}}
+ */
+export function planOpRecovery(op) {
+  const opId = op?.opId ?? null;
+  switch (op?.state) {
+    case SIDE_EFFECT_STATE.COMMITTED:
+      return {
+        opId,
+        action: RECOVERY_ACTION.SKIP,
+        reason: "already committed",
+      };
+    case SIDE_EFFECT_STATE.PREPARED:
+      // Intent only — no external effect was issued, so a clean re-run is safe.
+      return {
+        opId,
+        action: RECOVERY_ACTION.REDO,
+        reason: "prepared but never started — no effect issued",
+      };
+    case SIDE_EFFECT_STATE.FAILED:
+      // A clean failure means the effect did not land; idempotent ops re-run.
+      return op.idempotent
+        ? {
+            opId,
+            action: RECOVERY_ACTION.REDO,
+            reason: "failed cleanly and idempotent — safe to retry",
+          }
+        : {
+            opId,
+            action: RECOVERY_ACTION.INSPECT,
+            reason: "failed — verify no partial effect before retrying",
+          };
+    case SIDE_EFFECT_STATE.STARTED:
+    case SIDE_EFFECT_STATE.UNKNOWN:
+    default:
+      // Crashed mid-flight: the effect MAY have landed. Only idempotent ops are
+      // safe to redo; everything else must be inspected, never blindly repeated.
+      return op?.idempotent
+        ? {
+            opId,
+            action: RECOVERY_ACTION.REDO,
+            reason: "indeterminate but idempotent — safe to re-run",
+          }
+        : {
+            opId,
+            action: RECOVERY_ACTION.INSPECT,
+            reason:
+              "started but not confirmed — effect may have applied; do not repeat blindly",
+          };
+  }
+}
+
+/**
+ * Build a recovery plan for every op in a (crash-rebuilt) ledger.
+ *
+ * @param {SideEffectLedger|{ops:Array}} ledger
+ * @returns {{plans:Array, redo:string[], inspect:string[], skip:string[]}}
+ */
+export function reconcileSideEffects(ledger) {
+  const ops =
+    ledger instanceof SideEffectLedger
+      ? ledger.list()
+      : Array.isArray(ledger?.ops)
+        ? ledger.ops
+        : [];
+  const plans = ops.map((o) => planOpRecovery(o));
+  const bucket = (action) =>
+    plans.filter((p) => p.action === action).map((p) => p.opId);
+  return {
+    plans,
+    redo: bucket(RECOVERY_ACTION.REDO),
+    inspect: bucket(RECOVERY_ACTION.INSPECT),
+    skip: bucket(RECOVERY_ACTION.SKIP),
+  };
+}

package/src/lib/sub-agent-context.js

@@ -45,8 +45,10 @@ export class SubAgentContext {
    * @param {number} [options.maxIterations] - Iteration limit (fallback if no budget)
    * @param {import('./iteration-budget.js').IterationBudget} [options.iterationBudget] - Shared iteration budget (takes priority over maxIterations)
    * @param {number} [options.tokenBudget] - Optional token budget
-   * @param {object} [options.db] - Database instance
+   * @param {object} [options.db] - Database instance (memory recall source)
    * @param {object} [options.permanentMemory] - Permanent memory instance
+   * @param {boolean} [options.memoryEnabled=true] - When false, the child's
+   *   context engine suppresses hierarchical-memory recall (contract memory:false)
    * @param {object} [options.llmOptions] - LLM provider/model/key options
    * @param {string} [options.cwd] - Working directory
    * @param {boolean} [options.useWorktree] - Force worktree isolation (overrides flag)
@@ -77,6 +79,14 @@ export class SubAgentContext {
     // Shared run-wide TOTAL-sub-agent counter (one object across the whole tree)
     // so this sub-agent's own spawns draw from the same breadth pool.
     this.subAgentBudget = options.subAgentBudget || null;
+    // This context's EFFECTIVE subagent contract — the ceiling handed to its OWN
+    // nested spawns (threaded into the loop options so a nested spawn_sub_agent
+    // reads it as ctx.subAgentContract).
+    this.subAgentContract = options.subAgentContract || null;
+    // Skill capability INTERSECT: null = unrestricted; a list (possibly empty)
+    // restricts run_skill/list_skills in this context's loop to those skills.
+    this.skillAllowlist =
+      options.skillAllowlist != null ? options.skillAllowlist : null;
     this.cwd = options.cwd || process.cwd();
     this.status = "active";
     this.result = null;
@@ -93,10 +103,17 @@ export class SubAgentContext {
     // Independent message history — never shared with parent
     this.messages = [];
 
-    // Independent context engine — does not inherit parent's compaction/errors
+    // Independent context engine — does not inherit parent's compaction/errors.
+    // Memory recall is gated by the subagent contract: the spawn passes a `db`
+    // and memoryEnabled:true only when the resolved contract grants memory
+    // (context:fork from a memory-bearing parent, or explicit memory:true).
+    // Default (silent-`fresh`→memory:false) → no db + memoryEnabled:false → no
+    // recall, which is today's byte-identical behavior for a plain sub-agent.
+    this._memoryEnabled = options.memoryEnabled !== false;
     this.contextEngine = new CLIContextEngineering({
       db: options.db || null,
       permanentMemory: options.permanentMemory || null,
+      memoryEnabled: this._memoryEnabled,
       scope: {
         taskId: this.id,
         role: this.role,
@@ -145,6 +162,22 @@ export class SubAgentContext {
         : {};
     this._mcpClient = options.mcpClient || null;
 
+    // Inherited settings hooks (Pre/PostToolUse) for this child loop. null =
+    // no hooks (the spawn default). The spawn path passes the parent's hooks
+    // filtered by the contract's `hooks` allow-list; forwarded into agentLoop.
+    this._settingsHooks = options.settingsHooks || null;
+
+    // permissionMode confirmer for this child loop. null = no confirmer (the
+    // spawn default → the child denies ask/sensitive-file/git gates). The spawn
+    // sets this only for the autopilot (bypassPermissions) ALLOW confirmer.
+    this._permissionConfirm = options.permissionConfirm || null;
+
+    // permissionMode ApprovalGate for this child loop. null = ungated (the spawn
+    // default). The spawn sets a dedicated confirmer-less gate (seeded with the
+    // mode's tier) for the strict/trusted tiers so run_shell/browser_act are
+    // gated headlessly (CONFIRM→no-confirmer→DENY).
+    this._approvalGate = options.approvalGate || null;
+
     // Build isolated system prompt
     const basePrompt = buildSystemPrompt(this.cwd);
     const profilePrompt = this._profile?.systemPrompt
@@ -176,9 +209,25 @@ export class SubAgentContext {
       );
     }
 
-    // If worktree isolation is enabled, wrap execution in isolated worktree
-    if (this._useWorktree && isGitRepo(this._repoDir)) {
-      return this._runInWorktree(userPrompt, loopOptions);
+    // If worktree isolation is enabled, wrap execution in isolated worktree.
+    if (this._useWorktree) {
+      if (isGitRepo(this._repoDir)) {
+        return this._runInWorktree(userPrompt, loopOptions);
+      }
+      // FAIL CLOSED: isolation was explicitly requested but this is not a git
+      // repo. Never silently fall back to the parent checkout — refuse.
+      this.status = "failed";
+      this.completedAt = new Date().toISOString();
+      this.result = {
+        summary:
+          "Worktree isolation was requested but the working directory is not a git repository — refusing to run in the parent checkout.",
+        artifacts: [],
+        tokenCount: this._tokenCount,
+        toolsUsed: [...new Set(this._toolsUsed)],
+        iterationCount: this._iterationCount,
+        isolationError: true,
+      };
+      return this.result;
     }
 
     return this._runCore(userPrompt, loopOptions);
@@ -270,6 +319,10 @@ export class SubAgentContext {
       // Shared total-sub-agent counter so a nested spawn_sub_agent draws from
       // (and is bounded by) the run's single breadth pool.
       subAgentBudget: this.subAgentBudget,
+      // This context's effective contract = the ceiling for its nested spawns.
+      subAgentContract: this.subAgentContract,
+      // Skill allow-list restricting run_skill/list_skills in this loop.
+      skillAllowlist: this.skillAllowlist,
       ...loopOptions,
     };
     if (this.iterationBudget) {
@@ -298,6 +351,22 @@ export class SubAgentContext {
     if (this._mcpClient) {
       options.mcpClient = this._mcpClient;
     }
+    // Inherited Pre/PostToolUse hooks (spawn passes the parent's, filtered by
+    // the contract's `hooks` allow-list). Only set when non-null so a plain
+    // sub-agent keeps its no-hooks default.
+    if (this._settingsHooks) {
+      options.settingsHooks = this._settingsHooks;
+    }
+    // permissionMode confirmer (spawn sets it only for bypassPermissions). Only
+    // forward when present so a plain sub-agent keeps its implicit-deny default.
+    if (this._permissionConfirm) {
+      options.permissionConfirm = this._permissionConfirm;
+    }
+    // permissionMode ApprovalGate (spawn sets it for strict/trusted tiers). Only
+    // forward when present so a plain sub-agent stays ungated (byte-identical).
+    if (this._approvalGate) {
+      options.approvalGate = this._approvalGate;
+    }
 
     try {
       // Use a separate messages array for the agent loop

package/src/lib/subagent-inheritance.js

@@ -0,0 +1,112 @@
+/**
+ * Subagent capability INHERITANCE + INTERSECT (P1 §"补齐 Subagent 契约").
+ *
+ * A spawned sub-agent inherits the parent loop's MCP tools and Pre/PostToolUse
+ * hooks ONLY through these filters, keyed off the resolved contract's
+ * `mcpServers` / `hooks` allow-lists. The tri-state matches
+ * `resolveSubagentContract` (see subagent-contract.js):
+ *
+ *   allow === null   → inherit ALL (context:fork with an unrestricted parent)
+ *   allow === []     → inherit NONE (the silent-`fresh` default = today's
+ *                      behavior: a spawned child gets no MCP tools / no hooks)
+ *   allow === [...]  → inherit only the named servers / hook matchers
+ *
+ * Because the default is `[]` = none, wiring these is byte-identical for a
+ * plain sub-agent and only grants capabilities when the contract explicitly
+ * opts in (fork context or an explicit list). Pure — no I/O.
+ *
+ * @module subagent-inheritance
+ */
+
+/** Extract the server segment from an `mcp__<server>__<tool>` wire name. */
+export function mcpServerOf(name) {
+  const s = String(name || "");
+  if (!s.startsWith("mcp__")) return null;
+  const rest = s.slice(5);
+  const idx = rest.indexOf("__");
+  return idx === -1 ? rest || null : rest.slice(0, idx) || null;
+}
+
+/**
+ * Filter the parent's MCP plumbing to the servers the child may use.
+ *
+ * @param {object} parent  { extraToolDefinitions[], externalToolDescriptors{},
+ *                            externalToolExecutors{}, mcpClient }
+ * @param {string[]|null} allow  null=all, []=none, list=subset of server names
+ * @returns {object|null}  filtered plumbing, or null when nothing is inherited
+ */
+export function filterInheritedMcp(parent, allow) {
+  if (Array.isArray(allow) && allow.length === 0) return null; // none
+  const allowSet = Array.isArray(allow) ? new Set(allow) : null; // null = all
+  const serverAllowed = (server) =>
+    !allowSet || (server != null && allowSet.has(server));
+
+  const defs = Array.isArray(parent?.extraToolDefinitions)
+    ? parent.extraToolDefinitions
+    : [];
+  const descs =
+    parent?.externalToolDescriptors &&
+    typeof parent.externalToolDescriptors === "object"
+      ? parent.externalToolDescriptors
+      : {};
+  const execs =
+    parent?.externalToolExecutors &&
+    typeof parent.externalToolExecutors === "object"
+      ? parent.externalToolExecutors
+      : {};
+
+  const outDefs = defs.filter((d) => {
+    const name = d?.function?.name;
+    return name && serverAllowed(mcpServerOf(name));
+  });
+  const outDescs = {};
+  for (const [name, desc] of Object.entries(descs)) {
+    const server = desc?.serverName || mcpServerOf(name);
+    if (serverAllowed(server)) outDescs[name] = desc;
+  }
+  const outExecs = {};
+  for (const [name, exec] of Object.entries(execs)) {
+    const server = exec?.serverName || mcpServerOf(name);
+    if (serverAllowed(server)) outExecs[name] = exec;
+  }
+
+  if (
+    outDefs.length === 0 &&
+    Object.keys(outDescs).length === 0 &&
+    Object.keys(outExecs).length === 0
+  ) {
+    return null; // nothing survived the filter — inherit no MCP
+  }
+  return {
+    extraToolDefinitions: outDefs,
+    externalToolDescriptors: outDescs,
+    externalToolExecutors: outExecs,
+    mcpClient: parent?.mcpClient || null,
+  };
+}
+
+/**
+ * Filter the parent's settings hooks to the matchers the child may fire. Hooks
+ * have no name; a group's `matcher` (normalized: null/""→"*") is its identity.
+ *
+ * @param {object|null} settingsHooks  { [event]: [{matcher, hooks:[...]}] }
+ * @param {string[]|null} allow  null=all, []=none, list=subset of matchers
+ * @returns {object|null}  filtered hooks, or null when nothing is inherited
+ */
+export function filterInheritedHooks(settingsHooks, allow) {
+  if (Array.isArray(allow) && allow.length === 0) return null; // none
+  if (!settingsHooks || typeof settingsHooks !== "object") return null;
+  if (!Array.isArray(allow)) return settingsHooks; // null = inherit all as-is
+
+  const allowSet = new Set(allow);
+  const matcherKey = (g) =>
+    g?.matcher == null || g.matcher === "" ? "*" : String(g.matcher);
+
+  const out = {};
+  for (const [event, groups] of Object.entries(settingsHooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups.filter((g) => allowSet.has(matcherKey(g)));
+    if (kept.length > 0) out[event] = kept;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}