@doingdev/opencode-claude-manager-plugin 0.1.21 → 0.1.25

package/dist/plugin/orchestrator.plugin.js

@@ -3,7 +3,7 @@ import { evaluateBashCommand, extractBashCommand, } from '../safety/bash-safety.
 /**
  * Thin OpenCode orchestrator plugin with Claude Code specialist subagents.
  *
- * - Registers `claude-code` provider via ai-sdk-provider-claude-code.
+ * - Registers `claude-code` provider via a local shim over ai-sdk-provider-claude-code.
  * - Creates one orchestrator agent (uses the user's default OpenCode model).
  * - Creates 4 Claude Code subagents: planning + build × opus + sonnet.
  * - Enforces bash safety via the permission.ask hook.
@@ -12,14 +12,20 @@ import { evaluateBashCommand, extractBashCommand, } from '../safety/bash-safety.
  * options at this time. The subagent prompts compensate by setting high-quality
  * expectations directly.
  */
+// Resolve the shim path at module load time so it is stable for the lifetime
+// of the process. The compiled output for this file sits at dist/plugin/ and
+// the shim at dist/providers/, so we walk up one level.
+const claudeCodeShimUrl = new URL('../providers/claude-code-wrapper.js', import.meta.url).href;
 export const OrchestratorPlugin = async () => {
     return {
         config: async (config) => {
             config.provider ??= {};
             config.agent ??= {};
             // ── Provider ──────────────────────────────────────────────────────
+            // Uses a file:// shim so OpenCode's factory-finder heuristic sees only
+            // createClaudeCode and not createAPICallError from the upstream package.
             config.provider['claude-code'] ??= {
-                npm: 'ai-sdk-provider-claude-code',
+                npm: claudeCodeShimUrl,
                 models: {
                     opus: {
                         id: 'opus',
@@ -54,9 +60,11 @@ export const OrchestratorPlugin = async () => {
                 },
             };
             // ── Planning subagents ────────────────────────────────────────────
+            // Claude Code tools (Bash, Read, Write, Edit, …) are executed internally
+            // by the claude CLI subprocess and streamed back with providerExecuted:true.
+            // OpenCode's own tools must not be advertised to these agents.
             const claudeCodePermissions = {
-                '*': 'allow',
-                bash: 'allow',
+                '*': 'deny',
             };
             config.agent['claude-code-planning-opus'] ??= {
                 description: 'Claude Code Opus specialist for investigation, architecture, and planning.',

package/dist/plugin/service-factory.d.ts

@@ -0,0 +1,12 @@
+import { ClaudeSessionService } from '../claude/claude-session.service.js';
+import { SessionLiveTailer } from '../claude/session-live-tailer.js';
+import { ToolApprovalManager } from '../claude/tool-approval-manager.js';
+import { PersistentManager } from '../manager/persistent-manager.js';
+interface ClaudeManagerPluginServices {
+    manager: PersistentManager;
+    sessions: ClaudeSessionService;
+    approvalManager: ToolApprovalManager;
+    liveTailer: SessionLiveTailer;
+}
+export declare function getOrCreatePluginServices(worktree: string): ClaudeManagerPluginServices;
+export {};

package/dist/plugin/service-factory.js

@@ -0,0 +1,41 @@
+import { ClaudeAgentSdkAdapter } from '../claude/claude-agent-sdk-adapter.js';
+import { ClaudeSessionService } from '../claude/claude-session.service.js';
+import { SessionLiveTailer } from '../claude/session-live-tailer.js';
+import { ToolApprovalManager } from '../claude/tool-approval-manager.js';
+import { ClaudeMetadataService } from '../metadata/claude-metadata.service.js';
+import { RepoClaudeConfigReader } from '../metadata/repo-claude-config-reader.js';
+import { FileRunStateStore } from '../state/file-run-state-store.js';
+import { TranscriptStore } from '../state/transcript-store.js';
+import { ContextTracker } from '../manager/context-tracker.js';
+import { GitOperations } from '../manager/git-operations.js';
+import { SessionController } from '../manager/session-controller.js';
+import { PersistentManager } from '../manager/persistent-manager.js';
+import { managerPromptRegistry } from '../prompts/registry.js';
+const serviceCache = new Map();
+export function getOrCreatePluginServices(worktree) {
+    const cachedServices = serviceCache.get(worktree);
+    if (cachedServices) {
+        return cachedServices;
+    }
+    const approvalManager = new ToolApprovalManager();
+    const sdkAdapter = new ClaudeAgentSdkAdapter(undefined, approvalManager);
+    const metadataService = new ClaudeMetadataService(new RepoClaudeConfigReader(), sdkAdapter);
+    const sessionService = new ClaudeSessionService(sdkAdapter, metadataService);
+    const contextTracker = new ContextTracker();
+    const sessionController = new SessionController(sdkAdapter, contextTracker, managerPromptRegistry.claudeCodeSessionPrompt, managerPromptRegistry.modePrefixes);
+    const gitOps = new GitOperations(worktree);
+    const stateStore = new FileRunStateStore();
+    const transcriptStore = new TranscriptStore();
+    const manager = new PersistentManager(sessionController, gitOps, stateStore, contextTracker, transcriptStore);
+    // Try to restore active session state (fire and forget)
+    manager.tryRestore(worktree).catch(() => { });
+    const liveTailer = new SessionLiveTailer();
+    const services = {
+        manager,
+        sessions: sessionService,
+        approvalManager,
+        liveTailer,
+    };
+    serviceCache.set(worktree, services);
+    return services;
+}

package/dist/prompts/registry.d.ts

@@ -1,8 +1,2 @@
-/**
- * Agent prompt registry for the orchestrator + Claude Code subagent architecture.
- */
-export declare const prompts: {
-    orchestrator: string;
-    planningAgent: string;
-    buildAgent: string;
-};
+import type { ManagerPromptRegistry } from '../types/contracts.js';
+export declare const managerPromptRegistry: ManagerPromptRegistry;

package/dist/prompts/registry.js

@@ -1,37 +1,166 @@
-/**
- * Agent prompt registry for the orchestrator + Claude Code subagent architecture.
- */
-export const prompts = {
-    orchestrator: [
-        'You are the orchestrator — a CTO-level proxy for the user.',
-        'Your job is to gather minimal context, then delegate coding work to specialist Claude Code agents.',
-        '',
-        '## Rules',
-        '- Do NOT write or edit code yourself unless the user explicitly asks you to.',
-        '- Read files, search, and plan to understand the task, then delegate.',
-        '- Use planning agents (claude-code-planning-opus/sonnet) for investigation, architecture, and plans.',
-        '- Use build agents (claude-code-build-opus/sonnet) for implementation and validation.',
-        '- Run specialists in parallel when tasks are independent.',
-        '- Compare outputs from multiple specialists when the choice matters.',
-        '- Keep delegations focused: one clear objective per specialist call.',
-        '- Track multi-step work with todowrite/todoread.',
-        '- Ask the user (via question tool) when trade-offs need human judgment.',
-    ].join('\n'),
-    planningAgent: [
-        'You are a planning specialist. Investigate, analyze architecture, and produce implementation plans.',
+export const managerPromptRegistry = {
+    managerSystemPrompt: [
+        'You are a senior IC operating Claude Code through a persistent session.',
+        'Your job is to make Claude Code do the work — not to write code yourself.',
+        'Think like a staff engineer: correctness, maintainability, tests, rollback safety,',
+        'and clear communication to the user.',
+        '',
+        '## Decision loop',
+        'On every turn, choose exactly one action:',
+        '  investigate — read files, grep, search the codebase to build context',
+        '  delegate   — send a focused instruction to Claude Code via claude_manager_send',
+        '  review     — run claude_manager_git_diff to inspect what changed',
+        '  validate   — tell Claude Code to run tests, lint, or typecheck',
+        '  commit     — checkpoint good work with claude_manager_git_commit',
+        '  correct    — send a targeted fix instruction (never "try again")',
+        '  reset      — discard bad work with claude_manager_git_reset',
+        '  ask        — use the question tool for structured choices, or one narrow text question',
+        '',
+        'Default order: investigate → delegate → review → validate → commit.',
+        'Skip steps only when you have strong evidence they are unnecessary.',
+        '',
+        '## Before you delegate',
+        '1. Read the relevant files yourself (you have read, grep, glob).',
+        '   For broad investigations, scope them narrowly or use subagents to avoid',
+        '   polluting your own context with excessive file contents.',
+        '2. Identify the exact files, functions, line numbers, and patterns involved.',
+        '3. Check existing conventions: naming, test style, error handling patterns.',
+        '4. Craft an instruction that a senior engineer would find unambiguous.',
+        '   Bad:  "Fix the auth bug"',
+        '   Good: "In src/auth/session.ts, the `validateToken` function (line 42)',
+        '          throws on expired tokens instead of returning null. Change it to',
+        '          return null and update the caller in src/routes/login.ts:87."',
+        '',
+        '## After delegation — mandatory review',
+        'Never claim success without evidence:',
+        '1. claude_manager_git_diff — read the actual diff, not just the summary.',
+        '2. Verify the diff matches what you asked for. Check for:',
+        '   - Unintended changes or regressions',
+        '   - Missing test updates',
+        '   - Style violations against repo conventions',
+        '3. If changes look correct, tell Claude Code to run tests/lint/typecheck.',
+        '4. Only commit after verification passes.',
+        '5. If the diff is wrong: send a specific correction or reset.',
+        '',
+        '## Handling ambiguity',
+        'When requirements are unclear:',
+        '1. First, try to resolve it yourself — read code, check tests, grep for usage.',
+        '2. If ambiguity remains, ask the user ONE specific question.',
+        '   Prefer the question tool when discrete options exist (OpenCode shows choices in the UI).',
+        '   Bad:  "What should I do?"',
+        '   Good: "The `UserService` has both `deactivate()` and `softDelete()` —',
+        '          should the new endpoint use deactivation (reversible) or',
+        '          soft-delete (audit-logged)?"',
+        '3. Never block on multiple questions at once.',
+        '',
+        '## Correction and recovery',
+        'If Claude Code produces wrong output:',
+        '1. First correction: send a specific, targeted fix instruction.',
+        '2. Second correction on the same issue: reset, clear the session,',
+        '   and rewrite the prompt incorporating lessons from both failures.',
+        'Never send three corrections for the same problem in one session.',
+        '',
+        '## Multi-step tasks',
+        '- Use todowrite / todoread to track steps in OpenCode; keep items concrete and few.',
+        '- Decompose large tasks into sequential focused instructions.',
+        '- Commit after each successful step (checkpoint for rollback).',
+        '- Tell Claude Code to use subagents for independent parallel work.',
+        '- For complex design decisions, tell Claude Code to "think hard".',
+        '- Prefer small diffs — they are easier to review and safer to ship.',
         '',
-        '- Read code, grep, search — build full context before answering.',
-        '- Produce concrete plans: files to change, functions to modify, test strategy, risks.',
-        '- Do NOT edit files or run destructive commands unless explicitly asked.',
-        '- Be concise. End with a numbered action plan.',
+        '## Context management',
+        'Check the context snapshot returned by each send:',
+        '- Under 50%: proceed freely.',
+        '- 50–70%: finish current step, then evaluate if a fresh session is needed.',
+        '- Over 70%: use claude_manager_compact to reclaim context if the session',
+        '  still has useful state. Only clear if compaction is insufficient.',
+        '- Over 85%: clear the session immediately.',
+        'Use freshSession:true on claude_manager_send when switching to an unrelated',
+        'task or when the session context is contaminated. Prefer this over a manual',
+        'clear+send sequence — it is atomic and self-documenting.',
+        '',
+        '## Model and effort selection',
+        'Choose model and effort deliberately before each delegation:',
+        '- claude-opus-4-6 + high effort: default for most coding tasks.',
+        '- claude-sonnet-4-6 or claude-sonnet-4-5: faster/lighter work (simple renames,',
+        '  formatting, test scaffolding, quick investigations).',
+        '- effort "medium": acceptable for lighter tasks that do not require deep reasoning.',
+        '- effort "max": reserve for unusually hard problems (complex refactors,',
+        '  subtle concurrency bugs, large cross-cutting changes).',
+        "- Do not use Haiku for this plugin's coding-agent role.",
+        '',
+        '## Plan mode',
+        'When delegating with mode:"plan", Claude Code returns a read-only',
+        'implementation plan. The plan MUST be returned inline in the assistant',
+        'response — do NOT write plan artifacts to disk, create files, or rely on',
+        'ExitPlanMode. Treat the returned finalText as the plan. If the plan is',
+        'acceptable, switch to mode:"free" and delegate the implementation steps.',
+        '',
+        '## Tools reference',
+        'todowrite / todoread   — OpenCode session todo list (track multi-step work)',
+        'question               — OpenCode user prompt with options (clarify trade-offs)',
+        'claude_manager_send     — send instruction (creates or resumes session)',
+        '  freshSession:true — clear session first (use for unrelated tasks)',
+        '  model / effort — choose deliberately (see "Model and effort selection")',
+        'claude_manager_compact  — compress session context (preserves session state)',
+        'claude_manager_git_diff — review all uncommitted changes',
+        'claude_manager_git_commit — stage all + commit',
+        'claude_manager_git_reset  — hard reset + clean (destructive)',
+        'claude_manager_clear    — drop session, next send starts fresh',
+        'claude_manager_status   — context health snapshot',
+        'claude_manager_metadata — inspect repo Claude config',
+        'claude_manager_sessions — list sessions or read transcripts',
+        'claude_manager_runs     — list or inspect run records',
+        '',
+        '## Autonomy blockers — surface these to the user',
+        'Be candid about what you cannot do autonomously:',
+        '- Credentials, API keys, or secrets you do not have.',
+        '- Architectural decisions with trade-offs the user should weigh.',
+        '- Destructive actions on shared state (deploy, publish, force-push).',
+        '- Access to external services or environments you cannot reach.',
+        'State the blocker, what you need, and a concrete suggestion to unblock.',
     ].join('\n'),
-    buildAgent: [
-        'You are a build specialist. Implement, test, and validate changes.',
+    claudeCodeSessionPrompt: [
+        'You are directed by an expert automated operator.',
+        'Treat each message as a precise instruction from a senior engineer.',
         '',
-        '- Execute instructions precisely. Follow existing repo conventions.',
-        '- Consider edge cases and include relevant tests.',
+        '## Execution rules',
+        '- Execute instructions directly. Do not ask for clarification.',
+        '- Be concise — no preamble, no restating the task.',
+        '- Prefer targeted file reads over reading entire files.',
+        '- Use the Agent tool for independent parallel work.',
+        '',
+        '## Quality expectations',
+        '- Follow existing repo conventions (naming, style, patterns).',
+        '- When creating or modifying code, consider edge cases and error handling.',
+        '- When modifying existing code, preserve surrounding style and structure.',
+        '- If asked to implement a feature, include relevant tests unless told otherwise.',
         '- Run tests/lint/typecheck when instructed; report exact output on failure.',
-        '- Do NOT run git commit, git push, git reset, git checkout, or git stash.',
+        '',
+        '## Git boundary — do NOT run these commands:',
+        'git commit, git push, git reset, git checkout, git stash.',
+        'The operator manages all git operations externally.',
+        '',
+        '## Reporting',
         '- End with a brief verification summary: what was done, what was verified.',
+        '- Report blockers immediately with specifics: file, line, error message.',
+        '- If a task is partially complete, state exactly what remains.',
     ].join('\n'),
+    modePrefixes: {
+        plan: [
+            '[PLAN MODE] You are in read-only planning mode. Do NOT create or edit any files.',
+            'Do NOT use ExitPlanMode or write plan artifacts to disk.',
+            'Use read, grep, glob, and search tools only.',
+            'Analyze the codebase and produce a detailed implementation plan:',
+            'files to change, functions to modify, new files to create, test strategy,',
+            'and potential risks. End with a numbered step-by-step plan.',
+            'Return the entire plan inline in your response text.',
+        ].join(' '),
+        free: '',
+    },
+    contextWarnings: {
+        moderate: 'Session context is filling up ({percent}% estimated). Consider whether a fresh session would be more efficient.',
+        high: 'Session context is heavy ({percent}% estimated, {turns} turns, ${cost}). Start a new session or compact first.',
+        critical: 'Session context is near capacity ({percent}% estimated). Clear the session immediately before continuing.',
+    },
 };

package/dist/providers/claude-code-wrapper.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Thin re-export shim for ai-sdk-provider-claude-code.
+ *
+ * OpenCode's provider loader finds the provider factory by scanning
+ * `Object.keys(module).find(key => key.startsWith("create"))`. The upstream
+ * package exports `createAPICallError` before `createClaudeCode`, so OpenCode
+ * picks the wrong function and `.languageModel` ends up undefined.
+ *
+ * This shim re-exports only `createClaudeCode`, making it the sole "create*"
+ * export. The plugin references this file via a `file://` URL so the upstream
+ * package is still the actual implementation.
+ */
+export { createClaudeCode } from 'ai-sdk-provider-claude-code';

package/dist/providers/claude-code-wrapper.js

@@ -0,0 +1,13 @@
+/**
+ * Thin re-export shim for ai-sdk-provider-claude-code.
+ *
+ * OpenCode's provider loader finds the provider factory by scanning
+ * `Object.keys(module).find(key => key.startsWith("create"))`. The upstream
+ * package exports `createAPICallError` before `createClaudeCode`, so OpenCode
+ * picks the wrong function and `.languageModel` ends up undefined.
+ *
+ * This shim re-exports only `createClaudeCode`, making it the sole "create*"
+ * export. The plugin references this file via a `file://` URL so the upstream
+ * package is still the actual implementation.
+ */
+export { createClaudeCode } from 'ai-sdk-provider-claude-code';

package/dist/state/file-run-state-store.d.ts

@@ -0,0 +1,14 @@
+import type { PersistentRunRecord } from '../types/contracts.js';
+export declare class FileRunStateStore {
+    private readonly baseDirectoryName;
+    private readonly writeQueues;
+    constructor(baseDirectoryName?: string);
+    saveRun(run: PersistentRunRecord): Promise<void>;
+    getRun(cwd: string, runId: string): Promise<PersistentRunRecord | null>;
+    listRuns(cwd: string): Promise<PersistentRunRecord[]>;
+    updateRun(cwd: string, runId: string, update: (run: PersistentRunRecord) => PersistentRunRecord): Promise<PersistentRunRecord>;
+    private getRunKey;
+    private getRunsDirectory;
+    private getRunPath;
+    private enqueueWrite;
+}

package/dist/state/file-run-state-store.js

@@ -0,0 +1,87 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { isFileNotFoundError, writeJsonAtomically, } from '../util/fs-helpers.js';
+export class FileRunStateStore {
+    baseDirectoryName;
+    writeQueues = new Map();
+    constructor(baseDirectoryName = '.claude-manager') {
+        this.baseDirectoryName = baseDirectoryName;
+    }
+    async saveRun(run) {
+        await this.enqueueWrite(this.getRunKey(run.cwd, run.id), async () => {
+            const runPath = this.getRunPath(run.cwd, run.id);
+            await fs.mkdir(path.dirname(runPath), { recursive: true });
+            await writeJsonAtomically(runPath, run);
+        });
+    }
+    async getRun(cwd, runId) {
+        const runPath = this.getRunPath(cwd, runId);
+        try {
+            const content = await fs.readFile(runPath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (isFileNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async listRuns(cwd) {
+        const runsDirectory = this.getRunsDirectory(cwd);
+        try {
+            const entries = await fs.readdir(runsDirectory);
+            const runs = await Promise.all(entries
+                .filter((entry) => entry.endsWith('.json'))
+                .map(async (entry) => {
+                const content = await fs.readFile(path.join(runsDirectory, entry), 'utf8');
+                return JSON.parse(content);
+            }));
+            return runs.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+        }
+        catch (error) {
+            if (isFileNotFoundError(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async updateRun(cwd, runId, update) {
+        return this.enqueueWrite(this.getRunKey(cwd, runId), async () => {
+            const existingRun = await this.getRun(cwd, runId);
+            if (!existingRun) {
+                throw new Error(`Run ${runId} does not exist.`);
+            }
+            const updatedRun = update(existingRun);
+            const runPath = this.getRunPath(cwd, runId);
+            await fs.mkdir(path.dirname(runPath), { recursive: true });
+            await writeJsonAtomically(runPath, updatedRun);
+            return updatedRun;
+        });
+    }
+    getRunKey(cwd, runId) {
+        return `${cwd}:${runId}`;
+    }
+    getRunsDirectory(cwd) {
+        return path.join(cwd, this.baseDirectoryName, 'runs');
+    }
+    getRunPath(cwd, runId) {
+        return path.join(this.getRunsDirectory(cwd), `${runId}.json`);
+    }
+    async enqueueWrite(key, operation) {
+        const previousOperation = this.writeQueues.get(key) ?? Promise.resolve();
+        const resultPromise = previousOperation
+            .catch(() => undefined)
+            .then(operation);
+        const settledPromise = resultPromise.then(() => undefined, () => undefined);
+        this.writeQueues.set(key, settledPromise);
+        try {
+            return await resultPromise;
+        }
+        finally {
+            if (this.writeQueues.get(key) === settledPromise) {
+                this.writeQueues.delete(key);
+            }
+        }
+    }
+}

package/dist/state/transcript-store.d.ts

@@ -0,0 +1,15 @@
+import type { ClaudeSessionEvent } from '../types/contracts.js';
+export declare class TranscriptStore {
+    private readonly baseDirectoryName;
+    constructor(baseDirectoryName?: string);
+    /**
+     * Append new events to the transcript file for the given session.
+     * Creates the file if it does not exist. Strips trailing partials before persisting.
+     */
+    appendEvents(cwd: string, sessionId: string, newEvents: ClaudeSessionEvent[]): Promise<void>;
+    /**
+     * Read all persisted transcript events for a session.
+     */
+    readEvents(cwd: string, sessionId: string): Promise<ClaudeSessionEvent[]>;
+    private getTranscriptPath;
+}

package/dist/state/transcript-store.js

@@ -0,0 +1,44 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { appendTranscriptEvents, stripTrailingPartials, } from '../util/transcript-append.js';
+import { isFileNotFoundError, writeJsonAtomically, } from '../util/fs-helpers.js';
+export class TranscriptStore {
+    baseDirectoryName;
+    constructor(baseDirectoryName = '.claude-manager') {
+        this.baseDirectoryName = baseDirectoryName;
+    }
+    /**
+     * Append new events to the transcript file for the given session.
+     * Creates the file if it does not exist. Strips trailing partials before persisting.
+     */
+    async appendEvents(cwd, sessionId, newEvents) {
+        if (newEvents.length === 0) {
+            return;
+        }
+        const filePath = this.getTranscriptPath(cwd, sessionId);
+        const existing = await this.readEvents(cwd, sessionId);
+        const merged = appendTranscriptEvents(existing, newEvents);
+        const cleaned = stripTrailingPartials(merged);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await writeJsonAtomically(filePath, cleaned);
+    }
+    /**
+     * Read all persisted transcript events for a session.
+     */
+    async readEvents(cwd, sessionId) {
+        const filePath = this.getTranscriptPath(cwd, sessionId);
+        try {
+            const content = await fs.readFile(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (isFileNotFoundError(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    getTranscriptPath(cwd, sessionId) {
+        return path.join(cwd, this.baseDirectoryName, 'transcripts', `${sessionId}.json`);
+    }
+}