@op1/threads 0.1.2 → 0.1.4

package/README.md

@@ -35,11 +35,15 @@ threads_spawn({
 })
 ```
 
-The worker opens in a native tab without taking focus. Select that tab to read its conversation. Use `threads_list` to inspect reports and `/threads` to reopen closed worker tabs. Native `subagent` remains available for bounded tasks and role-specific reviews.
+The worker opens in a native tab without taking focus. Select that tab to read its conversation. Use `threads_list` to inspect reports and `/threads` to reopen closed worker tabs.
+
+Both the parent and managed workers can use native `subagent` for bounded tasks and role-specific reviews. The parent can mix direct subagent calls with managed threads. Each worker can work directly or delegate within its brief and inherited permissions, then review the results and submit its own combined report.
+
+The parent writes the `task` brief. The plugin appends an explicit reminder that native delegation is optional and that workers cannot call `threads_spawn`. Include the worker's delegation budget in the brief. Use `No children` only when the task requires it, since that also rules out native subagents.
 
 ## Tools
 
-The native tool names use namespace `threads` and individual names `spawn`, `list`, `send`, `interrupt`, and `report`.
+The native tool names use namespace `threads` and individual names `spawn`, `list`, `send`, `interrupt`, `hide`, and `report`.
 
 | Tool | Input | Result |
 | --- | --- | --- |
@@ -47,13 +51,14 @@ The native tool names use namespace `threads` and individual names `spawn`, `lis
 | `threads_list` | `{}` | `{ workers: WorkerView[] }` |
 | `threads_send` | `{ workerID, key, text }` | `{ workerID, messageID }` |
 | `threads_interrupt` | `{ workerID }` | Worker view |
+| `threads_hide` | `{ workerID }` | Worker view |
 | `threads_report` | `{ verdict, summary, evidence }` | `{ workerID, report }` |
 
 All fields are strings except `evidence`, which is an array of strings. Verdicts are `PASS`, `PASS WITH NOTES`, `FAIL`, and `INCONCLUSIVE`. Each tool returns JSON in native `content` and the same value in `output`.
 
 `directory` must exist and be absolute. Spawn uses native `subagent` permission gating. The worker uses the coordinator's agent and model, with resolved agent permissions followed by session permissions. Its actual tool actions still pass through native permission checks. There is no separate directory-approval flow or agent/model override.
 
-Tool identity comes from the calling session. Only the owning coordinator can send or interrupt. Only the exact original top-level worker can report. Native subagents and managed workers cannot spawn managed workers. Native `subagent` remains available.
+Tool identity comes from the calling session. Only the owning coordinator can send, interrupt, or hide a worker. Only the exact original top-level worker can report. Native subagents and managed workers cannot spawn managed workers. Native `subagent` remains available.
 
 ## Identity and retries
 
@@ -65,28 +70,36 @@ Send keys are scoped to the worker and determine a stable message ID. A retry wi
 
 ## Worker views and limits
 
-`WorkerView` contains `workerID`, `coordinatorID`, `key`, `title`, `directory`, `outcome`, and `report`. `outcome` is the native last execution outcome, or `null` before one exists. It is not current activity. Native tabs display current busy, attention, and unread state.
+`WorkerView` contains `workerID`, `coordinatorID`, `key`, `title`, `directory`, `outcome`, `report`, and `hidden`. `outcome` is the native last execution outcome, or `null` before one exists. It is not current activity. Native tabs display current busy, attention, and unread state.
 
 `report` is the explicit worker claim, or `null`. Native `succeeded` means the agent loop completed, not that the assigned task passed.
 
+`hidden` is the desired idle-tab visibility. Current activity, input requests, or selection can keep that tab open.
+
 Plugin option `maxWorkers` defaults to 4 and accepts integers from 1 through 32. Admission is serialized by coordinator within the loaded server process. A worker without a report continues to occupy a slot unless its native outcome is `failed` or `interrupted`. A successful run without a report does not silently free its slot.
 
 ## Terminal and RPC
 
 The terminal synchronizes workers before opening native tabs without changing focus. A TUI memory index survives plugin reloads and respects manually closed tabs. `/threads` explicitly reopens workers for open coordinator tabs. A new TUI recovers workers from durable storage. Closing the TUI does not interrupt workers.
 
+Workers with `PASS` or `PASS WITH NOTES` reports hide automatically once idle. This also applies to reports saved before upgrading. Unreported workers and `FAIL` or `INCONCLUSIVE` reports stay visible. The selected tab, running workers, and tabs needing input stay open until they are inactive.
+
+The coordinator can call `threads_hide` when a worker is no longer needed. Hiding preserves the conversation and report, survives restarts, and does not free an admission slot. `/threads` restores hidden workers and keeps them visible for inspection. A valid `threads_send` follow-up also restores its worker. Visibility overrides belong to the original report message ID, so recreating a deleted worker cannot inherit its hidden state.
+
+Reports reach the coordinator through silent synthetic messages. They remain available through `threads_list` and the session history without adding a notification row to the conversation. Older report notification rows remain in native history.
+
 All open native root-session tabs are automatically grouped by OpenCode project ID, including sessions not managed by this plugin. Projects follow their first appearance in the current tab order. Worktrees with the same project ID stay together.
 
-Within each project, running sessions, the selected tab, and sessions waiting for input come before idle sessions. Tabs with the same priority keep their relative order. Finished runs remain visible below active work and rise again when resumed or selected. Idle is a display priority, not a completion verdict. Each tab with unloaded project metadata stays in its own group until that metadata becomes available. Reconciliation moves only out-of-order tabs, without changing focus or closing and reopening them. Native tabs do not support divider rows.
+Within each project, running sessions, the selected tab, and sessions waiting for input come before idle sessions. Tabs with the same priority keep their relative order. Idle is a display priority, not a completion verdict. Each tab with unloaded project metadata stays in its own group until that metadata becomes available. Reconciliation moves only out-of-order tabs, without changing focus or closing and reopening them to reorder. Native tabs do not support divider rows.
 
-The read-only RPC definition is `ThreadsRpc` in `src/rpc.ts`, with ID `threads` and method `snapshot`:
+The RPC definition is `ThreadsRpc` in `src/rpc.ts`, with ID `threads`. `snapshot` is read-only. The user-invoked `restore` method clears hidden state for the supplied coordinators' workers. Both methods accept and return:
 
 ```ts
 input: { coordinatorIDs: string[] }
 result: { workers: WorkerView[] }
 ```
 
-The input accepts at most 100 coordinator IDs. Raw HTTP RPC requests wrap the input as `{ "input": { "coordinatorIDs": ["ses_..."] } }`. The method declares `errors: {}` and the RPC declares `events: {}`. The TUI subscribes to native session events and reconciles at most one snapshot at a time, with a three-second missed-event refresh.
+The input accepts at most 100 coordinator IDs. Raw HTTP RPC requests wrap the input as `{ "input": { "coordinatorIDs": ["ses_..."] } }`. Each method declares `errors: {}` and the RPC declares `events: {}`. The TUI subscribes to native session events and reconciles at most one snapshot at a time, with a three-second missed-event refresh.
 
 ## Verification and limits
 

package/index.ts

@@ -2,7 +2,7 @@ import { Plugin } from "@opencode/plugin";
 import type { SessionContext } from "@opencode/plugin/promise/session";
 import { z } from "zod";
 import { Report, ThreadsRpc, WorkerView } from "./src/rpc";
-import { Interrupt, Send, Spawn, threads } from "./src/threads";
+import { Send, Spawn, WorkerTarget, threads } from "./src/threads";
 
 export default Plugin.define({
   id: "op-threads",
@@ -26,6 +26,9 @@ export default Plugin.define({
       snapshot: async ({ coordinatorIDs }) => ({
         workers: (await Promise.all(coordinatorIDs.map(workers.list))).flat(),
       }),
+      restore: async ({ coordinatorIDs }) => ({
+        workers: (await Promise.all(coordinatorIDs.map(workers.restore))).flat(),
+      }),
     });
     await ctx.tool.transform((editor) => {
       editor.namespace({
@@ -35,7 +38,7 @@ export default Plugin.define({
       editor.add({
         name: "spawn",
         description:
-          "Delegate a task to a top-level worker in an existing absolute directory. Reuse key only for identical requests. No managed grandchildren.",
+          "Delegate a task to a top-level worker in an existing absolute directory. Both you and the worker may use native subagent when useful. Include any delegation limits in task. Workers cannot call threads_spawn. Reuse key only for identical requests.",
         input: Spawn,
         output: WorkerView,
         options: {
@@ -81,7 +84,7 @@ export default Plugin.define({
       editor.add({
         name: "interrupt",
         description: "Interrupt your worker without claiming task success.",
-        input: Interrupt,
+        input: WorkerTarget,
         output: WorkerView,
         options: { namespace: "threads", codemode: false },
         execute: async (input, tool) => {
@@ -89,6 +92,17 @@ export default Plugin.define({
           return { content: JSON.stringify(output), output };
         },
       });
+      editor.add({
+        name: "hide",
+        description: "Hide a worker you no longer need from the sidebar without deleting its conversation or report. Only its coordinator may hide it. Running, selected, or attention-needed tabs stay open until idle. Use /threads to restore hidden tabs.",
+        input: WorkerTarget,
+        output: WorkerView,
+        options: { namespace: "threads", codemode: false },
+        execute: async (input, tool) => {
+          const output = await workers.hide(tool.sessionID, input);
+          return { content: JSON.stringify(output), output };
+        },
+      });
       editor.add({
         name: "report",
         description:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@op1/threads",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Visible top-level worker sessions for OpenCode V2, with native tabs and durable reports.",
   "type": "module",
   "main": "./index.ts",

package/skills/managed-sessions/SKILL.md

@@ -5,36 +5,45 @@ description: Spawn and monitor visible top-level OpenCode workers with op-thread
 
 # Managed sessions
 
-Choose the delegation mode before launching work.
+Choose the delegation mode for each task. The parent can mix both modes in the same run.
 
 - Use native `subagent` for a bounded task or review.
 - Use `threads_spawn` for an independent workstream with its own visible session and assigned directory.
 
-Count both modes against the active protocol's delegation budget. Managed workers can use native subagents, but cannot create further managed workers. Keep every writer in its own assigned worktree. These tools do not create worktrees.
+Both the parent and managed workers may use native `subagent` when useful. Delegation is optional. Managed workers cannot create further managed workers. Count both modes and workers' native subagents against the active protocol's delegation budget. Keep every writer in its own assigned worktree. These tools do not create worktrees.
 
 ## Start work
 
 1. Confirm the `threads_spawn` tool is available. If it is unavailable, use native `subagent` or report that the plugin needs activation. Do not substitute a hidden `opencode run` process.
 2. Assign an existing absolute directory and a stable task key.
-3. Call `threads_spawn` with `key`, `title`, `directory`, and `task`. Include the goal, scope, relevant context, constraints, acceptance criteria, verification commands, and expected report in `task`.
+3. Call `threads_spawn` with `key`, `title`, `directory`, and `task`. Include the goal, scope, relevant context, constraints, delegation allowance, acceptance criteria, verification commands, and expected report in `task`.
 4. Save the returned worker session ID with the work unit.
 
 An identical spawn key retries the original admission. Different work requires a new key. A worker inherits the coordinator's agent, model, and permission constraints. It has a separate conversation, so include all context it needs in the task brief.
 
+## Write the delegation allowance
+
+The parent writes `task`; the plugin appends worker instructions. Give workers the option to delegate without requiring a sub-coordinator role. Include this allowance and the worker's share of the remaining delegation budget:
+
+> You may work directly or use native `subagent` for bounded tasks and reviews when useful. Pass your scope and constraints to subagents, review their results, and resolve outstanding work before calling `threads_report` yourself.
+
+Use a no-delegation restriction only for a task-specific reason or an explicit user constraint, and state the reason. Being a managed worker or having bounded scope does not by itself make the worker a leaf. To limit managed-thread nesting, say `Do not call threads_spawn` rather than `No children`.
+
 ## Coordinate
 
 - Use `threads_list` for a progress snapshot when making a scheduling or delivery decision.
 - Use `threads_send` with a stable message key for a correction or follow-up within the worker's assigned task.
 - Use `threads_interrupt` to stop that worker's execution.
+- Use `threads_hide` with `workerID` when a worker is no longer needed in the sidebar. This preserves its report and conversation. Hiding does not interrupt work or free an admission slot.
 - Do not repeatedly query status while waiting. Workers report to the coordinator through OpenCode's durable inbox.
 - After a service restart, inspect existing worker IDs before deciding whether to resume them. Do not launch replacement tasks solely because a session is idle.
 
 ## Finish
 
-The worker calls `threads_report` with a verdict, concise summary, and concrete evidence, then stops. Valid verdicts are `PASS`, `PASS WITH NOTES`, `FAIL`, and `INCONCLUSIVE`. Report partial work and blockers honestly.
+The worker reviews its subagents' results and resolves outstanding work before calling `threads_report` with a combined verdict, concise summary, and concrete evidence, then stops. Native subagents return results to the worker. Valid verdicts are `PASS`, `PASS WITH NOTES`, `FAIL`, and `INCONCLUSIVE`. Report partial work and blockers honestly.
 
 A worker report is a claim to review. Run the protocol's independent verification before marking the work unit complete. An idle session or a stopped loading indicator does not establish task success.
 
 ## Visibility
 
-The TUI plugin opens managed workers as ordinary tabs without changing focus. Each tab uses OpenCode's native activity indicators. Use `/threads` to reopen managed worker tabs you closed.
+The TUI plugin opens managed workers as ordinary tabs without changing focus. Workers with `PASS` or `PASS WITH NOTES` reports hide automatically once inactive. Failed, inconclusive, and unreported workers stay visible until the coordinator hides them. Running, selected, and attention-needed tabs stay open. Use `/threads` to restore hidden tabs for inspection. Sending a valid follow-up also restores that worker. Reports are delivered silently to the coordinator and remain available through `threads_list`.

package/src/rpc.ts

@@ -17,6 +17,7 @@ export const WorkerView = z.object({
   directory: z.string(),
   outcome: z.enum(["succeeded", "failed", "interrupted"]).nullable(),
   report: Report.nullable(),
+  hidden: z.boolean(),
 });
 
 export const ThreadsRpc = Rpc.define({
@@ -29,6 +30,11 @@ export const ThreadsRpc = Rpc.define({
       output: z.object({ workers: z.array(WorkerView) }),
       errors: {},
     },
+    restore: {
+      input: z.object({ coordinatorIDs: z.array(z.string()).max(100) }).strict(),
+      output: z.object({ workers: z.array(WorkerView) }),
+      errors: {},
+    },
   },
   events: {},
 });

package/src/threads.ts

@@ -42,7 +42,7 @@ export const Send = z
     text: z.string().min(1),
   })
   .strict();
-export const Interrupt = z.object({ workerID: sessionID }).strict();
+export const WorkerTarget = z.object({ workerID: sessionID }).strict();
 
 const digest = (parts: string[]) =>
   createHash("sha256").update(JSON.stringify(parts)).digest("hex");
@@ -94,12 +94,16 @@ export function threads(
     `workers/${link.coordinatorID}/${link.workerID}`;
   const reportKey = (link: z.infer<typeof Link>) =>
     `reports/${link.workerID}/${link.reportMessageID}`;
+  const visibilityKey = (link: z.infer<typeof Link>) =>
+    `visibility/${link.workerID}/${link.reportMessageID}`;
 
   async function view(
     session: NativeSession,
   ): Promise<z.infer<typeof WorkerView>> {
     const link = workerLink(session);
     const stored = await ctx.storage.get(reportKey(link));
+    const report = stored === undefined ? null : Report.parse(stored);
+    const visibility = await ctx.storage.get(visibilityKey(link));
     return {
       workerID: link.workerID,
       coordinatorID: link.coordinatorID,
@@ -107,7 +111,11 @@ export function threads(
       title: session.title ?? link.key,
       directory: session.location.directory,
       outcome: session.outcome ?? null,
-      report: stored === undefined ? null : Report.parse(stored),
+      report,
+      hidden:
+        visibility === undefined
+          ? report?.verdict === "PASS" || report?.verdict === "PASS WITH NOTES"
+          : z.boolean().parse(visibility),
     };
   }
 
@@ -132,6 +140,7 @@ export function threads(
           if (!missing.success || missing.data.sessionID !== link.workerID)
             throw error;
           await ctx.storage.remove(reportKey(link));
+          await ctx.storage.remove(visibilityKey(link));
           await ctx.storage.remove(entry.key);
           continue;
         }
@@ -152,6 +161,22 @@ export function threads(
 
   return {
     list,
+    async hide(actor: string, input: z.infer<typeof WorkerTarget>) {
+      const { session, link } = await owned(actor, input.workerID);
+      await ctx.storage.set(visibilityKey(link), true);
+      return view(session);
+    },
+    async restore(coordinatorID: string) {
+      const workers = await list(coordinatorID);
+      return Promise.all(
+        workers.map(async (worker) => {
+          if (!worker.hidden) return worker;
+          const { session, link } = await owned(coordinatorID, worker.workerID);
+          await ctx.storage.set(visibilityKey(link), false);
+          return view(session);
+        }),
+      );
+    },
     async spawn(
       actor: string,
       input: z.infer<typeof Spawn>,
@@ -224,13 +249,13 @@ export function threads(
           sessionID: link.workerID,
           id: link.initialMessageID,
           delivery: "queue",
-          text: `${input.task}\n\nYou are a managed worker assigned to ${input.directory}. Work only within the assigned scope. Do not call threads_spawn. When finished call threads_report with verdict, summary, and evidence. Runtime completion alone does not establish task success.`,
+          text: `${input.task}\n\nYou are a managed worker assigned to ${input.directory}. Work only within the assigned scope. You may use native subagent for bounded tasks or reviews when useful, within the brief's delegation limits and inherited permissions. Delegation is optional. Pass relevant context, scope, and constraints to each subagent. Do not call threads_spawn. Review your subagents' results and resolve any outstanding work before reporting. Only you call threads_report with the combined verdict, summary, and evidence; subagents return results to you. Runtime completion alone does not establish task success.`,
         });
         return view(await ctx.session.get({ sessionID: workerID }));
       });
     },
     async send(actor: string, input: z.infer<typeof Send>) {
-      await owned(actor, input.workerID);
+      const { link } = await owned(actor, input.workerID);
       const id = SessionMessage.ID.make(
         `msg_${digest([input.workerID, "send", input.key]).slice(0, 32)}`,
       );
@@ -243,9 +268,14 @@ export function threads(
       });
       if (admitted.payload.text !== input.text)
         throw new Error("This send key already belongs to different text");
+      if ((await ctx.storage.get(reportKey(link))) !== undefined) {
+        await ctx.storage.set(visibilityKey(link), false);
+      } else {
+        await ctx.storage.remove(visibilityKey(link));
+      }
       return { workerID: input.workerID, messageID: admitted.id };
     },
-    async interrupt(actor: string, input: z.infer<typeof Interrupt>) {
+    async interrupt(actor: string, input: z.infer<typeof WorkerTarget>) {
       await owned(actor, input.workerID);
       await ctx.session.interrupt({
         sessionID: input.workerID,
@@ -261,7 +291,6 @@ export function threads(
         id: link.reportMessageID,
         text: `Managed worker ${link.workerID} (${link.key}) report:\n${JSON.stringify(input)}`,
         metadata: { opThreadsReport: input, workerID: link.workerID },
-        description: `Worker report: ${link.key}`,
         delivery: "queue",
         resume: true,
       });

package/tui.ts

@@ -60,12 +60,30 @@ export default Plugin.define({
           ]),
         ].slice(0, 100);
         if (!coordinatorIDs.length) return;
-        const { workers } = await rpc.snapshot(
+        const { workers } = await (reopen ? rpc.restore : rpc.snapshot)(
           { coordinatorIDs },
           { location: ctx.location ?? ctx.data.location.default() },
         );
         for (const worker of workers) {
           if (stopped) return;
+          const tab = ctx.ui.tabs.list().find((tab) => tab.sessionID === worker.workerID);
+          if (
+            worker.hidden &&
+            !tab?.active &&
+            !tab?.busy &&
+            !tab?.attention &&
+            ctx.data.session.status(worker.workerID) !== "running"
+          ) {
+            if (tab && !ctx.ui.tabs.close(worker.workerID)) continue;
+            if (seen.workerIDs.includes(worker.workerID)) {
+              updateSeen((draft) => {
+                draft.workerIDs = draft.workerIDs.filter(
+                  (id) => id !== worker.workerID,
+                );
+              });
+            }
+            continue;
+          }
           if (!reopen && seen.workerIDs.includes(worker.workerID)) continue;
           await ctx.data.session.sync(worker.workerID);
           if (