polygram 0.8.0-rc.2 → 0.8.0-rc.21

package/lib/error-classify.js

@@ -97,7 +97,10 @@ const USER_MESSAGES = {
   missingToolInput: '⚠️ Session history looks corrupted. Try /new.',
   timeout:          '⏳ I went quiet too long without finishing. Try resending or simplifying.',
   format:           '⚠️ Invalid request format. Try rephrasing or /new.',
-  transient5xx:     '☁️ Anthropic is temporarily unavailable. Retrying once…',
+  // Used both for in-flight retry attempts AND for the post-retry-failed
+  // bubble-up message. Avoid promising "retrying once" since by the
+  // time the user reads it pm has already retried and given up.
+  transient5xx:     '☁️ Server hiccup — please try again in a moment.',
 };
 
 // Auto-recovery actions for kinds where the session is irrecoverable
@@ -183,15 +186,16 @@ function classify(err) {
   }
 
   // SDKAssistantMessage.error is a short string code from a fixed
-  // union — match those directly, not via regex.
+  // union — match those directly, not via regex. Result subtypes
+  // are checked LATER (after pattern matching) so a more-specific
+  // pattern in the message text (e.g. 'HTTP 401' inside an
+  // error_during_execution subtype) wins over the generic subtype
+  // mapping that defaults the entire error_during_execution class
+  // to transient.
   if (typeof err === 'string') {
     const sdkMessageError = matchSdkMessageError(err);
     if (sdkMessageError) return sdkMessageError;
   }
-  if (err?.subtype && typeof err.subtype === 'string') {
-    const sdkResultSubtype = matchSdkResultSubtype(err.subtype);
-    if (sdkResultSubtype) return sdkResultSubtype;
-  }
 
   const msg = extractMessage(err);
   for (const [kind, re] of Object.entries(PATTERNS)) {
@@ -205,6 +209,20 @@ function classify(err) {
     }
   }
 
+  // After pattern matching: try SDK result subtypes. A bare string
+  // like 'error_during_execution' (no message context) lands here
+  // and gets the friendly transient5xx kind. Object inputs with a
+  // subtype field also land here when their message text didn't
+  // match a more specific pattern.
+  if (typeof err === 'string') {
+    const sdkResultSubtype = matchSdkResultSubtype(err);
+    if (sdkResultSubtype) return sdkResultSubtype;
+  }
+  if (err?.subtype && typeof err.subtype === 'string') {
+    const sdkResultSubtype = matchSdkResultSubtype(err.subtype);
+    if (sdkResultSubtype) return sdkResultSubtype;
+  }
+
   // Fall-through: surface a snippet of the raw error so users at
   // least know SOMETHING happened. Same shape as before, just
   // routed through the classifier so callers get a uniform return.
@@ -252,8 +270,15 @@ function matchSdkMessageError(s) {
 
 // SDKResultMessage.subtype values (sdk.d.ts:3121). Most are
 // terminal-error indicators that don't have a clean pattern equivalent.
+//
+// `error_during_execution` is the SDK's catch-all for "something went
+// wrong mid-turn" — could be a transient stream/network blip OR a
+// systemic model issue. We treat it as transient (1 retry is cheap;
+// if it's systemic the second attempt fails fast). Pre-rc.5 this was
+// mapped to 'unknown' which fell through to the default "Hit a snag:
+// error_during_execution" template — leaking the SDK enum to users.
 const SDK_RESULT_SUBTYPE_MAP = {
-  error_during_execution:           'unknown',
+  error_during_execution:           'transient5xx',
   error_max_turns:                  'format',
   error_max_budget_usd:             'billing',
   error_max_structured_output_retries: 'format',
@@ -265,8 +290,12 @@ function matchSdkResultSubtype(s) {
   return {
     kind,
     userMessage: USER_MESSAGES[kind] ?? null,
-    isTransient: false, // result subtypes don't auto-retry; the
-                        // turn already burned its budget.
+    // Derive transience from the kind so error_during_execution →
+    // transient5xx → isTransient=true, matching the pattern-match
+    // branch's behaviour. pm guards retry with firstAssistantSeen=
+    // false, which prevents budget waste when the turn already had
+    // billable assistant output.
+    isTransient: kind === 'transient5xx' || kind === 'rateLimit',
     autoRecover: AUTO_RECOVER[kind] ?? null,
   };
 }

package/lib/history-preload.js

@@ -0,0 +1,160 @@
+/**
+ * SessionStart hook factory: preloads recent chat history into a
+ * fresh SDK Query so the agent has context on day-zero.
+ *
+ * Why: when polygram spawns a brand-new Query for a chat (daemon
+ * boot, /new, /reset), the SDK has no transcript — the model
+ * starts blank even though the chat has been running for weeks.
+ * The user has to re-explain context every time. This hook injects
+ * the last N polygram-stored messages into the new session's
+ * `additionalContext`, plus a hint that the agent can query the
+ * history skill for older messages it didn't get preloaded.
+ *
+ * Fires only when SessionStart's `source` is 'startup' or 'clear'
+ * (genuinely fresh sessions). Skips on 'resume' (SDK is restoring
+ * the prior transcript) and 'compact' (SDK just compacted; history
+ * is already in the post-compact summary).
+ *
+ * Reuses lib/history.js's `recent()` helper — same DB query the
+ * polygram history skill exposes via CLI, so the agent's skill
+ * invocations and our preload return consistent shapes.
+ */
+
+'use strict';
+
+const history = require('./history');
+
+const DEFAULT_PRELOAD_LIMIT = 15;
+const DEFAULT_PRELOAD_SINCE = '7d';
+
+/**
+ * Format a single message row as a transcript line.
+ *
+ *   [2026-04-30 09:15] Ivan Shumkov: hello
+ *   [2026-04-30 09:16] bot: hey
+ *
+ * Schema notes: messages table uses `direction` = 'in'|'out',
+ * `user` for the sender display name (inbound) or bot identity
+ * (outbound). reply_to_id is on the row directly. Attachment and
+ * voice flags live on the attachments table via JOIN — not
+ * surfaced here in the preload (operator-curated history docs are
+ * the place for that level of detail).
+ */
+function formatRow(row) {
+  const ts = new Date(row.ts).toISOString().replace('T', ' ').slice(0, 16);
+  const who = row.direction === 'in'
+    ? (row.user || row.user_id || 'user')
+    : (row.user || row.bot_name || 'bot');
+  const prefix = row.reply_to_id ? `[reply→#${row.reply_to_id}] ` : '';
+  const text = (row.text || '').replace(/\s+/g, ' ').slice(0, 600);
+  return `[${ts}] ${who}: ${prefix}${text}`;
+}
+
+/**
+ * Build the SessionStart hook callback.
+ *
+ * @param {object} opts
+ * @param {object} opts.db                     polygram db wrapper (has .raw better-sqlite3 instance)
+ * @param {string} opts.chatId                 the chat being spawned
+ * @param {string|null} [opts.threadId]
+ * @param {string[]} [opts.allowedChatIds]     scope-narrowing safety; defaults to [chatId]
+ * @param {number} [opts.limit]                max messages to preload (default 15)
+ * @param {string} [opts.since]                cutoff window (default '7d')
+ * @param {(kind: string, detail: object) => void} [opts.logEvent]
+ * @param {object} [opts.logger]
+ *
+ * @returns {async (input) => Promise<HookJSONOutput>}
+ */
+function makeSessionStartHook({
+  db,
+  chatId,
+  threadId = null,
+  allowedChatIds = null,
+  limit = DEFAULT_PRELOAD_LIMIT,
+  since = DEFAULT_PRELOAD_SINCE,
+  logEvent = null,
+  logger = console,
+} = {}) {
+  if (!db || !db.raw) throw new TypeError('db (with .raw better-sqlite3) required');
+  if (!chatId) throw new TypeError('chatId required');
+
+  return async (input) => {
+    try {
+      // Skip on resume / compact — transcript already has history.
+      if (input?.source === 'resume' || input?.source === 'compact') {
+        return { continue: true };
+      }
+
+      const scope = allowedChatIds || [String(chatId)];
+      let rows;
+      try {
+        // history.recent() expects the polygram db wrapper (it
+        // calls db.raw.prepare internally), not the raw bsqlite3.
+        rows = history.recent(db, {
+          chatId: String(chatId),
+          threadId: threadId ?? null,
+          limit,
+          since,
+          includeOutbound: true,
+          allowedChatIds: scope,
+        }) || [];
+      } catch (err) {
+        logger?.error?.(`[history-preload] recent() failed: ${err?.message || err}`);
+        return { continue: true };
+      }
+
+      if (rows.length === 0) {
+        return { continue: true };
+      }
+
+      // history.recent() returns rows in chronological order
+      // already (it does `ORDER BY ts DESC LIMIT N` then `.reverse()`
+      // internally — see lib/history.js:69).
+      const lines = rows.map(formatRow).join('\n');
+
+      const additionalContext = [
+        `<polygram-history chat_id="${chatId}"${threadId ? ` thread_id="${threadId}"` : ''} preloaded="${rows.length}" since="${since}">`,
+        lines,
+        `</polygram-history>`,
+        '',
+        '— More history available via `node skills/history/scripts/query.js`:',
+        '    recent <chat_id> [thread_id] --limit N  (older than the preload window)',
+        '    around --chat <id> --msg-id N           (context window around a message)',
+        '    search <term> [chat_id]                 (FTS5 across full transcript)',
+        '    by-user <name> [chat_id] [thread_id]',
+        '  Bot scope is auto-resolved from cwd; no admin flag needed.',
+      ].join('\n');
+
+      if (typeof logEvent === 'function') {
+        try {
+          logEvent('history-preloaded', {
+            chat_id: chatId,
+            session_source: input?.source ?? 'startup',
+            row_count: rows.length,
+            text_len: additionalContext.length,
+          });
+        } catch { /* swallow logger errors */ }
+      }
+
+      return {
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext,
+        },
+      };
+    } catch (err) {
+      logger?.error?.(`[history-preload] hook error: ${err?.message || err}`);
+      // Never throw out of a hook.
+      return { continue: true };
+    }
+  };
+}
+
+module.exports = {
+  makeSessionStartHook,
+  // Internals for tests
+  _formatRow: formatRow,
+  DEFAULT_PRELOAD_LIMIT,
+  DEFAULT_PRELOAD_SINCE,
+};

package/lib/pm-interface.js

@@ -0,0 +1,95 @@
+/**
+ * Canonical Pm interface (JSDoc typedef).
+ *
+ * Both `lib/process-manager.js` (CLI pm) and `lib/process-manager-sdk.js`
+ * (SDK pm) implement this. `lib/pm-router.js`'s `createPmRouter()`
+ * forwards calls to one or the other based on per-chat policy.
+ *
+ * Optional methods are marked `?` — the router exposes them too but
+ * returns documented sentinels when the routed pm doesn't implement
+ * them. Sites that need to feature-detect should call
+ * `pm.pickFor(sessionKey)` and probe `typeof X === 'function'` on
+ * the returned pm instance, not on the router.
+ *
+ * @typedef {object} PmEntry
+ *   The shape pm.get(sessionKey) returns. Different pms decorate it
+ *   with their own internal fields; only the documented fields below
+ *   are part of the public contract.
+ * @property {string} sessionKey
+ * @property {string|null} chatId
+ * @property {string|null} threadId
+ * @property {boolean} closed
+ * @property {boolean} inFlight
+ * @property {Array<object>} pendingQueue   — array of pending sends
+ *
+ * @typedef {object} PmSendResult
+ *   The shape pm.send() resolves with on success. Failure rejects.
+ * @property {string} text                  — final assistant text (may be '')
+ * @property {string|null} sessionId        — Claude session id (for resume)
+ * @property {number} cost                  — total cost USD
+ * @property {number} duration              — turn duration ms
+ * @property {string|null} error            — error string or null on success
+ * @property {object} metrics               — token / tool / msg counts
+ * @property {number} metrics.inputTokens
+ * @property {number} metrics.outputTokens
+ * @property {number} metrics.cacheCreationTokens
+ * @property {number} metrics.cacheReadTokens
+ * @property {number} metrics.numAssistantMessages
+ * @property {number} metrics.numToolUses
+ * @property {string|null} metrics.resultSubtype
+ *
+ * @typedef {object} PmSendOptions
+ * @property {number} [timeoutMs]
+ * @property {number} [maxTurnMs]
+ * @property {object} [context]             — opaque per-turn state (streamer, reactor, sourceMsgId)
+ *
+ * @typedef {object} PmSpawnContext
+ *   What polygram passes to spawnFn(sessionKey, ctx). Internal to
+ *   each pm but documented here so callers know what's available.
+ * @property {string|null} chatId
+ * @property {string|null} threadId
+ * @property {string} label
+ *
+ * @typedef {object} Pm
+ *   The unified ProcessManager interface. Both CLI and SDK pm
+ *   implement these; the router forwards.
+ *
+ *   Required (every pm has these):
+ * @property {(sessionKey: string) => boolean} has
+ * @property {(sessionKey: string) => PmEntry|null} get
+ * @property {(sessionKey: string, ctx: PmSpawnContext) => Promise<PmEntry>} getOrSpawn
+ * @property {(sessionKey: string, prompt: string, opts?: PmSendOptions) => Promise<PmSendResult>} send
+ * @property {(sessionKey: string) => Promise<void>} kill
+ * @property {(chatId: string|number) => Promise<void>} killChat
+ *   — closes ALL sessions belonging to a chat (broadcast across topics).
+ * @property {() => Promise<void>} shutdown
+ *   — graceful daemon-wide drain + close.
+ *
+ *   Optional (only one of the two pms implements these — feature-detect):
+ * @property {((sessionKey: string, text: string, opts?: object) => boolean)=} steer
+ *   — SDK pm only (rc.9 PostToolBatch hook drains buffer).
+ * @property {((sessionKey: string, model: string) => Promise<boolean>)=} setModel
+ *   — SDK pm only (Query.setModel live).
+ * @property {((sessionKey: string, settings: {effortLevel?: string}) => Promise<boolean>)=} applyFlagSettings
+ *   — SDK pm only (Query.applyFlagSettings live).
+ * @property {((sessionKey: string, mode: string) => Promise<boolean>)=} setPermissionMode
+ *   — SDK pm only.
+ * @property {((sessionKey: string, reason?: string) => {killed: boolean, queued: number})=} requestRespawn
+ *   — CLI pm only (drain pending queue then kill; respawn on next send).
+ * @property {((sessionKey: string, errCode: string) => number)=} drainQueue
+ *   — SDK pm only (reject all queued pendings with errCode).
+ * @property {((sessionKey: string) => Promise<void>)=} interrupt
+ *   — SDK pm only (Query.interrupt — non-destructive).
+ * @property {((sessionKey: string, opts?: {reason?: string}) => Promise<{closed: boolean, drainedPendings: number}>)=} resetSession
+ *   — SDK pm only (close Query + clear sessionId from DB).
+ *
+ *   Lifecycle introspection (for tests / debugging — not required
+ *   to be present, but both current pms expose them):
+ * @property {() => string[]=} keys      — sessionKey list
+ * @property {() => number=} size        — number of live sessions
+ */
+
+// This file is JSDoc-only; no runtime exports. It exists so editors
+// + the JSDoc-aware test mocks reference a single canonical type.
+
+module.exports = {};

package/lib/pm-router.js

@@ -0,0 +1,159 @@
+/**
+ * Per-chat ProcessManager router (rc.6+).
+ *
+ * Daemon hosts up to TWO pm instances simultaneously — the
+ * stream-json-CLI ProcessManager and the @anthropic-ai/claude-agent-sdk
+ * ProcessManagerSdk. Each chat is assigned to one of them based on
+ * env config:
+ *
+ *   POLYGRAM_USE_SDK=1                 → all chats SDK pm
+ *   POLYGRAM_SDK_CHATS=id1,id2,...     → those chats SDK; others CLI
+ *   neither set                        → all chats CLI
+ *
+ * The router exposes the same surface a single pm did, plus two
+ * introspection methods:
+ *
+ *   pm.pickFor(sessionKey)   → underlying pm instance (for feature
+ *                              detection at call sites)
+ *   pm.isSdkFor(sessionKey)  → boolean shortcut
+ *
+ * Lifecycle methods (`killChat`, `shutdown`) broadcast to BOTH pms
+ * when both are alive — a chat could have a session on either side
+ * (e.g. mid-config-change), so we don't risk leaking one.
+ *
+ * Optional methods (steer / setModel / applyFlagSettings /
+ * requestRespawn / drainQueue / interrupt / resetSession) forward
+ * when the routed pm has the method and return a sentinel otherwise.
+ * Sites that need to feature-detect should `pm.pickFor(sessionKey)`
+ * and check `typeof X === 'function'` directly.
+ *
+ * Used by `polygram.js` main() — Phase 5 + rc.6.
+ */
+
+'use strict';
+
+/**
+ * Parse the SDK-chats env config into a router policy.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.useSdkAll  — POLYGRAM_USE_SDK=1
+ * @param {Iterable<string>} [opts.sdkChats]  — POLYGRAM_SDK_CHATS list
+ * @param {(sessionKey: string) => string|null} opts.getChatIdFromKey
+ *
+ * @returns {object} { sdkAllChats, sdkSomeChats, sdkActive,
+ *                     sdkChatIdSet, pickPmKindFor }
+ */
+function makeRouterPolicy({ useSdkAll = false, sdkChats = [], getChatIdFromKey } = {}) {
+  if (typeof getChatIdFromKey !== 'function') {
+    throw new TypeError('getChatIdFromKey function required');
+  }
+  const sdkChatIdSet = new Set(
+    [...sdkChats].map((s) => String(s).trim()).filter(Boolean),
+  );
+  const sdkAllChats = !!useSdkAll && sdkChatIdSet.size === 0;
+  const sdkSomeChats = sdkChatIdSet.size > 0;
+  const sdkActive = sdkAllChats || sdkSomeChats;
+
+  function pickPmKindFor(sessionKey) {
+    if (sdkAllChats) return 'sdk';
+    if (!sdkSomeChats) return 'cli';
+    const chatId = String(getChatIdFromKey(sessionKey) ?? '');
+    return sdkChatIdSet.has(chatId) ? 'sdk' : 'cli';
+  }
+
+  return { sdkAllChats, sdkSomeChats, sdkActive, sdkChatIdSet, pickPmKindFor };
+}
+
+/**
+ * Build a routing pm proxy. cliPm is required; sdkPm is optional
+ * (null when SDK isn't enabled for any chat).
+ *
+ * @param {object} opts
+ * @param {object} opts.cliPm
+ * @param {object|null} opts.sdkPm
+ * @param {(sessionKey: string) => 'sdk'|'cli'} opts.pickPmKindFor
+ */
+function createPmRouter({ cliPm, sdkPm = null, pickPmKindFor } = {}) {
+  if (!cliPm) throw new TypeError('cliPm required');
+  if (typeof pickPmKindFor !== 'function') {
+    throw new TypeError('pickPmKindFor function required');
+  }
+
+  function routedPm(sessionKey) {
+    return pickPmKindFor(sessionKey) === 'sdk' && sdkPm ? sdkPm : cliPm;
+  }
+
+  return {
+    pickFor: routedPm,
+    isSdkFor(sessionKey) {
+      return pickPmKindFor(sessionKey) === 'sdk' && !!sdkPm;
+    },
+
+    // Methods that exist on every pm instance — direct routing.
+    has(sessionKey) { return routedPm(sessionKey).has(sessionKey); },
+    get(sessionKey) { return routedPm(sessionKey).get(sessionKey); },
+    getOrSpawn(sessionKey, ctx) { return routedPm(sessionKey).getOrSpawn(sessionKey, ctx); },
+    send(sessionKey, prompt, opts) { return routedPm(sessionKey).send(sessionKey, prompt, opts); },
+    kill(sessionKey) { return routedPm(sessionKey).kill(sessionKey); },
+
+    // Lifecycle methods broadcast to both pms because a chat may
+    // have spawned sessions on either side at different times.
+    async killChat(chatId) {
+      const tasks = [cliPm.killChat(chatId)];
+      if (sdkPm) tasks.push(sdkPm.killChat(chatId));
+      await Promise.all(tasks);
+    },
+    async shutdown() {
+      const tasks = [cliPm.shutdown()];
+      if (sdkPm) tasks.push(sdkPm.shutdown());
+      await Promise.all(tasks);
+    },
+
+    // Optional methods — forward when the routed pm implements
+    // them, return a documented sentinel otherwise. Use
+    // `pm.pickFor(sessionKey)` for proper feature detection at
+    // call sites that need to branch on capability.
+    steer(sessionKey, ...args) {
+      const target = routedPm(sessionKey);
+      return typeof target.steer === 'function' ? target.steer(sessionKey, ...args) : false;
+    },
+    resetSession(sessionKey, opts) {
+      const target = routedPm(sessionKey);
+      return typeof target.resetSession === 'function'
+        ? target.resetSession(sessionKey, opts)
+        : Promise.resolve({ closed: false, drainedPendings: 0 });
+    },
+    applyFlagSettings(sessionKey, settings) {
+      const target = routedPm(sessionKey);
+      return typeof target.applyFlagSettings === 'function'
+        ? target.applyFlagSettings(sessionKey, settings)
+        : Promise.resolve(false);
+    },
+    setModel(sessionKey, model) {
+      const target = routedPm(sessionKey);
+      return typeof target.setModel === 'function'
+        ? target.setModel(sessionKey, model)
+        : Promise.resolve(false);
+    },
+    requestRespawn(sessionKey, reason) {
+      const target = routedPm(sessionKey);
+      return typeof target.requestRespawn === 'function'
+        ? target.requestRespawn(sessionKey, reason)
+        : { killed: false, queued: 0 };
+    },
+    drainQueue(sessionKey, errCode) {
+      const target = routedPm(sessionKey);
+      return typeof target.drainQueue === 'function'
+        ? target.drainQueue(sessionKey, errCode)
+        : 0;
+    },
+    interrupt(sessionKey) {
+      const target = routedPm(sessionKey);
+      return typeof target.interrupt === 'function'
+        ? target.interrupt(sessionKey)
+        : Promise.resolve();
+    },
+  };
+}
+
+module.exports = { makeRouterPolicy, createPmRouter };

package/lib/process-manager-sdk.js

@@ -168,6 +168,18 @@ function makeInputController({ queueCap = DEFAULT_QUEUE_CAP } = {}) {
 
 // ─── ProcessManager ────────────────────────────────────────────────
 
+/**
+ * @anthropic-ai/claude-agent-sdk-backed ProcessManager. Implements
+ * the canonical Pm interface (`lib/pm-interface.js`). Optional
+ * methods exposed: `steer`, `setModel`, `applyFlagSettings`,
+ * `setPermissionMode`, `drainQueue`, `interrupt`, `resetSession`.
+ *
+ * Optional methods NOT implemented (CLI pm has this): `requestRespawn`.
+ * For mid-session config changes use `applyFlagSettings` (effort)
+ * or `setModel`.
+ *
+ * @implements {import('./pm-interface.js').Pm}
+ */
 class ProcessManagerSdk {
   constructor({
     cap = DEFAULT_CAP,
@@ -470,6 +482,7 @@ class ProcessManagerSdk {
             entry.inputController.push({
               type: 'user',
               message: { role: 'user', content: head.prompt },
+              parent_tool_use_id: null,
             });
           } catch (err) {
             entry.pendingQueue.shift();
@@ -655,6 +668,7 @@ class ProcessManagerSdk {
         entry.inputController.push({
           type: 'user',
           message: { role: 'user', content: prompt },
+          parent_tool_use_id: null,
         });
       } catch (err) {
         const idx = entry.pendingQueue.indexOf(pending);
@@ -754,13 +768,30 @@ class ProcessManagerSdk {
    * Returns true if push succeeded; false if session not found or
    * input controller closed.
    */
-  steer(sessionKey, text, { shouldQuery = true } = {}) {
+  steer(sessionKey, text, { shouldQuery = false } = {}) {
     const entry = this.procs.get(sessionKey);
     if (!entry || entry.closed) return false;
     try {
+      // 0.8.0-rc.7 (per v4 plan §0 row 9 + Phase 2 step 1's original
+      // shape): push with `shouldQuery: false` so the SDK appends to
+      // the transcript without trying to terminate the in-flight turn.
+      // The previous default `shouldQuery: true` triggered the CLI
+      // binary's `m87` gate (transcript well-formedness check) which
+      // emitted `result.subtype = error_during_execution` whenever a
+      // plain-text user message arrived while the assistant was mid-
+      // tool-use. With shouldQuery=false the message merges into the
+      // next natural user turn — the in-flight tools complete first,
+      // then the assistant sees the steered context.
+      //
+      // parent_tool_use_id is required by SDKUserMessage type
+      // (sdk.d.ts:3479-3498). The SDK runtime checks `!== null` in
+      // multiple places; omitting it falls through to wrong handling
+      // branches. The SDK's own `mz.send()` and `pz` replay set it
+      // to null explicitly.
       entry.inputController.push({
         type: 'user',
         message: { role: 'user', content: text },
+        parent_tool_use_id: null,
         priority: 'now',
         shouldQuery,
       });

package/lib/process-manager.js

@@ -93,6 +93,19 @@ function sumUsage(usageByMessage) {
   return out;
 }
 
+/**
+ * Stream-json CLI-backed ProcessManager. Implements the canonical
+ * Pm interface (`lib/pm-interface.js`). Optional methods exposed:
+ * `requestRespawn` — drain queue and respawn process on next send
+ * (kept for parity with rc.6+ feature-detection at the router; SDK
+ * pm uses `applyFlagSettings` + `setModel` for the same UX).
+ *
+ * Optional methods NOT implemented (SDK pm has these): `steer`,
+ * `setModel`, `applyFlagSettings`, `setPermissionMode`,
+ * `drainQueue`, `interrupt`, `resetSession`.
+ *
+ * @implements {import('./pm-interface.js').Pm}
+ */
 class ProcessManager {
   constructor({
     cap = DEFAULT_CAP,