chainlesschain 0.162.161 → 0.162.163

package/src/lib/agent-schedule-store.js

@@ -23,9 +23,147 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { randomUUID } from "crypto";
+import { isEntryExpired, effectiveFireAt } from "./schedule-planner.js";
+import { SUBAGENT_PERMISSION_MODES } from "./subagent-contract.js";
+import { parseGoalCondition } from "./goal-condition-engine.js";
 
 export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
 
+/** A valid absolute-epoch-ms expiry, or null (never expires). */
+function normalizeExpiresAt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * A non-negative integer jitter window (ms), or 0. Stored PER entry so each
+ * task carries its own deterministic spread — the schedule-planner applies a
+ * stable per-id offset within `[0, jitterMs)` so tasks sharing a cron minute
+ * fan out instead of firing as a thundering herd. 0 (the default) = no jitter.
+ */
+function normalizeJitterMs(v) {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * A per-task execution policy for wakeup/cron entries — how the spawned
+ * `cc agent` run should behave when this entry fires. Each field maps to a real
+ * `cc agent` flag consumed by `cc agenda run`, so a scheduled task can carry its
+ * OWN permission mode, worktree isolation and turn budget instead of inheriting
+ * whatever ambient environment `cc agenda run` happens to run in (the gap's
+ * "每个定时任务独立预算·权限模式·Worktree"). Returns `null` when nothing is set —
+ * the entry then omits `runPolicy` entirely and is byte-identical to before,
+ * so the default (unpolicied) task keeps spawning a plain `cc agent -p`.
+ *
+ *   - permissionMode  → `--permission-mode <mode>` (validated against the single
+ *                        source SUBAGENT_PERMISSION_MODES; invalid → dropped)
+ *   - worktree        → `--worktree` (run the task in a fresh git worktree)
+ *   - maxTurns        → `--max-turns <n>` (cap the agent loop — a real budget)
+ *   - goalCondition   → `--goal-condition <spec>` (re-drive the run to a
+ *                        completion condition; validated via parseGoalCondition,
+ *                        invalid spec → the whole goal set is dropped) with its
+ *                        own token/cost/time/outer-turn budget:
+ *       goalMaxTokens  → `--goal-max-tokens <n>`
+ *       goalMaxCost    → `--goal-max-cost <usd>`
+ *       goalMaxTime    → `--goal-max-time <ms>`
+ *       maxOuterTurns  → `--max-outer-turns <n>`
+ *     (the goal budgets are meaningless without a valid condition, so they are
+ *     only kept when the condition parses.)
+ *
+ * Monitors run a shell command / watch a file rather than spawning an agent, so
+ * a run policy does not apply to them.
+ */
+export function normalizeRunPolicy({
+  permissionMode = null,
+  worktree = false,
+  maxTurns = null,
+  goalCondition = null,
+  goalMaxTokens = null,
+  goalMaxCost = null,
+  goalMaxTime = null,
+  maxOuterTurns = null,
+} = {}) {
+  const policy = {};
+  if (
+    typeof permissionMode === "string" &&
+    SUBAGENT_PERMISSION_MODES.includes(permissionMode)
+  ) {
+    policy.permissionMode = permissionMode;
+  }
+  if (worktree === true) policy.worktree = true;
+  const turns = Math.floor(Number(maxTurns));
+  if (Number.isFinite(turns) && turns > 0) policy.maxTurns = turns;
+
+  // goal-condition + its budgets: run to a completion condition with a per-task
+  // token/cost/time/outer-turn budget. Validate the spec up front so a doomed
+  // condition never gets scheduled; an invalid spec drops the whole goal set.
+  if (typeof goalCondition === "string" && goalCondition.trim()) {
+    let validSpec = false;
+    try {
+      parseGoalCondition(goalCondition);
+      validSpec = true;
+    } catch {
+      // invalid spec → drop goalCondition and its budgets entirely
+    }
+    if (validSpec) {
+      policy.goalCondition = goalCondition.trim();
+      const gTokens = Math.floor(Number(goalMaxTokens));
+      if (Number.isFinite(gTokens) && gTokens > 0)
+        policy.goalMaxTokens = gTokens;
+      const gCost = Number(goalMaxCost);
+      if (Number.isFinite(gCost) && gCost > 0) policy.goalMaxCost = gCost;
+      const gTime = Math.floor(Number(goalMaxTime));
+      if (Number.isFinite(gTime) && gTime > 0) policy.goalMaxTime = gTime;
+      const outer = Math.floor(Number(maxOuterTurns));
+      if (Number.isFinite(outer) && outer > 0) policy.maxOuterTurns = outer;
+    }
+  }
+  return Object.keys(policy).length > 0 ? policy : null;
+}
+
+/**
+ * Resolve an entry's expiry: an explicit absolute `expiresAt` (epoch-ms) wins;
+ * otherwise a positive relative `expiresInMs` is anchored to the store's own
+ * `now` (symmetric with `delayMs` on a wakeup, and deterministic under an
+ * injected clock). No expiry → null.
+ */
+function resolveExpiresAt(expiresAt, expiresInMs, now) {
+  if (expiresAt != null) return normalizeExpiresAt(expiresAt);
+  const rel = Math.floor(Number(expiresInMs));
+  if (Number.isFinite(rel) && rel > 0) return normalizeExpiresAt(now + rel);
+  return null;
+}
+
+/** Is an entry currently in a schedulable (non-terminal) state? */
+function isSchedulableStatus(entry) {
+  return entry.kind === "wakeup"
+    ? entry.status === "pending"
+    : entry.status === "active";
+}
+
+/** Statuses an entry can never leave — safe to prune. */
+export const TERMINAL_STATUSES = Object.freeze([
+  "fired",
+  "matched",
+  "exhausted",
+  "expired",
+]);
+const TERMINAL_SET = new Set(TERMINAL_STATUSES);
+
+/** Best available "this entry reached a terminal state at" timestamp. */
+function terminalAt(entry) {
+  return (
+    entry.firedAt ??
+    entry.matchedAt ??
+    entry.expiredAt ??
+    entry.lastRunAt ??
+    entry.lastCheckAt ??
+    entry.createdAt ??
+    0
+  );
+}
+
 export function agentScheduleDir(homedir = os.homedir()) {
   return path.join(homedir, ".chainlesschain", "agent-schedule");
 }
@@ -154,11 +292,23 @@ export class AgentScheduleStore {
 
   // ── create ──────────────────────────────────────────────────────────────
 
-  scheduleWakeup({ prompt, delayMs = 0, dueAt = null, label = null } = {}) {
+  scheduleWakeup(options = {}) {
+    const {
+      prompt,
+      delayMs = 0,
+      dueAt = null,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("wakeup requires a prompt");
     }
     const now = this._now();
+    // The full options object is passed to normalizeRunPolicy, which reads only
+    // the policy fields it knows — new policy knobs need no signature change here.
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "wakeup",
@@ -166,6 +316,9 @@ export class AgentScheduleStore {
       label: label || null,
       dueAt:
         dueAt != null ? Number(dueAt) : now + Math.max(0, Number(delayMs) || 0),
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       status: "pending",
     };
@@ -175,7 +328,15 @@ export class AgentScheduleStore {
     return entry;
   }
 
-  createCron({ prompt, cron, label = null } = {}) {
+  createCron(options = {}) {
+    const {
+      prompt,
+      cron,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("cron requires a prompt");
     }
@@ -184,6 +345,8 @@ export class AgentScheduleStore {
     if (nextAt == null) {
       throw new Error(`cron "${cron}" has no upcoming match`);
     }
+    // Full options → normalizeRunPolicy (reads only known policy fields).
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "cron",
@@ -191,6 +354,9 @@ export class AgentScheduleStore {
       cron,
       label: label || null,
       nextAt,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       lastRunAt: null,
       runs: 0,
@@ -204,14 +370,56 @@ export class AgentScheduleStore {
 
   createMonitor({
     command,
+    watchFile = null,
+    watchUrl = null,
+    watchChange = false,
     intervalMs,
     stopWhen = null,
     notify = null,
     maxChecks = null,
     label = null,
+    expiresAt = null,
+    expiresInMs = null,
+    jitterMs = 0,
   } = {}) {
-    if (!command || typeof command !== "string") {
-      throw new Error("monitor requires a command");
+    // A monitor watches exactly one source:
+    //   - a shell `command`  → match its stdout/stderr
+    //   - a `watchFile`      → match its content, or fire when the file appears
+    //   - a `watchUrl`       → GET it and match the response body, or fire on 2xx
+    const hasCommand = typeof command === "string" && command.length > 0;
+    const hasFile = typeof watchFile === "string" && watchFile.length > 0;
+    const hasUrl = typeof watchUrl === "string" && watchUrl.length > 0;
+    const sourceCount = Number(hasCommand) + Number(hasFile) + Number(hasUrl);
+    if (sourceCount !== 1) {
+      throw new Error(
+        "monitor requires exactly one of `command`, `watchFile`, or `watchUrl`",
+      );
+    }
+    if (hasUrl) {
+      // Only http(s) endpoints — reject file:// and other schemes up-front so a
+      // bad URL errors at creation, not silently at the first poll.
+      let parsed;
+      try {
+        parsed = new URL(watchUrl);
+      } catch {
+        throw new Error(`monitor watchUrl is not a valid URL: ${watchUrl}`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(
+          `monitor watchUrl must be http(s), got: ${parsed.protocol}`,
+        );
+      }
+    }
+    if (watchChange) {
+      // `watchChange` is a file-only mode — fire when the file's mtime advances.
+      // It carries its own signal, so it cannot be combined with a stopWhen
+      // content pattern (that would be an ambiguous double condition).
+      if (!hasFile) {
+        throw new Error("monitor watchChange requires a watchFile");
+      }
+      if (stopWhen != null) {
+        throw new Error("monitor watchChange cannot be combined with stopWhen");
+      }
     }
     const interval = Math.max(1000, Number(intervalMs) || 60000);
     if (stopWhen != null) {
@@ -221,16 +429,24 @@ export class AgentScheduleStore {
       new RegExp(stopWhen);
     }
     const now = this._now();
+    const source = hasFile ? "file" : hasUrl ? "http" : "command";
     const entry = {
       id: randomUUID(),
       kind: "monitor",
-      command,
+      source,
+      command: hasCommand ? command : null,
+      watchFile: hasFile ? watchFile : null,
+      watchUrl: hasUrl ? watchUrl : null,
+      watchChange: hasFile ? Boolean(watchChange) : false,
+      lastMtimeMs: null,
       intervalMs: interval,
       stopWhen: stopWhen || null,
       notify: notify || null,
       maxChecks: maxChecks != null ? Number(maxChecks) : null,
       label: label || null,
       nextAt: now + interval,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
       createdAt: now,
       checks: 0,
       status: "active",
@@ -254,13 +470,45 @@ export class AgentScheduleStore {
   due(kind = null, atMs = null) {
     const now = atMs != null ? atMs : this._now();
     return this.list(kind).filter((entry) => {
-      if (entry.kind === "wakeup") {
-        return entry.status === "pending" && entry.dueAt <= now;
-      }
-      return entry.status === "active" && entry.nextAt <= now;
+      // An entry past its expiry never fires — even if it is not yet retired
+      // (defense-in-depth: retireExpired need not have run first).
+      if (isEntryExpired(entry, now)) return false;
+      if (!isSchedulableStatus(entry)) return false;
+      // The effective fire time applies the entry's OWN deterministic jitter
+      // (`entry.jitterMs`, default 0 → base fire time, byte-identical to the
+      // prior `dueAt`/`nextAt` comparison). A jittered entry fires slightly
+      // later, spreading tasks that share a cron minute.
+      const fireAt = effectiveFireAt(entry);
+      return fireAt != null && fireAt <= now;
     });
   }
 
+  /**
+   * Retire every schedulable entry whose `expiresAt` has passed (status →
+   * "expired", stamping `expiredAt`), across all kinds, so it never fires again.
+   * A daemon / `cc agenda run` calls this before firing due entries — mirroring
+   * the schedule-planner's "retire expired BEFORE due" semantics. Returns the
+   * list of retired entries.
+   */
+  retireExpired(atMs = null) {
+    const now = atMs != null ? atMs : this._now();
+    const retired = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      let changed = false;
+      for (const entry of entries) {
+        if (isSchedulableStatus(entry) && isEntryExpired(entry, now)) {
+          entry.status = "expired";
+          entry.expiredAt = now;
+          retired.push(entry);
+          changed = true;
+        }
+      }
+      if (changed) this._writeAll(kind, entries);
+    }
+    return retired;
+  }
+
   cancel(id) {
     for (const kind of SCHEDULE_KINDS) {
       const entries = this._readAll(kind);
@@ -274,6 +522,28 @@ export class AgentScheduleStore {
     return null;
   }
 
+  /**
+   * Remove terminal entries (fired / matched / exhausted / expired) whose
+   * terminal timestamp is at or before `before` (default: all terminal
+   * entries), across all kinds. Keeps the append-only JSONL store from growing
+   * without bound once entries finish. Returns the removed entries; only a kind
+   * that actually changed is rewritten.
+   */
+  pruneTerminal({ before = Infinity } = {}) {
+    const removed = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      const keep = entries.filter((entry) => {
+        const prunable =
+          TERMINAL_SET.has(entry.status) && terminalAt(entry) <= before;
+        if (prunable) removed.push(entry);
+        return !prunable;
+      });
+      if (keep.length !== entries.length) this._writeAll(kind, keep);
+    }
+    return removed;
+  }
+
   // ── lifecycle mutations (used by `cc agenda run`) ──────────────────────────
 
   /** Mark a one-shot wakeup fired (keeps history; due() skips it). */
@@ -303,11 +573,20 @@ export class AgentScheduleStore {
    * Record a monitor check. `matched` ends the monitor (done); otherwise it is
    * re-armed for the next interval, or exhausted once maxChecks is hit.
    */
-  recordMonitorCheck(id, { matched = false, atMs = null } = {}) {
+  recordMonitorCheck(
+    id,
+    { matched = false, atMs = null, mtimeMs = null } = {},
+  ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
       entry.checks = (entry.checks || 0) + 1;
       entry.lastCheckAt = now;
+      // Record the mtime baseline the first time we see the file (for a
+      // watchChange monitor); leave it fixed thereafter so "changed" always
+      // means "changed since we started watching".
+      if (mtimeMs != null && entry.lastMtimeMs == null) {
+        entry.lastMtimeMs = mtimeMs;
+      }
       if (matched) {
         entry.status = "matched";
         entry.matchedAt = now;

package/src/lib/agents.js

@@ -15,6 +15,21 @@
  *   model            model override for runs of this agent
  *   maxTurns         per-run iteration cap for this agent (positive integer)
  *   isolation        "worktree" → run in a fresh git worktree (gap 2026-07-11)
+ *   permission-mode  child permission mode (tighten-only vs parent)
+ *   skills           capability allow-list — skills the child may use
+ *   mcp-servers      capability allow-list — MCP servers the child may use
+ *   hooks            capability allow-list — hooks the child may run
+ *   memory           whether the child may read permanent memory
+ *   effort           reasoning effort (low|medium|high|xhigh)
+ *   background       run detached
+ *   context          "fresh" (default, isolated) | "fork" (inherit parent)
+ *   max-depth/max-children  ceilings this agent imposes on its own descendants
+ *   budget           { tokens, cost, time } caps
+ *
+ * The extended P1 contract (permission/skills/mcp/hooks/memory/effort/
+ * background/context/depth/children/budget) is normalized into a `contract`
+ * field via subagent-contract.js; the top-level tools/maxTurns/isolation are
+ * kept as-is for the existing spawn path.
  *
  * Project scope shadows personal on a name clash. Discovery + parse are pure
  * (inject fs/path/home) so the whole thing is unit-testable.
@@ -26,6 +41,7 @@ import { homedir } from "node:os";
 import yaml from "js-yaml";
 import { projectRootBase } from "./project-root.cjs";
 import { discoverPluginAgentLayers } from "./plugin-runtime/agents.js";
+import { normalizeSubagentContract } from "./subagent-contract.js";
 
 const _deps = { fs: fsDefault, path: pathDefault };
 
@@ -147,6 +163,9 @@ export function parseAgentFile(file, scope, opts = {}) {
     maxTurns:
       Number.isFinite(maxTurns) && maxTurns > 0 ? Math.floor(maxTurns) : null,
     isolation: data.isolation === "worktree" ? "worktree" : null,
+    // Extended P1 subagent contract (permission/skills/mcp/hooks/memory/effort/
+    // background/context/depth/children/budget), normalized + validated.
+    contract: normalizeSubagentContract(data),
     systemPrompt: body || "",
   };
 }

package/src/lib/background-agent-supervisor.js

@@ -15,6 +15,7 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getHomeDir } from "./paths.js";
+import { deriveSessionState } from "./session-lifecycle.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
@@ -347,6 +348,26 @@ export function normalizeBackgroundAgentTitle(title) {
   return value.slice(0, 160);
 }
 
+/**
+ * The canonical unified lifecycle state (session-lifecycle.js) for a session —
+ * folds the supervisor `status` + worker `phase` + `pendingApprovals` into one
+ * of the 10 canonical states so every consumer (dashboard, `cc daemon list
+ * --json`, an IDE bridge) reasons about a single vocabulary. Pure; call it at a
+ * DISPLAY boundary only. It is deliberately NOT baked into
+ * effectiveBackgroundAgentState because that function's output is spread back
+ * into writeBackgroundAgentState by the rename/pin/stop read-modify-write
+ * paths — a derived field there would leak into the on-disk schema.
+ */
+export function sessionLifecycleState(state) {
+  return deriveSessionState(state);
+}
+
+/** A display copy of `state` with the derived `lifecycleState` attached. */
+function withLifecycleState(state) {
+  if (!state) return state;
+  return { ...state, lifecycleState: deriveSessionState(state) };
+}
+
 export function effectiveBackgroundAgentState(state, options = {}) {
   if (!state) return null;
   if (state.status !== "running") return state;
@@ -403,13 +424,19 @@ export function effectiveBackgroundAgentState(state, options = {}) {
 }
 
 export function listBackgroundAgents(options = {}) {
-  return readdirSync(backgroundAgentsDir())
-    .filter((name) => name.endsWith(".json") && !name.includes(".job."))
-    .map((name) => readBackgroundAgentState(name.slice(0, -5)))
-    .filter(Boolean)
-    .map((state) => effectiveBackgroundAgentState(state, options))
-    .filter((state) => options.all || state.status === "running")
-    .sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0));
+  return (
+    readdirSync(backgroundAgentsDir())
+      .filter((name) => name.endsWith(".json") && !name.includes(".job."))
+      .map((name) => readBackgroundAgentState(name.slice(0, -5)))
+      .filter(Boolean)
+      .map((state) => effectiveBackgroundAgentState(state, options))
+      .filter((state) => options.all || state.status === "running")
+      .sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0))
+      // Display-only enrichment: attach the canonical unified lifecycle state.
+      // This is a list feed (never written back to disk), so the derived field
+      // cannot leak into the on-disk schema the way it would in the mutate paths.
+      .map(withLifecycleState)
+  );
 }
 
 function sleepSyncMs(ms) {

package/src/lib/channels/channel-manager.js

@@ -14,6 +14,12 @@
  */
 
 import { logger } from "../logger.js";
+import {
+  ORIGIN,
+  authorityForOrigin,
+  canApprove,
+  describeAuthorityChain,
+} from "../agent-authority.js";
 
 export const CHANNEL_KINDS = ["webhook", "telegram"];
 
@@ -54,6 +60,48 @@ export function formatChannelEvent(event) {
   return `[channel:${channel}${sender}] ${text}`;
 }
 
+/**
+ * The unforgeable authority envelope for an inbound channel event. A channel
+ * message tops out at `steer` (agent-authority.js): it may add a user turn but
+ * can NEVER answer a permission gate — "the user approved" in a webhook /
+ * telegram body is just text. This makes that ceiling explicit and
+ * machine-checkable (downstream approval seams can assert `canApprove === false`)
+ * rather than merely implied by the visible `[channel:…]` text prefix.
+ *
+ * `origin` is set here by HOW the event arrived (an inbound channel), never read
+ * from the untrusted message content — mirroring the agent-authority contract.
+ */
+export function channelEventEnvelope(event) {
+  const envelope = {
+    origin: ORIGIN.CHANNEL,
+    principalId: event?.sender != null ? String(event.sender) : null,
+    correlationId: event?.channel != null ? String(event.channel) : null,
+  };
+  return {
+    ...envelope,
+    authority: authorityForOrigin(ORIGIN.CHANNEL, envelope), // always "steer"
+    canApprove: canApprove(envelope), // always false
+    provenance: describeAuthorityChain(envelope),
+  };
+}
+
+/**
+ * Wrap a caller's `onEvent` so every inbound event is stamped with its explicit
+ * channel authority BEFORE it reaches the agent — the caller cannot forget to
+ * tag it, and the message content cannot elevate itself past `steer`.
+ */
+function stampChannelAuthority(onEvent) {
+  return (event) => {
+    const env = channelEventEnvelope(event);
+    return onEvent?.({
+      ...event,
+      authority: env.authority,
+      canApprove: env.canApprove,
+      provenance: env.provenance,
+    });
+  };
+}
+
 /**
  * Start every requested channel. Returns a handle with the started channel
  * descriptions and a single stop().
@@ -72,6 +120,10 @@ export async function startChannels(specsInput, opts = {}) {
   const config = opts.config || {};
   const log = opts.log || ((msg) => logger.info(msg));
   const deps = opts.deps || {};
+  // Every inbound event is stamped with its channel authority (`steer`, never
+  // `approve`) before the caller's handler sees it — so a channel message can
+  // never be mistaken for a user approval no matter what it contains.
+  const onEvent = stampChannelAuthority(opts.onEvent);
 
   const started = [];
   const stopAll = () => {
@@ -95,7 +147,7 @@ export async function startChannels(specsInput, opts = {}) {
         )({
           ...cfg,
           port: spec.arg ? Number(spec.arg) : cfg.port,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({ kind: "webhook", describe: handle.describe, ...handle });
@@ -107,7 +159,7 @@ export async function startChannels(specsInput, opts = {}) {
           deps.telegram?.startTelegramChannel || startTelegramChannel
         )({
           ...cfg,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({

package/src/lib/cli-context-engineering.js

@@ -46,11 +46,17 @@ export class CLIContextEngineering {
    * @param {string} [options.scope.taskId] - Task/sub-agent ID
    * @param {string} [options.scope.role] - Sub-agent role
    * @param {string} [options.scope.parentObjective] - Parent task objective
+   * @param {boolean} [options.memoryEnabled=true] - When false, hierarchical
+   *   memory recall is suppressed even if a `db` is present. The subagent
+   *   contract's `memory` boolean drives this for spawned children so a child
+   *   denied memory physically cannot recall it (defense-in-depth beyond the
+   *   spawn simply withholding the db).
    */
-  constructor({ db, permanentMemory, scope } = {}) {
+  constructor({ db, permanentMemory, scope, memoryEnabled = true } = {}) {
     this.db = db || null;
     this.permanentMemory = permanentMemory || null;
     this.scope = scope || null;
+    this.memoryEnabled = memoryEnabled !== false;
     this.errorHistory = [];
     this.taskContext = null;
     this._bm25 = null;
@@ -121,7 +127,8 @@ export class CLIContextEngineering {
     }
 
     // 3. Memory injection (scoped: higher threshold, namespace-aware)
-    if (this.db && userQuery) {
+    // Suppressed when memoryEnabled is false (subagent contract memory:false).
+    if (this.memoryEnabled && this.db && userQuery) {
       try {
         const memoryQuery = this.scope
           ? `[${this.scope.role}] ${userQuery}`