@orchestrator-claude/definitions 3.31.0 → 3.31.2

package/hooks/subagent-stop.ts

@@ -14,44 +14,103 @@ import {
   getField,
   getActiveWorkflow,
   outputContext,
-} from "./lib/api-client.js";
-import { createCheckpointIfNeeded } from "./lib/git-checkpoint.js";
+  readInvocationState,
+  consumeInvocationState,
+  completeAgentInvocation,
+  isInvocationStateStale,
+} from './lib/api-client.js';
+import { join } from 'node:path';
+import { createCheckpointIfNeeded } from './lib/git-checkpoint.js';
+import { appendObservation } from './lib/observations-helper.js';
 
-const HOOK = "SUBAGENT-STOP";
+const HOOK = 'SUBAGENT-STOP';
 
 async function main(): Promise<void> {
   const stdin = await readStdin();
-  log(HOOK, "SubagentStop triggered");
+  log(HOOK, 'SubagentStop triggered');
 
   const agentType =
-    getField(stdin, "agent_type") ||
-    getField(stdin, "tool_input.subagent_type") ||
-    "unknown";
+    getField(stdin, 'agent_type') || getField(stdin, 'tool_input.subagent_type') || 'unknown';
 
   const workflow = await getActiveWorkflow();
   if (!workflow) {
-    log(HOOK, "No active workflow, skipping");
+    log(HOOK, 'No active workflow, skipping');
     return;
   }
 
   log(HOOK, `agent=${agentType} workflow=${workflow.id} phase=${workflow.currentPhase}`);
 
-  // 1. Invocation tracking — agent self-reports via MCP; this is safety net
-  log(HOOK, `COMPLETE: agent=${agentType} (safety net — agent self-reports via MCP)`);
+  // 1. Invocation tracking safety net — complete via state file if agent did not self-report via MCP
+  const invocationState = readInvocationState(workflow.id, agentType);
+  if (invocationState) {
+    log(
+      HOOK,
+      `COMPLETE safety-net: found state file for agent=${agentType} invocationId=${invocationState.invocationId}`
+    );
+    if (isInvocationStateStale(invocationState)) {
+      log(
+        HOOK,
+        `COMPLETE safety-net: state file is stale (>4h) for invocationId=${invocationState.invocationId} — deleting without completing`
+      );
+      consumeInvocationState(workflow.id, agentType);
+    } else {
+      const completed = await completeAgentInvocation(
+        invocationState.invocationId,
+        'completed',
+        `Safety-net completion: agent ${agentType} finished phase ${workflow.currentPhase}`
+      );
+      if (completed) {
+        consumeInvocationState(workflow.id, agentType);
+        log(
+          HOOK,
+          `COMPLETE safety-net: invocationId=${invocationState.invocationId} marked complete, state file deleted`
+        );
+      } else {
+        log(
+          HOOK,
+          `COMPLETE safety-net: POST failed for invocationId=${invocationState.invocationId} (fail-open, continuing)`
+        );
+      }
+    }
+  } else {
+    log(
+      HOOK,
+      `COMPLETE: agent=${agentType} — no state file (agent self-reported via MCP or start hook skipped)`
+    );
+  }
 
   // 2. Git checkpoint if phase changed
   const commitHash = await createCheckpointIfNeeded(workflow.id, workflow.currentPhase);
 
   // 3. Guide main conversation — NO ping-pong, main IS the orchestrator
-  const parts: string[] = [`[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`];
+  const parts: string[] = [
+    `[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`,
+  ];
 
   if (commitHash) {
     parts.push(`Checkpoint: ${commitHash}.`);
   }
 
-  parts.push("Proceed to gate check via AskUserQuestion before advancing phase.");
+  parts.push('Proceed to gate check via AskUserQuestion before advancing phase.');
+
+  outputContext('SubagentStop', parts.join(' '));
 
-  outputContext("SubagentStop", parts.join(" "));
+  // 4. Write Tier B observation (fail-open)
+  try {
+    const sessionId = getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
+    const memoryBaseDir = join(process.cwd(), '.claude', 'agent-memory');
+    appendObservation(memoryBaseDir, agentType, {
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      phase: workflow.currentPhase,
+      workflow_id: workflow.id,
+      summary: `Agent ${agentType} completed phase ${workflow.currentPhase}${commitHash ? ` (checkpoint: ${commitHash})` : ''}`,
+      tags: [`agent:${agentType}`, `phase:${workflow.currentPhase}`],
+    });
+    log(HOOK, `Observation written for agent=${agentType}`);
+  } catch {
+    log(HOOK, 'Failed to write observation (fail-open, continuing)');
+  }
 }
 
 main().catch(() => process.exit(0));

package/hooks/user-prompt.ts

@@ -12,27 +12,28 @@ import {
   getNextAction,
   detectWorkflow,
   outputContext,
-} from "./lib/api-client.js";
+} from './lib/api-client.js';
+import { readSprintContext } from './lib/sprint-context.js';
 
-const HOOK = "USER-PROMPT";
+const HOOK = 'USER-PROMPT';
 
 async function main(): Promise<void> {
-  log(HOOK, "UserPromptSubmit triggered");
+  log(HOOK, 'UserPromptSubmit triggered');
 
   const stdin = await readStdin();
   const workflow = await getActiveWorkflow();
 
   if (!workflow) {
     // No active workflow — detect and suggest
-    const prompt = getField(stdin, "prompt");
+    const prompt = getField(stdin, 'prompt');
     if (!prompt) {
-      log(HOOK, "empty prompt, silence");
+      log(HOOK, 'empty prompt, silence');
       return;
     }
 
     const detection = await detectWorkflow(prompt);
     if (!detection) {
-      log(HOOK, "detect API failed/timeout, silence (fail-open)");
+      log(HOOK, 'detect API failed/timeout, silence (fail-open)');
       return;
     }
 
@@ -40,25 +41,25 @@ async function main(): Promise<void> {
     log(HOOK, `detected type=${workflowType} confidence=${confidence} mode=${suggestedMode}`);
 
     // Tier 1: interactive_analysis
-    if (workflowType === "interactive_analysis") {
+    if (workflowType === 'interactive_analysis') {
       outputContext(
-        "UserPromptSubmit",
+        'UserPromptSubmit',
         [
-          "[ORCHESTRATOR] This looks like an analytical/design request. How would you like to proceed?",
+          '[ORCHESTRATOR] This looks like an analytical/design request. How would you like to proceed?',
           '(a) Continue as a free conversation (no workflow)',
           '(b) Start an interactive_analysis workflow for structured exploration (cyclic phases: research → discuss → analyze)',
-          "",
+          '',
           'If you choose (b), I will call: mcp__orchestrator-tools__startWorkflow({ type: "interactive_analysis", prompt: "..." })',
-        ].join("\n")
+        ].join('\n')
       );
       return;
     }
 
     // Tier 2: high confidence (>= 0.7)
     if (confidence >= 0.7) {
-      const mode = suggestedMode || "standard";
+      const mode = suggestedMode || 'standard';
       outputContext(
-        "UserPromptSubmit",
+        'UserPromptSubmit',
         `[ORCHESTRATOR] Detected: ${workflowType} workflow (confidence: ${confidence}, suggested mode: ${mode}).\nTo start: mcp__orchestrator-tools__startWorkflow({ type: "${workflowType}", prompt: "...", mode: "${mode}" })\nOr continue without a workflow if this is exploratory.`
       );
       return;
@@ -67,7 +68,7 @@ async function main(): Promise<void> {
     // Tier 3: medium confidence (0.5-0.69)
     if (confidence >= 0.5) {
       outputContext(
-        "UserPromptSubmit",
+        'UserPromptSubmit',
         `[ORCHESTRATOR] Hint: this might be a ${workflowType} task. Consider starting a workflow if you plan to write code.`
       );
       return;
@@ -78,6 +79,33 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Active workflow — check for brainstorm context injection (RFC-027)
+  const prompt = getField(stdin, 'prompt');
+  if (/brainstorm/i.test(prompt)) {
+    try {
+      const sprintCtx = readSprintContext(workflow.id);
+      if (sprintCtx) {
+        const previousSummary =
+          sprintCtx.previousSprints.length === 0
+            ? 'none'
+            : sprintCtx.previousSprints.map((s) => `S${s.index}(${s.status})`).join(', ');
+
+        // Context format: keep in sync with brainstormContextBranch in user-prompt-brainstorm.test.ts
+        const brainstormContext = [
+          `[PARENT-DOC-CONTEXT] parentDocument=${sprintCtx.parentDocument} | sprint=${sprintCtx.sprintIndex} | scope=${sprintCtx.sprintScope} | previousSprints=${previousSummary}`,
+          `[ORCHESTRATOR] Include parent document context in this brainstorm. Read the RFC for background.`,
+        ].join('\n');
+
+        log(HOOK, `brainstorm detected, injecting sprint context for workflow=${workflow.id}`);
+        outputContext('UserPromptSubmit', brainstormContext);
+        return;
+      }
+    } catch {
+      // fail-open: if readSprintContext throws unexpectedly, continue to standard injection
+      log(HOOK, 'brainstorm context read failed, falling through to standard injection');
+    }
+  }
+
   // Active workflow — inject state
   const action = await getNextAction(workflow.id);
   let context: string;
@@ -89,7 +117,7 @@ async function main(): Promise<void> {
   }
 
   log(HOOK, `workflow=${workflow.id} hasAction=${action?.hasAction}`);
-  outputContext("UserPromptSubmit", context);
+  outputContext('UserPromptSubmit', context);
 }
 
 main().catch(() => process.exit(0));

package/hooks/workflow-guard.ts

@@ -1,10 +1,25 @@
 /**
  * workflow-guard.ts — PreToolUse[Write|Edit] hook (RFC-022 Phase 2)
  * Replaces workflow-guard.sh
+ *
  * Blocks writes to src/ and tests/ without active workflow.
- * Respects SKIP_WORKFLOW_GUARD, quick/interactive modes, sub-agent writes.
+ *
+ * Allow paths (in evaluation order):
+ *   1. SKIP_WORKFLOW_GUARD=true (explicit bypass, all paths)
+ *   2. Non-guarded path (file outside src/ or tests/)
+ *   3. Config/doc file extension (.json|.yaml|.yml|.md|.env*)
+ *   4. Active workflow + mode='quick' (main agent writes allowed by design)
+ *   5. Active workflow + mode='interactive' (writes unexpected, but allowed)
+ *   6. Active workflow + mode='direct' (ADR-017 Phase 3 — tracked via startDirectExecution)
+ *   7. Active workflow + caller is sub-agent (agent_id present in stdin)
+ *   8. Active workflow + SKIP_SUBAGENT_GUARD=true (DEPRECATED — ADR-013 §6.5.3, telemetered to observations.yaml)
+ * Deny paths:
+ *   - Active workflow + standard/full/legacy mode + main agent direct write (no agent_id, no bypass)
+ *   - No active workflow
  */
 
+import { join } from 'node:path';
+
 import {
   log,
   readStdin,
@@ -12,35 +27,39 @@ import {
   getActiveWorkflow,
   getWorkflowMode,
   outputPreToolUse,
-} from "./lib/api-client.js";
+} from './lib/api-client.js';
+import { appendObservation } from './lib/observations-helper.js';
 
-const HOOK = "WORKFLOW-GUARD";
+const HOOK = 'WORKFLOW-GUARD';
 
 async function main(): Promise<void> {
   const stdin = await readStdin();
-  const filePath = getField(stdin, "tool_input.file_path") || getField(stdin, "file_path") || getField(stdin, "input.file_path");
+  const filePath =
+    getField(stdin, 'tool_input.file_path') ||
+    getField(stdin, 'file_path') ||
+    getField(stdin, 'input.file_path');
 
   log(HOOK, `file_path=${filePath}`);
 
   // Explicit bypass
-  if (process.env.SKIP_WORKFLOW_GUARD === "true") {
-    log(HOOK, "ALLOW (SKIP_WORKFLOW_GUARD=true)");
+  if (process.env.SKIP_WORKFLOW_GUARD === 'true') {
+    log(HOOK, 'ALLOW (SKIP_WORKFLOW_GUARD=true)');
     outputPreToolUse({
-      decision: "allow",
-      context: "Workflow guard bypassed via SKIP_WORKFLOW_GUARD=true.",
+      decision: 'allow',
+      context: 'Workflow guard bypassed via SKIP_WORKFLOW_GUARD=true.',
     });
     return;
   }
 
   // Only guard src/ and tests/ paths
-  if (!filePath.includes("/src/") && !filePath.includes("/tests/")) {
-    log(HOOK, "ALLOW (non-guarded path)");
+  if (!filePath.includes('/src/') && !filePath.includes('/tests/')) {
+    log(HOOK, 'ALLOW (non-guarded path)');
     return;
   }
 
   // Allow config/doc files
   if (/\.(json|ya?ml|md|env(\..*)?)$/.test(filePath)) {
-    log(HOOK, "ALLOW (config/doc file)");
+    log(HOOK, 'ALLOW (config/doc file)');
     return;
   }
 
@@ -49,71 +68,111 @@ async function main(): Promise<void> {
 
   if (workflow) {
     const mode = await getWorkflowMode(workflow.id);
-    log(HOOK, `workflow=${workflow.id} mode=${mode || "legacy"}`);
+    log(HOOK, `workflow=${workflow.id} mode=${mode || 'legacy'}`);
 
-    if (mode === "quick") {
+    if (mode === 'quick') {
       outputPreToolUse({
-        decision: "allow",
+        decision: 'allow',
         context: `Active workflow: ${workflow.id} (mode: quick). Direct writes allowed in quick mode.`,
       });
       return;
     }
 
-    if (mode === "interactive") {
+    if (mode === 'interactive') {
       outputPreToolUse({
-        decision: "allow",
+        decision: 'allow',
         context: `Active workflow: ${workflow.id} (mode: interactive). Note: code writes are unexpected in interactive/analysis workflows.`,
       });
       return;
     }
 
+    // ADR-017 Phase 3: direct execution mode — main agent writes without sub-agent required
+    if (mode === 'direct') {
+      log(HOOK, `ALLOW (executionMode=direct, workflow: ${workflow.id})`);
+      outputPreToolUse({
+        decision: 'allow',
+        context: `Active workflow: ${workflow.id} (executionMode: direct). Direct writes allowed — record will be tracked via startDirectExecution/completeDirectExecution.`,
+      });
+      return;
+    }
+
     // Check if running inside a sub-agent
-    const agentId = getField(stdin, "agent_id");
+    const agentId = getField(stdin, 'agent_id');
     if (agentId) {
-      const agentType = getField(stdin, "agent_type");
-      log(HOOK, `ALLOW (sub-agent: ${agentType || "unknown"}, workflow: ${workflow.id})`);
+      const agentType = getField(stdin, 'agent_type');
+      log(HOOK, `ALLOW (sub-agent: ${agentType || 'unknown'}, workflow: ${workflow.id})`);
       outputPreToolUse({
-        decision: "allow",
-        context: `Active workflow: ${workflow.id}. Sub-agent ${agentType || "unknown"} write allowed.`,
+        decision: 'allow',
+        context: `Active workflow: ${workflow.id}. Sub-agent ${agentType || 'unknown'} write allowed.`,
       });
       return;
     }
 
     // Main agent writing directly — check SKIP_SUBAGENT_GUARD
-    if (process.env.SKIP_SUBAGENT_GUARD === "true") {
-      log(HOOK, `ALLOW (SKIP_SUBAGENT_GUARD=true, workflow: ${workflow.id})`);
+    // DEPRECATED per ADR-013 §6.5.3 — preferred replacements are mode='quick'
+    // (single-phase, main-agent writes) or mode='direct' (ADR-017 Phase 3,
+    // multi-phase main-agent writes with startDirectExecution audit trail).
+    // Each bypass is recorded to .claude/agent-memory/main/observations.yaml
+    // (RFC-027 Sprint 3) so usage can be measured before full removal.
+    if (process.env.SKIP_SUBAGENT_GUARD === 'true') {
+      log(HOOK, `ALLOW (SKIP_SUBAGENT_GUARD=true, workflow: ${workflow.id}) [DEPRECATED]`);
+
+      // Fail-open observation for cross-session telemetry
+      try {
+        const sessionId =
+          getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
+        const memoryBaseDir = join(process.cwd(), '.claude', 'agent-memory');
+        appendObservation(memoryBaseDir, 'main', {
+          timestamp: new Date().toISOString(),
+          session_id: sessionId,
+          phase: workflow.currentPhase || 'unknown',
+          workflow_id: workflow.id,
+          summary: `SKIP_SUBAGENT_GUARD bypass triggered. file=${filePath} mode=${mode || 'legacy'}. Prefer mode:'quick' or mode:'direct' (ADR-013 §6.5.3).`,
+          tags: ['skip_subagent_guard_bypass', 'deprecated_bypass', `mode:${mode || 'legacy'}`],
+        });
+      } catch {
+        // fail-open — never block on telemetry
+      }
+
       outputPreToolUse({
-        decision: "allow",
-        context: `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
+        decision: 'allow',
+        context: [
+          `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
+          '',
+          '⚠️ DEPRECATED per ADR-013 §6.5.3. Prefer:',
+          "  • mode:'quick' (startWorkflow({ mode: 'quick' })) — single-phase, main-agent writes allowed by design",
+          "  • mode:'direct' (ADR-017 Phase 3) — multi-phase, main-agent writes with startDirectExecution audit trail",
+          'Bypass logged to .claude/agent-memory/main/observations.yaml for usage review (S200+ remediation decision).',
+        ].join('\n'),
       });
       return;
     }
 
     // Main agent direct write — DENY
-    log(HOOK, `DENY (main agent direct write, mode=${mode || "legacy"})`);
+    log(HOOK, `DENY (main agent direct write, mode=${mode || 'legacy'})`);
     outputPreToolUse({
-      decision: "deny",
+      decision: 'deny',
       reason:
-        "Workflow Guard: Direct code writes are blocked. You must invoke a sub-agent (e.g. implementer) to write code. The sub-agent will have write access.",
+        'Workflow Guard: Direct code writes are blocked. You must invoke a sub-agent (e.g. implementer) to write code. The sub-agent will have write access.',
       context:
-        "Use the Agent tool to spawn an implementer sub-agent for code changes. The workflow-guard allows writes only from sub-agents (identified by agent_id in hook input).",
+        'Use the Agent tool to spawn an implementer sub-agent for code changes. The workflow-guard allows writes only from sub-agents (identified by agent_id in hook input).',
     });
     return;
   }
 
   // No active workflow — DENY
-  log(HOOK, "DENY (no active workflow)");
+  log(HOOK, 'DENY (no active workflow)');
   outputPreToolUse({
-    decision: "deny",
-    reason: "Workflow Guard: No active workflow. Direct implementation is not allowed.",
+    decision: 'deny',
+    reason: 'Workflow Guard: No active workflow. Direct implementation is not allowed.',
     context: [
-      "You MUST start a workflow before writing code:",
+      'You MUST start a workflow before writing code:',
       '1. mcp__orchestrator-tools__detectWorkflow({ prompt: "..." })',
       '2. mcp__orchestrator-tools__startWorkflow({ workflowType: "...", prompt: "..." })',
-      "3. Follow the nextStep returned by startWorkflow",
-      "",
-      "The workflow-guard hook blocks all writes to src/ and tests/ without an active workflow.",
-    ].join("\n"),
+      '3. Follow the nextStep returned by startWorkflow',
+      '',
+      'The workflow-guard hook blocks all writes to src/ and tests/ without an active workflow.',
+    ].join('\n'),
   });
 }