@op1/threads 0.1.5 → 0.1.6

package/README.md

@@ -47,7 +47,7 @@ The native tool names use namespace `threads` and individual names `spawn`, `lis
 
 | Tool | Input | Result |
 | --- | --- | --- |
-| `threads_spawn` | `{ key, title, directory, task }` | Worker view |
+| `threads_spawn` | `{ key, title, directory, task, agent? }` | Worker view |
 | `threads_list` | `{}` | `{ workers: WorkerView[] }` |
 | `threads_send` | `{ workerID, key, text }` | `{ workerID, messageID }` |
 | `threads_interrupt` | `{ workerID }` | Worker view |
@@ -56,21 +56,31 @@ The native tool names use namespace `threads` and individual names `spawn`, `lis
 
 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.
+`directory` must exist and be absolute. Without `agent`, the worker inherits the coordinator's active agent and resolved model, with agent permissions followed by session permissions.
+
+Set `agent` to use a configured profile, such as `agent: "vera-core"` for a VERA workstream or `agent: "vera-auditor-readonly"` for an independent review. The plugin resolves the profile in the assigned directory. OpenCode supplies its system prompt and step limit. The profile's model and variant take precedence; a profile without a model inherits the coordinator's resolved model. Explicit selection supports `primary`, `all`, and `subagent` profiles on OpenCode 2.0.3.
+
+Explicit selection requires the caller's ordered agent and session rules to allow `subagent` for that exact agent ID. A matching `deny` or `ask` rejects the request before creation. OpenCode's plugin API cannot request approval for an input-dependent agent ID.
+
+A selected worker uses its profile's permissions. Parent session `deny` and `ask` rules at creation become hard denials on the worker, and parent allows are not copied. This conservative rule also drops parent allow exceptions that follow a denial. It prevents inherited permissions from relaxing a read-only profile. Each managed worker receives one explicit grant for `threads_report`, whose handler verifies ownership. Native subagents retain their own profiles and inherit those session restrictions. Omitting `agent` keeps the existing inheritance behavior.
 
 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
 
-The coordinator ID and spawn key determine the worker ID. Worker metadata contains `opThreads` with exactly `workerID`, `coordinatorID`, `key`, `fingerprint`, `initialMessageID`, and `reportMessageID`. There is no native `parentID`.
+The coordinator ID and spawn key determine the worker ID. Worker metadata contains `opThreads` with exactly `workerID`, `coordinatorID`, `key`, `fingerprint`, `initialMessageID`, and `reportMessageID`. Explicit-role workers also carry `opThreadsRole: true`. There is no native `parentID`.
+
+The first create includes both message IDs. Identical spawn retries reuse the original session and initial message ID, even if the profile configuration has changed. They do not reset its agent or model. Changing the title, directory, task, or explicit agent under that key is an error. Requests that omit `agent` retain their pre-role fingerprint. Startup never replays initial prompts.
 
-The first create includes both message IDs. Subsequent creates adopt the original metadata returned by OpenCode. Identical spawn retries reuse the initial message ID. Changing the title, directory, or task under that key is an error. Startup never replays initial prompts.
+The initial prompt hook resolves a selected profile after OpenCode loads the assigned directory's configuration. It rechecks the caller's role authorization and selects the profile's model before admitting the task. If the profile is unavailable, admission fails without running the task. The indexed worker remains recoverable: fix the profile configuration and retry the identical request. Until initialization completes, managed follow-ups and direct prompts are rejected. Initialization is recorded after native admission; a retry repairs that record if interrupted between the two writes.
 
 Send keys are scoped to the worker and determine a stable message ID. A retry with different text is rejected. Each worker has one task and one terminal report. Identical report retries return the original report; conflicting reports are rejected. Send clarifications within the existing task, and use a new spawn key for new work. The persisted report view is keyed by the original report message ID, so recreating a deleted worker cannot inherit an old verdict.
 
 ## Worker views and limits
 
-`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.
+`WorkerView` contains `workerID`, `coordinatorID`, `key`, `title`, `directory`, `agent`, `model`, `outcome`, `report`, and `hidden`. `agent` and `model` reflect the native session's saved selection, or `null` if unset. A model contains `providerID`, `id`, and an optional `variant`.
+
+`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.
 
@@ -92,7 +102,7 @@ Reports reach the coordinator through silent synthetic messages. They remain ava
 
 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. 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.
+Within each project, running sessions and sessions waiting for input come before idle sessions. Tabs with the same priority keep their relative order. Selecting an idle tab does not reorder it. Native tab order is shared between terminals in the same directory, so sorting by each terminal's selection would make them repeatedly undo each other's moves. 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 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:
 
@@ -109,6 +119,10 @@ Run `bun run typecheck`, `bun test`, and `bun run verify:live`. The live check r
 
 Run `bun run verify:tabs` to verify project grouping across real git worktrees, activity-based ordering, permission prompts, completed and resumed workers, focus preservation, and TUI reopening.
 
+Run `bun run verify:roles` to verify named profiles against the native server and deterministic model endpoint. It checks actual system prompts, model variants, native delegation, read-only execution, reporting, and role-aware retries.
+
+Run `bun run verify:idle-tabs` to open two native terminals on different idle sessions in the same directory and verify that their shared tab order stays stable.
+
 Pass an extracted package directory to test the release artifact: `bun run verify:live /absolute/path/to/package`.
 
 The native session and plugin index are separate writes. A crash after session creation but before indexing requires an explicit identical spawn retry. A crash after native report admission but before saving the report view requires an explicit report retry; the native coordinator notification remains canonical and is not duplicated. There is no custom outbox or startup task replay.

package/index.ts

@@ -15,6 +15,11 @@ export default Plugin.define({
       .default(4)
       .parse(ctx.options.maxWorkers);
     const workers = threads(ctx, limit);
+    await ctx.session.hook("prompt", (event) => {
+      return workers.preparePrompt(
+        event.sessionID, event.messageID, event.metadata?.opThreadsCallerAgent,
+      );
+    });
     const models = new Map<
       SessionContext["sessionID"],
       SessionContext["model"]
@@ -38,7 +43,7 @@ export default Plugin.define({
       editor.add({
         name: "spawn",
         description:
-          "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.",
+          "Delegate a task to a top-level worker in an existing absolute directory. Set agent to a configured profile (for example vera-core); its prompt, model preference, and permissions apply. Omit agent to inherit your active agent and model. Native subagent remains available within the selected profile's permissions and task's delegation limits. Workers cannot call threads_spawn. Reuse key only for identical requests, including agent.",
         input: Spawn,
         output: WorkerView,
         options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@op1/threads",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Visible top-level worker sessions for OpenCode V2, with native tabs and durable reports.",
   "type": "module",
   "main": "./index.ts",
@@ -25,6 +25,8 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "verify:live": "uv run --with pyte python scripts/verify-live.py",
+    "verify:roles": "python3 scripts/verify-roles.py",
+    "verify:idle-tabs": "uv run --with pyte python scripts/verify-idle-tabs.py",
     "verify:tabs": "uv run --with pyte python scripts/verify-tab-groups.py"
   },
   "dependencies": {

package/skills/managed-sessions/SKILL.md

@@ -16,10 +16,15 @@ Both the parent and managed workers may use native `subagent` when useful. Deleg
 
 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, delegation allowance, acceptance criteria, verification commands, and expected report in `task`.
-4. Save the returned worker session ID with the work unit.
+3. If the tool schema supports `agent`, select a configured profile explicitly. Use `agent: "vera-core"` for a VERA workstream that owns integration and may delegate. Use a specialist profile for a leaf task or read-only review. Omitting `agent` inherits the caller's active agent and model. Older plugin versions always inherit them.
+4. Call `threads_spawn` with `key`, `title`, `directory`, `task`, and the selected `agent`. Include the goal, scope, relevant context, constraints, delegation allowance, acceptance criteria, verification commands, and expected report in `task`.
+5. Save the returned worker session ID and inspect its returned agent and model when present.
 
-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.
+An identical spawn key retries the original admission. Different work or a different agent requires a new key. A selected profile supplies its real system prompt, model preference, and permissions in the assigned directory. A profile without a model inherits the caller's resolved model. It has a separate conversation, so include all context it needs in the task brief. Mentioning a role in the brief does not select that profile.
+
+Explicit role selection requires an `allow` for `subagent` on that role ID. Selected workers carry parent session `deny` and `ask` rules as hard denials; parent allow exceptions do not reopen them. Read-only workers can still call their ownership-checked `threads_report` tool.
+
+If the selected profile is unavailable, fix its configuration and retry the identical spawn request. The indexed worker stays uninitialized until that retry succeeds. Do not use `threads_send` to start it.
 
 ## Write the delegation allowance
 
@@ -27,7 +32,7 @@ The parent writes `task`; the plugin appends worker instructions. Give workers t
 
 > 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`.
+Honor the selected profile's restrictions. A specialist that denies native delegation stays a leaf, and a read-only profile stays read-only. For a delegation-capable profile, add 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
 

package/src/permissions.ts

@@ -0,0 +1,32 @@
+import type { Permission } from "@opencode/schema/permission";
+
+function matches(pattern: string, value: string) {
+  const expression = pattern
+    .replaceAll("\\", "/")
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replaceAll("*", ".*")
+    .replaceAll("?", ".");
+  const normalized = value.replaceAll("\\", "/");
+  const match = new RegExp(
+    `^${expression}$`,
+    process.platform === "win32" ? "is" : "s",
+  ).exec(normalized);
+  return match?.[0] === normalized;
+}
+
+export function delegationEffect(
+  rules: Permission.Ruleset,
+  agentID: string,
+): Permission.Effect {
+  return rules.findLast((rule) =>
+    matches(rule.action, "subagent") && matches(rule.resource, agentID)
+  )?.effect ?? "ask";
+}
+
+export function requireDelegation(rules: Permission.Ruleset, agentID: string) {
+  if (delegationEffect(rules, agentID) !== "allow") {
+    throw new Error(
+      `Spawning agent "${agentID}" requires an explicit subagent allow for that agent ID; deny or ask cannot authorize managed spawning.`,
+    );
+  }
+}

package/src/rpc.ts

@@ -15,6 +15,12 @@ export const WorkerView = z.object({
   key: z.string(),
   title: z.string(),
   directory: z.string(),
+  agent: z.string().nullable(),
+  model: z.object({
+    providerID: z.string(),
+    id: z.string(),
+    variant: z.string().optional(),
+  }).nullable(),
   outcome: z.enum(["succeeded", "failed", "interrupted"]).nullable(),
   report: Report.nullable(),
   hidden: z.boolean(),

package/src/threads.ts

@@ -4,9 +4,11 @@ import { isAbsolute } from "node:path";
 import type { Plugin } from "@opencode/plugin";
 import type { SessionContext } from "@opencode/plugin/promise/session";
 import type { ToolContext } from "@opencode/plugin/promise/tool";
+import type { Permission } from "@opencode/schema/permission";
 import { Session } from "@opencode/schema/session";
 import { SessionMessage } from "@opencode/schema/session-message";
 import { z } from "zod";
+import { requireDelegation } from "./permissions";
 import { Report, WorkerView } from "./rpc";
 
 const sessionID = z.string().transform((value) => Session.ID.make(value));
@@ -33,6 +35,9 @@ export const Spawn = z
     title: z.string().min(1),
     directory: z.string().min(1),
     task: z.string().min(1),
+    agent: z.string().min(1).optional().describe(
+      "Configured agent ID in the worker's directory. Omit to inherit the caller's agent and model.",
+    ),
   })
   .strict();
 export const Send = z
@@ -49,7 +54,12 @@ const digest = (parts: string[]) =>
 export const workerIdentity = (coordinatorID: string, key: string) =>
   Session.ID.make(`ses_${digest([coordinatorID, key]).slice(0, 32)}`);
 export const fingerprint = (input: z.infer<typeof Spawn>) =>
-  digest([input.title, input.directory, input.task]);
+  digest([
+    input.title,
+    input.directory,
+    input.task,
+    ...(input.agent === undefined ? [] : [input.agent]),
+  ]);
 
 const locks = new Map<string, Promise<void>>();
 export async function serialized<T>(
@@ -96,6 +106,18 @@ export function threads(
     `reports/${link.workerID}/${link.reportMessageID}`;
   const visibilityKey = (link: z.infer<typeof Link>) =>
     `visibility/${link.workerID}/${link.reportMessageID}`;
+  const initializedKey = (link: z.infer<typeof Link>) =>
+    `initialized/${link.workerID}/${link.initialMessageID}`;
+
+  async function initialized(session: NativeSession, link: z.infer<typeof Link>) {
+    return session.metadata?.opThreadsRole !== true ||
+      await ctx.storage.get(initializedKey(link)) === true;
+  }
+
+  async function callerPermissions(session: NativeSession, agentID: string) {
+    const agent = await ctx.agent.get({ agentID, location: session.location });
+    return [...agent.data.permissions, ...(session.permissions ?? [])];
+  }
 
   async function view(
     session: NativeSession,
@@ -110,6 +132,8 @@ export function threads(
       key: link.key,
       title: session.title ?? link.key,
       directory: session.location.directory,
+      agent: session.agent ?? null,
+      model: session.model ?? null,
       outcome: session.outcome ?? null,
       report,
       hidden:
@@ -141,6 +165,7 @@ export function threads(
             throw error;
           await ctx.storage.remove(reportKey(link));
           await ctx.storage.remove(visibilityKey(link));
+          await ctx.storage.remove(initializedKey(link));
           await ctx.storage.remove(entry.key);
           continue;
         }
@@ -161,6 +186,34 @@ export function threads(
 
   return {
     list,
+    async preparePrompt(actor: string, messageID: string, callerAgent: unknown) {
+      const session = await ctx.session.get({ sessionID: actor });
+      if (session.metadata?.opThreadsRole !== true) return;
+      const recorded = Link.parse(session.metadata.opThreads);
+      if (session.parentID !== undefined || recorded.workerID !== session.id) return;
+      const link = workerLink(session);
+      if (await initialized(session, link)) return;
+      if (link.initialMessageID !== messageID || session.agent === undefined) {
+        throw new Error(
+          "Worker initialization is pending. Retry the original threads_spawn request.",
+        );
+      }
+      const coordinator = await ctx.session.get({ sessionID: link.coordinatorID });
+      requireDelegation(
+        await callerPermissions(coordinator, z.string().min(1).parse(callerAgent)),
+        session.agent,
+      );
+      const agent = await ctx.agent.get({
+        agentID: session.agent,
+        location: session.location,
+      });
+      if (agent.data.model) {
+        await ctx.session.switchModel({
+          sessionID: session.id,
+          model: agent.data.model,
+        });
+      }
+    },
     async hide(actor: string, input: z.infer<typeof WorkerTarget>) {
       const { session, link } = await owned(actor, input.workerID);
       await ctx.storage.set(visibilityKey(link), true);
@@ -199,9 +252,17 @@ export function threads(
           throw new Error("directory must be an existing absolute directory");
         }
         const workerID = workerIdentity(actor, input.key);
+        let session = await ctx.session.get({ sessionID: workerID }).catch(
+          (error: unknown) => {
+            const missing = MissingSession.safeParse(error);
+            if (!missing.success || missing.data.sessionID !== workerID)
+              throw error;
+            return undefined;
+          },
+        );
         const existing = await list(actor);
         if (
-          !existing.some((worker) => worker.workerID === workerID) &&
+          !session &&
           existing.filter(
             (worker) =>
               !worker.report &&
@@ -211,10 +272,6 @@ export function threads(
         ) {
           throw new Error(`Coordinator worker limit reached (${limit})`);
         }
-        const agent = await ctx.agent.get({
-          agentID: runtime.agent,
-          location: coordinator.location,
-        });
         const proposed = Link.parse({
           workerID,
           coordinatorID: actor,
@@ -223,18 +280,31 @@ export function threads(
           initialMessageID: SessionMessage.ID.create(),
           reportMessageID: SessionMessage.ID.create(),
         });
-        const session = await ctx.session.create({
-          id: workerID,
-          title: input.title,
-          location: { directory: input.directory },
-          agent: runtime.agent,
-          model: runtime.model,
-          permissions: [
-            ...agent.data.permissions,
-            ...(coordinator.permissions ?? []),
-          ],
-          metadata: { opThreads: proposed },
-        });
+        if (!session) {
+          const inherited = await callerPermissions(coordinator, runtime.agent);
+          if (input.agent !== undefined) requireDelegation(inherited, input.agent);
+          session = await ctx.session.create({
+            id: workerID,
+            title: input.title,
+            location: { directory: input.directory },
+            agent: input.agent ?? runtime.agent,
+            model: runtime.model,
+            permissions: [
+              ...(input.agent === undefined
+                ? inherited
+                : (coordinator.permissions ?? [])
+                    .filter((rule) => rule.effect !== "allow")
+                    .map((rule) => (
+                      { ...rule, effect: "deny" } satisfies Permission.Rule
+                    ))),
+              { action: "threads_report", resource: "*", effect: "allow" },
+            ],
+            metadata: {
+              opThreads: proposed,
+              ...(input.agent === undefined ? {} : { opThreadsRole: true }),
+            },
+          });
+        }
         const link = workerLink(session);
         if (
           link.coordinatorID !== actor ||
@@ -249,13 +319,22 @@ 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. 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.`,
+          metadata: input.agent === undefined
+            ? undefined
+            : { opThreadsCallerAgent: runtime.agent },
+          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 your 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.`,
         });
+        if (input.agent !== undefined) {
+          await ctx.storage.set(initializedKey(link), true);
+        }
         return view(await ctx.session.get({ sessionID: workerID }));
       });
     },
     async send(actor: string, input: z.infer<typeof Send>) {
-      const { link } = await owned(actor, input.workerID);
+      const { session, link } = await owned(actor, input.workerID);
+      if (!await initialized(session, link)) {
+        throw new Error("Worker initialization is pending. Retry the original threads_spawn request.");
+      }
       const id = SessionMessage.ID.make(
         `msg_${digest([input.workerID, "send", input.key]).slice(0, 32)}`,
       );

package/tui.ts

@@ -22,7 +22,7 @@ export default Plugin.define({
         const projectID = ctx.data.session.get(tab.sessionID)?.projectID;
         return {
           sessionID: tab.sessionID,
-          priority: tab.busy || tab.active || tab.attention,
+          priority: tab.busy || tab.attention,
           projectID:
             typeof projectID === "string" && projectID.length > 0
               ? projectID