@doingdev/opencode-claude-manager-plugin 0.1.18 → 0.1.20

package/README.md

@@ -4,15 +4,17 @@ This package provides an OpenCode plugin that lets an OpenCode-side manager agen
 
 ## Overview
 
-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 discovering Claude metadata, delegating work to Claude sessions, and splitting tasks into subagents (all using the same working directory).
+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.
 
 ## Features
 
 - 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.
-- Splits multi-step tasks into subagents that run sequentially in the same repository directory.
-- Persists manager runs under `.claude-manager/runs` so sessions can be inspected later.
-- Exposes manager-facing tools instead of relying on undocumented plugin-defined slash commands.
+- 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
 
@@ -49,10 +51,35 @@ If you are testing locally, point OpenCode at the local package or plugin file u
 
 ## OpenCode tools
 
-- `claude_manager_run` - run a task through Claude with optional splitting into subagents; returns a compact output summary and a `runId` for deeper inspection
-- `claude_manager_metadata` - inspect available Claude commands, skills, hooks, and settings
-- `claude_manager_sessions` - list Claude sessions or inspect a saved transcript
-- `claude_manager_runs` - inspect persisted manager run records
+### Session management
+
+- `claude_manager_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).
+- `claude_manager_compact` — compress the active session context while preserving session state. Use before clearing when context is high but salvageable.
+- `claude_manager_clear` — drop the active session entirely; next send starts fresh.
+- `claude_manager_status` — get current session health: context %, turns, cost, session ID.
+
+### Git operations
+
+- `claude_manager_git_diff` — review all uncommitted changes (staged + unstaged).
+- `claude_manager_git_commit` — stage all changes and commit with a message.
+- `claude_manager_git_reset` — hard reset + clean (destructive).
+
+### Inspection
+
+- `claude_manager_metadata` — inspect available Claude commands, skills, hooks, and settings.
+- `claude_manager_sessions` — list Claude sessions or inspect a saved transcript.
+- `claude_manager_runs` — list or inspect persisted manager run records (may be empty if tasks were sent directly via `claude_manager_send` rather than the run-tracking path).
+
+### Tool approval
+
+- `claude_manager_approval_policy` — view the current tool approval policy.
+- `claude_manager_approval_decisions` — view recent tool approval decisions.
+- `claude_manager_approval_update` — add/remove rules, change default action, or enable/disable approval.
 
 ## Plugin-provided agents and commands
 
@@ -69,13 +96,26 @@ These are added to OpenCode config at runtime by the plugin, so they do not requ
 Typical flow inside OpenCode:
 
 1. Inspect Claude capabilities with `claude_manager_metadata`.
-2. Delegate work with `claude_manager_run`.
-3. Inspect saved Claude history with `claude_manager_sessions` or prior orchestration records with `claude_manager_runs`.
+2. Delegate work with `claude_manager_send`.
+3. Review changes with `claude_manager_git_diff`, then commit or reset.
+4. Inspect saved Claude history with `claude_manager_sessions` or prior orchestration records with `claude_manager_runs`.
+
+Example tasks:
+
+```text
+Use claude_manager_send to implement the new validation logic in src/auth.ts, then review with claude_manager_git_diff.
+```
+
+Start a fresh session for an unrelated task:
+
+```text
+Use claude_manager_send with freshSession:true to investigate the failing CI test in test/api.test.ts using mode:"plan".
+```
 
-Example task:
+Reclaim context mid-session:
 
 ```text
-Use claude_manager_run to split this implementation into subagents and summarize the final result.
+Use claude_manager_compact to free up context, then continue with the next implementation step.
 ```
 
 ## Local Development
@@ -136,8 +176,8 @@ After trusted publishing is working, you can tighten npm package security by dis
 ## Limitations
 
 - Claude slash commands and skills come primarily from filesystem discovery; SDK probing is available but optional.
-- Multiple subagents share one working directory and run one after another to avoid overlapping edits.
-- Run state is local to the repo under `.claude-manager/` and is ignored by git.
+- 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/manager/parallel-session-job-manager.d.ts

@@ -0,0 +1,49 @@
+import type { ClaudeAgentSdkAdapter } from '../claude/claude-agent-sdk-adapter.js';
+import type { ParallelSessionJobRecord, SessionMode } from '../types/contracts.js';
+/**
+ * Runs additional Claude Code SDK sessions concurrently with the main persistent session.
+ * Same worktree from multiple jobs can conflict on git — callers should use plan mode or branches.
+ */
+export declare class ParallelSessionJobManager {
+    private readonly sdkAdapter;
+    private readonly sessionPrompt;
+    private readonly modePrefixes;
+    private readonly jobs;
+    constructor(sdkAdapter: ClaudeAgentSdkAdapter, sessionPrompt: string, modePrefixes: {
+        plan: string;
+        free: string;
+    });
+    static get maxConcurrent(): number;
+    startJob(params: {
+        cwd: string;
+        message: string;
+        model?: string;
+        mode?: SessionMode;
+        resumeSessionId?: string;
+    }): {
+        ok: true;
+        jobId: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    private runJob;
+    abortJob(jobId: string): {
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    };
+    getJob(jobId: string): ParallelSessionJobRecord | undefined;
+    listJobs(): ParallelSessionJobRecord[];
+    private runningCount;
+    waitForJobs(params: {
+        jobIds: string[];
+        mode: 'any' | 'all';
+        timeoutMs?: number;
+    }): Promise<{
+        finishedJobIds: string[];
+        timedOut: boolean;
+        pendingJobIds: string[];
+    }>;
+}

package/dist/manager/parallel-session-job-manager.js

@@ -0,0 +1,177 @@
+import { randomUUID } from 'node:crypto';
+const MAX_CONCURRENT = 5;
+function createCompletionLatch() {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+/**
+ * Runs additional Claude Code SDK sessions concurrently with the main persistent session.
+ * Same worktree from multiple jobs can conflict on git — callers should use plan mode or branches.
+ */
+export class ParallelSessionJobManager {
+    sdkAdapter;
+    sessionPrompt;
+    modePrefixes;
+    jobs = new Map();
+    constructor(sdkAdapter, sessionPrompt, modePrefixes) {
+        this.sdkAdapter = sdkAdapter;
+        this.sessionPrompt = sessionPrompt;
+        this.modePrefixes = modePrefixes;
+    }
+    static get maxConcurrent() {
+        return MAX_CONCURRENT;
+    }
+    startJob(params) {
+        if (this.runningCount() >= MAX_CONCURRENT) {
+            return {
+                ok: false,
+                error: `At most ${MAX_CONCURRENT} parallel Claude Code jobs may run at once. Wait or abort a job first.`,
+            };
+        }
+        const jobId = randomUUID();
+        const now = new Date().toISOString();
+        const mode = params.mode ?? 'free';
+        const prefix = this.modePrefixes[mode];
+        const prompt = prefix ? `${prefix}\n\n${params.message}` : params.message;
+        const input = {
+            cwd: params.cwd,
+            prompt,
+            persistSession: true,
+            permissionMode: mode === 'plan' ? 'plan' : 'acceptEdits',
+            includePartialMessages: true,
+            model: params.model,
+            resumeSessionId: params.resumeSessionId,
+            settingSources: ['user', 'project', 'local'],
+            agentProgressSummaries: true,
+        };
+        if (!params.resumeSessionId) {
+            input.systemPrompt = this.sessionPrompt;
+            input.model ??= 'claude-opus-4-6';
+            input.effort ??= 'high';
+        }
+        const abortController = new AbortController();
+        input.abortSignal = abortController.signal;
+        const preview = params.message.length > 120
+            ? `${params.message.slice(0, 120)}...`
+            : params.message;
+        const { promise: completion, resolve: resolveCompletion } = createCompletionLatch();
+        const record = {
+            id: jobId,
+            cwd: params.cwd,
+            status: 'running',
+            createdAt: now,
+            updatedAt: now,
+            promptPreview: preview,
+            resumeSessionId: params.resumeSessionId,
+        };
+        this.jobs.set(jobId, {
+            record,
+            abortController,
+            completion,
+            resolveCompletion,
+        });
+        void this.runJob(jobId, input, resolveCompletion);
+        return { ok: true, jobId };
+    }
+    async runJob(jobId, input, resolveCompletion) {
+        const entry = this.jobs.get(jobId);
+        if (!entry) {
+            resolveCompletion();
+            return;
+        }
+        try {
+            const result = await this.sdkAdapter.runSession(input);
+            const rec = entry.record;
+            rec.updatedAt = new Date().toISOString();
+            rec.status = 'completed';
+            rec.sessionId = result.sessionId;
+            rec.finalText = result.finalText;
+            rec.turns = result.turns;
+            rec.totalCostUsd = result.totalCostUsd;
+        }
+        catch (error) {
+            const rec = entry.record;
+            rec.updatedAt = new Date().toISOString();
+            if (rec.status !== 'aborted') {
+                rec.status = 'failed';
+                rec.error = error instanceof Error ? error.message : String(error);
+            }
+        }
+        finally {
+            resolveCompletion();
+        }
+    }
+    abortJob(jobId) {
+        const entry = this.jobs.get(jobId);
+        if (!entry) {
+            return { ok: false, error: 'Unknown job id' };
+        }
+        if (entry.record.status !== 'running') {
+            return { ok: false, error: 'Job is not running' };
+        }
+        entry.record.status = 'aborted';
+        entry.record.updatedAt = new Date().toISOString();
+        entry.abortController.abort();
+        return { ok: true };
+    }
+    getJob(jobId) {
+        return this.jobs.get(jobId)?.record;
+    }
+    listJobs() {
+        return [...this.jobs.values()]
+            .map((j) => j.record)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    runningCount() {
+        let n = 0;
+        for (const { record } of this.jobs.values()) {
+            if (record.status === 'running') {
+                n += 1;
+            }
+        }
+        return n;
+    }
+    async waitForJobs(params) {
+        const unique = [...new Set(params.jobIds)].filter((id) => this.jobs.has(id));
+        if (unique.length === 0) {
+            return {
+                finishedJobIds: [],
+                timedOut: false,
+                pendingJobIds: [],
+            };
+        }
+        const waitWork = async () => {
+            if (params.mode === 'any') {
+                await Promise.race(unique.map((id) => this.jobs.get(id).completion));
+            }
+            else {
+                await Promise.all(unique.map((id) => this.jobs.get(id).completion));
+            }
+        };
+        let timedOut = false;
+        if (params.timeoutMs !== undefined && params.timeoutMs > 0) {
+            await Promise.race([
+                waitWork(),
+                new Promise((resolve) => {
+                    setTimeout(() => {
+                        timedOut = true;
+                        resolve();
+                    }, params.timeoutMs);
+                }),
+            ]);
+        }
+        else {
+            await waitWork();
+        }
+        const finishedJobIds = unique.filter((id) => this.jobs.get(id)?.record.status !== 'running');
+        const pendingJobIds = unique.filter((id) => this.jobs.get(id)?.record.status === 'running');
+        return {
+            finishedJobIds,
+            timedOut,
+            pendingJobIds,
+        };
+    }
+}

package/dist/manager/persistent-manager.d.ts

@@ -19,6 +19,7 @@ export declare class PersistentManager {
      */
     sendMessage(cwd: string, message: string, options?: {
         model?: string;
+        effort?: 'low' | 'medium' | 'high' | 'max';
         mode?: 'plan' | 'free';
         abortSignal?: AbortSignal;
     }, onEvent?: ClaudeSessionEventHandler): Promise<{

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

@@ -3,6 +3,7 @@ import { managerPromptRegistry } from '../prompts/registry.js';
 import { getOrCreatePluginServices } from './service-factory.js';
 const MANAGER_TOOL_IDS = [
     'claude_manager_send',
+    'claude_manager_compact',
     'claude_manager_git_diff',
     'claude_manager_git_commit',
     'claude_manager_git_reset',
@@ -31,6 +32,7 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                 // Research agent can inspect but not send or modify
                 researchPermissions[toolId] =
                     toolId === 'claude_manager_send' ||
+                        toolId === 'claude_manager_compact' ||
                         toolId === 'claude_manager_git_commit' ||
                         toolId === 'claude_manager_git_reset' ||
                         toolId === 'claude_manager_clear' ||
@@ -50,6 +52,9 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                     codesearch: 'allow',
                     webfetch: 'allow',
                     websearch: 'allow',
+                    todowrite: 'allow',
+                    todoread: 'allow',
+                    question: 'allow',
                     ...managerPermissions,
                 },
                 prompt: managerPromptRegistry.managerSystemPrompt,
@@ -109,15 +114,27 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                     'Auto-creates a session on first call. Resumes the existing session on subsequent calls. ' +
                     'Returns the assistant response and current context health snapshot. ' +
                     'Use mode "plan" for read-only investigation and planning (no edits), ' +
-                    'or "free" (default) for normal execution with edit permissions.',
+                    'or "free" (default) for normal execution with edit permissions. ' +
+                    'Set freshSession to clear the active session before sending (use for unrelated tasks). ' +
+                    'Prefer claude-opus-4-6 (default) for most coding work; use a Sonnet model for faster/lighter tasks. ' +
+                    'Prefer effort "high" (default) for most work; use "medium" for lighter tasks and "max" for especially hard problems.',
                 args: {
                     message: tool.schema.string().min(1),
-                    model: tool.schema.string().optional(),
+                    model: tool.schema
+                        .enum(['claude-opus-4-6', 'claude-sonnet-4-6', 'claude-sonnet-4-5'])
+                        .optional(),
+                    effort: tool.schema
+                        .enum(['low', 'medium', 'high', 'max'])
+                        .default('high'),
                     mode: tool.schema.enum(['plan', 'free']).default('free'),
+                    freshSession: tool.schema.boolean().default(false),
                     cwd: tool.schema.string().optional(),
                 },
                 async execute(args, context) {
                     const cwd = args.cwd ?? context.worktree;
+                    if (args.freshSession) {
+                        await services.manager.clearSession(cwd);
+                    }
                     const hasActiveSession = services.manager.getStatus().sessionId !== null;
                     const promptPreview = args.message.length > 100
                         ? args.message.slice(0, 100) + '...'
@@ -133,7 +150,12 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                     });
                     let turnsSoFar = 0;
                     let costSoFar = 0;
-                    const result = await services.manager.sendMessage(cwd, args.message, { model: args.model, mode: args.mode, abortSignal: context.abort }, (event) => {
+                    const result = await services.manager.sendMessage(cwd, args.message, {
+                        model: args.model,
+                        effort: args.effort,
+                        mode: args.mode,
+                        abortSignal: context.abort,
+                    }, (event) => {
                         if (event.turns !== undefined) {
                             turnsSoFar = event.turns;
                         }
@@ -298,6 +320,36 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                     }, null, 2);
                 },
             }),
+            claude_manager_compact: tool({
+                description: 'Compact the active Claude Code session to reclaim context space. ' +
+                    'Sends /compact to the session, which compresses prior conversation while preserving state. ' +
+                    'Use before clearing when context is high but the session still has useful state. ' +
+                    'Fails if there is no active session.',
+                args: {
+                    cwd: tool.schema.string().optional(),
+                },
+                async execute(args, context) {
+                    const cwd = args.cwd ?? context.worktree;
+                    annotateToolRun(context, 'Compacting session', {});
+                    const result = await services.manager.compactSession(cwd);
+                    const snap = services.manager.getStatus();
+                    const contextWarning = formatContextWarning(snap);
+                    context.metadata({
+                        title: contextWarning
+                            ? `Claude Code: Compacted — context at ${snap.estimatedContextPercent}%`
+                            : `Claude Code: Compacted (${snap.totalTurns} turns, $${(snap.totalCostUsd ?? 0).toFixed(4)})`,
+                        metadata: { sessionId: result.sessionId },
+                    });
+                    return JSON.stringify({
+                        sessionId: result.sessionId,
+                        finalText: result.finalText,
+                        turns: result.turns,
+                        totalCostUsd: result.totalCostUsd,
+                        context: snap,
+                        contextWarning,
+                    }, null, 2);
+                },
+            }),
             claude_manager_git_diff: tool({
                 description: 'Run git diff to see all current changes (staged + unstaged) relative to HEAD.',
                 args: {

package/dist/prompts/registry.js

@@ -14,7 +14,7 @@ export const managerPromptRegistry = {
         '  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        — ask the user one narrow, high-value question',
+        '  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.',
@@ -46,6 +46,7 @@ export const managerPromptRegistry = {
         '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',
@@ -60,6 +61,7 @@ export const managerPromptRegistry = {
         '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.',
@@ -70,11 +72,37 @@ export const managerPromptRegistry = {
         '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%: compact or clear before sending heavy instructions.',
+        '- 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)',
@@ -121,10 +149,12 @@ export const managerPromptRegistry = {
     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: '',
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doingdev/opencode-claude-manager-plugin",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "OpenCode plugin that orchestrates Claude Code sessions.",
   "keywords": [
     "opencode",