feat: pop a finished delegated child thread out to top level

apps/mobile/src/features/threads/ThreadHeader.tsx

@@ -21,6 +21,8 @@ export function ThreadHeader(props: {
   readonly hasThreadCwd: boolean;
   readonly inspectorMode: ThreadInspectorMode | null;
   readonly onOpenFilesInspector: () => void;
+  /** Present only on a delegated child the user may pop out. */
+  readonly onPopOut?: () => void;
 }) {
   const goBack = useWorkspaceBackNavigation();
   const { toggleAuxiliaryPane, startNewTask } = useAdaptiveWorkspaceLayout();
@@ -40,6 +42,16 @@ export function ThreadHeader(props: {
         },
       ]
     : [];
+  if (props.onPopOut) {
+    actions.push({
+      accessibilityLabel: "Pop out to top level",
+      icon: "arrow.up.right.circle",
+      subtitle: "Make it an ordinary thread",
+      overflowOnly: true,
+      separateBackground: false,
+      onPress: props.onPopOut,
+    });
+  }
   const menus = [gitMenu, terminalMenu].filter((menu): menu is AppBarMenu => menu !== null);
 
   return (

apps/mobile/src/features/threads/ThreadRouteScreen.tsx

@@ -90,7 +90,10 @@ import { useSelectedThreadGitState } from "../../state/use-selected-thread-git-s
 import { useSelectedThreadRequests } from "../../state/use-selected-thread-requests";
 import { useSelectedThreadWorktree } from "../../state/use-selected-thread-worktree";
 import { useThreadComposerState } from "../../state/use-thread-composer-state";
-import { resolveMergeBackTargetThreadId } from "@t3tools/client-runtime/state/thread-relationships";
+import {
+  resolveMergeBackTargetThreadId,
+  threadPopOutAvailability,
+} from "@t3tools/client-runtime/state/thread-relationships";
 import { resolveLatestMergeBackRun } from "@t3tools/client-runtime/state/thread-workflows";
 import { threadEnvironment } from "../../state/threads";
 import { EMPTY_ENVIRONMENT_THREAD_STATE } from "@t3tools/client-runtime/state/threads";
@@ -447,6 +450,44 @@ function ThreadRouteContent(
   const navigation = useNavigation();
   const selectDetail = useSelectWorkspaceDetail();
   const openPullRequest = useOpenPullRequest();
+  const popOut = useAtomCommand(threadEnvironment.popOut, { reportFailure: false });
+  const popOutBusyRef = useRef(false);
+  const popOutAvailability =
+    selectedThread && canOperateThread
+      ? threadPopOutAvailability(selectedThread.source)
+      : "unsupported";
+  const handlePopOut = () => {
+    if (!selectedThread || popOutBusyRef.current) return;
+    if (popOutAvailability === "blocked") {
+      Dialog.alert("Can't pop out yet", "Wait for it to finish or stop it first.");
+      return;
+    }
+    const environmentId = selectedThread.environmentId;
+    const threadId = selectedThread.id;
+    Dialog.confirm({
+      title: "Pop out to top level?",
+      message:
+        "It becomes an ordinary thread in your list and stops reporting to the thread that started it.",
+      confirmText: "Pop out",
+      onConfirm: () => {
+        if (popOutBusyRef.current) return;
+        popOutBusyRef.current = true;
+        void popOut({ environmentId, input: { threadId } })
+          .then((result) => {
+            if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+              const error = squashAtomCommandFailure(result);
+              Dialog.alert(
+                "Could not pop out thread",
+                error instanceof Error ? error.message : "Try again.",
+              );
+            }
+          })
+          .finally(() => {
+            popOutBusyRef.current = false;
+          });
+      },
+    });
+  };
   const mergeBack = useAtomCommand(threadEnvironment.mergeBack, "merge thread back");
   const mergeBackTargetThreadId = resolveMergeBackTargetThreadId(selectedThreadDetail);
   const mergeBackRun =
@@ -983,6 +1024,7 @@ function ThreadRouteContent(
                 inspectorMode={inspectorMode}
                 onOpenFilesInspector={handleOpenFilesInspector}
                 onReturnToThread={props.onReturnToThread}
+                onPopOut={popOutAvailability === "unsupported" ? undefined : handlePopOut}
               />
             )
           }

apps/server/src/mcp/OrchestratorMcpService.ts

@@ -2751,6 +2751,22 @@ const make = Effect.gen(function* () {
         }
         return yield* remoteDelegation.cancel(scope, remoteTask, input);
       }
+      // Pop-out needs every task in the child to have ended, and it leaves this thread's control.
+      const childShell = yield* threadManagement
+        .getThreadShell(childThreadId)
+        .pipe(Effect.mapError(threadManagementFailure));
+      if (childShell?.lineage.detachedFrom?.threadId === scope.thread.threadId) {
+        if (!isTerminalTaskStatus(current.status)) {
+          return yield* failure(
+            "invalid_request",
+            `Thread ${childThreadId} was popped out to top level and no longer belongs to this task.`,
+          );
+        }
+        return {
+          taskId: input.taskId,
+          status: current.status,
+        } satisfies OrchestratorMcpTaskCancelResult;
+      }
       const key = yield* requestKey(input.clientRequestId);
       const parentProjection = yield* loadThreadRecords(scope.thread.threadId, []);
       // Cancelling stops the child and every task under it, each a write to a

apps/server/src/mcp/toolkits/core.test.ts

@@ -605,6 +605,60 @@ it.effect("rejects an unknown organize target instead of archiving the calling t
   );
 });
 
+it.effect("allows an agent to pop out only its own child", () => {
+  const dispatched: Array<unknown> = [];
+  return Effect.gen(function* () {
+    const server = yield* McpServer.McpServer;
+    const otherThreadId = ThreadId.make("mcp-core-child");
+    for (const target of [undefined, threadId, otherThreadId, ThreadId.make("unrelated")]) {
+      const result = yield* server
+        .callTool({
+          name: "t3_thread_organize",
+          arguments: { action: "pop_out", ...(target === undefined ? {} : { threadId: target }) },
+        })
+        .pipe(
+          Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
+          Effect.provideService(McpSchema.McpServerClient, client),
+        );
+      if (target === otherThreadId) expect(result.isError).not.toBe(true);
+      else
+        expect(declaredFailure(result)).toMatchObject({
+          code: "invalid_request",
+          message: expect.stringContaining("cannot pop itself out"),
+        });
+    }
+    expect(dispatched).toMatchObject([{ type: "thread.detach", threadId: otherThreadId }]);
+  }).pipe(
+    Effect.provide(
+      layerThreadToolkit.pipe(
+        Layer.provideMerge(McpHttpServer.layerInProcessMcpServer),
+        Layer.provide(NodeCrypto.layer),
+        Layer.provide(
+          Layer.mock(ThreadManagement.ThreadManagementService)({
+            getThreadShell: (id) => Effect.succeed(McpToolAccessTestkit.liveThreadShell(id)),
+            getProjectThreadRecords: ({ threadId: id }) => {
+              const shell = McpToolAccessTestkit.liveThreadShell(id);
+              return Effect.succeed(
+                McpToolAccessTestkit.idleThreadProjection({
+                  ...shell,
+                  lineage: {
+                    ...shell.lineage,
+                    parentThreadId: id === ThreadId.make("mcp-core-child") ? threadId : null,
+                  },
+                }),
+              );
+            },
+            dispatch: (command) => {
+              dispatched.push(command);
+              return Effect.succeed({ sequence: 1 } as never);
+            },
+          }),
+        ),
+      ),
+    ),
+  );
+});
+
 it.effect("keeps unexpected handler defects private through the production registration", () =>
   Effect.gen(function* () {
     const server = yield* McpServer.McpServer;

apps/server/src/mcp/toolkits/thread/handlers.ts

@@ -344,7 +344,7 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, {
   ),
   t3_thread_organize: writesThread((input) =>
     Effect.gen(function* () {
-      const { threads, projection, caller } = yield* readThread(input.threadId);
+      const { threads, projection, caller, scope } = yield* readThread(input.threadId);
       const common = { commandId: yield* newCommandId(), threadId: projection.thread.id };
       if (input.action === "settle") {
         return yield* threads
@@ -369,6 +369,21 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, {
         case "mark_unread":
           command = { ...common, type: "thread.mark-unread" };
           break;
+        case "pop_out":
+          // Otherwise a child could leave its parent's Stop on its own.
+          if (
+            scope.client?.senderThread !== undefined ||
+            (caller !== undefined &&
+              (caller.id === projection.thread.id ||
+                caller.id !== projection.thread.lineage.parentThreadId))
+          ) {
+            return yield* new OrchestratorMcpFailure({
+              code: "invalid_request",
+              message: "A thread cannot pop itself out; its parent or the user can.",
+            });
+          }
+          command = { ...common, type: "thread.detach" };
+          break;
         default:
           command = { ...common, type: `thread.${input.action}` };
       }

apps/server/src/mcp/toolkits/thread/tools.ts

@@ -32,7 +32,7 @@ import * as McpInvocationContext from "../../McpInvocationContext.ts";
 
 const ThreadOrganizeTool = Tool.make("t3_thread_organize", {
   description:
-    "Pin, snooze, settle, archive, or mark a thread unread. Omit `threadId` for this thread. `snooze` needs `snoozedUntil`. Settling this thread applies at turn end. A failed turn or queued message leaves it active.",
+    "Pin, snooze, settle, archive, mark unread, or pop out a finished child. Omit `threadId` for this thread. `snooze` needs `snoozedUntil`. Settling this thread waits for a clean turn end and empty queue.",
   parameters: Schema.Struct({
     environmentId: OrchestratorMcpEnvironmentTarget,
     threadId: Schema.optional(ThreadId),
@@ -46,6 +46,7 @@ const ThreadOrganizeTool = Tool.make("t3_thread_organize", {
       "archive",
       "unarchive",
       "mark_unread",
+      "pop_out",
     ]),
     snoozedUntil: Schema.optional(IsoDateTime),
   }),