@cocorograph/hub-agent 0.8.43 → 0.8.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.43",
+  "version": "0.8.45",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの Claude / Codex チャットと tmux セッションを中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/claude-stream-bridge.mjs

@@ -439,6 +439,7 @@ export class ClaudeStreamSession {
     onPermissionCancel,
     onExit,
     onError,
+    onOptions,
     onReap,
     onTurnSettled,
   }) {
@@ -481,6 +482,7 @@ export class ClaudeStreamSession {
     this.onPermissionCancel = onPermissionCancel
     this.onExit = onExit
     this.onError = onError
+    this.onOptions = onOptions
     /** ターン完走後に遅延クローズする際、manager にセッション撤去を依頼するコールバック */
     this.onReap = onReap
     /** RC-4: result を届けずにターンが終わった (abort/異常終了) ときに呼ぶコールバック。
@@ -551,6 +553,11 @@ export class ClaudeStreamSession {
     /** この session オブジェクトの世代 (T06603)。上記 nextQueueGeneration の説明を参照。
      *  **同一プロセス内の順序のみ**を保証する (プロセス間は backend の接続フェンスが担う)。 */
     this._queueGeneration = nextQueueGeneration()
+    /** model / permissionMode の「次ターン desired」authority identity。
+     * UUID は同一 session object の一致確認だけに使い、大小・生成順は比較しない。 */
+    this._optionsInstanceId = randomUUID()
+    /** 上記instance内だけで比較するCAS revision。queue seq/generationとは独立。 */
+    this._optionsRevision = 0
     /** 配達確認の再表明用 (T06603): この session が受理 (キュー投入 or 直接配送) した
      *  input_id の直近リング。`claude.input.ack` は一度きりのユニキャストで、WS 切断が
      *  30s を超えると ws-client の ctrl バッファから破棄され二度と再送されない。その結果
@@ -988,12 +995,9 @@ export class ClaudeStreamSession {
    *  browser 接続へライブに流れる (= 通常の生成中表示と同じ)。再アタッチ前の確定分は
    *  browser 側の jsonl hydrate (history.request) で復元するため、ここでは replay しない。
    *
-   *  改修5 (2026-05-29): モデル/権限/拡張思考のターン切替。再アタッチ時に opts で
-   *  新しい値が渡され、現在値と異なれば applyRuntimeOptions で反映する。これにより
-   *  入力欄下バッジの変更が「同一セッション(常駐 query)を維持したまま次ターンから」
-   *  効くようになる。従来は reattach が stream_id だけ差し替えていたため、起動済み
-   *  query の model/permission/thinking は初期値のまま変わらなかった (バッジが効かない
-   *  不具合の原因)。 */
+   *  通常 attach は購読 + current snapshot 取得専用。model / permissionMode は CAS request
+   *  (`claude.session.options.set`) だけが変更できる。maxThinkingTokens / effort は今回の
+   *  authority 対象外なので、既存 attach 反映を維持する。 */
   reattach(stream_id, opts = undefined) {
     this.stream_id = stream_id
     // 多端末共有: この端末を購読集合に追加 (無効時は未使用)。旧端末の stream_id は
@@ -1005,7 +1009,12 @@ export class ClaudeStreamSession {
       clearTimeout(this._idleTimer)
       this._idleTimer = null
     }
-    if (opts) this.applyRuntimeOptions(opts)
+    if (opts) {
+      this.applyRuntimeOptions({
+        maxThinkingTokens: opts.maxThinkingTokens,
+        effort: opts.effort,
+      })
+    }
     // キュー再表示バグ修正 (0.6.30): 再アタッチした端末は queue_state のライブ配信を
     // 取りこぼしている (jsonl hydrate にはキュー状態が含まれない)。現在の pending を
     // force で再 emit し、再表示端末・後から接続した端末の送信待ちチップを復元する。
@@ -1064,11 +1073,13 @@ export class ClaudeStreamSession {
    *  maxThinkingTokens に 0/null が来たら次 spawn 時に budget オフ (thinking 未指定) となる。 */
   applyRuntimeOptions({ model, permissionMode, maxThinkingTokens, effort } = {}) {
     const q = this._residentQuery
+    let desiredOptionsChanged = false
     // モデル
     if (model !== undefined) {
       const next = model || null
       if (next !== this.model) {
         this.model = next
+        desiredOptionsChanged = true
         if (q && typeof q.setModel === "function") {
           q.setModel(next || undefined).catch((err) =>
             this.logger?.warn(
@@ -1084,6 +1095,7 @@ export class ClaudeStreamSession {
       const next = permissionMode || null
       if (next !== this.permissionMode) {
         this.permissionMode = next
+        desiredOptionsChanged = true
         // setPermissionMode は有効な mode を要求する。null/空 (=未指定へ戻す) は
         // SDK 側に「解除」API が無いため、保持値の更新のみ (次回 spawn で既定に従う)。
         if (next && q && typeof q.setPermissionMode === "function") {
@@ -1116,6 +1128,84 @@ export class ClaudeStreamSession {
     if (effort !== undefined) {
       this.effort = effort || null
     }
+    if (desiredOptionsChanged) {
+      this._optionsRevision += 1
+      try {
+        this.onOptions?.(this.optionsSnapshot())
+      } catch (err) {
+        this.logger?.warn?.(
+          { err: err?.message, stream_id: this.stream_id },
+          "onOptions callback threw",
+        )
+      }
+    }
+  }
+
+  /** Exact-base CAS で model / permissionMode の次ターン desired を変更する。 */
+  setSessionOptions({ baseOptionsInstanceId, baseOptionsRevision, patch }) {
+    const current = () => this.optionsSnapshot()
+    const hasModel = patch && Object.hasOwn(patch, "model")
+    const hasPermissionMode =
+      patch && Object.hasOwn(patch, "permission_mode")
+    if (
+      !patch ||
+      typeof patch !== "object" ||
+      Array.isArray(patch) ||
+      Object.keys(patch).length === 0 ||
+      Object.keys(patch).some(
+        (key) => key !== "model" && key !== "permission_mode",
+      ) ||
+      !(hasModel || hasPermissionMode) ||
+      (hasModel &&
+        !(patch.model === null || typeof patch.model === "string")) ||
+      (hasPermissionMode &&
+        !(
+          patch.permission_mode === null ||
+          typeof patch.permission_mode === "string"
+        ))
+    ) {
+      return { outcome: "invalid_patch", current: current() }
+    }
+    if (
+      baseOptionsInstanceId !== this._optionsInstanceId ||
+      !Number.isSafeInteger(baseOptionsRevision) ||
+      baseOptionsRevision !== this._optionsRevision
+    ) {
+      return { outcome: "conflict", current: current() }
+    }
+
+    // attach/configと同じく空文字はdefault(null)。比較前に正規化してnull状態のnoopを保つ。
+    const normalizedPatch = {
+      ...(hasModel ? { model: patch.model || null } : {}),
+      ...(hasPermissionMode
+        ? { permission_mode: patch.permission_mode || null }
+        : {}),
+    }
+    const nextModel = hasModel ? normalizedPatch.model : this.model
+    const nextPermissionMode =
+      hasPermissionMode
+        ? normalizedPatch.permission_mode
+        : this.permissionMode
+    if (nextModel === this.model && nextPermissionMode === this.permissionMode) {
+      return { outcome: "noop", current: current() }
+    }
+    this.applyRuntimeOptions({
+      ...(hasModel ? { model: normalizedPatch.model } : {}),
+      ...(hasPermissionMode
+        ? { permissionMode: normalizedPatch.permission_mode }
+        : {}),
+    })
+    return { outcome: "applied", current: current() }
+  }
+
+  /** 次ターンに使う desired options。SDK setter の成功実測値ではない。 */
+  optionsSnapshot() {
+    return {
+      model: this.model,
+      permission_mode: this.permissionMode,
+      options_instance_id: this._optionsInstanceId,
+      options_revision: this._optionsRevision,
+    }
   }
 
   /** モデルが effort / adaptive thinking 対応かどうか。
@@ -2534,12 +2624,10 @@ export class ClaudeStreamBridge extends EventEmitter {
         // 多端末共有 (T06542 で常時): 旧 stream_id を Map から消さない。同一セッションを複数端末が
         // 購読する状態を作り、どの端末の input/permission/interrupt も解決できるようにする
         // (旧端末は reattach.streamIds に足され、backend が session group へ fan-out する)。
-        // 改修5: 再アタッチ時に model/permission/maxThinkingTokens を引き継ぎ反映する。
-        // browser はバッジ変更時に新しい値を載せた claude.attach を同一 resume で送る
-        // ため、ここで適用すると常駐 query を維持したまま次ターンから切り替わる。
+        // 通常 attach は購読 + current snapshot 取得だけ。旧 frontend は capability flag を
+        // 送らず model/permission を載せるが、新 agent は live session では fail-closed で無視する。
+        // maxThinkingTokens / effort は model/permission authority の対象外なので既存反映を維持。
         live.reattach(stream_id, {
-          model,
-          permissionMode,
           maxThinkingTokens:
             typeof maxThinkingTokens === "number" ? maxThinkingTokens : null,
           effort,
@@ -2562,6 +2650,7 @@ export class ClaudeStreamBridge extends EventEmitter {
           resuming: true,
           reattached: true,
           turn_active: live._busy === true,
+          ...live.optionsSnapshot(),
         }
       }
     }
@@ -2635,6 +2724,14 @@ export class ClaudeStreamBridge extends EventEmitter {
           error: err?.message || String(err),
         })
       },
+      onOptions: (snapshot) => {
+        // bridge 内部イベントは wire type を持たない。wire 契約は main builder に閉じる。
+        this.emit("sessionoptions", {
+          stream_id: session.stream_id,
+          session_id: session.sessionId,
+          ...snapshot,
+        })
+      },
       onReap: (info) => {
         // ターン完走後の遅延クローズ、または R1(a) 子プロセス死亡時の即 evict。Map / 索引から
         // 撤去し exit を emit する。多端末共有では複数端末キーが Map に載っているのでまとめて外す。
@@ -2680,9 +2777,39 @@ export class ClaudeStreamBridge extends EventEmitter {
       stream_id,
       resuming: !!resumeSessionId,
       turn_active: session._busy === true,
+      ...session.optionsSnapshot(),
     }
   }
 
+  /** browser の session options CAS request。常に current snapshot 付き outcome を返す。 */
+  setSessionOptions({
+    stream_id,
+    session_id,
+    base_options_instance_id,
+    base_options_revision,
+    patch,
+  }) {
+    const session = this.sessions.get(stream_id)
+    if (!session) {
+      return { outcome: "stream_missing", current: null }
+    }
+    // CAS操作もpermission reply/inputと同じユーザー活性。dead-terminal GCとwarm LRUを更新する。
+    session.touch(stream_id)
+    // fresh は SDK init 前だけ sessionId=null。同じ stream なら CAS 可能だが、session group の
+    // identity がまだ無いため他端末はこの fresh session を購読できない。
+    if (session.sessionId !== session_id) {
+      return {
+        outcome: "session_mismatch",
+        current: session.optionsSnapshot(),
+      }
+    }
+    return session.setSessionOptions({
+      baseOptionsInstanceId: base_options_instance_id,
+      baseOptionsRevision: base_options_revision,
+      patch,
+    })
+  }
+
   /**
    * browser → claude の user メッセージ。1 件 = 1 query (resume チェーン)。
    *

package/src/codex-stream-bridge.mjs

@@ -136,6 +136,14 @@ const STUCK_TURN_TTL_MS = readPositiveIntEnv(
   60 * 60 * 1000,
 )
 
+// 子 turn の停止 handle 台帳を回収できる最短 age（既定 4h）。通常は保護 TTL（既定 1h）を
+// 先に超えて protectionExpiredAtMs が立ち、その後も長時間 heartbeat が無い record だけを回収する。
+// つまり保護 TTL 直後には停止可能性を残し、台帳だけが永久化することも避ける。設定で保護 TTL を
+// 4h 以上へ延ばした場合も、protectionExpiredAtMs が立つまでは active handle を回収しない。
+const SUBAGENT_INTERRUPT_RECORD_TTL_MS = 4 * 60 * 60 * 1000
+/** 個別停止中に後発 descendant を拾う再走査回数。無制限 spawn に応答を占有されない上限。 */
+const SUBAGENT_INTERRUPT_SCAN_ROUNDS = 3
+
 // 案B (T06542): 死端末 GC の TTL。多端末購読で、応答を返さなくなった（クラッシュ / タブ強制終了で
 // codex.detach を送れなかった）購読端末を購読集合から掃除する閾値。claude-stream-bridge.mjs の
 // DEAD_TERMINAL_TTL_MS（既定 1h）と同型・同既定。stuck turn TTL とは別軸（あちらはターン固着、
@@ -774,6 +782,8 @@ export class CodexStreamBridge extends EventEmitter {
       subagentInterruptRegistry: new Map(),
       /** dynamicToolCall(spawn_agent) の item.id -> 表示メタデータ。 */
       subagentSpawnMetadata: new Map(),
+      /** invalid background の同一 item 再送で warn を重複させない bounded set。 */
+      subagentInvalidBackgroundWarned: new Set(),
       /** live subAgentActivity の spawn metadata miss を child thread/read で補完する
        * single-flight 台帳。key = agentThreadId, value = 進行中 Promise。 */
       subagentRoleReads: new Map(),
@@ -1668,8 +1678,12 @@ export class CodexStreamBridge extends EventEmitter {
       description:
         metadata?.description || previous?.description || subagentFallbackName(agentPath),
       prompt: metadata?.prompt || previous?.prompt || "",
-      // background は spawn 時に確定する属性。後続通知に metadata が無くても true を失わない。
-      background: metadata?.background === true || previous?.background === true,
+      // metadata に明示 boolean があるときは後着値を権威とする。metadata miss は spawn の
+      // background 省略既定と同じ true に倒し、明示 false だけが訂正する。
+      background:
+        typeof metadata?.background === "boolean"
+          ? metadata.background
+          : previous?.background ?? true,
       atMs: transitionAtMs,
       startedAtMs:
         phase === "started" && terminalSubagentPhase(previous?.phase)
@@ -1791,12 +1805,35 @@ export class CodexStreamBridge extends EventEmitter {
       if (!args) return
       const agent = typeof args.agent_type === "string" ? args.agent_type.trim() : ""
       const agentExplicit = agent.length > 0
+      // 現行 Codex schema は background を送らず spawn は非同期で返るため、省略・非 boolean は
+      // 背景扱いにする。invalid 値は本文を永続ログへ出さず、型と item id だけを記録する。
+      const hasBackground = Object.prototype.hasOwnProperty.call(args, "background")
+      const background = typeof args.background === "boolean" ? args.background : true
+      if (hasBackground && typeof args.background !== "boolean") {
+        if (!session.subagentInvalidBackgroundWarned.has(item.id)) {
+          session.subagentInvalidBackgroundWarned.add(item.id)
+          while (session.subagentInvalidBackgroundWarned.size > 256) {
+            session.subagentInvalidBackgroundWarned.delete(
+              session.subagentInvalidBackgroundWarned.values().next().value,
+            )
+          }
+          const backgroundType = Array.isArray(args.background)
+            ? "array"
+            : args.background === null
+              ? "null"
+              : typeof args.background
+          this.logger?.warn?.(
+            { item_id: item.id, background_type: backgroundType },
+            "codex subagent spawn background must be boolean; defaulting to background",
+          )
+        }
+      }
       const metadata = {
         agent: agentExplicit ? agent : null,
         agentExplicit,
         description: typeof args.task_name === "string" && args.task_name ? args.task_name : null,
         prompt: typeof args.message === "string" ? args.message : null,
-        background: args.background === true,
+        background,
       }
       session.subagentSpawnMetadata.set(item.id, metadata)
       while (session.subagentSpawnMetadata.size > 256) {
@@ -1892,32 +1929,52 @@ export class CodexStreamBridge extends EventEmitter {
     }
     const { parentThreadId, ownerTurnId, ...mutableFields } = fields
     Object.assign(record, mutableFields, { lastSeenAtMs: now })
+    delete record.protectionExpiredAtMs
     if (!record.parentThreadId && typeof parentThreadId === "string" && parentThreadId) {
       record.parentThreadId = parentThreadId
     }
     if (!record.ownerTurnId && typeof ownerTurnId === "string" && ownerTurnId) {
       record.ownerTurnId = ownerTurnId
     }
-    const expiredBefore = now - 4 * 60 * 60 * 1000
+    this._sweepSubagentInterruptRegistry(session, now)
+    return record
+  }
+
+  /** delta hot path。対象 record だけを更新し、全台帳 sweep/sort は行わない。 */
+  _heartbeatSubagentInterruptRecord(session, threadId, now = Date.now()) {
+    const record = session?.subagentInterruptRegistry?.get(threadId)
+    if (!record) return null
+    record.lastSeenAtMs = now
+    delete record.protectionExpiredAtMs
+    return record
+  }
+
+  /** lifecycle 更新時だけ、完了済みまたは保護失効済みの古い停止 record と上限超過を回収する。 */
+  _sweepSubagentInterruptRegistry(session, now = Date.now()) {
+    const registry = session?.subagentInterruptRegistry
+    if (!registry) return
+    const expiredBefore = now - SUBAGENT_INTERRUPT_RECORD_TTL_MS
     for (const [id, candidate] of session.subagentInterruptRegistry) {
-      if (candidate.turnId === null && candidate.lastSeenAtMs < expiredBefore) {
+      const evictable = candidate.turnId === null || candidate.protectionExpiredAtMs !== undefined
+      if (evictable && candidate.lastSeenAtMs < expiredBefore) {
         this._evictSubagentInterruptRecord(session, id, candidate)
       }
     }
-    while (session.subagentInterruptRegistry.size > 256) {
-      const oldest = [...session.subagentInterruptRegistry.entries()]
-        .filter(([, candidate]) => candidate.turnId === null)
+    while (registry.size > 256) {
+      const oldest = [...registry.entries()]
+        .filter(([, candidate]) => (
+          candidate.turnId === null || candidate.protectionExpiredAtMs !== undefined
+        ))
         .sort((a, b) => a[1].lastSeenAtMs - b[1].lastSeenAtMs)[0]
       if (!oldest) {
         this.logger?.warn?.(
-          { size: session.subagentInterruptRegistry.size, limit: 256 },
+          { size: registry.size, limit: 256 },
           "codex subagent interrupt registry exceeds limit with all records active",
         )
         break
       }
       this._evictSubagentInterruptRecord(session, oldest[0], oldest[1])
     }
-    return record
   }
 
   _evictSubagentInterruptRecord(session, threadId, record) {
@@ -1927,25 +1984,50 @@ export class CodexStreamBridge extends EventEmitter {
     session.subagentInterruptRegistry.delete(threadId)
   }
 
+  /**
+   * 子 record から root までの所有チェーンを辿る。cycle は呼び出し側が停止対象から除外する。
+   * @returns {{ownerRootTurnId:string|null, hasBackgroundAncestor:boolean, lineage:string[], cycle:boolean}}
+   */
   _subagentOwnership(session, record) {
     const visited = new Set()
+    const lineage = []
     let current = record
     let hasBackgroundAncestor = false
     while (current) {
-      if (visited.has(current.threadId)) return { ownerRootTurnId: null, hasBackgroundAncestor }
+      if (visited.has(current.threadId)) {
+        return { ownerRootTurnId: null, hasBackgroundAncestor, lineage, cycle: true }
+      }
       visited.add(current.threadId)
+      lineage.push(current.threadId)
+      // background は表示台帳の省略既定を含む。親チェーン上の背景 root を一度検出したら、
+      // capability 対応 browser の root interrupt では部分木全体を残す。
       if (session.subagents.get(current.threadId)?.background === true) {
         hasBackgroundAncestor = true
       }
       if (current.parentThreadId === session.threadId) {
-        return { ownerRootTurnId: current.ownerTurnId || null, hasBackgroundAncestor }
+        return {
+          ownerRootTurnId: current.ownerTurnId || null,
+          hasBackgroundAncestor,
+          lineage,
+          cycle: false,
+        }
       }
       current = session.subagentInterruptRegistry.get(current.parentThreadId)
     }
-    return { ownerRootTurnId: null, hasBackgroundAncestor }
+    return { ownerRootTurnId: null, hasBackgroundAncestor, lineage, cycle: false }
   }
 
-  async _interruptSubagent(session, record, targetRootTurnId) {
+  async _interruptSubagent(
+    session,
+    record,
+    targetRootTurnId,
+    {
+      allowBackground = false,
+      requireRootOwnership = true,
+      expectedDelegationId = null,
+      expectedAncestorThreadId = null,
+    } = {},
+  ) {
     const displayed = session.subagents.get(record.threadId)
     const backgroundKnown = displayed ? typeof displayed.background === "boolean" : false
     const background = backgroundKnown ? displayed.background : null
@@ -1957,11 +2039,21 @@ export class CodexStreamBridge extends EventEmitter {
       const mismatch = parseTurnMismatch(reason)
       const latestRecord = session.subagentInterruptRegistry.get(record.threadId)
       const latestOwnership = latestRecord ? this._subagentOwnership(session, latestRecord) : null
+      const latestDisplayed = session.subagents.get(record.threadId)
+      const lineageStillMatches = !expectedAncestorThreadId || (
+        latestOwnership &&
+        !latestOwnership.cycle &&
+        latestOwnership.lineage.includes(expectedAncestorThreadId)
+      )
       if (
         mismatch &&
         latestRecord?.turnId === mismatch.found &&
-        latestOwnership?.ownerRootTurnId === targetRootTurnId &&
-        !latestOwnership.hasBackgroundAncestor
+        (!expectedDelegationId || latestDisplayed?.delegationId === expectedDelegationId) &&
+        lineageStillMatches &&
+        (!requireRootOwnership || (
+          latestOwnership?.ownerRootTurnId === targetRootTurnId &&
+          (allowBackground || !latestOwnership.hasBackgroundAncestor)
+        ))
       ) {
         try {
           await session.client.request("turn/interrupt", {
@@ -1986,6 +2078,15 @@ export class CodexStreamBridge extends EventEmitter {
           }
         }
       }
+      if (mismatch && latestRecord?.turnId === mismatch.found && !lineageStillMatches) {
+        this.logger?.warn?.(
+          {
+            thread_id: record.threadId,
+            expected_ancestor_thread_id: expectedAncestorThreadId,
+          },
+          "codex subagent interrupt retry skipped after ownership changed",
+        )
+      }
       return {
         threadId: record.threadId,
         turnId: record.turnId,
@@ -1997,6 +2098,111 @@ export class CodexStreamBridge extends EventEmitter {
     }
   }
 
+  /**
+   * 対象子と active descendants を停止する。対象 RPC 待ちや子停止中に増えた descendant も
+   * 最大3ラウンド再走査する。上限後の未処理 active turn は skipped へ明示し、無限 spawn に
+   * WebSocket 応答を占有されないようにする。
+   * @returns {Promise<object>} targetOutcome/targetReason は対象自身、outcome は部分木全体の結果。
+   */
+  async interruptSubagent({ stream_id, delegation_id, agent_thread_id }) {
+    const session = this._require(stream_id)
+    this._touch(session, stream_id)
+    const displayed = session.subagents.get(agent_thread_id)
+    if (!displayed || displayed.delegationId !== delegation_id) {
+      return { outcome: "failed", reason: "subagent_not_found", children: [], skipped: [] }
+    }
+    const record = session.subagentInterruptRegistry.get(agent_thread_id)
+    const result = record?.turnId
+      ? await this._interruptSubagent(session, { ...record }, null, {
+          allowBackground: true,
+          requireRootOwnership: false,
+          expectedDelegationId: delegation_id,
+        })
+      : { outcome: "no_active_turn", reason: "subagent_not_active" }
+    const children = []
+    const processedTurns = new Set()
+    const warnedCycleThreads = new Set()
+    const turnKey = (candidate) => `${candidate.threadId}\u0000${candidate.turnId}`
+    const activeDescendants = () => [...session.subagentInterruptRegistry.values()]
+      .filter((candidate) => {
+        if (!candidate?.turnId || candidate.threadId === agent_thread_id) return false
+        const ownership = this._subagentOwnership(session, candidate)
+        if (ownership.cycle) {
+          if (!warnedCycleThreads.has(candidate.threadId)) {
+            warnedCycleThreads.add(candidate.threadId)
+            this.logger?.warn?.(
+              { thread_id: candidate.threadId },
+              "codex subagent descendant skipped because ownership chain is cyclic",
+            )
+          }
+          return false
+        }
+        return ownership.lineage.includes(agent_thread_id)
+      })
+
+    for (let round = 0; round < SUBAGENT_INTERRUPT_SCAN_ROUNDS; round += 1) {
+      const descendants = activeDescendants()
+        .filter((candidate) => !processedTurns.has(turnKey(candidate)))
+        .map((candidate) => ({ ...candidate }))
+      if (descendants.length === 0) break
+      for (const descendant of descendants) {
+        const key = turnKey(descendant)
+        // 同じ round の先行 RPC 待ち中にも lineage/turn は動き得るため、送信直前にも live 台帳で確認する。
+        const current = session.subagentInterruptRegistry.get(descendant.threadId)
+        const ownership = current ? this._subagentOwnership(session, current) : null
+        if (
+          !current?.turnId ||
+          current.turnId !== descendant.turnId ||
+          ownership?.cycle ||
+          !ownership?.lineage.includes(agent_thread_id)
+        ) {
+          this.logger?.warn?.(
+            { thread_id: descendant.threadId, round: round + 1 },
+            "codex subagent descendant skipped after ownership changed before interrupt",
+          )
+          continue
+        }
+        processedTurns.add(key)
+        const childResult = await this._interruptSubagent(session, { ...current }, null, {
+          allowBackground: true,
+          requireRootOwnership: false,
+          expectedAncestorThreadId: agent_thread_id,
+        })
+        children.push(childResult)
+        if (childResult?.threadId && childResult?.turnId) {
+          processedTurns.add(turnKey(childResult))
+        }
+      }
+    }
+    const targetOutcome = result.outcome
+    const descendantInterrupted = children.some((child) => child.outcome === "interrupted")
+    const outcome =
+      targetOutcome === "no_active_turn" && descendantInterrupted
+        ? "interrupted"
+        : targetOutcome
+    const response = {
+      ...result,
+      outcome,
+      targetOutcome,
+      delegationId: displayed.delegationId,
+      agentThreadId: displayed.agentThreadId,
+      children,
+      skipped: activeDescendants()
+        .filter((candidate) => !processedTurns.has(turnKey(candidate)))
+        .map((candidate) => ({
+          threadId: candidate.threadId,
+          turnId: candidate.turnId,
+          reason: "spawned_during_interrupt",
+        })),
+    }
+    // 部分木として成功した応答に failure 用 reason を残さない。対象単体の理由は別軸で保持する。
+    if (outcome === "interrupted" && result.reason) {
+      delete response.reason
+      response.targetReason = result.reason
+    }
+    return response
+  }
+
   _subagentSnapshots(session, history = session?.historyItems) {
     const items = Array.isArray(history) ? history : []
     const startedIndexByThread = new Map()
@@ -2077,21 +2283,47 @@ export class CodexStreamBridge extends EventEmitter {
               { agentPath: record.agentPath, metadata, atMs: lastTurnAtMs },
               { emit: false },
             )
-          } else if (
-            thread?.status?.type === "active" &&
-            (!lastTurn || lastTurn.status === "inProgress")
-          ) {
-            this._setSubagentPhase(
-              session,
-              record.agentThreadId,
-              "started",
-              {
-                agentPath: record.agentPath,
-                metadata,
-                atMs: record.startedAtMs,
-              },
-              { emit: false },
-            )
+          } else if (thread?.status?.type === "active") {
+            if (
+              lastTurn?.status === "inProgress" &&
+              typeof lastTurn.id === "string" &&
+              lastTurn.id
+            ) {
+              this._setSubagentPhase(
+                session,
+                record.agentThreadId,
+                "started",
+                {
+                  agentPath: record.agentPath,
+                  metadata,
+                  atMs: record.startedAtMs,
+                },
+                { emit: false },
+              )
+              this._touchSubagentInterruptRecord(session, record.agentThreadId, {
+                turnId: lastTurn.id,
+                startedAtMs: lastTurnAtMs,
+              })
+            } else {
+              // active 表示なのに停止 RPC に必要な turn ID が無い。running と表示すると停止可能な
+              // capability を偽るため、cold snapshot は正直な terminal へ倒す。
+              this._setSubagentPhase(
+                session,
+                record.agentThreadId,
+                "failed",
+                { agentPath: record.agentPath, metadata, atMs: lastTurnAtMs },
+                { emit: false },
+              )
+              this.logger?.warn?.(
+                {
+                  thread_id: session.threadId,
+                  subagent_thread_id: record.agentThreadId,
+                  child_status: thread?.status?.type || null,
+                  last_turn_status: lastTurn?.status || null,
+                },
+                "codex active subagent resume lacked an interruptible turn id; marked failed",
+              )
+            }
           } else {
             session.subagents.delete(record.agentThreadId)
           }
@@ -2168,6 +2400,14 @@ export class CodexStreamBridge extends EventEmitter {
     // ※ hub-agent 再起動 (cold resume) では historyItems が揮発するため青バブルへ戻る (claude の
     //    jsonl at-rest と同じ許容範囲。source 永続マップは TTL/ID 再利用の複雑さに見合わないため不採用)。
     const eventThreadId = msg?.params?.threadId
+    if (
+      typeof eventThreadId === "string" &&
+      eventThreadId !== session.threadId &&
+      session.subagentInterruptRegistry.has(eventThreadId)
+    ) {
+      // lifecycle 以外の message/reasoning/tool delta も子 turn の生存証跡。root 通知は更新しない。
+      this._heartbeatSubagentInterruptRecord(session, eventThreadId)
+    }
     const taggedParams = this._tagInjectSourceOnItem(session, msg)
     let effectiveParams = taggedParams || msg.params
     const childRecord =
@@ -2350,6 +2590,7 @@ export class CodexStreamBridge extends EventEmitter {
 
   _onClientExit(session, info) {
     if (session.dead) return
+    this._markRunningSubagentsKilled(session)
     session.dead = true
     // round3: app-server が死んだら barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
@@ -2614,15 +2855,17 @@ export class CodexStreamBridge extends EventEmitter {
 
   /**
    * @returns {Promise<
-   *   | { outcome: "interrupted", turnId: string, corrected: boolean }
-   *   | { outcome: "no_active_turn" }
-   *   | { outcome: "failed", reason: string }
+   *   ({children: object[], skipped: object[]} & (
+   *     | { outcome: "interrupted", turnId: string, corrected: boolean }
+   *     | { outcome: "no_active_turn" }
+   *     | { outcome: "failed", reason: string }
+   *   ))
    * >}
    */
-  async interrupt({ stream_id }) {
+  async interrupt({ stream_id, preserve_background_subagents = false }) {
     const session = this._require(stream_id)
     this._touch(session, stream_id)
-    if (!session.activeTurnId) return { outcome: "no_active_turn", children: [] }
+    if (!session.activeTurnId) return { outcome: "no_active_turn", children: [], skipped: [] }
 
     const turnId = session.activeTurnId
     let attemptedRootTurnId = turnId
@@ -2665,13 +2908,35 @@ export class CodexStreamBridge extends EventEmitter {
     const children = []
     const targetRootTurnId = attemptedRootTurnId
     const interruptSnapshot = [...session.subagentInterruptRegistry.values()].map((record) => ({ ...record }))
+    // skipped は「今回の owner turn の停止候補」ではなく、応答時点で実際に継続中の
+    // root 直下 background 一覧。frontend の「継続中」表示と一致させるため owner に依存しない。
+    const skipped = preserve_background_subagents === true
+      ? interruptSnapshot.flatMap((record) => {
+          const displayed = session.subagents.get(record.threadId)
+          if (
+            !record.turnId ||
+            record.parentThreadId !== session.threadId ||
+            displayed?.background !== true
+          ) return []
+          return [{
+            threadId: record.threadId,
+            delegationId: displayed.delegationId,
+            reason: "background",
+          }]
+        })
+      : []
     for (const record of interruptSnapshot) {
       if (!record.turnId) continue
       const ownership = this._subagentOwnership(session, record)
-      if (ownership.ownerRootTurnId !== targetRootTurnId || ownership.hasBackgroundAncestor) continue
-      children.push(await this._interruptSubagent(session, { ...record }, targetRootTurnId))
+      if (preserve_background_subagents === true && ownership.hasBackgroundAncestor) {
+        continue
+      }
+      if (ownership.ownerRootTurnId !== targetRootTurnId) continue
+      children.push(await this._interruptSubagent(session, { ...record }, targetRootTurnId, {
+        allowBackground: preserve_background_subagents !== true,
+      }))
     }
-    return { ...result, children }
+    return { ...result, children, skipped }
   }
 
   /** サーバー発の承認/入力要求への応答。result の shape は method ごとに呼び出し側が組み立てる。 */
@@ -3298,13 +3563,57 @@ export class CodexStreamBridge extends EventEmitter {
     // ⚠️ activeTurnId の判定より **前** に置くこと。背景コマンドが残るのは turn/completed の
     //    後（= activeTurnId が null に戻った後）なので、下の early return を通すと届かない。
     if (this._hasLiveExec(session, now)) return true
+    if (this._hasLiveSubagentTurn(session, now)) return true
     if (!session.activeTurnId) return false
     return now - (session.lastActivityMs ?? now) <= this._stuckTurnTtlMs
   }
 
+  _hasLiveSubagentTurn(session, now = Date.now()) {
+    const registry = session?.subagentInterruptRegistry
+    if (!registry || registry.size === 0) return false
+    let active = false
+    for (const record of registry.values()) {
+      if (!record?.turnId) continue
+      const elapsed = now - (record.lastSeenAtMs ?? 0)
+      if (elapsed <= this._stuckTurnTtlMs) {
+        active = true
+        continue
+      }
+      // TTL は warm-session 保護だけを失効させる。停止 RPC に必要な turnId は破壊しない。
+      // 長時間無出力の正常な子でも、明示停止を受けたときに同じ handle を利用できるようにする。
+      if (record.protectionExpiredAtMs === undefined) {
+        record.protectionExpiredAtMs = now
+        this.logger?.warn?.(
+          {
+            stream_id: session.stream_id,
+            thread_id: record.threadId,
+            turn_id: record.turnId,
+            elapsed_ms: elapsed,
+            ttl_ms: this._stuckTurnTtlMs,
+          },
+          "codex subagent turn protection expired",
+        )
+      }
+    }
+    return active
+  }
+
+  _markRunningSubagentsKilled(session, atMs = Date.now()) {
+    for (const record of session?.subagents?.values?.() || []) {
+      if (record.phase !== "started") continue
+      this._setSubagentPhase(
+        session,
+        record.agentThreadId,
+        "killed",
+        { agentPath: record.agentPath, atMs },
+      )
+    }
+  }
+
   /** 実際に app-server を止めてセッションを撤去し exit を emit する（reconcile 共通処理）。 */
   _reapSession(session, now, reason) {
     if (session.dead) return
+    this._markRunningSubagentsKilled(session, now)
     session.dead = true
     // round3: reap した session の barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
@@ -3492,6 +3801,7 @@ export class CodexStreamBridge extends EventEmitter {
   shutdown() {
     // 案B: distinct session で走査（多対一 Map の重複 stop を避ける）。
     for (const session of this._liveSessions()) {
+      this._markRunningSubagentsKilled(session)
       session.dead = true
       // round3: shutdown で barrier を解除し queue 入力を reject（promise 宙吊り防止）。
       this._settleTurnActiveWaiter(session)

package/src/main.mjs

@@ -978,6 +978,9 @@ export async function startDaemon({ version, claudeSdk } = {}) {
     claudeBridge.on("exit", ({ stream_id, code, reason, session_id }) => {
       client.send({ type: "claude.exit", stream_id, code, reason, session_id })
     })
+    claudeBridge.on("sessionoptions", (message) => {
+      client.send(buildClaudeSessionOptionsPayload(message))
+    })
     claudeBridge.on("turnsettled", ({ cwd }) => {
       // RC-4: result を届けずにターンが終わった (abort/異常終了)。チャット信号の
       // status=processing を waiting に落として三点リーダー/ステータスドットの固着を防ぐ
@@ -2052,6 +2055,58 @@ export function buildCodexChatPatch(status, contextPct, threadId, isAuthority) {
   return patch
 }
 
+/** 次ターンに使う desired options。現在ターンの setter 成功を観測した値ではない。 */
+function desiredOptionsWire(snapshot) {
+  // stream_missing はcurrent不明。null(default)と偽装せずoptions fields自体を省く。
+  if (!snapshot) return {}
+  return {
+    model: snapshot?.model ?? null,
+    permission_mode: snapshot?.permission_mode ?? null,
+    options_instance_id: snapshot?.options_instance_id,
+    options_revision: snapshot?.options_revision,
+  }
+}
+
+/** claude.ready の wire payload。bridge attach info の options snapshot を透過する。 */
+export function buildClaudeReadyPayload(streamId, info) {
+  return {
+    type: "claude.ready",
+    stream_id: streamId,
+    resuming: info?.resuming === true,
+    ...desiredOptionsWire(info),
+    turn_active: info?.turn_active === true,
+    history_pushed: info?.resuming === true,
+    supports_queue_input_id: true,
+    supports_queue_snapshot: true,
+    supports_session_options_cas: true,
+  }
+}
+
+/** bridge internal options event → session fanout wire。 */
+export function buildClaudeSessionOptionsPayload(message) {
+  return {
+    type: "claude.session.options",
+    stream_id: message.stream_id,
+    session_id: message.session_id ?? null,
+    ...desiredOptionsWire(message),
+  }
+}
+
+/** options CAS result は要求元 stream だけへ返す。 */
+export function buildClaudeSessionOptionsResultPayload(
+  streamId,
+  requestId,
+  result,
+) {
+  return {
+    type: "claude.session.options.result",
+    stream_id: streamId,
+    request_id: requestId,
+    outcome: result.outcome,
+    ...desiredOptionsWire(result.current),
+  }
+}
+
 /** codex.ready の wire payload を組み立てる。history は同じ配列参照を保持し、
  * started_history_index が指す位置を main 側の加工でずらさない。表示を保持する reconnect
  * (`info.subagents` 未定義) では subagents キー自体を省略し、空 snapshot で既存表示を消さない。 */
@@ -2068,6 +2123,9 @@ export function buildCodexReadyPayload(streamId, info, queueState) {
     thread_status: info?.threadStatus || null,
     last_turn_status: info?.lastTurnStatus || null,
     queue_state: queueState,
+    // Browser は旧 hub-agent との混在期間、この明示 capability が true のときだけ
+    // 子 thread の個別停止 UI を有効化する。省略は未対応を意味する。
+    supports_subagent_interrupt: true,
   }
   if (Array.isArray(info?.subagents)) {
     payload.subagents = info.subagents.map((subagent) => ({
@@ -3194,26 +3252,69 @@ export function handleCodexChatInput(msg, ctx) {
   return p
 }
 
+/**
+ * codex.interrupt を root / individual へ振り分ける。
+ * - delegation_id と agent_thread_id が非空文字列なら individual（request_id 必須・echo する）
+ * - 両 ID が欠落または null なら root（現 frontend 契約。request_id は相関に使わず常に null）
+ * - 片方だけ、または非 null の不正値が混ざれば individual ID validation error
+ */
 export async function handleCodexInterrupt(msg, ctx) {
   let result
-  if (!ctx.codexBridge) {
-    result = { outcome: "failed", reason: "bridge_unavailable", children: [] }
+  const hasDelegationId = typeof msg.delegation_id === "string" && msg.delegation_id.length > 0
+  const hasAgentThreadId = typeof msg.agent_thread_id === "string" && msg.agent_thread_id.length > 0
+  const hasEitherId = msg.delegation_id != null || msg.agent_thread_id != null
+  const isSubagentInterrupt = hasDelegationId && hasAgentThreadId
+  const hasRequestId = typeof msg.request_id === "string" && msg.request_id.length > 0
+  if (hasEitherId && !(hasDelegationId && hasAgentThreadId)) {
+    result = { outcome: "failed", reason: "invalid_subagent_interrupt_ids", children: [], skipped: [] }
+  } else if (isSubagentInterrupt && !hasRequestId) {
+    result = { outcome: "failed", reason: "invalid_subagent_interrupt_request_id", children: [], skipped: [] }
+  } else if (!ctx.codexBridge) {
+    result = { outcome: "failed", reason: "bridge_unavailable", children: [], skipped: [] }
   } else {
     try {
-      result = await ctx.codexBridge.interrupt({ stream_id: msg.stream_id })
-      if (result.outcome === "failed") {
+      const bridgeResult = hasDelegationId
+        ? await ctx.codexBridge.interruptSubagent({
+            stream_id: msg.stream_id,
+            delegation_id: msg.delegation_id,
+            agent_thread_id: msg.agent_thread_id,
+          })
+        : await ctx.codexBridge.interrupt({
+            stream_id: msg.stream_id,
+            preserve_background_subagents: msg.preserve_background_subagents === true,
+          })
+      const validOutcome = ["interrupted", "failed", "no_active_turn"].includes(
+        bridgeResult?.outcome,
+      )
+      if (!bridgeResult || typeof bridgeResult !== "object" || Array.isArray(bridgeResult) || !validOutcome) {
+        ctx.logger?.warn?.(
+          {
+            bridge_result_type: Array.isArray(bridgeResult) ? "array" : typeof bridgeResult,
+            bridge_outcome: typeof bridgeResult?.outcome === "string" ? bridgeResult.outcome : null,
+          },
+          "codex.interrupt bridge returned an invalid result",
+        )
+        result = { outcome: "failed", reason: "invalid_bridge_result", children: [], skipped: [] }
+      } else {
+        result = {
+          ...bridgeResult,
+          children: Array.isArray(bridgeResult.children) ? bridgeResult.children : [],
+          skipped: Array.isArray(bridgeResult.skipped) ? bridgeResult.skipped : [],
+        }
+      }
+      if (result.outcome === "failed" && result.reason !== "invalid_bridge_result") {
         ctx.logger?.warn?.({ err: result.reason }, "codex.interrupt failed")
       }
     } catch (err) {
       const reason = err?.message || String(err)
       ctx.logger?.warn?.({ err: reason }, "codex.interrupt failed")
-      result = { outcome: "failed", reason, children: [] }
+      result = { outcome: "failed", reason, children: [], skipped: [] }
     }
   }
   ctx.client.send({
     type: "codex.interrupt.response",
     stream_id: msg.stream_id,
-    request_id: msg.request_id ?? null,
+    request_id: isSubagentInterrupt && hasRequestId ? msg.request_id : null,
     ...result,
   })
 }
@@ -3768,27 +3869,7 @@ async function dispatch(msg, ctx) {
             effort: msg.effort || ctx.config?.claude_effort || null,
             resumeSessionId,
           })
-          ctx.client.send({
-            type: "claude.ready",
-            stream_id,
-            resuming: info.resuming,
-            // 再接続時の生成状態は resident session を保持する hub-agent が正本。
-            // jsonl 履歴末尾の推測だけでは「実際は busy なのに UI は idle」となり、
-            // 送信ボタンが楽観バブルを作る一方 agent はキューへ積む二重表示が起きる。
-            turn_active: info.turn_active === true,
-            history_pushed: resumeSessionId !== null,
-            // id 空間統一 (2026-07-08): この agent は browser の input_id をキュー id として
-            // 採用し、楽観送信待ちアイテムの確認前キャンセルに対応することを通知する capability。
-            // 旧 agent にはこのフラグが無く、browser は楽観アイテムの×を出さない (ゴースト
-            // 実行防止のフォールバック)。
-            supports_queue_input_id: true,
-            // pull 型再同期 capability (T06603, 2026-07-25): この agent は
-            // claude.queue.request に claude.queue.response で答え、queue_state に
-            // 版番号 (seq) と受理済み input_id (accepted) を載せることを通知する。
-            // 旧 agent はこのフラグが無く、browser は従来の「配信到達に依存する」
-            // 挙動へフォールバックする (混在期間も安全に段階デプロイできる)。
-            supports_queue_snapshot: true,
-          })
+          ctx.client.send(buildClaudeReadyPayload(stream_id, info))
           if (resumeSessionId) {
             void ctx.siblingInjectBridge
               ?.replayDelegations(cwdArg || process.env.HOME || process.cwd(), resumeSessionId)
@@ -3874,6 +3955,23 @@ async function dispatch(msg, ctx) {
         }
         return
       }
+      case "claude.session.options.set": {
+        const result = ctx.claudeBridge?.setSessionOptions({
+          stream_id: msg.stream_id,
+          session_id: msg.session_id ?? null,
+          base_options_instance_id: msg.base_options_instance_id,
+          base_options_revision: msg.base_options_revision,
+          patch: msg.patch,
+        }) || { outcome: "stream_missing", current: null }
+        ctx.client.send(
+          buildClaudeSessionOptionsResultPayload(
+            msg.stream_id,
+            msg.request_id,
+            result,
+          ),
+        )
+        return
+      }
       case "claude.input":
         // message: { role: 'user', content: string | Array } を期待
         handleClaudeChatInput(msg, ctx)

package/src/ws-client.mjs

@@ -56,6 +56,9 @@ const MIN_BACKOFF_AFTER_5XX_MS = 5_000
 //     「送信待ち(未配信)」が消えない (S1/S3)。再接続 flush で遅れて届けば即解消する。
 //   - claude/codex の event / ready / exit / error / permission:
 //     喪失すると新規セッションの楽観バブルが本物へ昇格できず、再 attach も固着する。
+//   - claude.session.options.result: options.set は再要求型RPCではなく明示intentの終端。
+//     agent→Hub切断中のapplied resultも保持し、request_idで同streamへ戻す。frontend側の
+//     stale-stream/request mismatch/10s timeoutが遅延結果を無害化する（LWW圧縮はしない）。
 //   - claude.jsonl.event / session.event: TUI と一覧の確定状態を復元する。
 // 高頻度の delta 系はここに積まず (下の isEphemeral*DeltaEvent で除外)、低頻度な
 // ack/event がリング evict されるのを防ぐ (ack/event は 1 件ずつ意味を持つ)。
@@ -63,6 +66,8 @@ const BUFFERED_CTRL_TYPES = new Set([
   "claude.jsonl.event",
   "claude.event",
   "claude.ready",
+  "claude.session.options",
+  "claude.session.options.result",
   "claude.exit",
   "claude.error",
   "claude.permission.request",