@robinmarin/opencode-teams 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Marin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @robinmarin/opencode-teams
+
+An [OpenCode](https://opencode.ai) plugin that adds agent teams — spawn, coordinate, and shut down sub-agent sessions directly from your lead session.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `team_create` | Create a new team. The calling session becomes the lead. |
+| `team_spawn` | Spawn a sub-agent with a role and initial prompt. |
+| `team_message` | Send a message to a specific member or the lead. |
+| `team_broadcast` | Send a message to all active members. |
+| `team_status` | Show member statuses and task counts. |
+| `team_shutdown` | Shut down one or all members. |
+| `team_task_add` | Add a task to the team's task board. |
+| `team_task_claim` | Claim a pending task (respects dependency ordering). |
+| `team_task_done` | Mark a task as completed and report newly unblocked tasks. |
+
+## How it works
+
+- Team state is persisted to `~/.config/opencode/teams/<teamName>/config.json`
+- When a member goes idle after being busy, the plugin automatically notifies the lead
+- Spawned sub-agents receive a system prompt instructing them not to use team tools
+
+## Installation
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["npm:@robinmarin/opencode-teams"]
+}
+```
+
+Restart OpenCode. The nine team tools will be available in your session.
+
+## Local Development
+
+```bash
+# 1. Install dependencies
+bun install
+
+# 2. Build
+bun run build
+
+# 3. Point OpenCode at the local build
+# Add to ~/.config/opencode/opencode.json:
+# {
+#   "plugin": ["file:///absolute/path/to/opencode-teams/dist/index.js"]
+# }
+```
+
+## Development
+
+```bash
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Lint
+bun run lint
+```
+
+## State schema
+
+Team configs live at `~/.config/opencode/teams/<name>/config.json`:
+
+```json
+{
+  "name": "my-team",
+  "leadSessionId": "sess_abc123",
+  "members": {
+    "alice": {
+      "name": "alice",
+      "sessionId": "sess_def456",
+      "status": "ready",
+      "agentType": "default",
+      "model": "anthropic/claude-sonnet-4-5",
+      "spawnedAt": "2026-04-05T10:00:00.000Z"
+    }
+  },
+  "tasks": {},
+  "createdAt": "2026-04-05T10:00:00.000Z"
+}
+```
+
+Member statuses: `ready | busy | shutdown_requested | shutdown | error`
+
+## Known Limitations
+
+**Sub-agent tool isolation is instruction-only.** The `@opencode-ai/sdk` `session.create()` body only accepts `{ parentID, title }` — there is no deny list or permissions field. Sub-agents are told not to use team tools via their system prompt, but a model could ignore this instruction. A future SDK version may expose per-session deny rules; at that point the six team tools should be explicitly denied for all spawned sessions.
+
+**Mid-turn idle notification race.** If the lead session is mid-turn (actively generating a response) when a teammate goes idle, the `session.idle` event fires and the plugin sends a `promptAsync` to the lead. OpenCode queues this message; the lead will not re-enter its loop until the current turn completes. There is no mechanism to interrupt an in-progress turn.
+
+**No nested teams.** Sub-agents spawned by a lead cannot themselves create teams or spawn further sub-agents. The team management tools are reserved for the original lead session.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const TeamPlugin: Plugin;
+export declare const server: Plugin;
+export default TeamPlugin;

package/dist/index.js

@@ -0,0 +1,10 @@
+import { createEventHandler } from "./messaging.js";
+import { createTools } from "./tools.js";
+const TeamPlugin = async ({ client }) => {
+    return {
+        event: createEventHandler(client),
+        tool: createTools(client),
+    };
+};
+export const server = TeamPlugin;
+export default TeamPlugin;

package/dist/messaging.d.ts

@@ -0,0 +1,17 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { Event } from "@opencode-ai/sdk";
+type Client = PluginInput["client"];
+/**
+ * Creates an event handler to be registered as the `event` hook in the plugin's
+ * returned Hooks object.
+ *
+ * On every `session.idle` event:
+ * - If the session is not part of any team → ignore
+ * - If the session is the team lead → log if any members are busy (no auto-prompt)
+ * - If the session is a team member going idle → update status to "ready";
+ *   if they were previously "busy", notify the lead
+ */
+export declare function createEventHandler(client: Client): (input: {
+    event: Event;
+}) => Promise<void>;
+export {};

package/dist/messaging.js

@@ -0,0 +1,89 @@
+import { findTeamBySession, listTeams, markStaleMembersAsError, updateMember } from "./state.js";
+/**
+ * On startup, scan all teams for members whose status is "busy" or
+ * "shutdown_requested" — these represent sessions that were live when the
+ * process last died. Mark them as "error" so the lead can decide what to do.
+ */
+async function recoverStaleMembers() {
+    const teamNames = await listTeams();
+    for (const teamName of teamNames) {
+        try {
+            const recovered = await markStaleMembersAsError(teamName);
+            for (const { memberName, previousStatus } of recovered) {
+                console.log(`[opencode-teams] Recovery: member ${memberName} in team ${teamName} was stale (${previousStatus}), marked as error`);
+            }
+        }
+        catch (err) {
+            console.error(`[opencode-teams] Recovery: failed to recover team ${teamName}:`, err);
+        }
+    }
+}
+/**
+ * Creates an event handler to be registered as the `event` hook in the plugin's
+ * returned Hooks object.
+ *
+ * On every `session.idle` event:
+ * - If the session is not part of any team → ignore
+ * - If the session is the team lead → log if any members are busy (no auto-prompt)
+ * - If the session is a team member going idle → update status to "ready";
+ *   if they were previously "busy", notify the lead
+ */
+export function createEventHandler(client) {
+    // Fire-and-forget startup recovery — do not block plugin init
+    recoverStaleMembers().catch((err) => {
+        console.error("[opencode-teams] recoverStaleMembers failed:", err);
+    });
+    return async ({ event }) => {
+        if (event.type !== "session.idle")
+            return;
+        const { sessionID } = event.properties;
+        let found;
+        try {
+            found = await findTeamBySession(sessionID);
+        }
+        catch (err) {
+            console.error("[opencode-teams] error in findTeamBySession:", err);
+            return;
+        }
+        if (found === null)
+            return;
+        const { team, memberName } = found;
+        // Lead going idle — check if any members are still busy
+        if (memberName === "__lead__") {
+            const busyMembers = Object.values(team.members).filter((m) => m.status === "busy");
+            if (busyMembers.length > 0) {
+                const names = busyMembers.map((m) => m.name).join(", ");
+                console.debug(`[opencode-teams] Lead session ${sessionID} is idle but members [${names}] are still busy. ` +
+                    `Lead may need to be re-prompted when they finish.`);
+            }
+            return;
+        }
+        // Team member going idle
+        const member = team.members[memberName];
+        if (member === undefined)
+            return;
+        const wasBusy = member.status === "busy";
+        // Update member status to ready
+        try {
+            await updateMember(team.name, memberName, { status: "ready" });
+        }
+        catch (err) {
+            console.error(`[opencode-teams] Failed to update member ${memberName} status to ready:`, err);
+            return;
+        }
+        // If they were busy, notify the lead
+        if (wasBusy) {
+            const notifyMsg = `[System]: Teammate ${memberName} has gone idle and may need a follow-up or new task.`;
+            try {
+                const parts = [{ type: "text", text: notifyMsg }];
+                await client.session.promptAsync({
+                    path: { id: team.leadSessionId },
+                    body: { parts },
+                });
+            }
+            catch (err) {
+                console.error(`[opencode-teams] Failed to notify lead of idle member ${memberName}:`, err);
+            }
+        }
+    };
+}

package/dist/state.d.ts

@@ -0,0 +1,61 @@
+export type MemberStatus = "ready" | "busy" | "shutdown_requested" | "shutdown" | "error";
+export type TeamMember = {
+    name: string;
+    sessionId: string;
+    status: MemberStatus;
+    agentType: string;
+    model: string;
+    spawnedAt: string;
+};
+export type TeamTask = {
+    id: string;
+    title: string;
+    description: string;
+    status: "pending" | "in_progress" | "completed" | "blocked";
+    assignee: string | null;
+    dependsOn: string[];
+    createdAt: string;
+};
+export type TeamConfig = {
+    name: string;
+    leadSessionId: string;
+    members: Record<string, TeamMember>;
+    tasks: Record<string, TeamTask>;
+    createdAt: string;
+};
+/** For use in tests only. Pass the temp directory to isolate state. */
+export declare function setTestTeamsDir(dir: string | undefined): void;
+export declare function readTeam(name: string): Promise<TeamConfig | null>;
+export declare function writeTeam(config: TeamConfig): Promise<void>;
+export declare function updateMember(teamName: string, memberName: string, patch: Partial<TeamMember>): Promise<void>;
+export declare function findTeamBySession(sessionId: string): Promise<{
+    team: TeamConfig;
+    memberName: string;
+} | null>;
+export declare function claimTask(teamName: string, taskId: string, memberName: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Atomically marks a task as completed and computes which tasks are now
+ * unblocked — all in a single lock pass to avoid TOCTOU races.
+ */
+export declare function completeTask(teamName: string, taskId: string): Promise<{
+    ok: true;
+    unblockedTaskIds: string[];
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * In a single lock pass, marks all busy/shutdown_requested members in a team
+ * as error. Returns the list of recovered members with their previous status,
+ * so callers can log without re-reading the file.
+ */
+export declare function markStaleMembersAsError(teamName: string): Promise<Array<{
+    memberName: string;
+    previousStatus: MemberStatus;
+}>>;
+export declare function listTeams(): Promise<string[]>;

package/dist/state.js

@@ -0,0 +1,245 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+// Overridable for testing — set via setTestTeamsDir()
+let _overrideTeamsDir;
+/** For use in tests only. Pass the temp directory to isolate state. */
+export function setTestTeamsDir(dir) {
+    _overrideTeamsDir = dir;
+    // Clear the reverse index so tests start clean
+    sessionIndex.clear();
+}
+function teamsDir() {
+    if (_overrideTeamsDir !== undefined)
+        return _overrideTeamsDir;
+    return path.join(os.homedir(), ".config", "opencode", "teams");
+}
+function teamDir(name) {
+    return path.join(teamsDir(), name);
+}
+function teamConfigPath(name) {
+    return path.join(teamDir(name), "config.json");
+}
+// ---------------------------------------------------------------------------
+// In-process write lock (per team name)
+// ---------------------------------------------------------------------------
+const writeLocks = new Map();
+function withLock(key, fn) {
+    const current = writeLocks.get(key) ?? Promise.resolve();
+    let resolve;
+    const next = new Promise((res) => {
+        resolve = res;
+    });
+    writeLocks.set(key, next);
+    return current.then(fn).finally(resolve);
+}
+// ---------------------------------------------------------------------------
+// In-memory reverse index: sessionId → { teamName, memberName }
+//
+// Kept in sync on every write. Unknown sessions fall back to a full disk scan
+// that populates the index as a side effect, making subsequent lookups O(1).
+// ---------------------------------------------------------------------------
+const sessionIndex = new Map();
+function indexTeam(config) {
+    // Remove any stale entries for this team before re-indexing
+    for (const [sessionId, entry] of sessionIndex) {
+        if (entry.teamName === config.name)
+            sessionIndex.delete(sessionId);
+    }
+    sessionIndex.set(config.leadSessionId, {
+        teamName: config.name,
+        memberName: "__lead__",
+    });
+    for (const [memberName, member] of Object.entries(config.members)) {
+        sessionIndex.set(member.sessionId, { teamName: config.name, memberName });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function readTeam(name) {
+    const configPath = teamConfigPath(name);
+    try {
+        const raw = await fs.readFile(configPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function writeTeam(config) {
+    return withLock(config.name, async () => {
+        const dir = teamDir(config.name);
+        await fs.mkdir(dir, { recursive: true });
+        const configPath = teamConfigPath(config.name);
+        const tmpPath = `${configPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, configPath);
+        indexTeam(config);
+    });
+}
+export async function updateMember(teamName, memberName, patch) {
+    return withLock(teamName, async () => {
+        const configPath = teamConfigPath(teamName);
+        const raw = await fs.readFile(configPath, "utf-8");
+        const config = JSON.parse(raw);
+        const existing = config.members[memberName];
+        if (existing === undefined) {
+            throw new Error(`Member "${memberName}" not found in team "${teamName}"`);
+        }
+        config.members[memberName] = { ...existing, ...patch };
+        const tmpPath = `${configPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, configPath);
+        indexTeam(config);
+    });
+}
+export async function findTeamBySession(sessionId) {
+    // Fast path: index hit
+    const entry = sessionIndex.get(sessionId);
+    if (entry !== undefined) {
+        const team = await readTeam(entry.teamName);
+        if (team === null) {
+            sessionIndex.delete(sessionId);
+            return null;
+        }
+        return { team, memberName: entry.memberName };
+    }
+    // Slow path: full disk scan; populate index as a side effect so future
+    // lookups for any session in these teams are O(1).
+    let names;
+    try {
+        names = await listTeams();
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        const team = await readTeam(name);
+        if (team === null)
+            continue;
+        indexTeam(team);
+        if (team.leadSessionId === sessionId)
+            return { team, memberName: "__lead__" };
+        for (const [memberName, member] of Object.entries(team.members)) {
+            if (member.sessionId === sessionId)
+                return { team, memberName };
+        }
+    }
+    return null;
+}
+export async function claimTask(teamName, taskId, memberName) {
+    return withLock(teamName, async () => {
+        const configPath = teamConfigPath(teamName);
+        const raw = await fs.readFile(configPath, "utf-8");
+        const config = JSON.parse(raw);
+        const task = config.tasks[taskId];
+        if (task === undefined) {
+            return { ok: false, reason: `Task "${taskId}" not found in team "${teamName}".` };
+        }
+        if (task.status !== "pending") {
+            return { ok: false, reason: `Task "${taskId}" is not pending (current status: "${task.status}").` };
+        }
+        const blocking = [];
+        for (const depId of task.dependsOn) {
+            const dep = config.tasks[depId];
+            if (dep === undefined || dep.status !== "completed") {
+                blocking.push(depId);
+            }
+        }
+        if (blocking.length > 0) {
+            return {
+                ok: false,
+                reason: `Task "${taskId}" is blocked by: ${blocking.join(", ")}. Complete those tasks first.`,
+            };
+        }
+        config.tasks[taskId] = { ...task, status: "in_progress", assignee: memberName };
+        const tmpPath = `${configPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, configPath);
+        return { ok: true };
+    });
+}
+/**
+ * Atomically marks a task as completed and computes which tasks are now
+ * unblocked — all in a single lock pass to avoid TOCTOU races.
+ */
+export async function completeTask(teamName, taskId) {
+    return withLock(teamName, async () => {
+        const configPath = teamConfigPath(teamName);
+        const raw = await fs.readFile(configPath, "utf-8");
+        const config = JSON.parse(raw);
+        const task = config.tasks[taskId];
+        if (task === undefined) {
+            return { ok: false, reason: `Task "${taskId}" not found in team "${teamName}".` };
+        }
+        config.tasks[taskId] = { ...task, status: "completed" };
+        const unblockedTaskIds = [];
+        for (const [id, t] of Object.entries(config.tasks)) {
+            if (t.status !== "pending")
+                continue;
+            if (!t.dependsOn.includes(taskId))
+                continue;
+            const allDone = t.dependsOn.every((depId) => config.tasks[depId]?.status === "completed");
+            if (allDone)
+                unblockedTaskIds.push(id);
+        }
+        const tmpPath = `${configPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, configPath);
+        return { ok: true, unblockedTaskIds };
+    });
+}
+/**
+ * In a single lock pass, marks all busy/shutdown_requested members in a team
+ * as error. Returns the list of recovered members with their previous status,
+ * so callers can log without re-reading the file.
+ */
+export async function markStaleMembersAsError(teamName) {
+    return withLock(teamName, async () => {
+        const configPath = teamConfigPath(teamName);
+        let raw;
+        try {
+            raw = await fs.readFile(configPath, "utf-8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        const config = JSON.parse(raw);
+        const recovered = [];
+        let dirty = false;
+        for (const [name, member] of Object.entries(config.members)) {
+            if (member.status === "busy" || member.status === "shutdown_requested") {
+                recovered.push({ memberName: name, previousStatus: member.status });
+                config.members[name] = { ...member, status: "error" };
+                dirty = true;
+            }
+        }
+        if (!dirty)
+            return [];
+        const tmpPath = `${configPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, configPath);
+        // Session IDs did not change — index does not need updating
+        return recovered;
+    });
+}
+export async function listTeams() {
+    const dir = teamsDir();
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import type { PluginInput, ToolDefinition } from "@opencode-ai/plugin";
+type Client = PluginInput["client"];
+export declare function createTools(client: Client): Record<string, ToolDefinition>;
+export {};

package/dist/tools.js

@@ -0,0 +1,467 @@
+import { tool } from "@opencode-ai/plugin";
+import { claimTask, completeTask, findTeamBySession, readTeam, updateMember, writeTeam, } from "./state.js";
+// Use the plugin's bundled Zod instance to avoid version mismatch
+const z = tool.schema;
+// ---------------------------------------------------------------------------
+// tool definitions
+// ---------------------------------------------------------------------------
+function makeTools(client) {
+    // ---------------------------------------------------------------------------
+    // team_create
+    // ---------------------------------------------------------------------------
+    const team_create = tool({
+        description: "Create a new agent team. The calling session becomes the team lead.",
+        args: {
+            name: z.string().describe("Unique team name"),
+            description: z.string().optional().describe("Optional team description"),
+        },
+        async execute(args, context) {
+            try {
+                const existing = await readTeam(args.name);
+                if (existing !== null) {
+                    return `Error: Team "${args.name}" already exists.`;
+                }
+                await writeTeam({
+                    name: args.name,
+                    leadSessionId: context.sessionID,
+                    members: {},
+                    tasks: {},
+                    createdAt: new Date().toISOString(),
+                });
+                return `Team "${args.name}" created. You are the lead (session: ${context.sessionID}).`;
+            }
+            catch (err) {
+                console.error("[team_create] error:", err);
+                return `Error creating team: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_spawn
+    // ---------------------------------------------------------------------------
+    const team_spawn = tool({
+        description: "Spawn a new sub-agent session as a team member with a specific role.",
+        args: {
+            teamName: z.string().describe("Name of the team to add the member to"),
+            memberName: z.string().describe("Unique name for this team member"),
+            role: z
+                .string()
+                .describe("Role description for this member (e.g. 'backend engineer', 'code reviewer')"),
+            initialPrompt: z
+                .string()
+                .describe("Initial task or instructions to send to the member"),
+            model: z
+                .string()
+                .optional()
+                .describe("Model override (e.g. 'anthropic/claude-haiku-4-5'). Defaults to session model."),
+        },
+        async execute(args, context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" does not exist. Create it first with team_create.`;
+                }
+                if (team.members[args.memberName] !== undefined) {
+                    return `Error: Member "${args.memberName}" already exists in team "${args.teamName}".`;
+                }
+                // Create the new session
+                const createResult = await client.session.create({
+                    body: { title: `[${args.teamName}] ${args.memberName}` },
+                });
+                if (createResult.error !== undefined) {
+                    return `Error creating session for member: ${JSON.stringify(createResult.error)}`;
+                }
+                const sessionId = createResult.data.id;
+                // Known limitation: @opencode-ai/sdk session.create() only accepts
+                // { parentID, title } in its body — there is no deny list or permissions
+                // field. Sub-agent tool isolation is therefore instruction-only. A
+                // future SDK version may expose a deny list; at that point add explicit
+                // deny rules for all six team tools here for defence in depth.
+                const systemPrompt = [
+                    `You are "${args.memberName}", a ${args.role} on team "${args.teamName}".`,
+                    `Your lead session ID is: ${team.leadSessionId}.`,
+                    `You were spawned to work on specific tasks. Complete them thoroughly.`,
+                    `IMPORTANT: You must NOT use team management tools (team_create, team_spawn, team_message, team_broadcast, team_status, team_shutdown). These tools are reserved for the team lead only.`,
+                    `When you complete a task, summarize your results clearly so the lead can review them.`,
+                ].join("\n");
+                // Parse optional model selector
+                let modelOpt;
+                if (typeof args.model === "string") {
+                    const slashIdx = args.model.indexOf("/");
+                    if (slashIdx !== -1) {
+                        modelOpt = {
+                            providerID: args.model.slice(0, slashIdx),
+                            modelID: args.model.slice(slashIdx + 1),
+                        };
+                    }
+                }
+                // Write member into team state BEFORE firing the prompt so that state
+                // is always consistent — a live session always has a state record.
+                const now = new Date().toISOString();
+                await writeTeam({
+                    ...team,
+                    members: {
+                        ...team.members,
+                        [args.memberName]: {
+                            name: args.memberName,
+                            sessionId,
+                            status: "busy",
+                            agentType: "default",
+                            model: args.model ?? "default",
+                            spawnedAt: now,
+                        },
+                    },
+                });
+                // Fire initial prompt; if it throws, mark the member as error so
+                // callers know the session is in an unknown state.
+                try {
+                    await client.session.promptAsync({
+                        path: { id: sessionId },
+                        body: {
+                            parts: [{ type: "text", text: args.initialPrompt }],
+                            system: systemPrompt,
+                            ...(modelOpt !== undefined ? { model: modelOpt } : {}),
+                        },
+                    });
+                }
+                catch (promptErr) {
+                    console.error("[team_spawn] promptAsync failed:", promptErr);
+                    try {
+                        await updateMember(args.teamName, args.memberName, {
+                            status: "error",
+                        });
+                    }
+                    catch (updateErr) {
+                        console.error("[team_spawn] failed to update member status to error:", updateErr);
+                    }
+                    return `Error sending initial prompt to member "${args.memberName}": ${String(promptErr)}`;
+                }
+                return `Member "${args.memberName}" spawned (session: ${sessionId}). Initial prompt sent.`;
+            }
+            catch (err) {
+                console.error("[team_spawn] error:", err);
+                return `Error spawning member: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_message
+    // ---------------------------------------------------------------------------
+    const team_message = tool({
+        description: "Send a message to a specific team member or the team lead.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            to: z.string().describe("Recipient: member name or 'lead'"),
+            message: z.string().describe("Message to send"),
+        },
+        async execute(args, context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" not found.`;
+                }
+                // Determine sender name
+                const senderInfo = await findTeamBySession(context.sessionID);
+                const senderName = senderInfo !== null ? senderInfo.memberName : context.sessionID;
+                // Resolve target session ID
+                let targetSessionId;
+                if (args.to === "lead") {
+                    targetSessionId = team.leadSessionId;
+                }
+                else {
+                    const member = team.members[args.to];
+                    if (member === undefined) {
+                        return `Error: Member "${args.to}" not found in team "${args.teamName}".`;
+                    }
+                    if (member.status === "shutdown" ||
+                        member.status === "shutdown_requested") {
+                        return `Error: Member "${args.to}" is in shutdown state and cannot receive messages.`;
+                    }
+                    targetSessionId = member.sessionId;
+                }
+                const prefixedMessage = `[Team message from ${senderName}]: ${args.message}`;
+                await client.session.promptAsync({
+                    path: { id: targetSessionId },
+                    body: { parts: [{ type: "text", text: prefixedMessage }] },
+                });
+                return `Message sent to "${args.to}".`;
+            }
+            catch (err) {
+                console.error("[team_message] error:", err);
+                return `Error sending message: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_broadcast
+    // ---------------------------------------------------------------------------
+    const team_broadcast = tool({
+        description: "Broadcast a message to all active team members (status: ready or busy), excluding the sender.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            message: z
+                .string()
+                .describe("Message to broadcast to all active members"),
+        },
+        async execute(args, context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" not found.`;
+                }
+                const senderInfo = await findTeamBySession(context.sessionID);
+                const senderName = senderInfo !== null ? senderInfo.memberName : context.sessionID;
+                const prefixedMessage = `[Team broadcast from ${senderName}]: ${args.message}`;
+                const messaged = [];
+                for (const [memberName, member] of Object.entries(team.members)) {
+                    if (member.sessionId === context.sessionID)
+                        continue; // skip sender
+                    if (member.status !== "ready" && member.status !== "busy") {
+                        continue;
+                    }
+                    try {
+                        await client.session.promptAsync({
+                            path: { id: member.sessionId },
+                            body: { parts: [{ type: "text", text: prefixedMessage }] },
+                        });
+                        messaged.push(memberName);
+                    }
+                    catch (err) {
+                        console.error(`[team_broadcast] failed to message ${memberName}:`, err);
+                    }
+                }
+                if (messaged.length === 0) {
+                    return `Broadcast sent to no members (no active members found excluding sender).`;
+                }
+                return `Broadcast sent to: ${messaged.join(", ")}.`;
+            }
+            catch (err) {
+                console.error("[team_broadcast] error:", err);
+                return `Error broadcasting: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_status
+    // ---------------------------------------------------------------------------
+    const team_status = tool({
+        description: "Get the current status of a team: members, their statuses, and task counts.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+        },
+        async execute(args, _context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" not found.`;
+                }
+                const memberLines = Object.values(team.members).map((m) => `  - ${m.name} [${m.status}] session=${m.sessionId} model=${m.model} spawned=${m.spawnedAt}`);
+                const tasksByStatus = {
+                    pending: 0,
+                    in_progress: 0,
+                    completed: 0,
+                    blocked: 0,
+                };
+                for (const task of Object.values(team.tasks)) {
+                    tasksByStatus[task.status] = (tasksByStatus[task.status] ?? 0) + 1;
+                }
+                const lines = [
+                    `Team: ${team.name}`,
+                    `Lead session: ${team.leadSessionId}`,
+                    `Created: ${team.createdAt}`,
+                    ``,
+                    `Members (${Object.keys(team.members).length}):`,
+                    ...memberLines,
+                    ``,
+                    `Tasks: pending=${tasksByStatus["pending"] ?? 0} in_progress=${tasksByStatus["in_progress"] ?? 0} completed=${tasksByStatus["completed"] ?? 0} blocked=${tasksByStatus["blocked"] ?? 0}`,
+                ];
+                return lines.join("\n");
+            }
+            catch (err) {
+                console.error("[team_status] error:", err);
+                return `Error getting status: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_shutdown
+    // ---------------------------------------------------------------------------
+    const team_shutdown = tool({
+        description: "Shut down one or all team members by sending them a shutdown message.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            memberName: z
+                .string()
+                .optional()
+                .describe("Member to shut down. Omit to shut down all active members."),
+        },
+        async execute(args, _context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" not found.`;
+                }
+                const shutdownMsg = "[System]: You are being shut down. Complete your current thought and stop.";
+                const targets = [];
+                if (typeof args.memberName === "string") {
+                    const member = team.members[args.memberName];
+                    if (member === undefined) {
+                        return `Error: Member "${args.memberName}" not found in team "${args.teamName}".`;
+                    }
+                    targets.push({ name: args.memberName, sessionId: member.sessionId });
+                }
+                else {
+                    for (const [name, member] of Object.entries(team.members)) {
+                        if (member.status === "ready" || member.status === "busy") {
+                            targets.push({ name, sessionId: member.sessionId });
+                        }
+                    }
+                }
+                const shut = [];
+                for (const target of targets) {
+                    try {
+                        await client.session.promptAsync({
+                            path: { id: target.sessionId },
+                            body: { parts: [{ type: "text", text: shutdownMsg }] },
+                        });
+                        await updateMember(args.teamName, target.name, {
+                            status: "shutdown_requested",
+                        });
+                        shut.push(target.name);
+                    }
+                    catch (err) {
+                        console.error(`[team_shutdown] failed for ${target.name}:`, err);
+                    }
+                }
+                if (shut.length === 0) {
+                    return `No members were shut down (no active members found).`;
+                }
+                return `Shutdown requested for: ${shut.join(", ")}.`;
+            }
+            catch (err) {
+                console.error("[team_shutdown] error:", err);
+                return `Error shutting down: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_task_add
+    // ---------------------------------------------------------------------------
+    const team_task_add = tool({
+        description: "Add a task to the team's task board.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            title: z.string().describe("Short title for the task"),
+            description: z.string().describe("Full description of the task"),
+            assignee: z
+                .string()
+                .optional()
+                .describe("Name of the member to assign the task to (optional)"),
+            dependsOn: z
+                .array(z.string())
+                .optional()
+                .describe("Task IDs this task is blocked by (optional)"),
+        },
+        async execute(args, _context) {
+            try {
+                const team = await readTeam(args.teamName);
+                if (team === null) {
+                    return `Error: Team "${args.teamName}" not found.`;
+                }
+                const taskId = `task_${Date.now()}`;
+                const now = new Date().toISOString();
+                await writeTeam({
+                    ...team,
+                    tasks: {
+                        ...team.tasks,
+                        [taskId]: {
+                            id: taskId,
+                            title: args.title,
+                            description: args.description,
+                            status: "pending",
+                            assignee: args.assignee ?? null,
+                            dependsOn: args.dependsOn ?? [],
+                            createdAt: now,
+                        },
+                    },
+                });
+                return `Task "${args.title}" added with ID: ${taskId}.`;
+            }
+            catch (err) {
+                console.error("[team_task_add] error:", err);
+                return `Error adding task: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_task_claim
+    // ---------------------------------------------------------------------------
+    const team_task_claim = tool({
+        description: "Claim a pending task, marking it as in_progress. Fails if the task has incomplete dependencies.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            taskId: z.string().describe("ID of the task to claim"),
+        },
+        async execute(args, context) {
+            try {
+                // Look up the calling member's name via their session ID
+                const found = await findTeamBySession(context.sessionID);
+                const memberName = found !== null && found.memberName !== "__lead__"
+                    ? found.memberName
+                    : context.sessionID;
+                const result = await claimTask(args.teamName, args.taskId, memberName);
+                if (!result.ok) {
+                    return `Error: ${result.reason}`;
+                }
+                return `Task "${args.taskId}" claimed by "${memberName}" and is now in_progress.`;
+            }
+            catch (err) {
+                console.error("[team_task_claim] error:", err);
+                return `Error claiming task: ${String(err)}`;
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // team_task_done
+    // ---------------------------------------------------------------------------
+    const team_task_done = tool({
+        description: "Mark a task as completed and report any newly unblocked tasks.",
+        args: {
+            teamName: z.string().describe("Name of the team"),
+            taskId: z.string().describe("ID of the task to mark as completed"),
+        },
+        async execute(args, _context) {
+            try {
+                const result = await completeTask(args.teamName, args.taskId);
+                if (!result.ok) {
+                    return `Error: ${result.reason}`;
+                }
+                const unblockedMsg = result.unblockedTaskIds.length > 0
+                    ? ` Newly unblocked: ${result.unblockedTaskIds.join(", ")}.`
+                    : "";
+                return `Task "${args.taskId}" marked as completed.${unblockedMsg}`;
+            }
+            catch (err) {
+                console.error("[team_task_done] error:", err);
+                return `Error completing task: ${String(err)}`;
+            }
+        },
+    });
+    return {
+        team_create,
+        team_spawn,
+        team_message,
+        team_broadcast,
+        team_status,
+        team_shutdown,
+        team_task_add,
+        team_task_claim,
+        team_task_done,
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory — call this at plugin init with the live client
+// ---------------------------------------------------------------------------
+export function createTools(client) {
+    return makeTools(client);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@robinmarin/opencode-teams",
+  "version": "0.1.0",
+  "description": "OpenCode plugin — spawn and coordinate sub-agent teams from your lead session",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai",
+    "agents",
+    "multi-agent",
+    "teams"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.3.15",
+    "@opencode-ai/sdk": "^1.3.15",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "bun-types": "^1.3.11",
+    "typescript": "^6.0.2"
+  }
+}