feat(web): hide subagent threads from user-facing thread lists

shivamhwp · shivamhwp · commit 05fe44ce61d2 · 2026-07-28T21:01:06.000+05:30
A subagent's child thread is an implementation detail of the agent that
owns it, not a conversation the user started. Listing them alongside real
threads makes the sidebar grow with every delegation.

Filtered at the source — the shell snapshot the server serves — so every
client sees the same set rather than each re-deriving it. The web client
filters again for locally-held state, and the thread route redirects to
the parent if a subagent thread is reached directly.

Mobile is part of the sweep, not left behind. It still offered "Open
subagent thread" and had no redirect to fall back on, so it would have
navigated to a thread the client no longer receives. Its relationships
banner also needed the same subagent-edge filter web has: those edges are
derived from the projection rather than from thread shells, so they
survive the shell filtering and would have rendered as "Unavailable" —
and, sorting first, could have taken over the banner headline.

Trade-off worth stating plainly: a subagent's transcript becomes
unreachable. The Agents panel added in the previous PR shows what an
agent did and what it returned, but not its full conversation. That is
the intended shape here, and the "Open subagent thread" affordances are
removed on both clients rather than left as dead ends.
diff --git a/apps/mobile/src/features/threads/ThreadRelationshipsBanner.tsx b/apps/mobile/src/features/threads/ThreadRelationshipsBanner.tsx
@@ -83,7 +83,13 @@ export function ThreadRelationshipsBanner(props: {
   const rows = useMemo(
     () =>
       copySorted(
-        immediateThreadRelationships(graph, props.threadId),
+        // Subagent edges come from the projection, not from thread shells, so
+        // they survive the shell filtering and would point at threads the
+        // client no longer receives — rendering as "Unavailable", and taking
+        // over the banner headline when they sort first.
+        immediateThreadRelationships(graph, props.threadId).filter(
+          (relationship) => relationship.edge.kind !== "subagent",
+        ),
         (left, right) =>
           Number(right.threadId === mergeTargetThreadId) -
           Number(left.threadId === mergeTargetThreadId),
diff --git a/apps/mobile/src/features/threads/thread-work-log.tsx b/apps/mobile/src/features/threads/thread-work-log.tsx
@@ -125,9 +125,6 @@ function ThreadActivityThreadLink(props: {
   if (item.type === "thread_created") {
     targetThreadId = item.targetThreadId;
     label = "Open created thread";
-  } else if (item.type === "subagent") {
-    targetThreadId = support.subagent?.childThreadId ?? item.childThreadId;
-    label = "Open subagent thread";
   } else if (item.type === "fork") {
     targetThreadId =
       item.targetThreadId === row.sourceThreadId && item.source.type === "run"
diff --git a/apps/server/src/orchestration-v2/ThreadManagementService.test.ts b/apps/server/src/orchestration-v2/ThreadManagementService.test.ts
@@ -3,13 +3,18 @@ import {
   CommandId,
   NodeId,
   type OrchestrationV2Command,
+  type OrchestrationV2ThreadShell,
   ProjectId,
   ProviderInstanceId,
   RunId,
   ThreadId,
 } from "@t3tools/contracts";
 
-import { existingThreadIdsForCommand, withCreationProvenance } from "./ThreadManagementService.ts";
+import {
+  existingThreadIdsForCommand,
+  userFacingShellSnapshot,
+  withCreationProvenance,
+} from "./ThreadManagementService.ts";
 
 it("stamps authoritative provenance on commands that create threads or messages", () => {
   const command: OrchestrationV2Command = {
@@ -161,3 +166,59 @@ it("identifies every existing thread that must be hydrated before dispatch", ()
     }),
   ).toEqual([parentThreadId, targetThreadId]);
 });
+
+it("removes internal subagent children from active and archived shell collections", () => {
+  const rootId = ThreadId.make("thread:thread-management:root");
+  const forkId = ThreadId.make("thread:thread-management:fork");
+  const lineageSubagentId = ThreadId.make("thread:thread-management:lineage-subagent");
+  const nodeSubagentId = ThreadId.make("thread:thread-management:node-subagent");
+  const shell = (
+    id: ThreadId,
+    lineage: OrchestrationV2ThreadShell["lineage"],
+    forkedFrom: OrchestrationV2ThreadShell["forkedFrom"],
+  ) =>
+    ({
+      id,
+      lineage,
+      forkedFrom,
+    }) as OrchestrationV2ThreadShell;
+  const rootLineage = {
+    rootThreadId: rootId,
+    parentThreadId: null,
+    relationshipToParent: null,
+  } as const;
+  const snapshot = userFacingShellSnapshot({
+    schemaVersion: 3,
+    snapshotSequence: 10,
+    threads: [
+      shell(rootId, rootLineage, null),
+      shell(
+        forkId,
+        {
+          rootThreadId: rootId,
+          parentThreadId: rootId,
+          relationshipToParent: "fork",
+        },
+        { type: "run", threadId: rootId, runId: RunId.make("run:thread-management:fork") },
+      ),
+      shell(
+        lineageSubagentId,
+        {
+          rootThreadId: rootId,
+          parentThreadId: rootId,
+          relationshipToParent: "subagent",
+        },
+        null,
+      ),
+    ],
+    archivedThreads: [
+      shell(nodeSubagentId, rootLineage, {
+        type: "node",
+        nodeId: NodeId.make("node:thread-management:subagent"),
+      }),
+    ],
+  });
+
+  expect(snapshot.threads.map((thread) => thread.id)).toEqual([rootId, forkId]);
+  expect(snapshot.archivedThreads).toEqual([]);
+});
diff --git a/apps/server/src/orchestration-v2/ThreadManagementService.ts b/apps/server/src/orchestration-v2/ThreadManagementService.ts
@@ -204,6 +204,16 @@ export class ThreadManagementService extends Context.Service<
   ThreadManagementServiceShape
 >()("t3/orchestration-v2/ThreadManagementService") {}
 
+export const isInternalSubagentThread = (
+  thread: Pick<OrchestrationV2ThreadShell, "forkedFrom" | "lineage">,
+) => thread.lineage.relationshipToParent === "subagent" || thread.forkedFrom?.type === "node";
+
+export const userFacingShellSnapshot = (snapshot: OrchestrationV2ThreadShellSnapshot) => ({
+  ...snapshot,
+  threads: snapshot.threads.filter((thread) => !isInternalSubagentThread(thread)),
+  archivedThreads: snapshot.archivedThreads.filter((thread) => !isInternalSubagentThread(thread)),
+});
+
 export function isActiveRun(run: OrchestrationV2Run): boolean {
   return (
     run.status === "preparing" ||
@@ -359,10 +369,7 @@ const make = Effect.gen(function* () {
       Effect.map((snapshot) =>
         snapshot.threads
           .filter((thread) => thread.projectId === input.projectId)
-          .filter(
-            (thread) =>
-              input.includeSubagents || thread.lineage.relationshipToParent !== "subagent",
-          )
+          .filter((thread) => input.includeSubagents || !isInternalSubagentThread(thread))
           .toSorted(
             (left, right) =>
               DateTime.toEpochMillis(right.updatedAt) - DateTime.toEpochMillis(left.updatedAt) ||
diff --git a/apps/server/src/orchestration-v2/http.ts b/apps/server/src/orchestration-v2/http.ts
@@ -66,7 +66,9 @@ export const orchestrationHttpApiLayer = HttpApiBuilder.group(
       const base = yield* sql.withTransaction(
         Effect.gen(function* () {
           const projects = yield* projectionSnapshotQuery.getShellSnapshotWithoutEnrichment();
-          const threads = yield* threadManagement.getShellSnapshot();
+          const threads = yield* threadManagement
+            .getShellSnapshot()
+            .pipe(Effect.map(ThreadManagementService.userFacingShellSnapshot));
           return {
             schemaVersion: threads.schemaVersion,
             snapshotSequence: yield* applicationEvents.latestApplicationSequence,
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
@@ -219,7 +219,7 @@ export const resolveAutoBootstrapWelcomeTargets = Effect.gen(function* () {
     const shell = yield* threads.getShellSnapshot();
     const existingThread = shell.threads.find(
       (thread) =>
-        thread.projectId === project.id && thread.lineage.relationshipToParent !== "subagent",
+        thread.projectId === project.id && !ThreadManagement.isInternalSubagentThread(thread),
     );
     if (existingThread === undefined) {
       const launched = yield* threadLaunch.launch({
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
@@ -770,7 +770,9 @@ const makeWsRpcLayer = (
             const base = yield* sql.withTransaction(
               Effect.gen(function* () {
                 const projects = yield* projectionSnapshotQuery.getShellSnapshotWithoutEnrichment();
-                const threads = yield* threadManagement.getShellSnapshot();
+                const threads = yield* threadManagement
+                  .getShellSnapshot()
+                  .pipe(Effect.map(ThreadManagementService.userFacingShellSnapshot));
                 return {
                   schemaVersion: threads.schemaVersion,
                   snapshotSequence: yield* applicationEvents.latestApplicationSequence,
@@ -819,7 +821,12 @@ const makeWsRpcLayer = (
             const survivors = coalesceShellApplicationEvents(events);
             const needsThreadSnapshot = survivors.some((stored) => !("aggregateKind" in stored));
             const threadSnapshot = needsThreadSnapshot
-              ? yield* threadManagement.getShellSnapshot().pipe(Effect.map(Option.some))
+              ? yield* threadManagement
+                  .getShellSnapshot()
+                  .pipe(
+                    Effect.map(ThreadManagementService.userFacingShellSnapshot),
+                    Effect.map(Option.some),
+                  )
               : Option.none();
             return yield* Effect.forEach(
               survivors,
@@ -955,7 +962,9 @@ const makeWsRpcLayer = (
         .withTransaction(
           Effect.gen(function* () {
             const projects = yield* projectionSnapshotQuery.getShellSnapshotWithoutEnrichment();
-            const threads = yield* threadManagement.getShellSnapshot();
+            const threads = yield* threadManagement
+              .getShellSnapshot()
+              .pipe(Effect.map(ThreadManagementService.userFacingShellSnapshot));
             return {
               schemaVersion: threads.schemaVersion,
               snapshotSequence: yield* applicationEvents.latestApplicationSequence,
@@ -988,6 +997,7 @@ const makeWsRpcLayer = (
           .pipe(
             Stream.mapEffect((stored) =>
               threadManagement.getShellSnapshot().pipe(
+                Effect.map(ThreadManagementService.userFacingShellSnapshot),
                 Effect.map((nextSnapshot) =>
                   archivedShellStreamItemFromSnapshot({ stored, snapshot: nextSnapshot }),
                 ),
diff --git a/apps/web/src/components/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
@@ -33,7 +33,14 @@ import {
   sortProjectsForSidebar,
   THREAD_JUMP_HINT_SHOW_DELAY_MS,
 } from "./Sidebar.logic";
-import { EnvironmentId, ProjectId, ProviderInstanceId, RunId, ThreadId } from "@t3tools/contracts";
+import {
+  EnvironmentId,
+  NodeId,
+  ProjectId,
+  ProviderInstanceId,
+  RunId,
+  ThreadId,
+} from "@t3tools/contracts";
 import {
   DEFAULT_INTERACTION_MODE,
   DEFAULT_RUNTIME_MODE,
@@ -260,6 +267,13 @@ describe("sidebar thread lineage helpers", () => {
     });
 
     expect(isSidebarSubagentThread(subagent)).toBe(true);
+    expect(
+      isSidebarSubagentThread(
+        makeThreadFixture({
+          forkedFrom: { type: "node", nodeId: NodeId.make("node-provider-subagent") },
+        }),
+      ),
+    ).toBe(true);
     expect(isSidebarSubagentThread(makeThreadFixture())).toBe(false);
   });
 
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
@@ -1,6 +1,9 @@
 import * as React from "react";
 import type { ContextMenuItem } from "@t3tools/contracts";
 import type { SidebarProjectSortOrder, SidebarThreadSortOrder } from "@t3tools/contracts/settings";
+import { isInternalSubagentThread as isSidebarSubagentThread } from "../threadVisibility";
+
+export { isSidebarSubagentThread };
 import {
   getThreadSortTimestamp,
   sortThreads,
@@ -92,12 +95,8 @@ export function buildMultiSelectThreadContextMenuItems(input: {
   ];
 }
 
-export function isSidebarSubagentThread(thread: Pick<SidebarThreadSummary, "lineage">): boolean {
-  return thread.lineage.relationshipToParent === "subagent";
-}
-
 export function filterSidebarV2VisibleThreads<
-  T extends Pick<SidebarThreadSummary, "archivedAt" | "lineage"> & {
+  T extends Pick<SidebarThreadSummary, "archivedAt" | "forkedFrom" | "lineage"> & {
     environmentId: string;
     projectId: string;
   },
@@ -832,7 +831,7 @@ export function sortLogicalProjectsForSidebar<
 
 export function sortSidebarV2ProjectGroups<
   TProject extends LogicalSidebarProject,
-  TThread extends ScopedSidebarThread & Pick<SidebarThreadSummary, "lineage">,
+  TThread extends ScopedSidebarThread & Pick<SidebarThreadSummary, "forkedFrom" | "lineage">,
 >(
   projects: readonly TProject[],
   threads: readonly TThread[],
diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
@@ -109,6 +109,7 @@ import {
   filterSidebarV2VisibleThreads,
   firstValidTimestampMs,
   hasUnseenCompletion,
+  isSidebarSubagentThread,
   isTrailingDoubleClick,
   orderItemsByPreferredIds,
   resolveAdjacentThreadId,
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -852,7 +852,7 @@ describe("MessagesTimeline", () => {
     );
 
     expect(markup).toContain('data-v2-item-type="subagent"');
-    expect(markup).toContain('aria-label="Open Package audit"');
+    expect(markup).not.toContain('aria-label="Open Package audit"');
     expect(markup).toContain("Reading src/index.ts");
     expect(markup).not.toContain("Inspect the package");
     expect(markup).not.toContain('data-v2-subagent-result-disclosure="true"');
@@ -908,7 +908,7 @@ describe("MessagesTimeline", () => {
     expect(markup).toContain('data-v2-subagent-result-disclosure="true"');
     expect(markup).toContain('data-v2-subagent-result="true"');
     expect(markup).toContain('aria-label="Show full result for Isolation report"');
-    expect(markup).toContain('aria-label="Open Isolation report"');
+    expect(markup).not.toContain('aria-label="Open Isolation report"');
     expect(markup).toContain("Tests should be isolated.");
     expect(markup).toContain("Result: no shared state.");
     expect(markup).not.toContain("Explain test isolation");
@@ -961,7 +961,7 @@ describe("MessagesTimeline", () => {
     );
 
     expect(markup).toContain('data-v2-item-type="subagent"');
-    expect(markup).toContain('aria-label="Open Package audit"');
+    expect(markup).not.toContain('aria-label="Open Package audit"');
     expect(markup).toContain("Reading src/index.ts");
     expect(markup).not.toContain("Partial streamed answer so far");
     expect(markup).not.toContain('data-v2-subagent-result-disclosure="true"');
diff --git a/apps/web/src/components/chat/ThreadRelationshipsControl.tsx b/apps/web/src/components/chat/ThreadRelationshipsControl.tsx
@@ -104,21 +104,23 @@ export function ThreadRelationshipsPanel(props: {
   const [busyAction, setBusyAction] = useState<"merge" | "detach" | null>(null);
   const latestCompletedRun = projection?.runs.findLast((run) => run.status === "completed") ?? null;
   const mergeTargetThreadId = resolveMergeBackTargetThreadId(projection);
-  const relationshipRows = immediateThreadRelationships(graph, props.threadId).toSorted(
-    (left, right) =>
-      relationshipSortKey({
-        edge: left.edge,
-        threadId: left.threadId,
-        currentThreadId: props.threadId,
-        mergeTargetThreadId,
-      }) -
-      relationshipSortKey({
-        edge: right.edge,
-        threadId: right.threadId,
-        currentThreadId: props.threadId,
-        mergeTargetThreadId,
-      }),
-  );
+  const relationshipRows = immediateThreadRelationships(graph, props.threadId)
+    .filter((relationship) => relationship.edge.kind !== "subagent")
+    .toSorted(
+      (left, right) =>
+        relationshipSortKey({
+          edge: left.edge,
+          threadId: left.threadId,
+          currentThreadId: props.threadId,
+          mergeTargetThreadId,
+        }) -
+        relationshipSortKey({
+          edge: right.edge,
+          threadId: right.threadId,
+          currentThreadId: props.threadId,
+          mergeTargetThreadId,
+        }),
+    );
   const canMerge = mergeTargetThreadId !== null && latestCompletedRun !== null;
   const canDetach = projection ? canDetachThreadProviderSession(projection) : false;
 
diff --git a/apps/web/src/components/chat/V2ItemInspector.tsx b/apps/web/src/components/chat/V2ItemInspector.tsx
@@ -259,12 +259,6 @@ export const V2ItemInspector = memo(function V2ItemInspector(props: V2ItemInspec
         </Button>
       ) : null}
 
-      {item.type === "subagent" && item.childThreadId !== null ? (
-        <Button size="xs" variant="outline" onClick={() => props.onOpenThread(item.childThreadId!)}>
-          Open subagent thread
-        </Button>
-      ) : null}
-
       {item.type === "handoff" ? (
         <div className="space-y-1 rounded-md border border-border/45 p-2 text-muted-foreground">
           <p>
diff --git a/apps/web/src/components/chat/V2LifecycleRow.tsx b/apps/web/src/components/chat/V2LifecycleRow.tsx
@@ -144,7 +144,7 @@ export function V2LifecycleRow(props: {
         title={subagentDisplayTitle(item.title ?? "Subagent")}
         detail={detail}
         badge={item.status}
-        threadId={item.childThreadId}
+        threadId={null}
         expandedDetail={finalResult}
         onOpenThread={props.onOpenThread}
       />
diff --git a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
diff --git a/apps/web/src/state/entities.ts b/apps/web/src/state/entities.ts
diff --git a/apps/web/src/threadVisibility.test.ts b/apps/web/src/threadVisibility.test.ts
diff --git a/apps/web/src/threadVisibility.ts b/apps/web/src/threadVisibility.ts
