@doingdev/opencode-claude-manager-plugin 0.1.22 → 0.1.26

package/README.md

@@ -1,43 +1,36 @@
-# OpenCode Claude Code Subagents Plugin
+# OpenCode Claude Manager Plugin
 
-Thin OpenCode orchestrator plugin with Claude Code specialist subagents.
+This package provides an OpenCode plugin that lets an OpenCode-side agent hierarchy orchestrate Claude Code sessions through a stable local bridge.
 
 ## Overview
 
-This plugin turns OpenCode into a lightweight orchestrator that delegates coding work to Claude Code specialists. Instead of a monolithic manager with custom tools, it registers:
+Use this when you want OpenCode to act as a manager over Claude Code instead of talking to Claude directly. The plugin gives OpenCode a stable tool surface for delegating work to Claude Code sessions, managing session lifecycle (compact, clear, fresh start), reviewing changes via git, and inspecting session history.
 
-- **1 orchestrator agent** (`opencode-orchestrator`) — runs on the user's default OpenCode model, gathers context, and delegates to specialists.
-- **4 Claude Code subagents** — planning and build specialists, each available in Opus and Sonnet variants.
-- **1 provider** (`claude-code`) — backed by [`ai-sdk-provider-claude-code`](https://ai-sdk.dev/providers/community-providers/claude-code).
+## Features
 
-No custom tools are exposed. The orchestrator uses only OpenCode's built-in tools (read, grep, glob, list, webfetch, question, todowrite, todoread, task) and delegates actual coding to Claude Code subagents.
-
-## Architecture
-
-```
-User → OpenCode Orchestrator (user's model)
-           ├── claude-code-planning-opus    (claude-code/opus)
-           ├── claude-code-planning-sonnet  (claude-code/sonnet)
-           ├── claude-code-build-opus       (claude-code/opus)
-           └── claude-code-build-sonnet     (claude-code/sonnet)
-```
-
-**Planning agents** are positioned for investigation, architecture, and plans.
-**Build agents** are positioned for implementation, testing, and validation.
+- Runs Claude Code tasks from OpenCode through `@anthropic-ai/claude-agent-sdk`.
+- Persistent sessions with `freshSession`, model, and effort controls for safe task isolation.
+- Context lifecycle: compact (preserve state) or clear (start fresh).
+- 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.
+- Optionally persists manager run records under `.claude-manager/runs` for post-hoc inspection (populated when tasks are executed through the run-tracking path).
 
 ## Requirements
 
 - Node `22+`
 - OpenCode with plugin loading enabled
-- Claude Code available on the machine (the `ai-sdk-provider-claude-code` provider connects to it)
+- Access to Claude Code / Claude Agent SDK on the machine where OpenCode is running
 
 ## Installation
 
+Install from the npm registry:
+
 ```bash
 pnpm add @doingdev/opencode-claude-manager-plugin
 ```
 
-Or for local development:
+Or for local development in this repo:
 
 ```bash
 pnpm install
@@ -46,38 +39,89 @@ pnpm run build
 
 ## OpenCode Config
 
+Add the plugin to your OpenCode config:
+
 ```json
 {
   "plugin": ["@doingdev/opencode-claude-manager-plugin"]
 }
 ```
 
-## Agents
+If you are testing locally, point OpenCode at the local package or plugin file using your normal local plugin workflow.
 
-| Agent                         | Model                | Mode     | Role                                                      |
-| ----------------------------- | -------------------- | -------- | --------------------------------------------------------- |
-| `opencode-orchestrator`       | user's default       | primary  | CTO-level orchestrator; gathers context, delegates coding |
-| `claude-code-planning-opus`   | `claude-code/opus`   | subagent | Investigation, architecture, planning                     |
-| `claude-code-planning-sonnet` | `claude-code/sonnet` | subagent | Lighter investigation and planning                        |
-| `claude-code-build-opus`      | `claude-code/opus`   | subagent | Implementation and validation                             |
-| `claude-code-build-sonnet`    | `claude-code/sonnet` | subagent | Lighter implementation tasks                              |
+## OpenCode tools
 
-## Bash Safety
+### Engineer session
 
-A minimal safety layer enforces deny rules via the `permission.ask` hook:
+- `engineer_send` — send a message to the persistent Claude Code session. Auto-creates on first call, resumes on subsequent calls.
+  - `message` (required) — the instruction to send.
+  - `mode` — `"plan"` (read-only investigation) or `"free"` (default, normal execution with edits).
+  - `freshSession` — set to `true` to clear the active session before sending. Use when switching to an unrelated task or when context is contaminated.
+  - `model` — `"claude-opus-4-6"` (default, recommended for most coding work), `"claude-sonnet-4-6"`, or `"claude-sonnet-4-5"` (faster/lighter tasks).
+  - `effort` — `"high"` (default), `"medium"` (lighter tasks), `"low"`, or `"max"` (especially hard problems).
+- `engineer_compact` — compress the active session context while preserving session state. Use before clearing when context is high but salvageable.
+- `engineer_clear` — drop the active session entirely; next send starts fresh.
+- `engineer_status` — get current session health: context %, turns, cost, session ID.
 
-- `rm -rf /` — denied
-- `git push --force` — denied
-- `git reset --hard` — denied
-- All other bash commands — allowed (including `pnpm test`, `pnpm lint`, `pnpm build`, etc.)
+### Git operations
 
-## Limitations
+- `git_diff` — review all uncommitted changes (staged + unstaged).
+- `git_commit` — stage all changes and commit with a message.
+- `git_reset` — hard reset + clean (destructive).
+
+### Inspection
+
+- `engineer_metadata` — inspect available Claude commands, skills, hooks, and settings.
+- `engineer_sessions` — list Claude sessions or inspect a saved transcript.
+- `engineer_runs` — list or inspect persisted manager run records (may be empty if tasks were sent directly via `engineer_send` rather than the run-tracking path).
+
+### Tool approval
+
+- `approval_policy` — view the current tool approval policy.
+- `approval_decisions` — view recent tool approval decisions.
+- `approval_update` — add/remove rules, change default action, or enable/disable approval.
+
+## Agent hierarchy
+
+The plugin registers a CTO → Manager → Engineer hierarchy through the OpenCode plugin `config` hook:
+
+- **`cto`** (primary agent) — sets direction and orchestrates work by spawning `manager` subagents. Has read/search/web tools but does NOT operate Claude Code directly.
+- **`manager`** (subagent) — operates a Claude Code engineer through a persistent session. Has the full tool surface (`engineer_*`, `git_*`, `approval_*`) plus read/search/web tools for investigation.
+- **Engineer** — the Claude Code persistent session itself (not an OpenCode agent). Receives instructions from the manager, executes code changes, and reports results.
+
+These are added to OpenCode config at runtime by the plugin, so they do not require separate manual `opencode.json` entries.
+
+## Quick Start
+
+Typical flow inside OpenCode:
+
+1. Inspect Claude capabilities with `engineer_metadata`.
+2. Delegate work with `engineer_send`.
+3. Review changes with `git_diff`, then commit or reset.
+4. Inspect saved Claude history with `engineer_sessions` or prior orchestration records with `engineer_runs`.
+
+Example tasks:
+
+```text
+Use engineer_send to implement the new validation logic in src/auth.ts, then review with git_diff.
+```
+
+Start a fresh session for an unrelated task:
+
+```text
+Use engineer_send with freshSession:true to investigate the failing CI test in test/api.test.ts using mode:"plan".
+```
+
+Reclaim context mid-session:
 
-- Claude Code `effort` is not currently configurable through OpenCode provider/model options. The subagent prompts compensate by setting high-quality expectations directly.
-- The `ai-sdk-provider-claude-code` community provider must be available for the Claude Code subagents to function.
+```text
+Use engineer_compact to free up context, then continue with the next implementation step.
+```
 
 ## Local Development
 
+Clone the repo and run:
+
 ```bash
 pnpm install
 pnpm run lint
@@ -86,9 +130,54 @@ pnpm run test
 pnpm run build
 ```
 
+The compiled plugin output is written to `dist/`.
+
 ## Publishing
 
-This package is configured for the npm scope `@doingdev`. See the GitHub Actions workflow for automated publishing via npm trusted publishing.
+This package is configured for the npm scope `@doingdev`.
+
+This repository uses npm trusted publishing with GitHub Actions OIDC, so you do not need an `NPM_TOKEN` secret once npm is configured correctly.
+
+Before the first automated publish, configure npm trusted publishing for `@doingdev/opencode-claude-manager-plugin` on npmjs.com:
+
+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.
+
+Notes for trusted publishing:
+
+- 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.
+
+Release flow:
+
+```bash
+pnpm login
+pnpm whoami
+pnpm version patch
+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.
+- Context tracking is heuristic-based; actual SDK context usage may differ slightly.
 
 ## Scripts
 

package/dist/claude/claude-agent-sdk-adapter.d.ts

@@ -0,0 +1,27 @@
+import { type Options, type Query, type SDKSessionInfo, type SessionMessage, type SettingSource } from '@anthropic-ai/claude-agent-sdk';
+import type { ClaudeCapabilitySnapshot, ClaudeSessionEvent, ClaudeSessionRunResult, ClaudeSessionSummary, ClaudeSessionTranscriptMessage, RunClaudeSessionInput } from '../types/contracts.js';
+import type { ToolApprovalManager } from './tool-approval-manager.js';
+export type ClaudeSessionEventHandler = (event: ClaudeSessionEvent) => void | Promise<void>;
+interface ClaudeAgentSdkFacade {
+    query(params: {
+        prompt: string;
+        options?: Options;
+    }): Query;
+    listSessions(options?: {
+        dir?: string;
+    }): Promise<SDKSessionInfo[]>;
+    getSessionMessages(sessionId: string, options?: {
+        dir?: string;
+    }): Promise<SessionMessage[]>;
+}
+export declare class ClaudeAgentSdkAdapter {
+    private readonly sdkFacade;
+    private readonly approvalManager?;
+    constructor(sdkFacade?: ClaudeAgentSdkFacade, approvalManager?: ToolApprovalManager | undefined);
+    runSession(input: RunClaudeSessionInput, onEvent?: ClaudeSessionEventHandler): Promise<ClaudeSessionRunResult>;
+    listSavedSessions(cwd?: string): Promise<ClaudeSessionSummary[]>;
+    getTranscript(sessionId: string, cwd?: string): Promise<ClaudeSessionTranscriptMessage[]>;
+    probeCapabilities(cwd: string, settingSources?: SettingSource[]): Promise<ClaudeCapabilitySnapshot>;
+    private buildOptions;
+}
+export {};