chainlesschain 0.162.166 → 0.162.167

package/src/lib/settings-hook-events.cjs

@@ -178,6 +178,159 @@ function runSessionStartHooks(settingsHooks, { source, cwd, sessionId } = {}) {
   return { additionalContext: aggregateContext(outcome.results) };
 }
 
+/**
+ * CwdChanged settings hooks (observe + context injection). Fired when the
+ * working directory changes mid-session (`/cd`) — a distinct lifecycle event
+ * (Claude-Code-parity extension) automation can react to (re-audit trust of the
+ * new dir, reload a per-dir tool config, …). Observe-only: a cwd change never
+ * gates flow, so any `block` decision is ignored and only emitted context is
+ * returned. No-op (byte-unchanged) without a registered CwdChanged hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runCwdChangedHooks(
+  settingsHooks,
+  { oldCwd, newCwd, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "CwdChanged", newCwd || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "CwdChanged",
+    {
+      hook_event_name: "CwdChanged",
+      old_cwd: oldCwd || null,
+      cwd: newCwd || cwd || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: newCwd || cwd,
+    event: "CwdChanged",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * WorktreeCreate settings hooks (observe + context injection). Fired right after
+ * `cc agent --worktree` carves a fresh isolated git worktree — a hook can react
+ * (register the worktree with an external tracker, seed per-branch tooling,
+ * warm a build cache). The matcher target is the branch name, so a regex matcher
+ * can scope to a branch pattern. Observe-only: worktree setup already succeeded,
+ * so a `block` decision is ignored and only emitted context is returned. No-op
+ * (byte-unchanged) without a registered WorktreeCreate hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runWorktreeCreateHooks(
+  settingsHooks,
+  { worktreePath, branch, baseSha, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "WorktreeCreate", branch || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "WorktreeCreate",
+    {
+      hook_event_name: "WorktreeCreate",
+      worktree_path: worktreePath || null,
+      branch: branch || null,
+      base_sha: baseSha || null,
+      cwd: cwd || worktreePath || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: cwd || worktreePath,
+    event: "WorktreeCreate",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * WorktreeRemove settings hooks (observe + context injection). Fired when a
+ * `cc agent --worktree` session finishes and its worktree is torn down (or when
+ * a `keep` decision leaves it in place — `removed` distinguishes the two) — a
+ * hook can react (unregister the worktree, prune a per-branch cache, notify CI).
+ * Matcher target is the branch name. Observe-only: teardown already happened, so
+ * a `block` decision is ignored and only emitted context is returned. No-op
+ * (byte-unchanged) without a registered WorktreeRemove hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runWorktreeRemoveHooks(
+  settingsHooks,
+  { worktreePath, branch, removed, reason, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "WorktreeRemove", branch || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "WorktreeRemove",
+    {
+      hook_event_name: "WorktreeRemove",
+      worktree_path: worktreePath || null,
+      branch: branch || null,
+      removed: removed === true,
+      reason: reason || null,
+      cwd: cwd || worktreePath || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: cwd || worktreePath,
+    event: "WorktreeRemove",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * InstructionsLoaded settings hooks (observe + context injection). Fired once at
+ * session start after the project-instruction block (cc.md / CLAUDE.md / AGENTS.md
+ * hierarchy + `.claude/rules/*`) is composed into the system prompt — a hook can
+ * react to WHICH instruction files are authoritative this session (audit them,
+ * warn on an unexpected local override, load a companion tool config). The
+ * caller passes the EXACT loaded set; this producer trims each entry to
+ * `{path, scope, truncated}` (never the file CONTENT — a hook that wants content
+ * reads the path). Observe-only: instructions are already loaded, so a `block`
+ * decision is ignored and only emitted context is returned. No-op (byte-unchanged)
+ * without a registered InstructionsLoaded hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runInstructionsLoadedHooks(
+  settingsHooks,
+  { files, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "InstructionsLoaded", "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const list = Array.isArray(files) ? files : [];
+  const payload = withDeliveryId(
+    "InstructionsLoaded",
+    {
+      hook_event_name: "InstructionsLoaded",
+      files: list.map((f) => ({
+        path: f?.path || null,
+        scope: f?.scope || null,
+        truncated: f?.truncated === true,
+      })),
+      count: list.length,
+      cwd: cwd || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd,
+    event: "InstructionsLoaded",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
 /**
  * Generic observe-only fire (SessionEnd / Stop / PreCompact). Returns the raw
  * runHooks outcome so callers can read a block reason; never gates flow here.
@@ -206,6 +359,10 @@ function runObserveHooks(
 module.exports = {
   runUserPromptSubmitHooks,
   runSessionStartHooks,
+  runCwdChangedHooks,
+  runWorktreeCreateHooks,
+  runWorktreeRemoveHooks,
+  runInstructionsLoadedHooks,
   runObserveHooks,
   aggregateContext,
   partitionAsyncHooks,

package/src/lib/settings-hooks.cjs

@@ -49,6 +49,10 @@ const HOOK_EVENTS = Object.freeze([
   "PreCompact",
   "Notification",
   "PermissionRequest",
+  "CwdChanged",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "InstructionsLoaded",
 ]);
 
 /**

package/src/lib/shell-approval.js

@@ -24,6 +24,13 @@ import {
   APPROVAL_RISK as RISK,
   APPROVAL_DECISION as DECISION,
 } from "@chainlesschain/session-core";
+import {
+  classifyCodeAcquisition,
+  hasGlobalInstall,
+  applyRiskFloor,
+  recordInstallCommandAudit,
+  resolveInstallPolicy,
+} from "./install-command-policy.js";
 
 export const SHELL_TO_RISK = {
   allow: RISK.LOW,
@@ -37,13 +44,49 @@ export async function evaluateShellCommandWithApproval({
   sessionId = null,
   approvalGate = null,
   shellPolicyOptions = {},
+  installPolicy = null,
 } = {}) {
   const shellPolicy = sharedShellPolicy.evaluateShellCommandPolicy(
     command,
     shellPolicyOptions,
   );
 
-  const riskLevel = SHELL_TO_RISK[shellPolicy.decision] || RISK.MEDIUM;
+  let riskLevel = SHELL_TO_RISK[shellPolicy.decision] || RISK.MEDIUM;
+
+  // Unified install-command classification (OPT-IN via installPolicy). A package
+  // install (npm/pip/winget/brew/…) fetches and runs third-party code, so it is
+  // a distinct, auditable permission type regardless of which tool does it. When
+  // a riskFloor is configured it RAISES (never lowers) the risk before gating;
+  // audit records the attempt. Absent/disabled → nothing runs, byte-unchanged.
+  // Explicit policy wins; otherwise self-activate from env (CC_INSTALL_AUDIT /
+  // CC_INSTALL_RISK_FLOOR) so the real run_shell path picks it up with no extra
+  // wiring. Both unset → disabled → the block below is skipped, byte-unchanged.
+  const effectiveInstallPolicy =
+    installPolicy || resolveInstallPolicy({ env: process.env });
+  let install = null;
+  if (effectiveInstallPolicy && effectiveInstallPolicy.enabled) {
+    const cls = classifyCodeAcquisition(command);
+    if (cls.flagged) {
+      install = cls;
+      if (effectiveInstallPolicy.riskFloor) {
+        riskLevel = applyRiskFloor(riskLevel, effectiveInstallPolicy.riskFloor);
+      }
+      if (effectiveInstallPolicy.audit) {
+        recordInstallCommandAudit(
+          {
+            command,
+            shellDecision: shellPolicy.decision,
+            riskLevel,
+            installs: cls.installs,
+            remoteExec: cls.remoteExec,
+            global: hasGlobalInstall(cls),
+            sessionId,
+          },
+          effectiveInstallPolicy.auditOpts || {},
+        );
+      }
+    }
+  }
 
   // Hard-blocked rules bypass the gate entirely — the gate tier cannot
   // up-authorize them.
@@ -56,6 +99,7 @@ export async function evaluateShellCommandWithApproval({
       shellPolicy,
       riskLevel,
       policy: null,
+      install,
     };
   }
 
@@ -69,6 +113,7 @@ export async function evaluateShellCommandWithApproval({
       shellPolicy,
       riskLevel,
       policy: null,
+      install,
     };
   }
 
@@ -87,6 +132,7 @@ export async function evaluateShellCommandWithApproval({
     shellPolicy,
     riskLevel,
     policy: gateResult.policy,
+    install,
     // Explainability passthrough (autoMode.decisions wrapper attaches these):
     // which gate rule fired and why — surfaced in the permission chain.
     gateReason: gateResult.reason ?? null,

package/src/repl/add-dir.js

@@ -61,10 +61,68 @@ export function resolveAddDir(input, { cwd, existing = [], deps } = {}) {
  */
 export function formatAddDirRoots(cwd, extraRoots) {
   const extras = Array.isArray(extraRoots) ? extraRoots : [];
-  const lines = [`Working roots (${1 + extras.length}):`, `  ${cwd}  (primary)`];
+  const lines = [
+    `Working roots (${1 + extras.length}):`,
+    `  ${cwd}  (primary)`,
+  ];
   for (const r of extras) lines.push(`  ${r}`);
   if (extras.length === 0) {
     lines.push("  (no extra roots — add one with /add-dir <dir>)");
   }
   return lines.join("\n");
 }
+
+/**
+ * The full workspace root list a session advertises to MCP servers (`roots/list`):
+ * the primary cwd first, then each extra `--add-dir` / `/add-dir` root, all
+ * resolved absolute and de-duplicated (the primary is dropped from the extras if
+ * a caller re-added it). Pure. Mirrors what the system prompt advertises so an
+ * MCP server sees the same roots the model does.
+ *
+ * @param {string} cwd            primary working directory
+ * @param {string[]} extraRoots   additional roots
+ * @returns {string[]}            deduped absolute dirs, primary first
+ */
+export function workspaceRootDirs(cwd, extraRoots) {
+  const primary = nodePath.resolve(cwd);
+  const out = [primary];
+  const seen = new Set([primary]);
+  for (const r of Array.isArray(extraRoots) ? extraRoots : []) {
+    if (!r) continue;
+    const abs = nodePath.resolve(cwd, String(r));
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Best-effort broadcast of a changed workspace-root list to every connected MCP
+ * client (via `client.setRoots(dirs)`, which advertises the new list AND fires
+ * `notifications/roots/list_changed` only when it actually changed). Skips
+ * nullish/duplicate clients and any without `setRoots`; a failing client never
+ * disturbs the others or the caller. Returns the number of clients notified.
+ * Claude-Code 2.1.203 roots-change parity for the `/add-dir` (and startup
+ * `--add-dir`) vector, mirroring what `/cd` already does via
+ * `notifyRootsListChanged`.
+ *
+ * @param {Array<object|null|undefined>} clients   MCP clients (may repeat/null)
+ * @param {string[]} dirs                           absolute root dirs
+ * @returns {number}
+ */
+export function notifyMcpRootsChanged(clients, dirs) {
+  let notified = 0;
+  const seen = new Set();
+  for (const c of Array.isArray(clients) ? clients : []) {
+    if (!c || seen.has(c) || typeof c.setRoots !== "function") continue;
+    seen.add(c);
+    try {
+      c.setRoots(dirs);
+      notified += 1;
+    } catch {
+      /* best-effort — one server's failure must not block the rest */
+    }
+  }
+  return notified;
+}

package/src/repl/agent-repl.js

@@ -1045,6 +1045,7 @@ export async function startAgentRepl(options = {}) {
   // `undefined` so the runtime default-on path — and CC_PROJECT_MEMORY=0 — keep
   // their existing behaviour byte-identically.
   const _leanNoProjectMemory = options.projectMemory === false;
+  let _loadedReplInstructions = null;
   let _replBaseSystem = composeSystemPrompt(
     buildSystemPrompt(process.cwd(), {
       additionalDirectories,
@@ -1054,6 +1055,9 @@ export async function startAgentRepl(options = {}) {
       systemPrompt: options.systemPrompt,
       appendSystemPrompt: options.appendSystemPrompt,
       projectMemory: _leanNoProjectMemory ? false : undefined,
+      onInstructionsLoaded: (loaded) => {
+        _loadedReplInstructions = loaded;
+      },
     },
   );
   let _activeOutputStyle = null; // { name, body }
@@ -1088,6 +1092,25 @@ export async function startAgentRepl(options = {}) {
     // best-effort — no output style
   }
 
+  // settings.json InstructionsLoaded hooks (observe-only): fire once with the
+  // exact loaded instruction file set so a hook can audit which cc.md/CLAUDE.md/
+  // AGENTS.md/rules are authoritative this session. Best-effort; no-op when
+  // project memory is off or no hook is registered.
+  if (_settingsHooks && _loadedReplInstructions) {
+    try {
+      const { runInstructionsLoadedHooks } =
+        await import("../lib/settings-hook-events.cjs");
+      const ctx = runInstructionsLoadedHooks(_settingsHooks, {
+        files: _loadedReplInstructions.files,
+        cwd: process.cwd(),
+        sessionId,
+      }).additionalContext;
+      if (ctx) messages.push({ role: "system", content: ctx });
+    } catch (_err) {
+      // best-effort
+    }
+  }
+
   // settings.json SessionStart hooks → inject session context (observe-only).
   if (_settingsHooks) {
     try {
@@ -1267,6 +1290,23 @@ export async function startAgentRepl(options = {}) {
     }
   }
 
+  // Seed connected MCP servers with the startup workspace roots when the session
+  // began with extra `--add-dir` roots — otherwise `roots/list` would only ever
+  // return the cwd until the first mid-session /add-dir. No-op (byte-unchanged)
+  // when there are no extra roots. Best-effort.
+  if (additionalDirectories.length > 0) {
+    try {
+      const { workspaceRootDirs, notifyMcpRootsChanged } =
+        await import("./add-dir.js");
+      notifyMcpRootsChanged(
+        [_adhocMcp?.mcpClient, _bundleMcpClient],
+        workspaceRootDirs(process.cwd(), additionalDirectories),
+      );
+    } catch {
+      /* best-effort — root advertisement must not block session startup */
+    }
+  }
+
   // Apply bundle approval policy to this session (after both gate and sessionId are ready)
   if (_bundleResolved?.approvalPolicy?.default && _approvalGate && sessionId) {
     try {
@@ -2382,8 +2422,12 @@ export async function startAgentRepl(options = {}) {
     if (trimmed === "/add-dir" || trimmed.startsWith("/add-dir ")) {
       const arg = trimmed.slice("/add-dir".length).trim();
       try {
-        const { resolveAddDir, formatAddDirRoots } =
-          await import("./add-dir.js");
+        const {
+          resolveAddDir,
+          formatAddDirRoots,
+          workspaceRootDirs,
+          notifyMcpRootsChanged,
+        } = await import("./add-dir.js");
         if (!arg) {
           logger.log(
             "\n" +
@@ -2417,6 +2461,14 @@ export async function startAgentRepl(options = {}) {
             messages[0].content = _activeOutputStyle
               ? `${_replBaseSystem}\n\n${_activeOutputStyle.body}`
               : _replBaseSystem;
+            // The workspace root LIST changed — advertise it to connected MCP
+            // servers and fire notifications/roots/list_changed so they re-query
+            // roots/list (Claude-Code 2.1.203 parity, same as /cd but with an
+            // explicit new root, not just a cwd-derived change).
+            notifyMcpRootsChanged(
+              [_adhocMcp?.mcpClient, _bundleMcpClient],
+              workspaceRootDirs(process.cwd(), additionalDirectories),
+            );
             logger.log(chalk.green(`Added working root: ${res.dir}`));
           }
         }
@@ -3002,9 +3054,11 @@ export async function startAgentRepl(options = {}) {
         logger.info(`cwd: ${process.cwd()}`);
       } else {
         try {
+          const oldCwd = process.cwd();
           const expanded = target.replace(/^~(?=$|[\\/])/, os.homedir());
           process.chdir(path.resolve(process.cwd(), expanded));
-          logger.log(chalk.green(`cwd → ${process.cwd()}`));
+          const newCwd = process.cwd();
+          logger.log(chalk.green(`cwd → ${newCwd}`));
           // MCP roots derive from cwd — tell connected servers to re-query
           // roots/list (Claude-Code 2.1.203 change-notification parity).
           for (const c of [_adhocMcp?.mcpClient, _bundleMcpClient]) {
@@ -3016,6 +3070,34 @@ export async function startAgentRepl(options = {}) {
               }
             }
           }
+          // CwdChanged settings hooks (lifecycle-event parity): the working dir
+          // just changed, so fire CwdChanged with old→new cwd — a hook can
+          // observe/react (re-audit the new dir's trust, reload per-dir config).
+          // Observe-only (a cwd change never gates flow); best-effort; no-op
+          // (byte-unchanged) without a registered CwdChanged hook.
+          if (_settingsHooks && oldCwd !== newCwd) {
+            try {
+              const { runCwdChangedHooks, dispatchAsyncHooks } =
+                await import("../lib/settings-hook-events.cjs");
+              const payload = { oldCwd, newCwd, sessionId };
+              runCwdChangedHooks(_settingsHooks, payload);
+              if (!_asyncHookSupervisor) {
+                const { AsyncHookSupervisor } =
+                  await import("../lib/async-hook-supervisor.cjs");
+                _asyncHookSupervisor = new AsyncHookSupervisor({
+                  persistStats: true,
+                });
+              }
+              dispatchAsyncHooks(
+                _settingsHooks,
+                "CwdChanged",
+                { old_cwd: oldCwd, cwd: newCwd, session_id: sessionId || null },
+                { cwd: newCwd, supervisor: _asyncHookSupervisor },
+              );
+            } catch {
+              /* CwdChanged firing is best-effort */
+            }
+          }
         } catch (err) {
           logger.error(`/cd failed: ${err.message}`);
         }

package/src/runtime/headless-runner.js

@@ -707,6 +707,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   let sideEffectSeq = 0;
   let currentSideEffectOpId = null;
   let resumeSideEffectContext = null;
+  let resumeAsyncHookContext = null;
   const persistSideEffectLedger = () => {
     if (!persist) return;
     try {
@@ -767,6 +768,34 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       } catch {
         resumeSideEffectContext = null;
       }
+      // On resume, recover any async-hook REWAKE (a background check that opted
+      // in and FAILED) that the previous run parked but died before draining —
+      // surface it to the model instead of silently swallowing the failure. The
+      // take also clears the bucket so it isn't replayed on a later resume.
+      try {
+        const { takePending } = await import("../lib/async-hook-queue.cjs");
+        const recovered = takePending(
+          { sessionId, now: deps.now ? deps.now() : Date.now() },
+          deps.asyncHookQueuePath || undefined,
+          deps.asyncHookQueueFs || undefined,
+        );
+        if (Array.isArray(recovered) && recovered.length > 0) {
+          const lines = recovered.map((r) => {
+            const detail = r.error || r.additionalContext || "failed";
+            return `  • ${r.command} — ${detail}`;
+          });
+          resumeAsyncHookContext =
+            "Recovery notice — the previous run was interrupted after these " +
+            "background (async) hook checks FAILED but before you were told. " +
+            "Review each failure and decide whether it still needs action:\n" +
+            lines.join("\n");
+          writeErr(
+            `⚠ Recovered ${recovered.length} failed async-hook check(s) from interrupted run (resume ${resumeId}).\n`,
+          );
+        }
+      } catch {
+        resumeAsyncHookContext = null;
+      }
     }
   }
 
@@ -856,6 +885,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // rules.md (in buildSystemPrompt) + the cc.md/CLAUDE.md block. Absent flag
   // (undefined) leaves both paths byte-identical.
   const _leanNoProjectMemory = options.projectMemory === false;
+  let _loadedInstructions = null;
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, {
       additionalDirectories,
@@ -867,6 +897,9 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       outputStyle: outputStyleBody,
       instructionExcludes,
       projectMemory: _leanNoProjectMemory ? false : undefined,
+      onInstructionsLoaded: (loaded) => {
+        _loadedInstructions = loaded;
+      },
     },
   );
 
@@ -896,6 +929,26 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   }
 
+  // settings.json InstructionsLoaded hooks (observe-only): the project-instruction
+  // block was just composed — fire with the EXACT loaded file set so a hook can
+  // audit which cc.md/CLAUDE.md/AGENTS.md/rules are authoritative this session.
+  // Any emitted context is injected like SessionStart's. Best-effort; no-op when
+  // project memory is off (no loaded set) or no hook is registered.
+  let instructionsLoadedContext = null;
+  if (settingsHooks && _loadedInstructions) {
+    try {
+      const { runInstructionsLoadedHooks } =
+        await import("../lib/settings-hook-events.cjs");
+      instructionsLoadedContext = runInstructionsLoadedHooks(settingsHooks, {
+        files: _loadedInstructions.files,
+        cwd,
+        sessionId,
+      }).additionalContext;
+    } catch (_err) {
+      instructionsLoadedContext = null;
+    }
+  }
+
   // settings.json SessionStart hooks → inject session context (observe-only).
   let sessionStartContext = null;
   if (settingsHooks) {
@@ -950,12 +1003,18 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // No-op on a healthy alternating transcript.
   const messages = mergeConsecutiveMessages([
     { role: "system", content: systemContent },
+    ...(instructionsLoadedContext
+      ? [{ role: "system", content: instructionsLoadedContext }]
+      : []),
     ...(sessionStartContext
       ? [{ role: "system", content: sessionStartContext }]
       : []),
     ...(resumeSideEffectContext
       ? [{ role: "system", content: resumeSideEffectContext }]
       : []),
+    ...(resumeAsyncHookContext
+      ? [{ role: "system", content: resumeAsyncHookContext }]
+      : []),
     ...history,
     { role: "user", content: userMessageContent },
   ]);
@@ -1160,7 +1219,16 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     try {
       const { AsyncHookSupervisor } =
         await import("../lib/async-hook-supervisor.cjs");
-      _hookSupervisor = new AsyncHookSupervisor({ persistStats: true });
+      _hookSupervisor = new AsyncHookSupervisor({
+        persistStats: true,
+        // Durably park failed-rewake signals keyed by session so a crash before
+        // the turn loop drains them doesn't lose the failure — recovered on the
+        // next `--resume` (see the resume block above). Only a PERSISTABLE
+        // session can be resumed, so the queue follows `persist`; a one-shot /
+        // --ephemeral run stays byte-unchanged (no session id → no writes).
+        persistQueue: persist,
+        sessionId: persist ? sessionId : null,
+      });
     } catch {
       _hookSupervisor = null; // async hooks are best-effort
     }

package/src/runtime/headless-stream.js

@@ -1078,6 +1078,7 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   // cc.md/CLAUDE.md instruction block. Only `=== false` changes anything; when
   // the flag is absent (undefined) both paths stay byte-identical.
   const _leanNoProjectMemory = options.projectMemory === false;
+  let _loadedInstructions = null;
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, {
       additionalDirectories,
@@ -1093,10 +1094,31 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
       outputStyle: outputStyleBody,
       instructionExcludes,
       projectMemory: _leanNoProjectMemory ? false : undefined,
+      onInstructionsLoaded: (loaded) => {
+        _loadedInstructions = loaded;
+      },
     },
   );
   const messages = [{ role: "system", content: systemContent }];
 
+  // settings.json InstructionsLoaded hooks (observe-only): fire once with the
+  // exact loaded instruction file set right after the system prompt is built.
+  // Best-effort; no-op when project memory is off or no hook is registered.
+  if (settingsHooks && _loadedInstructions) {
+    try {
+      const { runInstructionsLoadedHooks } =
+        await import("../lib/settings-hook-events.cjs");
+      const ctx = runInstructionsLoadedHooks(settingsHooks, {
+        files: _loadedInstructions.files,
+        cwd,
+        sessionId,
+      }).additionalContext;
+      if (ctx) messages.push({ role: "system", content: ctx });
+    } catch (_err) {
+      // best-effort
+    }
+  }
+
   // §3.5.13 flywheel consumption (design module 101): in a PDH session, lead
   // with the user's standing feedback preferences learned ACROSS sessions
   // (corrections + net sentiment) so the agent honours past corrections from