@doingdev/opencode-claude-manager-plugin 0.1.64 → 0.1.66

package/README.md

@@ -1,48 +1,37 @@
-# OpenCode Claude Manager Plugin
+# @doingdev/opencode-claude-manager-plugin
 
-This package provides an OpenCode plugin that lets an OpenCode-side agent hierarchy orchestrate Claude Code sessions through a stable local bridge.
+OpenCode plugin that adds a manager-style orchestration layer over Claude Code sessions. A `cto` agent reads the repo, asks focused questions, and delegates to named engineers who each run work in their own persistent Claude Code session.
 
-## Overview
+Useful when you want OpenCode to investigate first, split work across named engineers with session continuity, and keep git and review controls at the manager layer.
 
-Use this when you want OpenCode to act like a real technical lead over Claude Code instead of being a thin relay. The plugin gives you a CTO agent that can ask better questions, explicitly assign named engineers, reuse each engineer's Claude session for continuity, preserve wrapper-level engineer memory, compare multiple plans, and keep git/review work at the manager layer.
+## What it adds
 
-## Features
-
-- Runs Claude Code tasks from OpenCode through `@anthropic-ai/claude-agent-sdk`.
-- Creates a persistent named team: `Tom`, `John`, `Maya`, `Sara`, and `Alex`.
-- Reuses one Claude Code session per engineer within the active CTO team.
-- Reloads prior engineer wrapper context so each named subagent can prompt Claude better over time.
-- Uses named engineer subagents for live delegated work while keeping both wrapper memory and Claude session continuity underneath.
-- Keeps session babysitting out of the normal user flow — no public reset/fresh-session controls.
-- Discovers repo-local Claude metadata from `.claude/skills`, `.claude/commands`, `CLAUDE.md`, and settings hooks.
-- Git integration: diff, commit, and reset from the manager layer.
-- Tool approval policy for governing which Claude Code tools are allowed.
-- Persists local team state and transcripts under `.claude-manager/` for continuity and inspection.
+- `cto` orchestrator that reads, delegates, reviews diffs, and owns all manager tools. Never edits files directly.
+- Five persistent general engineers — `tom`, `john`, `maya`, `sara`, `alex` — each backed by its own Claude Code session that survives across assignments in the same CTO session.
+- `team-planner` that runs two engineers in parallel and returns a single synthesized plan.
+- `browser-qa` browser verification specialist using Playwright-oriented prompting. Does not implement code.
+- Manager tools for team state, git, transcript/history inspection, and tool approval policy.
+- Local runtime state under `.claude-manager/` persisted across turns.
 
 ## Requirements
 
-- Node `22+`
+- Node `>=22`
 - OpenCode with plugin loading enabled
-- Access to Claude Code / Claude Agent SDK on the machine where OpenCode is running
-
-## Installation
+- Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) available to the Node process
+- Git - required for the git tools
+- OpenCode Playwright skill/command - required for `browser-qa`
 
-Install from the npm registry:
+## Install
 
 ```bash
 pnpm add @doingdev/opencode-claude-manager-plugin
+# npm install @doingdev/opencode-claude-manager-plugin
+# yarn add @doingdev/opencode-claude-manager-plugin
 ```
 
-Or for local development in this repo:
-
-```bash
-pnpm install
-pnpm run build
-```
-
-## OpenCode Config
+## Setup
 
-Add the plugin to your OpenCode config:
+Add the plugin to `opencode.json` in your project root:
 
 ```json
 {
@@ -50,137 +39,134 @@ Add the plugin to your OpenCode config:
 }
 ```
 
-If you are testing locally, point OpenCode at the local package or plugin file using your normal local plugin workflow.
+Agents register automatically at runtime. No manual agent entries needed.
 
-## OpenCode tools
+## Key concepts
 
-### CTO orchestration
+**Delegation model.** The CTO reads the repo and context, decides what to do, and sends work to a named engineer via the `claude` tool. The engineer runs that assignment inside its own Claude Code session. The CTO never edits files directly.
 
-- Use the built-in OpenCode `task` tool to delegate to named engineers: `tom`, `john`, `maya`, `sara`, `alex`.
-- `team_status` — inspect the current CTO team's engineer bindings, Claude session IDs, busy flags, and context snapshots.
+**Engineer persistence.** Each engineer's Claude Code session persists within a CTO session. A follow-up assignment to the same engineer resumes with prior context, which helps with multi-step tasks or when the engineer already understands a subsystem.
 
-### Engineer bridge
+**Modes.** When delegating, the CTO picks a mode:
+- `explore` — read-only investigation. No file edits.
+- `implement` — hands-on implementation work.
+- `verify` — tests, lint, spot-checks after changes.
 
-- `claude` — available only inside named engineer subagents. Sends work through that engineer's persistent Claude Code session.
-  - `mode` (required) — `explore`, `implement`, or `verify`.
-  - `message` (required) — the work to do.
-  - `model` (optional) — `claude-opus-4-6` or `claude-sonnet-4-6`.
+**Teams.** Each CTO session has its own team. State is keyed by CTO session ID under `.claude-manager/teams/`.
 
-### Git operations
+## Agents
 
-- `git_diff` — review all uncommitted changes (staged + unstaged).
-- `git_commit` — stage all changes and commit with a message.
-- `git_reset` — hard reset + clean (destructive).
+| Agent | Role |
+|---|---|
+| `cto` | Orchestrator. Reads, delegates, reviews, owns manager tools. Does not edit files. |
+| `tom`, `john`, `maya`, `sara`, `alex` | General engineers. Each exposes only the `claude` tool backed by its own persistent Claude Code session. |
+| `team-planner` | Thin wrapper around `plan_with_team`. Runs two engineers in parallel, returns a synthesized plan. |
+| `browser-qa` | Browser verification specialist. Uses Playwright-oriented prompting. Does not implement code. |
 
-### Inspection
+## Tools
 
-- `list_transcripts` — list available session transcripts or inspect a specific transcript by ID.
-- `list_history` — list saved CTO teams for the worktree or inspect one team by ID.
+### Engineer tool
 
-### Tool approval
+Each general engineer exposes one tool:
 
-- `approval_policy` — view the current tool approval policy.
-- `approval_decisions` — view recent tool approval decisions.
-- `approval_update` — add/remove rules, enable/disable approval, or clear decision history. Policy uses a **deny-list**: tools not matching any rule are **allowed**; use explicit **deny** rules to block. `defaultAction` is always `allow` (cannot be set to deny).
+| Tool | Parameters | Notes |
+|---|---|---|
+| `claude` | `mode` (`explore`/`implement`/`verify`), `assignment` (text), optional `model` | Model choices: `claude-opus-4-6` or `claude-sonnet-4-6`. Defaults to the session default. |
 
-## Agent hierarchy
+### CTO tools
 
-The plugin registers a CTO + named engineer team through the OpenCode plugin `config` hook:
+| Tool | Description |
+|---|---|
+| `team_status` | Show current team: engineers, sessions, context levels. |
+| `reset_engineer` | Clear a stuck engineer's Claude session, wrapper history, or both. |
+| `git_diff` | Diff with optional path filter, staged flag, or ref. |
+| `git_commit` | Commit staged changes with a message and optional file list. |
+| `git_reset` | **Destructive.** Runs `git reset --hard HEAD && git clean -fd`. |
+| `git_status` | Short status and cleanliness check. |
+| `git_log` | Recent commit log. |
+| `list_transcripts` | List saved Claude session transcripts in `.claude-manager/transcripts/`. |
+| `list_history` | List saved team state in `.claude-manager/teams/`. |
+| `approval_policy` | Read the active tool approval policy. |
+| `approval_decisions` | Read the logged approval decisions. |
+| `approval_update` | Update the tool approval policy. |
 
-- **`cto`** (primary agent) — owns the outcome, finds missing requirements, spawns named engineers with the Task tool, compares plans, reviews diffs, and manages git.
-- **`tom`**, **`john`**, **`maya`**, **`sara`**, **`alex`** (subagents) — thin named engineer wrappers. Each uses the `claude` tool and keeps one persistent Claude Code session.
-- **`team-planner`** (subagent) — thin planning wrapper that runs `plan_with_team` so the UI shows live planning activity.
-- **Claude Code sessions** — the underlying execution layer. One session per engineer inside the active team.
+### team-planner tool
 
-These are added to OpenCode config at runtime by the plugin, so they do not require separate manual `opencode.json` entries.
+| Tool | Description |
+|---|---|
+| `plan_with_team` | Runs two general engineers in parallel on the same planning task, then synthesizes one recommended plan. `browser-qa` is not part of the planning pool. |
 
-## Quick Start
+## Approval policy
 
-Typical flow inside OpenCode:
+Each engineer's Claude Code session runs under a tool approval manager. The policy is **deny-list based**: unmatched tools stay allowed and `defaultAction` is always `allow`.
 
-1. Ask the `cto` agent for the work.
-2. Let `cto` investigate lightly, then spawn one or more named engineers with the Task tool.
-3. Review changes with `git_diff`, then commit or reset.
-4. Inspect saved Claude history with `list_transcripts` or saved team state with `list_history` / `team_status`.
+Rule fields:
+- `pattern` — glob matching the tool name.
+- `inputPattern` (optional) — substring match against tool input.
+- `action` — `allow` or `deny`.
+- `message` (optional) — shown when the rule fires.
 
-Example tasks:
+Default rules block patterns like `rm -rf /`, `git push --force`, and `git reset --hard`. Read the active policy with `approval_policy`, inspect logged decisions with `approval_decisions`, and change rules with `approval_update`.
 
+## Workflows
+
+**Investigate then implement:**
 ```text
-Ask CTO to send Tom to implement the new validation logic in src/auth.ts, then review with git_diff.
+Ask cto to inspect the failing billing tests, send tom to implement the smallest safe fix, then review with git_diff.
 ```
 
-For a larger feature where you want investigation first and then a stronger combined plan:
-
+**Dual-engineer planning:**
 ```text
-Ask CTO to inspect the billing feature scope, then use team-planner to run two independent investigations and synthesize the best implementation plan.
+Ask cto to use team-planner to produce a two-engineer plan for adding SSO to the auth module.
 ```
 
-## Local Development
-
-Clone the repo and run:
-
-```bash
-pnpm install
-pnpm run lint
-pnpm run typecheck
-pnpm run test
-pnpm run build
+**Browser verification:**
+```text
+Ask cto to send browser-qa to verify the signup flow on http://localhost:3000 and report failures.
 ```
 
-The compiled plugin output is written to `dist/`.
+**Reuse engineer context:**
+```text
+Ask cto to send john to add error handling to the function he just implemented.
+```
 
-## Publishing
+**Inspect state before committing:**
+```text
+Ask cto to run git_diff, summarize the changes, then run git_commit with a descriptive message.
+```
 
-This package is configured for the npm scope `@doingdev`.
+## State
 
-This repository uses npm trusted publishing with GitHub Actions OIDC, so you do not need an `NPM_TOKEN` secret once npm is configured correctly.
+Runtime state is local to the worktree and gitignored:
 
-Before the first automated publish, configure npm trusted publishing for `@doingdev/opencode-claude-manager-plugin` on npmjs.com:
+```text
+.claude-manager/
+  teams/                  # One JSON file per CTO session (team ID)
+  transcripts/            # Claude session event logs
+  approval-policy.json    # Active policy, if customized
+  debug.log               # NDJSON debug log from plugin hooks
+```
 
-1. Open the package settings on npmjs.com.
-2. Go to the `Trusted Publisher` section.
-3. Choose `GitHub Actions`.
-4. Set the GitHub owner/user to your account or org.
-5. Set the repository name.
-6. Set the workflow filename to `publish.yml`.
-7. Leave the environment name empty unless you later add a GitHub Actions environment back to the workflow.
+- State is not shared across machines or worktrees.
+- Continuity is strongest within a single CTO session. Restarting the CTO session starts a new team.
+- Undo at the CTO level propagates to engineer wrapper sessions and inner Claude Code sessions.
 
-Notes for trusted publishing:
+## Limits and caveats
 
-- npm trusted publishing requires GitHub-hosted runners.
-- npm recommends Node `22.14.0+` with npm CLI `11.5.1+`; the workflows use Node `24`.
-- Provenance is generated automatically by npm for trusted publishes from public GitHub repositories.
+- Context usage tracking is heuristic, not exact SDK-reported truth. Actual token counts may differ.
+- `browser-qa` returns `PLAYWRIGHT_UNAVAILABLE: <reason>` if the Playwright skill or command is missing.
+- `plan_with_team` runs two general engineers. `browser-qa` is excluded from the planning pool.
+- `git_reset` is destructive and immediate. Run `git_diff` first to inspect state.
+- Engineer context degrades if sessions are reset or if the CTO session is restarted mid-task.
 
-Release flow:
+## Development
 
 ```bash
-pnpm login
-pnpm whoami
-pnpm version patch
+pnpm install
 pnpm run lint
 pnpm run typecheck
 pnpm run test
 pnpm run build
 ```
 
-Then publish from GitHub by either:
-
-- creating a GitHub Release, or
-- running the `Publish` workflow manually from the Actions tab
-
-After trusted publishing is working, you can tighten npm package security by disabling token-based publishing for the package in npm settings.
-
-## Limitations
-
-- Claude slash commands and skills come primarily from filesystem discovery; SDK probing is available but optional.
-- Session state is local to the repo under `.claude-manager/` and is ignored by git.
-- The strongest team continuity comes when engineers are spawned from the active `cto` session; the plugin maps named engineers back to that active team automatically.
-- Context tracking is heuristic-based; actual SDK context usage may differ slightly.
-
-## Scripts
-
-- `pnpm run build`
-- `pnpm run typecheck`
-- `pnpm run lint`
-- `pnpm run format`
-- `pnpm run test`
+`dist/` is generated output. Do not edit it directly.

package/dist/claude/claude-agent-sdk-adapter.js

@@ -120,7 +120,7 @@ export class ClaudeAgentSdkAdapter {
     async getTranscript(sessionId, cwd) {
         const messages = await this.sdkFacade.getSessionMessages(sessionId, cwd ? { dir: cwd } : undefined);
         return messages.map((message) => ({
-            role: message.type,
+            role: message.type === 'user' ? 'user' : 'assistant',
             sessionId: message.session_id,
             messageId: message.uuid,
             text: extractText(message.message),

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from '@opencode-ai/plugin';
 import { ClaudeManagerPlugin } from './plugin/claude-manager.plugin.js';
-export type { ClaudeCapabilitySnapshot, ClaudeSessionRunResult, ClaudeSessionSummary, ClaudeSessionTranscriptMessage, ManagerPromptRegistry, RunClaudeSessionInput, SessionContextSnapshot, GitDiffResult, GitOperationResult, ContextWarningLevel, SessionMode, EngineerName, EngineerWorkMode, EngineerFailureKind, EngineerFailureResult, WrapperHistoryEntry, TeamEngineerRecord, TeamRecord, EngineerTaskResult, PlanDraft, SynthesizedPlanResult, ToolApprovalRule, ToolApprovalPolicy, ToolApprovalDecision, } from './types/contracts.js';
+export type { ClaudeCapabilitySnapshot, ClaudeSessionRunResult, ClaudeSessionSummary, ClaudeSessionTranscriptMessage, ManagerPromptRegistry, RunClaudeSessionInput, SessionContextSnapshot, GitDiffResult, GitOperationResult, ContextWarningLevel, SessionMode, EngineerName, EngineerWorkMode, EngineerFailureKind, EngineerFailureResult, WrapperHistoryEntry, AgentMessageStatus, AgentMessage, TeamEngineerRecord, TeamRecord, EngineerTaskResult, PlanDraft, SynthesizedPlanResult, ToolApprovalRule, ToolApprovalPolicy, ToolApprovalDecision, } from './types/contracts.js';
 export { ClaudeManagerPlugin };
 export declare const plugin: Plugin;

package/dist/manager/team-orchestrator.js

@@ -223,7 +223,7 @@ export class TeamOrchestrator {
     }
     static classifyError(error) {
         const message = error instanceof Error ? error.message : String(error);
-        let failureKind = 'unknown';
+        let failureKind;
         if (message.includes('already working on another assignment')) {
             failureKind = 'engineerBusy';
         }

package/dist/plugin/agents/common.d.ts

@@ -11,8 +11,8 @@ export declare const ENGINEER_AGENT_IDS: {
 };
 /** General named engineers only (Tom/John/Maya/Sara/Alex). BrowserQA is a specialist registered separately. */
 export declare const ENGINEER_AGENT_NAMES: readonly ["Tom", "John", "Maya", "Sara", "Alex"];
-export declare const CTO_ONLY_TOOL_IDS: readonly ["team_status", "reset_engineer", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update"];
-export declare const ALL_RESTRICTED_TOOL_IDS: readonly ["team_status", "reset_engineer", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update", "claude"];
+export declare const CTO_ONLY_TOOL_IDS: readonly ["team_status", "reset_engineer", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update", "inspect_team_inbox"];
+export declare const ALL_RESTRICTED_TOOL_IDS: readonly ["team_status", "reset_engineer", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update", "inspect_team_inbox", "claude"];
 export type ToolPermission = 'allow' | 'ask' | 'deny';
 export type AgentPermission = {
     '*'?: ToolPermission;

package/dist/plugin/agents/common.js

@@ -25,6 +25,7 @@ export const CTO_ONLY_TOOL_IDS = [
     'approval_policy',
     'approval_decisions',
     'approval_update',
+    'inspect_team_inbox',
 ];
 const ENGINEER_TOOL_IDS = ['claude'];
 export const ALL_RESTRICTED_TOOL_IDS = [...CTO_ONLY_TOOL_IDS, ...ENGINEER_TOOL_IDS];
@@ -50,6 +51,10 @@ export function buildEngineerPermissions() {
         '*': 'deny',
         ...denied,
         claude: 'allow',
+        send_message: 'allow',
+        list_inbox: 'allow',
+        get_message: 'allow',
+        ack_message: 'allow',
     };
 }
 export function denyRestrictedToolsGlobally(permissions) {

package/dist/plugin/claude-manager.plugin.js

@@ -4,6 +4,7 @@ import { appendDebugLog } from '../util/fs-helpers.js';
 import { isEngineerName } from '../team/roster.js';
 import { TeamOrchestrator, createActionableError, getFailureGuidanceText, } from '../manager/team-orchestrator.js';
 import { AGENT_BROWSER_QA, AGENT_CTO, AGENT_TEAM_PLANNER, buildBrowserQaAgentConfig, buildCtoAgentConfig, buildEngineerAgentConfig, buildTeamPlannerAgentConfig, denyRestrictedToolsGlobally, ENGINEER_AGENT_IDS, ENGINEER_AGENT_NAMES, } from './agents/index.js';
+import { ackMessage, buildInboxNotice, getMessage, getUnreadCount, listAllInboxes, listInbox, sendMessage, } from './inbox-ops.js';
 import { clearLatestRevertProcessed, clearRevertProcessed, getOrCreatePluginServices, getParentSessionId, getSessionTeam, getWrapperSessionMapping, isRevertAlreadyProcessed, markRevertProcessed, registerParentSession, registerSessionTeam, setWrapperSessionMapping, } from './service-factory.js';
 const MODEL_ENUM = ['claude-opus-4-6', 'claude-sonnet-4-6'];
 const MODE_ENUM = ['explore', 'implement', 'verify'];
@@ -314,6 +315,14 @@ export const ClaudeManagerPlugin = async ({ worktree, client }) => {
             if (wrapperContext) {
                 output.system.push(wrapperContext);
             }
+            // Inject inbox notice if the engineer has unread peer messages.
+            const team = await services.teamStore.getTeam(worktree, mapping.teamId);
+            if (team) {
+                const unreadCount = getUnreadCount(team, mapping.workerName);
+                if (unreadCount > 0) {
+                    output.system.push(buildInboxNotice(unreadCount));
+                }
+            }
         },
         tool: {
             claude: tool({
@@ -436,6 +445,101 @@ export const ClaudeManagerPlugin = async ({ worktree, client }) => {
                     return JSON.stringify({ reset: true, engineer: engineer ?? args.engineer }, null, 2);
                 },
             }),
+            send_message: tool({
+                description: 'Send a peer message to another engineer on your team. Use this for requests, questions, and recommendations — not to assign work (only CTO assigns work). Reference files by path using the filePaths arg — never paste file contents. Supply replyToId when replying to keep thread context (reply chains are capped at 5 deep; loop in the CTO if deeper coordination is needed). If you receive conflicting guidance from multiple peers, stop and ask the CTO for direction.',
+                args: {
+                    to: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex', 'BrowserQA']),
+                    subject: tool.schema.string().min(1),
+                    body: tool.schema.string().min(1),
+                    filePaths: tool.schema.string().array().optional(),
+                    replyToId: tool.schema.string().optional(),
+                },
+                async execute(args, context) {
+                    const engineer = engineerFromAgent(context.agent);
+                    const existing = getWrapperSessionMapping(context.worktree, context.sessionID);
+                    const persisted = existing ??
+                        (await services.orchestrator.findTeamByWrapperSession(context.worktree, context.sessionID));
+                    const teamId = persisted?.teamId ?? (await resolveTeamId(context.sessionID));
+                    annotateToolRun(context, `${engineer} → send_message to ${args.to}`, { teamId });
+                    const result = await sendMessage(services.teamStore, context.worktree, teamId, engineer, args.to, args.subject, args.body, { filePaths: args.filePaths, replyToId: args.replyToId });
+                    return JSON.stringify(result, null, 2);
+                },
+            }),
+            list_inbox: tool({
+                description: 'List your unread peer messages (ID, sender, subject, timestamp). Use get_message to read a full message body.',
+                args: {},
+                async execute(_args, context) {
+                    const engineer = engineerFromAgent(context.agent);
+                    const existing = getWrapperSessionMapping(context.worktree, context.sessionID);
+                    const persisted = existing ??
+                        (await services.orchestrator.findTeamByWrapperSession(context.worktree, context.sessionID));
+                    const teamId = persisted?.teamId ?? (await resolveTeamId(context.sessionID));
+                    annotateToolRun(context, `${engineer} → list_inbox`, { teamId });
+                    const messages = await listInbox(services.teamStore, context.worktree, teamId, engineer);
+                    const summaries = messages.map(({ id, fromEngineer, subject, createdAt, depth, replyToId, filePaths }) => ({
+                        id,
+                        from: fromEngineer,
+                        subject,
+                        createdAt,
+                        depth,
+                        ...(replyToId !== undefined && { replyToId }),
+                        ...(filePaths !== undefined && filePaths.length > 0 && { filePaths }),
+                    }));
+                    return JSON.stringify({ count: summaries.length, messages: summaries }, null, 2);
+                },
+            }),
+            get_message: tool({
+                description: 'Read the full body of a peer message by its ID.',
+                args: {
+                    messageId: tool.schema.string().min(1),
+                },
+                async execute(args, context) {
+                    const engineer = engineerFromAgent(context.agent);
+                    const existing = getWrapperSessionMapping(context.worktree, context.sessionID);
+                    const persisted = existing ??
+                        (await services.orchestrator.findTeamByWrapperSession(context.worktree, context.sessionID));
+                    const teamId = persisted?.teamId ?? (await resolveTeamId(context.sessionID));
+                    annotateToolRun(context, `${engineer} → get_message`, { teamId, messageId: args.messageId });
+                    const message = await getMessage(services.teamStore, context.worktree, teamId, engineer, args.messageId);
+                    if (!message) {
+                        return JSON.stringify({ error: 'Message not found.' });
+                    }
+                    return JSON.stringify(message, null, 2);
+                },
+            }),
+            ack_message: tool({
+                description: 'Acknowledge a peer message to hide it from your inbox. The message is retained for CTO inspection but will not appear in future list_inbox results.',
+                args: {
+                    messageId: tool.schema.string().min(1),
+                },
+                async execute(args, context) {
+                    const engineer = engineerFromAgent(context.agent);
+                    const existing = getWrapperSessionMapping(context.worktree, context.sessionID);
+                    const persisted = existing ??
+                        (await services.orchestrator.findTeamByWrapperSession(context.worktree, context.sessionID));
+                    const teamId = persisted?.teamId ?? (await resolveTeamId(context.sessionID));
+                    annotateToolRun(context, `${engineer} → ack_message`, { teamId, messageId: args.messageId });
+                    const ok = await ackMessage(services.teamStore, context.worktree, teamId, engineer, args.messageId);
+                    return JSON.stringify({ acked: ok }, null, 2);
+                },
+            }),
+            inspect_team_inbox: tool({
+                description: 'Read all peer messages across all engineers on the team, including acked messages. Optionally filter by engineer.',
+                args: {
+                    teamId: tool.schema.string().optional(),
+                    engineer: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex', 'BrowserQA']).optional(),
+                },
+                async execute(args, context) {
+                    const teamId = args.teamId ?? context.sessionID;
+                    annotateToolRun(context, 'Inspecting team inbox', { teamId, engineer: args.engineer });
+                    const team = await services.orchestrator.getOrCreateTeam(context.worktree, teamId);
+                    const allInboxes = listAllInboxes(team);
+                    if (args.engineer) {
+                        return JSON.stringify({ [args.engineer]: allInboxes[args.engineer] ?? [] }, null, 2);
+                    }
+                    return JSON.stringify(allInboxes, null, 2);
+                },
+            }),
             git_diff: tool({
                 description: 'Show diff of uncommitted changes. Use paths to filter to specific files or use ref to compare against another branch, tag, or commit.',
                 args: {

package/dist/plugin/inbox-ops.d.ts

@@ -0,0 +1,50 @@
+import type { AgentMessage, EngineerName, TeamRecord } from '../types/contracts.js';
+import type { TeamStateStore } from '../state/team-state-store.js';
+export declare const MAX_INBOX_SIZE = 50;
+export declare const MAX_MESSAGE_BODY_LENGTH = 4000;
+export declare const MAX_MESSAGE_SUBJECT_LENGTH = 200;
+/**
+ * Maximum reply-chain depth. A top-level message has depth 0; each reply
+ * increments by 1. Attempts to exceed this cap are rejected with a message
+ * directing the agent to loop in the CTO.
+ */
+export declare const MAX_THREAD_DEPTH = 5;
+export type SendMessageResult = {
+    ok: true;
+    message: AgentMessage;
+} | {
+    ok: false;
+    error: string;
+};
+export interface SendMessageOptions {
+    /** File paths referenced in the message. Paths only — contents are never embedded. */
+    filePaths?: string[];
+    /**
+     * ID of the message being replied to. Must be a message in the sender's own inbox.
+     * Providing this increments the thread depth and enforces the MAX_THREAD_DEPTH cap.
+     */
+    replyToId?: string;
+}
+/**
+ * Deliver a peer message from one engineer to another on the same team.
+ * All validation and persistence happen atomically via the write queue.
+ */
+export declare function sendMessage(store: TeamStateStore, cwd: string, teamId: string, fromEngineer: EngineerName, toEngineer: EngineerName, subject: string, body: string, options?: SendMessageOptions): Promise<SendMessageResult>;
+/**
+ * Return all unread messages for an engineer, in FIFO order.
+ * Acked messages are excluded.
+ */
+export declare function listInbox(store: TeamStateStore, cwd: string, teamId: string, engineerName: EngineerName): Promise<AgentMessage[]>;
+/** Fetch a single message by ID. Returns null if not found or if it belongs to a different engineer. */
+export declare function getMessage(store: TeamStateStore, cwd: string, teamId: string, engineerName: EngineerName, messageId: string): Promise<AgentMessage | null>;
+/**
+ * Mark a message as acked (hidden from list_inbox).
+ * Returns true if the ack was applied, false if the message was not found or already acked.
+ */
+export declare function ackMessage(store: TeamStateStore, cwd: string, teamId: string, engineerName: EngineerName, messageId: string): Promise<boolean>;
+/** Count unread messages for one engineer without hitting the store. */
+export declare function getUnreadCount(team: TeamRecord, engineerName: EngineerName): number;
+/** Build a concise notice to inject into the engineer's system prompt. */
+export declare function buildInboxNotice(unreadCount: number): string;
+/** Return all inboxes on a team (including acked messages) for CTO inspection. */
+export declare function listAllInboxes(team: TeamRecord): Record<string, AgentMessage[]>;