osborn 0.9.217 → 0.9.219

package/dist/claude-llm.d.ts

@@ -46,6 +46,10 @@ export declare const NAMED_AGENTS: {
         description: string;
         tools: string[];
         grounded: boolean;
+        coordination: {
+            then: string[];
+            startNote: string;
+        };
         model: string;
         prompt: string;
     };
@@ -59,12 +63,28 @@ export declare const NAMED_AGENTS: {
         description: string;
         tools: string[];
         grounded: boolean;
+        policy: {
+            write: "anywhere";
+        };
+        reminder: string;
+        coordination: {
+            then: string[];
+            mode: "parallel";
+            startNote: string;
+        };
         model: string;
         prompt: string;
     };
     tester: {
         description: string;
         tools: string[];
+        policy: {
+            write: {
+                extensions: RegExp;
+                label: string;
+                matchBasename: boolean;
+            };
+        };
         model: string;
         prompt: string;
     };
@@ -78,6 +98,12 @@ export declare const NAMED_AGENTS: {
     reviewer: {
         description: string;
         tools: string[];
+        policy: {
+            write: {
+                extensions: RegExp;
+                label: string;
+            };
+        };
         model: string;
         prompt: string;
     };

package/dist/claude-llm.js

@@ -366,6 +366,12 @@ export const NAMED_AGENTS = {
         ].join(' '),
         tools: ['Read', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch', 'Task'],
         grounded: true, // applyGrounding() injects the osborn-recall command + ensures Bash
+        // Declarative flow. == today: after the researcher finishes, a reasoner-based
+        // research gate judges completeness and may send it back for more.
+        coordination: {
+            then: ['reasoner'],
+            startNote: 'When you finish, a reasoner-based gate judges whether your findings are COMPLETE and well-sourced against the task; thin or unsourced findings get sent back to you. Cite file paths + line numbers and explicitly note what you looked for but did NOT find.',
+        },
         model: 'sonnet',
         prompt: [
             'You are Osborn\'s research agent. Your job is information gathering — thorough, structured, factual.',
@@ -468,6 +474,17 @@ export const NAMED_AGENTS = {
         ].join(' '),
         tools: ['Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Glob', 'Grep', 'NotebookRead', 'NotebookEdit'],
         grounded: true, // applyGrounding() injects the osborn-recall command
+        policy: { write: 'anywhere' }, // sole writer — unrestricted; funnels through canUseTool
+        // Soft behavior via the composable `reminder` seam → SDK criticalSystemReminder_EXPERIMENTAL.
+        // Pinned into the writer's system prompt as a hard-to-ignore reminder.
+        reminder: 'BEFORE you write implementation code: make sure a test exists for the behavior you are about to change. If none exists, say so explicitly in your report so the tester can cover it — the tester is the agent that writes tests. NEVER weaken, skip, or delete a test to make your change pass.',
+        // Declarative flow (drives SubagentStop dispatch + SubagentStart injection).
+        // == today: after the writer finishes, reviewer AND tester run in parallel.
+        coordination: {
+            then: ['reviewer', 'tester'],
+            mode: 'parallel',
+            startNote: 'When you finish, your change is automatically verified in parallel: a reviewer checks correctness against the git diff, and a tester runs the suite. Make the change review-ready and leave the tree in a runnable state — do not skip cleanup expecting a second pass.',
+        },
         model: 'opus',
         prompt: [
             'You are Osborn\'s writer agent. You execute file changes with a verify-first approach.',
@@ -520,6 +537,8 @@ export const NAMED_AGENTS = {
             'NOT GROUNDED: no session index access — runs tests with fresh eyes, adversarial validation.',
         ].join(' '),
         tools: ['Bash', 'Read', 'Glob', 'Grep', 'Write', 'Edit'],
+        // Fail-closed: may ONLY write test files (basename .test/.spec.[jt]sx?).
+        policy: { write: { extensions: /\.(test|spec)\.[jt]sx?$/, label: 'test', matchBasename: true } },
         model: 'sonnet',
         prompt: [
             'You are Osborn\'s tester agent. Your job is running tests and builds, then reporting results.',
@@ -669,6 +688,8 @@ export const NAMED_AGENTS = {
             'NOT GROUNDED: no session index access — reviews with fresh eyes for unbiased adversarial check.',
         ].join(' '),
         tools: ['Read', 'Glob', 'Grep', 'Bash', 'Write', 'Edit'],
+        // Fail-closed: may ONLY write documentation files.
+        policy: { write: { extensions: /\.(md|markdown|mdx|txt|rst|adoc)$/i, label: 'documentation' } },
         model: 'sonnet',
         prompt: [
             'You are Osborn\'s reviewer agent. You are the VERIFY step in a generator-verifier loop.',
@@ -836,6 +857,64 @@ export function applyGrounding(agents, sessionId, workingDir) {
     }
     return out;
 }
+const DEFAULT_WRITE_POLICY = 'workspace';
+/** Path is inside the per-session sandbox workspace. */
+function isWorkspacePath(filePath) {
+    return !!filePath && (filePath.includes('/osb/') ||
+        filePath.includes('.osborn/sessions/') ||
+        filePath.includes('.osborn/research/'));
+}
+/** Effective write policy for the acting agent (null agentType = main orchestrator). */
+function resolveWritePolicy(agentType, roster) {
+    const def = agentType ? roster?.[agentType] : null;
+    return def?.policy?.write ?? DEFAULT_WRITE_POLICY;
+}
+/**
+ * Decide a Write/Edit/MultiEdit against a policy. Pure — no side effects.
+ *   'allow'  → let it fall through (→ canUseTool workspace auto-approve, or {}).
+ *   'defer'  → PreToolUse returns permissionDecision:'ask' (canUseTool decides).
+ *   'deny'   → hard block with reason.
+ */
+function decideWrite(policy, filePath) {
+    if (policy === 'anywhere')
+        return { decision: 'defer' };
+    if (policy === 'workspace') {
+        if (filePath && !isWorkspacePath(filePath)) {
+            return { decision: 'deny', reason: 'Research mode: writes restricted to session workspace.' };
+        }
+        return { decision: 'allow' };
+    }
+    // Extension whitelist — fail closed (empty/unknown path denied).
+    const target = policy.matchBasename ? (filePath ? basename(resolve(filePath)) : '') : filePath;
+    if (!filePath || !policy.extensions.test(target)) {
+        const reason = filePath
+            ? `Write denied: ${filePath} is not a ${policy.label} file. This agent may only write ${policy.label} files.`
+            : 'Write denied: could not determine target file path. Failing closed.';
+        return { decision: 'deny', reason };
+    }
+    return { decision: 'defer' };
+}
+/** Coordination config for the acting/target agent (null agentType = main). */
+function coordinationFor(agentType, roster) {
+    const def = agentType ? roster?.[agentType] : null;
+    return def?.coordination ?? null;
+}
+/**
+ * Strip/map behavior meta-fields so the roster is a clean AgentDefinition set
+ * for the SDK: drop `policy` (write-gate) and `coordination` (hook-driven),
+ * and map `reminder` → criticalSystemReminder_EXPERIMENTAL. NEVER mutates input.
+ */
+function finalizeRoster(agents) {
+    const out = {};
+    for (const [name, agent] of Object.entries(agents)) {
+        const { policy, reminder, coordination, ...rest } = agent;
+        if (reminder && !rest.criticalSystemReminder_EXPERIMENTAL) {
+            rest.criticalSystemReminder_EXPERIMENTAL = reminder;
+        }
+        out[name] = rest;
+    }
+    return out;
+}
 const RESEARCH_TOOLS = [
     'Read', 'Write', 'Edit', 'Glob', 'Grep',
     'Bash', 'WebSearch', 'WebFetch',
@@ -1955,6 +2034,10 @@ class ClaudeLLMStream extends llm.LLMStream {
                 ? getSessionWorkspace(this.#opts.workingDirectory, sessionId)
                 : null;
             const allowedTools = this.#opts.allowedTools || [];
+            // Roster the PreToolUse write-gate reads policy from — the PRE-strip view
+            // (retains `policy`), so DB-backed custom agents (set_agents) get their
+            // write policy enforced too. The SDK receives the finalized copy (agents:).
+            const enforcementRoster = this.#opts.agents ?? NAMED_AGENTS;
             const sdkOptions = {
                 cwd: this.#opts.workingDirectory,
                 permissionMode: this.#opts.permissionMode,
@@ -2072,54 +2155,41 @@ class ClaudeLLMStream extends llm.LLMStream {
                                         }
                                         console.log(`🔧 Tool call ${turnToolCallCount}/${TOOL_CALL_BUDGET}: ${toolName}`);
                                     }
-                                    // Write/Edit/MultiEdit access control
-                                    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
-                                        // Writer sub-agent gets full write access everywhere
-                                        console.log('verifying agent_type', agentType);
-                                        // Writer agent: no longer auto-approved — falls through to canUseTool for permission dialog
-                                        if (agentType === 'writer') {
-                                            console.log(`✍️ Writer agent: deferring to canUseTool for permission`);
+                                    // Delegation-point injection — when the hub spawns a sub-agent, add
+                                    // that agent's discretionary delegationNote to the hub's context
+                                    // (e.g. "add a tester for high-risk edits"). Empty by default → inert.
+                                    if (toolName === 'Task') {
+                                        const targetType = String(toolInput?.subagent_type || '');
+                                        const note = coordinationFor(targetType || null, enforcementRoster)?.delegationNote;
+                                        if (note) {
                                             this.#eventEmitter.emit('tool_use', { name: toolName, input: toolInput, agentRole: agentType || 'main' });
-                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
+                                            console.log(`🤝 Delegation note → subagent_type=${targetType}`);
+                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: note } };
                                         }
-                                        // Reviewer agent: ONLY documentation-extension files allowed — fail closed
-                                        if (agentType === 'reviewer') {
-                                            const reviewerPath = String(toolInput.file_path || '');
-                                            const DOC_EXTENSIONS = /\.(md|markdown|mdx|txt|rst|adoc)$/i;
-                                            if (!reviewerPath || !DOC_EXTENSIONS.test(reviewerPath)) {
-                                                const reason = reviewerPath
-                                                    ? `Reviewer write denied: ${reviewerPath} is not a documentation file (.md/.markdown/.mdx/.txt/.rst/.adoc). Reviewer may only write documentation.`
-                                                    : 'Reviewer write denied: could not determine target file path. Failing closed.';
-                                                console.log(`🚫 Reviewer write blocked: ${reviewerPath || '(no path)'} — not a doc extension`);
-                                                this.#eventEmitter.emit('tool_blocked', { name: toolName, reason });
-                                                return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason };
-                                            }
-                                            console.log(`📝 Reviewer doc write allowed: ${reviewerPath}`);
-                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
+                                    }
+                                    // Write/Edit/MultiEdit access control — DATA-DRIVEN by each agent's
+                                    // declarative policy.write (see AgentWritePolicy). Replaces the old
+                                    // hardcoded per-role branches; DB-backed custom agents get enforced too.
+                                    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+                                        const filePath = String(toolInput.file_path || '');
+                                        const policy = resolveWritePolicy(agentType, enforcementRoster);
+                                        const { decision, reason } = decideWrite(policy, filePath);
+                                        console.log(`🔎 Write gate: agent=${agentType ?? 'main'} policy=${JSON.stringify(policy)} path="${filePath || '(none)'}" → ${decision}`);
+                                        if (decision === 'deny') {
+                                            this.#eventEmitter.emit('tool_blocked', { name: toolName, reason });
+                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason };
                                         }
-                                        // Tester agent: ONLY test files allowed — fail closed
-                                        if (agentType === 'tester') {
-                                            const testerPath = String(toolInput.file_path || '');
-                                            const STRICT_TEST_FILE = /\.(test|spec)\.[jt]sx?$/;
-                                            const resolvedBase = testerPath ? basename(resolve(testerPath)) : '';
-                                            if (!testerPath || !STRICT_TEST_FILE.test(resolvedBase)) {
-                                                const reason = testerPath
-                                                    ? `Tester write denied: ${testerPath} is not a test file (basename must match .test.ts/tsx/js/jsx or .spec.ts/tsx/js/jsx). Tester may only write test files.`
-                                                    : 'Tester write denied: could not determine target file path. Failing closed.';
-                                                console.log(`🚫 Tester write blocked: ${testerPath || '(no path)'} — not a test file`);
-                                                this.#eventEmitter.emit('tool_blocked', { name: toolName, reason });
-                                                return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason };
+                                        if (decision === 'defer') {
+                                            // Writer (write:'anywhere') surfaces its write in the live trace
+                                            // before the permission dialog; adversarial agents (reviewer/tester)
+                                            // do NOT emit here — parity with the prior hardcoded branches.
+                                            if (policy === 'anywhere') {
+                                                this.#eventEmitter.emit('tool_use', { name: toolName, input: toolInput, agentRole: agentType || 'main' });
                                             }
-                                            console.log(`🧪 Tester test-file write allowed: ${testerPath}`);
                                             return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
                                         }
-                                        // All other agents (main, researcher, reasoner, etc.): workspace only
-                                        const filePath = String(toolInput.file_path || '');
-                                        if (filePath && !filePath.includes('/osb/') && !filePath.includes('.osborn/sessions/') && !filePath.includes('.osborn/research/')) {
-                                            console.log(`🚫 Research mode: blocked write to ${filePath} (agent_type: ${agentType ?? 'main'})`);
-                                            this.#eventEmitter.emit('tool_blocked', { name: toolName, reason: 'Research mode: writes restricted to session workspace' });
-                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason: 'Research mode: writes restricted to session workspace.' };
-                                        }
+                                        // decision === 'allow' → fall through to the shared tail (emits
+                                        // tool_use, returns {} → canUseTool workspace auto-approve).
                                     }
                                     console.log(`🔧 Claude: ${toolName}`);
                                     this.#eventEmitter.emit('tool_use', { name: toolName, input: toolInput, agentRole: agentType || 'main' });
@@ -2466,6 +2536,12 @@ class ClaudeLLMStream extends llm.LLMStream {
                             hooks: [async (input) => {
                                     console.log('[LIFECYCLE-PROBE] SubagentStart', JSON.stringify(input));
                                     this.#eventEmitter.emit('agent_started', { agent_type: input?.agent_type, agent_id: input?.agent_id });
+                                    // Inject the agent's declarative startNote (who it is paired with) —
+                                    // reliable, always-seen at boot regardless of what the hub relayed.
+                                    const startNote = coordinationFor(input?.agent_type ?? null, enforcementRoster)?.startNote;
+                                    if (startNote) {
+                                        return { hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: startNote } };
+                                    }
                                     return {};
                                 }]
                         }],
@@ -2478,15 +2554,34 @@ class ClaudeLLMStream extends llm.LLMStream {
                                     const aid = input?.agent_id ?? ('sa-' + Date.now());
                                     statusManager.upsertDispatch(aid, { subagentType: at, dispatchState: 'completed', artifact: msg });
                                     this.#eventEmitter.emit('task_completed', { agent_type: at, agent_id: aid, last_assistant_message: String(msg).slice(0, 400) });
-                                    // Infinite-loop guard — never re-dispatch the reviewer, tester, or reasoner.
+                                    // Infinite-loop guard — verifiers never re-dispatch (they carry no
+                                    // coordination.then anyway; this is defense-in-depth against a
+                                    // DB-backed agent accidentally arming a loop).
                                     if (at === 'reviewer' || at === 'tester' || at === 'reasoner')
                                         return {};
-                                    if (at === 'writer' && msg) {
-                                        void this.#llmRef.spawnReviewer(aid, msg, this.#eventEmitter);
-                                        void this.#llmRef.spawnTester(aid, msg, this.#eventEmitter);
-                                    }
-                                    else if (at === 'researcher' && msg) {
-                                        void this.#llmRef.spawnResearchGate(aid, msg, this.#eventEmitter);
+                                    // Declarative verifier chaining — driven by the finishing agent's
+                                    // coordination.then (replaces the hardcoded writer/researcher branches).
+                                    const coord = coordinationFor(at ?? null, enforcementRoster);
+                                    if (coord?.then?.length && msg) {
+                                        const spawn = (role) => {
+                                            if (role === 'reviewer')
+                                                return this.#llmRef.spawnReviewer(aid, msg, this.#eventEmitter);
+                                            if (role === 'tester')
+                                                return this.#llmRef.spawnTester(aid, msg, this.#eventEmitter);
+                                            if (role === 'reasoner' || role === 'gate')
+                                                return this.#llmRef.spawnResearchGate(aid, msg, this.#eventEmitter);
+                                            console.warn(`[DISPATCH] unknown coordination target '${role}' for ${at} — skipped`);
+                                            return Promise.resolve();
+                                        };
+                                        if (coord.mode === 'sequential') {
+                                            // Await in order WITHOUT blocking the hook return (fire the chain async).
+                                            void (async () => { for (const r of coord.then)
+                                                await spawn(r); })();
+                                        }
+                                        else {
+                                            for (const r of coord.then)
+                                                void spawn(r);
+                                        }
                                     }
                                     return {};
                                 }]
@@ -2513,9 +2608,9 @@ class ClaudeLLMStream extends llm.LLMStream {
                 // opts.agents is undefined — the ?? NAMED_AGENTS fallback would skip
                 // the override entirely. Explicitly apply applyTurbo(NAMED_AGENTS)
                 // so built-in agents always get FAST_MODEL when turbo is on.
-                agents: applyGrounding(this.#llmRef.turbo
+                agents: finalizeRoster(applyGrounding(this.#llmRef.turbo
                     ? applyTurbo(this.#opts.agents ?? NAMED_AGENTS, true)
-                    : (this.#opts.agents ?? NAMED_AGENTS), this.#sessionId, this.#opts.workingDirectory),
+                    : (this.#opts.agents ?? NAMED_AGENTS), this.#sessionId, this.#opts.workingDirectory)),
             };
             // Run Claude Agent SDK query() and stream results
             let hasOutput = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osborn",
-  "version": "0.9.217",
+  "version": "0.9.219",
   "description": "Voice AI coding assistant - local agent that connects to Osborn frontend",
   "type": "module",
   "bin": {