@doingdev/opencode-claude-manager-plugin 0.1.60 → 0.1.62

package/dist/src/manager/team-orchestrator.js

@@ -122,6 +122,7 @@ export class TeamOrchestrator {
                 persistSession: true,
                 includePartialMessages: true,
                 permissionMode: 'acceptEdits',
+                allowedTools: workerCaps?.sessionAllowedTools,
                 restrictWriteTools: input.mode === 'explore' || (workerCaps?.restrictWriteTools ?? false),
                 model: input.model,
                 effort: (workerCaps?.restrictWriteTools ?? false)
@@ -219,6 +220,9 @@ export class TeamOrchestrator {
         else if (message.includes('context') || message.includes('token limit')) {
             failureKind = 'contextExhausted';
         }
+        else if (message.includes('does not support implement mode')) {
+            failureKind = 'modeNotSupported';
+        }
         else if (message.includes('denied') || message.includes('not allowed')) {
             failureKind = 'toolDenied';
         }
@@ -426,7 +430,7 @@ export class TeamOrchestrator {
         const now = new Date().toISOString();
         await this.teamStore.updateTeam(cwd, teamId, (team) => {
             if (!team.activePlan) {
-                throw new Error(`Cannot update slice: team "${teamId}" has no active plan. Call confirm_plan first.`);
+                throw new Error(`Cannot update slice: team "${teamId}" has no active plan. Persist an active plan before updating slices.`);
             }
             const sliceExists = team.activePlan.slices.some((s) => s.index === sliceIndex);
             if (!sliceExists) {
@@ -483,9 +487,10 @@ function buildModeInstruction(mode) {
     switch (mode) {
         case 'explore':
             return [
-                'Investigation mode.',
-                'Read, search, and reason about the codebase.',
-                'Produce a concrete plan with specific file paths and an approach.',
+                'Exploration mode.',
+                'Read, search, and reason about the codebase without editing files.',
+                'The caller should specify the desired output for this exploration task, such as root cause, findings, affected files, options, risk review, or a concrete plan.',
+                'If the caller does not specify the output shape, return concise findings, relevant file paths, open questions, and the recommended next step.',
                 'Do not create or edit files.',
             ].join(' ');
         case 'implement':
@@ -578,6 +583,8 @@ export function getFailureGuidanceText(failureKind) {
             return 'This engineer is currently working on another assignment. Wait for them to finish, choose a different engineer, or try again shortly.';
         case 'toolDenied':
             return 'A tool permission was denied during the assignment. Check the approval policy and tool permissions, then retry.';
+        case 'modeNotSupported':
+            return 'This engineer does not support the requested work mode. BrowserQA only supports explore and verify modes — use a general engineer (Tom, John, Maya, Sara, Alex) for implement tasks.';
         case 'aborted':
             return 'The assignment was cancelled by the user or an abort signal was triggered. Review the request and try again.';
         case 'sdkError':

package/dist/src/plugin/agents/browser-qa.js

@@ -12,6 +12,10 @@ export function buildWorkerCapabilities(prompts) {
             plannerEligible: false,
             isRuntimeUnavailableResponse: (text) => text.trimStart().startsWith('PLAYWRIGHT_UNAVAILABLE:'),
             runtimeUnavailableTitle: '❌ Playwright unavailable',
+            // Pre-approve the Playwriter toolchain at the SDK level so headless sessions
+            // never stall waiting for interactive confirmation. Write tools remain blocked
+            // by restrictWriteTools and the canUseTool write-filter.
+            sessionAllowedTools: ['Skill', 'Bash', 'Read', 'Grep', 'Glob', 'LS', 'ListDirectory'],
         },
     };
 }

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

@@ -11,9 +11,9 @@ 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", "confirm_plan", "advance_slice", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update"];
+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 ENGINEER_TOOL_IDS: readonly ["claude"];
-export declare const ALL_RESTRICTED_TOOL_IDS: readonly ["team_status", "reset_engineer", "confirm_plan", "advance_slice", "list_transcripts", "list_history", "git_diff", "git_commit", "git_reset", "git_status", "git_log", "approval_policy", "approval_decisions", "approval_update", "claude"];
+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 type ToolPermission = 'allow' | 'ask' | 'deny';
 export type AgentPermission = {
     '*'?: ToolPermission;

package/dist/src/plugin/agents/common.js

@@ -15,8 +15,6 @@ export const ENGINEER_AGENT_NAMES = PLANNER_ELIGIBLE_ENGINEERS;
 export const CTO_ONLY_TOOL_IDS = [
     'team_status',
     'reset_engineer',
-    'confirm_plan',
-    'advance_slice',
     'list_transcripts',
     'list_history',
     'git_diff',

package/dist/src/plugin/agents/team-planner.js

@@ -13,7 +13,7 @@ function buildTeamPlannerPermissions() {
 }
 export function buildTeamPlannerAgentConfig(prompts) {
     return {
-        description: 'Runs dual-engineer planning by calling plan_with_team. Automatically selects two non-overlapping available engineers if engineer names are not provided.',
+        description: 'Thin planning wrapper that calls plan_with_team for dual-engineer synthesis with live UI activity.',
         mode: 'subagent',
         hidden: false,
         color: '#D97757',

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

@@ -1,5 +1,6 @@
 import { tool } from '@opencode-ai/plugin';
 import { managerPromptRegistry } from '../prompts/registry.js';
+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';
@@ -206,49 +207,6 @@ export const ClaudeManagerPlugin = async ({ worktree, client }) => {
                     }, null, 2);
                 },
             }),
-            confirm_plan: tool({
-                description: 'Persist plan confirmation and optional slice metadata after the user confirms a plan. For large tasks, provide a slice list to enable per-slice progress tracking. Set preAuthorized to true only when the user has explicitly said to proceed through all slices without further confirmation.',
-                args: {
-                    summary: tool.schema.string().min(1),
-                    taskSize: tool.schema.enum(['trivial', 'simple', 'large']),
-                    slices: tool.schema.string().array().optional(),
-                    preAuthorized: tool.schema.boolean().optional(),
-                },
-                async execute(args, context) {
-                    const teamId = context.sessionID;
-                    annotateToolRun(context, 'Persisting confirmed plan', {
-                        teamId,
-                        taskSize: args.taskSize,
-                        sliceCount: args.slices?.length ?? 0,
-                    });
-                    const activePlan = await services.orchestrator.setActivePlan(context.worktree, teamId, {
-                        summary: args.summary,
-                        taskSize: args.taskSize,
-                        slices: args.slices ?? [],
-                        preAuthorized: args.preAuthorized ?? false,
-                    });
-                    return JSON.stringify(activePlan, null, 2);
-                },
-            }),
-            advance_slice: tool({
-                description: 'Mark a plan slice as done (or skipped) and advance to the next one. Use this after each slice completes to track large-task progress.',
-                args: {
-                    sliceIndex: tool.schema.number(),
-                    status: tool.schema.enum(['done', 'skipped']).optional(),
-                },
-                async execute(args, context) {
-                    const teamId = context.sessionID;
-                    const status = args.status ?? 'done';
-                    annotateToolRun(context, `Advancing slice ${args.sliceIndex} → ${status}`, {
-                        teamId,
-                        sliceIndex: args.sliceIndex,
-                        status,
-                    });
-                    await services.orchestrator.updateActivePlanSlice(context.worktree, teamId, args.sliceIndex, status);
-                    const team = await services.orchestrator.getOrCreateTeam(context.worktree, teamId);
-                    return JSON.stringify({ activePlan: team.activePlan ?? null }, null, 2);
-                },
-            }),
             reset_engineer: tool({
                 description: 'Reset a stuck or corrupted engineer. Clears the busy flag. Optionally clears the Claude session (starts fresh) and/or wrapper history.',
                 args: {
@@ -499,6 +457,19 @@ async function runEngineerAssignment(input, context) {
                 guidance,
             },
         });
+        try {
+            await appendDebugLog(services.debugLogPath, {
+                type: 'engineer_failure',
+                engineer: failure.engineer,
+                teamId: failure.teamId,
+                mode: failure.mode,
+                failureKind: failure.failureKind,
+                message: failure.message.slice(0, 300),
+            });
+        }
+        catch {
+            // Log write failures must not mask the original error.
+        }
         throw createActionableError(failure, error);
     }
     await services.orchestrator.recordWrapperExchange(context.worktree, input.teamId, input.engineer, context.sessionID, input.mode, input.message, result.finalText);

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

@@ -11,6 +11,7 @@ interface ClaudeManagerPluginServices {
     teamStore: TeamStateStore;
     orchestrator: TeamOrchestrator;
     workerCapabilities: Partial<Record<EngineerName, WorkerCapabilities>>;
+    debugLogPath: string;
 }
 export declare function getOrCreatePluginServices(worktree: string): ClaudeManagerPluginServices;
 export declare function clearPluginServices(): void;

package/dist/src/plugin/service-factory.js

@@ -21,8 +21,9 @@ export function getOrCreatePluginServices(worktree) {
         return existing;
     }
     const approvalPolicyPath = path.join(worktree, '.claude-manager', 'approval-policy.json');
+    const debugLogPath = path.join(worktree, '.claude-manager', 'debug.log');
     const approvalManager = new ToolApprovalManager(undefined, undefined, approvalPolicyPath);
-    const sdkAdapter = new ClaudeAgentSdkAdapter(undefined, approvalManager);
+    const sdkAdapter = new ClaudeAgentSdkAdapter(undefined, approvalManager, debugLogPath);
     const sessionService = new ClaudeSessionService(sdkAdapter);
     const gitOps = new GitOperations(worktree);
     const teamStore = new TeamStateStore();
@@ -37,6 +38,7 @@ export function getOrCreatePluginServices(worktree) {
         teamStore,
         orchestrator,
         workerCapabilities,
+        debugLogPath,
     };
     serviceRegistry.set(worktree, services);
     return services;

package/dist/src/prompts/registry.js

@@ -1,10 +1,11 @@
 export const managerPromptRegistry = {
     ctoSystemPrompt: [
         'You are a principal engineer orchestrating a team of AI-powered engineers.',
-        'Your role is to decompose work, delegate precisely, review diffs for production risks, and verify outcomes.',
+        'Your role is to investigate first, delegate precisely, review diffs for production risks, and verify outcomes.',
         'You do not write code. All edits go through engineers. You multiply output by coordinating parallel work and catching issues others miss.',
         '',
-        '# Operating Loop: Orient → Classify → Plan → Confirm → Delegate → Review → Verify → Close',
+        '# Operating Loop: Orient → Investigate → Decide → Delegate → Review → Verify → Close',
+        'Treat this loop as adaptive, not rigid. You may revisit earlier steps, skip unnecessary steps, or improvise when the work demands it—as long as you stay explicit about why.',
         '',
         '## Orient: Understand the request',
         '- Extract what you can from the user message, codebase (read/grep/glob/codesearch), prior engineer results, and `websearch`/`webfetch` when relevant.',
@@ -13,38 +14,33 @@ export const managerPromptRegistry = {
         '- If requirements are vague or architecture is unclear, use `question` tool with 2–3 concrete options, your recommendation, and what breaks if user picks differently.',
         '- Only ask when the decision will materially change scope, architecture, risk, or how you verify—and you cannot resolve it from context.',
         '',
-        '## Classify: Frame the work',
+        '## Investigate: Reduce uncertainty before choosing a path',
+        '- Start with the smallest useful investigation. For a bug, get to root cause. For a feature, inspect the existing surface area before inventing a plan.',
+        '- You may investigate yourself with read-only tools or delegate exploration to one engineer when that is faster or gives better continuity.',
+        '- When delegating exploration, explicitly say what artifact you want back: root cause, findings, affected files, options, risk review, file map, or a concrete plan.',
+        '- Do not default exploration to planning. Use planning only when the task is genuinely complex, ambiguous, cross-cutting, or risky.',
+        '',
+        '## Decide: Choose the lightest process that fits the work',
         '- Is this a bug fix, feature, refactor, or something else?',
         '- Task size: classify as trivial (single-line fix, unambiguous, no side effects), simple (one focused task, clear scope, 1–2 files), or large (multiple steps, cross-cutting changes, requires vertical slicing).',
         '- What could go wrong? Is it reversible or irreversible? Can it fail in prod?',
         '- Does it require careful rollout, data migration, observability, or backwards compatibility handling?',
         '- Are there decisions the user has not explicitly made (architecture, scope, deployment strategy)?',
-        '',
-        '## Plan: Decompose into engineer work',
-        '- For small, focused tasks: delegate to a named engineer with structured context (goal, acceptance criteria, relevant files, constraints, verification).',
-        "- For medium or large tasks: use `task(subagent_type: 'team-planner', ...)` for dual-engineer exploration and plan synthesis.",
-        '  - Team-planner automatically selects two non-overlapping engineers by availability and context; you may optionally specify lead and challenger.',
-        '  - Challenger engineer identifies missing decisions, risks, and scope gaps before implementation.',
-        '- For large tasks: break into vertical slices before delegating. Each slice must deliver end-to-end, user-testable value independently (e.g., "user can register and receive a confirmation email", "user can view billing history"). Horizontal layers (e.g., "just types", "just tests") are not vertical slices. Document slices when calling `confirm_plan`.',
-        '- Break work into independent pieces that can run in parallel. Two engineers exploring then synthesizing beats one engineer doing everything sequentially.',
-        '- Before delegating, state your success criteria, not just the task. What done looks like. How you will verify it.',
-        '',
-        '## Confirm: Get user buy-in before implementing',
-        '- After planning but before dispatching any engineer in implement mode, present the plan to the user with the `question` tool.',
-        '- State what will be built or changed, which files or systems are affected, what success looks like, and any risks or open decisions.',
-        '- If team-planner synthesis surfaced a recommendedQuestion, include it here as part of the confirmation question.',
-        '- Do not proceed to implementation until the user confirms the plan.',
-        '- After the user confirms, call `confirm_plan` with a summary, taskSize, and (for large tasks) the slice list. Set preAuthorized: true only if the user explicitly says to proceed through all slices without further confirmation.',
-        '- For large tasks not preAuthorized: confirm each slice with the user before dispatching it.',
-        '- Skip `question` only when: the user has explicitly said "proceed" or "just do it", the change is a trivial fix with no ambiguity, or the task is purely exploratory (no edits).',
-        '- If the user refines or rejects the plan, revise it and re-confirm before implementing.',
+        '- For trivial or simple work with clear scope: delegate directly to one engineer.',
+        '- For bugs or unclear requests: investigate first, then decide whether implementation is now straightforward.',
+        "- For complex or cross-cutting work: use `task(subagent_type: 'team-planner', ...)` so the wrapper can sharpen the request and run `plan_with_team` with live UI activity.",
+        '- Ask the user to confirm only when the decision materially changes scope, risk, rollout, or architecture. Do not force confirmation for every non-trivial task.',
         '',
         '## Delegate: Send precise assignments',
-        "- For single-engineer work: use `task(subagent_type: 'tom'|'john'|'maya'|'sara'|'alex', ...)` and structure the prompt with goal, acceptance criteria, relevant files, constraints, and verification.",
-        "- For dual-engineer planning: use `task(subagent_type: 'team-planner', ...)` which will lead + challenger synthesis.",
+        "- For single-engineer work: use `task(subagent_type: 'tom'|'john'|'maya'|'sara'|'alex', ...)` and structure the prompt with goal, mode, expected deliverable, acceptance criteria, relevant context, constraints, and verification.",
+        "- For complex planning work: use `task(subagent_type: 'team-planner', ...)`. The wrapper preserves live activity in the UI while it inspects context lightly and runs `plan_with_team`.",
         "- For browser/UI verification: use `task(subagent_type: 'browser-qa', ...)` with a clear verification goal. BrowserQA uses the Playwright skill to verify in a real browser and can run safe bash when needed.",
-        '- Each assignment includes: goal, acceptance criteria, relevant context, constraints, and verification method.',
-        '- For large tasks: after each slice completes, call `advance_slice` to record progress, then confirm the next slice with the user before dispatching (unless preAuthorized).',
+        '- For large tasks: break work into genuine vertical slices before implementation. Each slice must deliver end-to-end, user-testable value independently (e.g., "user can register and receive a confirmation email", "user can view billing history"). Horizontal layers (e.g., "just types", "just tests") are not vertical slices.',
+        '- Break work into independent pieces that can run in parallel. Two engineers exploring and then synthesizing is often better than one engineer guessing alone.',
+        '- Before delegating, state success criteria and expected output shape, not just the task. Say what done looks like and how you will verify it.',
+        '- If planning surfaced a recommendedQuestion or the work is risky enough to need confirmation, use the `question` tool before implementation. Otherwise, delegate directly.',
+        '',
+        '- Each assignment includes: goal, mode, expected deliverable, acceptance criteria, relevant context, constraints, and verification method.',
         '- Reuse the same engineer when follow-up work builds on their prior context.',
         '- Only one implementing engineer modifies the worktree at a time. Parallelize exploration, research, and browser verification freely.',
         '- Context warnings (moderate/high/critical) are informational only. Do NOT reset an engineer session in response to a context warning. Sessions auto-reset only on an actual contextExhausted error.',
@@ -79,6 +75,7 @@ export const managerPromptRegistry = {
         '',
         '- Questions: Use the `question` tool when a decision will materially affect scope, architecture, or how you verify the outcome. Name the decision, offer 2–3 concrete options, state your recommendation, and say what breaks if the user picks differently. One high-leverage question at a time.',
         '- Reframing: Before planning, ask what the user is actually trying to achieve, not just what they asked for. If the request sounds like a feature, ask what job-to-be-done it serves.',
+        '- Exploration outputs: when you send an engineer in explore mode, specify the expected output explicitly. Examples: root cause, findings, affected files, options, risk review, or implementation plan.',
         '- Engineer selection: When assigning to a single engineer, prefer lower context pressure and less-recently-used engineers. Reuse if follow-up work builds on prior context.',
         '- Context warnings: At moderate/high/critical context levels the system surfaces a warning. These are advisory — do not force session reset. Reserve reset for actual contextExhausted errors only.',
         '- Failure handling:',
@@ -107,6 +104,7 @@ export const managerPromptRegistry = {
         '',
         'Your wrapper context from prior turns is reloaded automatically. Use it to avoid repeating work or re-explaining context that Claude Code already knows.',
         "Return the tool result directly. Add your own commentary only when something was unexpected or needs the CTO's attention.",
+        'Explore mode is caller-directed. Follow the requested output shape instead of defaulting to a plan. If the assignment does not specify the output, return findings, relevant files, open questions, and the recommended next step.',
         'If you discover during implementation that the agreed approach is not viable (unexpected constraints, wrong files, missing context), stop immediately and surface the deviation to the CTO before proceeding with a different approach. Do not silently implement something different from what was confirmed.',
     ].join('\n'),
     engineerSessionPrompt: [
@@ -117,6 +115,7 @@ export const managerPromptRegistry = {
         'When investigating bugs:',
         '- Always explore the root cause before implementing a fix. Do not assume; verify.',
         '- If three fix attempts fail, question the architecture, not the hypothesis.',
+        '- In explore mode, return the artifact the caller asked for. Do not default to a plan unless the caller explicitly asks for one.',
         '',
         'When writing code:',
         '- Consider rollout/migration/observability implications: Will this require staged rollout, data migration, new metrics, or log/trace points?',
@@ -158,14 +157,15 @@ export const managerPromptRegistry = {
         '<answer or NONE>',
     ].join('\n'),
     teamPlannerPrompt: [
-        'You are the team planner. Your only job is to invoke `plan_with_team`.',
+        'You are the team-planner wrapper. Your job is to help the CTO get a stronger plan for complex work while preserving live activity in the UI.',
         '`plan_with_team` dispatches two engineers in parallel (lead + challenger) then synthesizes their plans.',
         '',
-        'Call `plan_with_team` immediately with the task and any engineer names provided.',
+        'Call `plan_with_team` with the task and any engineer names provided.',
         '- If lead and challenger engineer names are both specified, use them.',
         '- If either name is missing, `plan_with_team` will auto-select two non-overlapping engineers based on availability and context.',
-        'Do not attempt any planning or analysis yourself. Delegate entirely to `plan_with_team`.',
-        'After `plan_with_team` returns, pass the full result back to the CTO unchanged. Do not modify, summarize, or act on the synthesis; the CTO will present it to the user for confirmation.',
+        '- Keep the wrapper thin. Do not do your own repo investigation or solo planning.',
+        '- If the request is blocked by a missing decision, ask one focused question with a recommendation instead of guessing.',
+        'After `plan_with_team` returns, pass the full result back to the CTO unchanged.',
     ].join('\n'),
     browserQaAgentPrompt: [
         "You are the browser QA specialist on the CTO's team.",

package/dist/src/types/contracts.d.ts

@@ -4,9 +4,9 @@ export interface ManagerPromptRegistry {
     engineerSessionPrompt: string;
     /** Prompt prepended to the user prompt of the synthesis runTask call inside plan_with_team. */
     planSynthesisPrompt: string;
-    /** Visible subagent prompt for teamPlanner — thin bridge that calls plan_with_team. */
+    /** Visible subagent prompt for teamPlanner — thin wrapper that calls plan_with_team. */
     teamPlannerPrompt: string;
-    /** Visible subagent prompt for browserQa — thin bridge that calls claude tool for browser verification. */
+    /** Visible subagent prompt for browserQa — thin wrapper that calls claude tool for browser verification. */
     browserQaAgentPrompt: string;
     /** Prompt prepended to browser verification task prompts in Claude Code sessions. */
     browserQaSessionPrompt: string;
@@ -146,7 +146,7 @@ export interface TeamEngineerRecord {
     wrapperHistory: WrapperHistoryEntry[];
     context: SessionContextSnapshot;
 }
-export type EngineerFailureKind = 'sdkError' | 'contextExhausted' | 'toolDenied' | 'aborted' | 'engineerBusy' | 'unknown';
+export type EngineerFailureKind = 'sdkError' | 'contextExhausted' | 'toolDenied' | 'modeNotSupported' | 'aborted' | 'engineerBusy' | 'unknown';
 export interface EngineerFailureResult {
     teamId: string;
     engineer: EngineerName;
@@ -206,6 +206,13 @@ export interface WorkerCapabilities {
     isRuntimeUnavailableResponse?: (finalText: string) => boolean;
     /** Metadata title for the runtime-unavailable event. */
     runtimeUnavailableTitle?: string;
+    /**
+     * Explicit SDK-level pre-approval list for this worker's inner Claude Code session.
+     * Tools in this list bypass interactive confirmation prompts (they are still subject to
+     * the `canUseTool` write-restriction and approval-policy filters).
+     * Absent = falls back to `['Skill']` via the default adapter behaviour.
+     */
+    sessionAllowedTools?: string[];
 }
 export interface GitDiffResult {
     hasDiff: boolean;

package/dist/src/util/fs-helpers.d.ts

@@ -1,2 +1,8 @@
 export declare function writeJsonAtomically(filePath: string, data: unknown): Promise<void>;
 export declare function isFileNotFoundError(error: unknown): error is NodeJS.ErrnoException;
+/**
+ * Appends a single NDJSON line to a debug log file.
+ * Creates the parent directory if it does not exist.
+ * A `ts` (ISO timestamp) field is injected automatically.
+ */
+export declare function appendDebugLog(logPath: string, entry: Record<string, unknown>): Promise<void>;

package/dist/src/util/fs-helpers.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
+import path from 'node:path';
 export async function writeJsonAtomically(filePath, data) {
     const tempPath = `${filePath}.${randomUUID()}.tmp`;
     await fs.writeFile(tempPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
@@ -8,3 +9,13 @@ export async function writeJsonAtomically(filePath, data) {
 export function isFileNotFoundError(error) {
     return (error instanceof Error && 'code' in error && error.code === 'ENOENT');
 }
+/**
+ * Appends a single NDJSON line to a debug log file.
+ * Creates the parent directory if it does not exist.
+ * A `ts` (ISO timestamp) field is injected automatically.
+ */
+export async function appendDebugLog(logPath, entry) {
+    const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
+    await fs.mkdir(path.dirname(logPath), { recursive: true });
+    await fs.appendFile(logPath, line, 'utf8');
+}

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

@@ -1,5 +1,9 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { ClaudeAgentSdkAdapter } from '../src/claude/claude-agent-sdk-adapter.js';
+import { ToolApprovalManager } from '../src/claude/tool-approval-manager.js';
 function createFakeQuery(messages) {
     return {
         async *[Symbol.asyncIterator]() {
@@ -494,6 +498,45 @@ describe('ClaudeAgentSdkAdapter', () => {
         const gitLogResult = await capturedCanUseTool('Bash', { command: 'git log --oneline -10' }, {});
         expect(gitLogResult.behavior).toBe('allow');
     });
+    it('allows Playwriter-style bash commands when restrictWriteTools is true', async () => {
+        let capturedCanUseTool;
+        const adapter = new ClaudeAgentSdkAdapter({
+            query: (params) => {
+                capturedCanUseTool = params.options?.canUseTool;
+                return createFakeQuery([
+                    {
+                        type: 'result',
+                        subtype: 'success',
+                        session_id: 'ses_playwriter',
+                        is_error: false,
+                        result: 'ok',
+                        num_turns: 1,
+                        total_cost_usd: 0,
+                    },
+                ]);
+            },
+            listSessions: async () => [],
+            getSessionMessages: async () => [],
+        });
+        await adapter.runSession({
+            cwd: '/tmp/project',
+            prompt: 'Run Playwriter tests',
+            restrictWriteTools: true,
+        });
+        expect(capturedCanUseTool).toBeDefined();
+        // Non-destructive Playwriter commands must be allowed
+        const playwriterResult = await capturedCanUseTool('Bash', { command: 'playwriter session new' }, {});
+        expect(playwriterResult.behavior).toBe('allow');
+        const npxResult = await capturedCanUseTool('Bash', { command: 'npx playwriter session new' }, {});
+        expect(npxResult.behavior).toBe('allow');
+        const listResult = await capturedCanUseTool('Bash', { command: 'playwriter session list' }, {});
+        expect(listResult.behavior).toBe('allow');
+        // Destructive commands must still be denied
+        const rmResult = await capturedCanUseTool('Bash', { command: 'rm -rf /tmp/screenshots' }, {});
+        expect(rmResult.behavior).toBe('deny');
+        const redirectResult = await capturedCanUseTool('Bash', { command: 'echo "data" > out.txt' }, {});
+        expect(redirectResult.behavior).toBe('deny');
+    });
     it('allows write tools when restrictWriteTools is false', async () => {
         let capturedCanUseTool;
         const adapter = new ClaudeAgentSdkAdapter({
@@ -548,4 +591,117 @@ describe('ClaudeAgentSdkAdapter', () => {
         });
         expect(capturedPermissionMode).toBe('plan');
     });
+    describe('debug log', () => {
+        let tmpDir;
+        afterEach(async () => {
+            if (tmpDir) {
+                await rm(tmpDir, { recursive: true, force: true });
+            }
+        });
+        it('appends a tool_denied entry when restrictWriteTools denies a write tool', async () => {
+            tmpDir = await mkdtemp(join(tmpdir(), 'adapter-log-'));
+            const logPath = join(tmpDir, '.claude-manager', 'debug.log');
+            let capturedCanUseTool;
+            const adapter = new ClaudeAgentSdkAdapter({
+                query: (params) => {
+                    capturedCanUseTool = params.options?.canUseTool;
+                    return createFakeQuery([
+                        {
+                            type: 'result',
+                            subtype: 'success',
+                            session_id: 'ses_log',
+                            is_error: false,
+                            result: 'ok',
+                            num_turns: 1,
+                            total_cost_usd: 0,
+                        },
+                    ]);
+                },
+                listSessions: async () => [],
+                getSessionMessages: async () => [],
+            }, undefined, logPath);
+            await adapter.runSession({ cwd: '/tmp/project', prompt: 'Test', restrictWriteTools: true });
+            expect(capturedCanUseTool).toBeDefined();
+            const result = await capturedCanUseTool('Edit', { file_path: 'x.ts' }, {});
+            expect(result.behavior).toBe('deny');
+            const content = await readFile(logPath, 'utf8');
+            const entry = JSON.parse(content.trim().split('\n')[0]);
+            expect(entry.type).toBe('tool_denied');
+            expect(entry.toolName).toBe('Edit');
+            expect(entry.reason).toBe('restrictWriteTools');
+            expect(typeof entry.ts).toBe('string');
+        });
+        it('appends a tool_denied entry when the approval manager denies a tool', async () => {
+            tmpDir = await mkdtemp(join(tmpdir(), 'adapter-log-policy-'));
+            const logPath = join(tmpDir, '.claude-manager', 'debug.log');
+            const approvalManager = new ToolApprovalManager({
+                rules: [
+                    {
+                        id: 'deny-bash',
+                        toolPattern: 'Bash',
+                        inputPattern: 'rm -rf /',
+                        action: 'deny',
+                        denyMessage: 'rm -rf / is not allowed',
+                    },
+                ],
+                enabled: true,
+            });
+            let capturedCanUseTool;
+            const adapter = new ClaudeAgentSdkAdapter({
+                query: (params) => {
+                    capturedCanUseTool = params.options?.canUseTool;
+                    return createFakeQuery([
+                        {
+                            type: 'result',
+                            subtype: 'success',
+                            session_id: 'ses_policy',
+                            is_error: false,
+                            result: 'ok',
+                            num_turns: 1,
+                            total_cost_usd: 0,
+                        },
+                    ]);
+                },
+                listSessions: async () => [],
+                getSessionMessages: async () => [],
+            }, approvalManager, logPath);
+            await adapter.runSession({ cwd: '/tmp/project', prompt: 'Test' });
+            expect(capturedCanUseTool).toBeDefined();
+            const result = await capturedCanUseTool('Bash', { command: 'rm -rf /' }, {});
+            expect(result.behavior).toBe('deny');
+            const content = await readFile(logPath, 'utf8');
+            const entry = JSON.parse(content.trim().split('\n')[0]);
+            expect(entry.type).toBe('tool_denied');
+            expect(entry.toolName).toBe('Bash');
+            expect(entry.reason).toBe('approvalPolicy');
+            expect(typeof entry.ts).toBe('string');
+        });
+        it('does not create a log file when no debugLogPath is provided', async () => {
+            tmpDir = await mkdtemp(join(tmpdir(), 'adapter-no-log-'));
+            let capturedCanUseTool;
+            const adapter = new ClaudeAgentSdkAdapter({
+                query: (params) => {
+                    capturedCanUseTool = params.options?.canUseTool;
+                    return createFakeQuery([
+                        {
+                            type: 'result',
+                            subtype: 'success',
+                            session_id: 'ses_nolog',
+                            is_error: false,
+                            result: 'ok',
+                            num_turns: 1,
+                            total_cost_usd: 0,
+                        },
+                    ]);
+                },
+                listSessions: async () => [],
+                getSessionMessages: async () => [],
+            });
+            await adapter.runSession({ cwd: '/tmp/project', prompt: 'Test', restrictWriteTools: true });
+            const result = await capturedCanUseTool('Edit', { file_path: 'x.ts' }, {});
+            expect(result.behavior).toBe('deny');
+            // No log file should exist
+            await expect(readFile(join(tmpDir, 'debug.log'), 'utf8')).rejects.toThrow();
+        });
+    });
 });