@orchestrator-claude/cli 3.11.0 → 3.12.0

package/templates/base/claude/hooks/orch-helpers.sh

@@ -60,28 +60,33 @@ orch_get_token() {
   fi
 }
 
-# Get the active (in_progress) workflow ID
+# Get the active (non-terminal) workflow ID
+# Checks in_progress, awaiting_agent, and awaiting_approval statuses
 orch_get_active_workflow() {
   local token
   token=$(orch_get_token) || return 1
 
-  local resp
-  resp=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows?status=in_progress&limit=1" \
-    -H "Authorization: Bearer $token" \
-    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || return 1
-
-  echo "$resp" | node -e "
-    let d='';
-    process.stdin.on('data',c=>d+=c);
-    process.stdin.on('end',()=>{
-      try {
-        const j=JSON.parse(d);
-        const wfs=j.data||j;
-        const wf=Array.isArray(wfs)?wfs[0]:wfs;
-        const id=wf?.id||'';
-        if(id) console.log(id); else process.exit(1);
-      } catch { process.exit(1); }
-    });" 2>/dev/null
+  local status id
+  for status in in_progress awaiting_agent awaiting_approval; do
+    local resp
+    resp=$(curl -sf --max-time 3 "${API_URL}/api/v1/workflows?status=${status}&limit=1" \
+      -H "Authorization: Bearer $token" \
+      -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || continue
+
+    id=$(echo "$resp" | node -e "
+      let d='';
+      process.stdin.on('data',c=>d+=c);
+      process.stdin.on('end',()=>{
+        try {
+          const j=JSON.parse(d);
+          const wfs=j.data||j;
+          const wf=Array.isArray(wfs)?wfs[0]:wfs;
+          const id=wf?.id||'';
+          if(id) console.log(id); else process.exit(1);
+        } catch { process.exit(1); }
+      });" 2>/dev/null) && [ -n "$id" ] && echo "$id" && return 0
+  done
+  return 1
 }
 
 # Call getNextAction for a workflow
@@ -90,7 +95,7 @@ orch_get_next_action() {
   local token
   token=$(orch_get_token) || return 1
 
-  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/next-action" \
+  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/pending-action" \
     -H "Authorization: Bearer $token" \
     -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
 }
@@ -102,7 +107,7 @@ orch_evaluate_gate() {
   local token
   token=$(orch_get_token) || return 1
 
-  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/evaluate-gate" \
+  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/gate/evaluate" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $token" \
     -H "X-Project-ID: $PROJECT_ID" \

package/templates/base/claude/hooks/ping-pong-enforcer.sh

@@ -1,72 +1,58 @@
 #!/bin/bash
-# ping-pong-enforcer.sh — ADR-013 Core Hook
-# Trigger: PostToolUse on Agent
-# Purpose: After ANY sub-agent returns, automatically call getNextAction
-#          and inject the result into the conversation.
+# ping-pong-enforcer.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: PostToolUse on Task (Agent tool)
+# Purpose: After ANY sub-agent returns, call getNextAction and inject
+#          the result as additionalContext into the main conversation.
 #
-# This makes Ping-Pong DETERMINISTIC: the LLM always receives the next
-# action regardless of whether it "remembers" to call getNextAction.
-#
-# Output goes to stdout → injected into Claude conversation context.
-# Exit 0 always (non-blocking — informational injection).
+# Output: JSON with additionalContext containing next action instructions
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/orch-helpers.sh"
 
-# Read stdin (Claude Code passes tool result JSON)
-STDIN_DATA=$(orch_read_stdin)
 orch_log "PING-PONG: PostToolUse Agent triggered"
 
 # Find active workflow
-WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || {
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
   orch_log "PING-PONG: No active workflow, skipping"
   exit 0
-}
+fi
 
 orch_log "PING-PONG: Active workflow=$WORKFLOW_ID"
 
 # Call getNextAction
-NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || {
-  orch_log "PING-PONG: getNextAction failed, skipping"
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+
+if [ -z "$NEXT_ACTION" ]; then
+  orch_log "PING-PONG: getNextAction failed or empty"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"[PING-PONG] Workflow ${WORKFLOW_ID} is active but getNextAction returned empty. Check workflow status with mcp__orchestrator-tools__getStatus.\"}}"
   exit 0
-}
+fi
 
-# Parse response
+# Extract key fields for the context message
 HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
-STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
 AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
-CURRENT_PHASE=$(orch_json_field "$NEXT_ACTION" "currentPhase")
+STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+PROMPT=$(orch_json_field "$NEXT_ACTION" "pendingAction.prompt")
 
-orch_log "PING-PONG: hasAction=$HAS_ACTION status=$STATUS agent=$AGENT phase=$CURRENT_PHASE"
+orch_log "PING-PONG: hasAction=$HAS_ACTION agent=$AGENT status=$STATUS"
 
-# Inject result into conversation
 if [ "$HAS_ACTION" = "true" ]; then
   if [ "$STATUS" = "awaiting_agent" ]; then
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — next action: invoke agent '$AGENT'"
-    echo "You MUST invoke this agent via Task tool with subagent_type='$AGENT'."
-    echo "Workflow ID: $WORKFLOW_ID | Phase: $CURRENT_PHASE"
+    CONTEXT="[PING-PONG] Next action for workflow ${WORKFLOW_ID}: Invoke agent '${AGENT}' via Agent tool. Status: awaiting_agent."
+    [ -n "$PROMPT" ] && CONTEXT="${CONTEXT} Prompt: ${PROMPT}"
   elif [ "$STATUS" = "awaiting_approval" ]; then
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — AWAITING HUMAN APPROVAL"
-    echo "Phase: $CURRENT_PHASE. Ask the user to review artifacts and approve before continuing."
-    echo "After approval, call: mcp__orchestrator-tools__approveAction({ workflowId: '$WORKFLOW_ID' })"
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} requires human approval before continuing. Ask the user to approve, then call mcp__orchestrator-tools__approveAction."
   else
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — pending action status: $STATUS"
-    echo "Full response: $NEXT_ACTION"
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} pending action: agent=${AGENT}, status=${STATUS}."
   fi
 else
-  if [ "$CURRENT_PHASE" = "implement" ]; then
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no more actions. Phase: implement."
-    echo "You MUST call: mcp__orchestrator-tools__completeWorkflow({ workflowId: '$WORKFLOW_ID' })"
-  else
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no pending actions. Phase: $CURRENT_PHASE."
-  fi
+  CONTEXT="[PING-PONG] No pending actions for workflow ${WORKFLOW_ID}. If current phase is implement, call mcp__orchestrator-extended__completeWorkflow to finalize."
 fi
 
+# Output structured JSON
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":$(echo "$CONTEXT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.stringify(d)))" 2>/dev/null)}}"
 exit 0

package/templates/base/claude/hooks/prompt-orchestrator.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# prompt-orchestrator.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: UserPromptSubmit
+# Purpose: On every user prompt, inject orchestrator context.
+#          If no workflow active, remind about workflow requirement.
+#          If workflow active, inject current state.
+#
+# Output: JSON with additionalContext (never blocks prompts)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "PROMPT-ORCH: UserPromptSubmit triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  # No workflow — inject reminder (lightweight, no API calls)
+  orch_log "PROMPT-ORCH: No active workflow, injecting reminder"
+  echo '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"[ORCHESTRATOR] No active workflow. If this request involves creating, modifying, or fixing code, you must start a workflow first (detectWorkflow → startWorkflow). The workflow-guard hook will block writes to src/ without a workflow."}}'
+  exit 0
+fi
+
+# Active workflow — inject state
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+PA_STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+if [ "$HAS_ACTION" = "true" ]; then
+  CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}. Next: invoke '${AGENT}' (${PA_STATUS})."
+else
+  CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}. No pending actions."
+fi
+
+orch_log "PROMPT-ORCH: workflow=$WORKFLOW_ID hasAction=$HAS_ACTION"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(echo "$CONTEXT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.stringify(d)))" 2>/dev/null)}}"
+exit 0

package/templates/base/claude/hooks/session-orchestrator.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# session-orchestrator.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: SessionStart
+# Purpose: On session start, check for active workflow and inject context.
+#          Helps the LLM resume work from where it left off.
+#
+# Output: JSON with additionalContext containing workflow state
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "SESSION-ORCH: SessionStart hook triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  orch_log "SESSION-ORCH: No active workflow"
+  echo '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[ORCHESTRATOR] No active workflow. For feature requests, bug fixes, or refactoring, start with:\n1. mcp__orchestrator-tools__detectWorkflow\n2. mcp__orchestrator-tools__startWorkflow\n3. Follow the nextStep returned\n\nDirect implementation is blocked by the workflow-guard hook."}}'
+  exit 0
+fi
+
+# Get workflow details
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID} (could not fetch details — auth failed).\"}}"
+  exit 0
+fi
+
+STATUS_RESP=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/status" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || STATUS_RESP=""
+
+PHASE=$(orch_json_field "$STATUS_RESP" "currentPhase")
+STATUS=$(orch_json_field "$STATUS_RESP" "status")
+WF_TYPE=$(orch_json_field "$STATUS_RESP" "type")
+
+# Get next action
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+PA_STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}\nType: ${WF_TYPE}\nPhase: ${PHASE}\nStatus: ${STATUS}"
+
+if [ "$HAS_ACTION" = "true" ]; then
+  CONTEXT="${CONTEXT}\nNext action: invoke '${AGENT}' (${PA_STATUS})"
+fi
+
+orch_log "SESSION-ORCH: Injecting workflow context (wf=$WORKFLOW_ID phase=$PHASE)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$(echo "$CONTEXT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.stringify(d)))" 2>/dev/null)}}"
+exit 0

package/templates/base/claude/hooks/workflow-guard.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# workflow-guard.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: PreToolUse on Write|Edit
+# Purpose: Block writes to src/ and tests/ when no active workflow exists.
+#
+# Output: JSON with permissionDecision (deny/allow) + additionalContext
+# Exit 0 with JSON = structured decision
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+STDIN_DATA=$(orch_read_stdin)
+
+# Extract file path (Claude Code wraps in tool_input)
+FILE_PATH=$(orch_json_field "$STDIN_DATA" "tool_input.file_path")
+[ -z "$FILE_PATH" ] && FILE_PATH=$(orch_json_field "$STDIN_DATA" "file_path")
+[ -z "$FILE_PATH" ] && FILE_PATH=$(orch_json_field "$STDIN_DATA" "input.file_path")
+
+orch_log "workflow-guard: file_path=$FILE_PATH"
+
+# Only guard src/ and tests/ paths (production code)
+case "$FILE_PATH" in
+  */src/*|*/tests/*)
+    ;;
+  *)
+    orch_log "workflow-guard: ALLOW (non-guarded path)"
+    exit 0
+    ;;
+esac
+
+# Allow config and non-code files
+case "$FILE_PATH" in
+  *.json|*.yml|*.yaml|*.md|*.env|*.env.*)
+    orch_log "workflow-guard: ALLOW (config/doc file)"
+    exit 0
+    ;;
+esac
+
+# Check for active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -n "$WORKFLOW_ID" ]; then
+  orch_log "workflow-guard: ALLOW (active workflow: $WORKFLOW_ID)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Active workflow: ${WORKFLOW_ID}. Write allowed.\"}}"
+  exit 0
+fi
+
+# No active workflow — DENY with structured instructions
+orch_log "workflow-guard: DENY (no active workflow)"
+echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Workflow Guard: No active workflow. Direct implementation is not allowed.","additionalContext":"You MUST start a workflow before writing code:\n1. mcp__orchestrator-tools__detectWorkflow({ prompt: \"...\" })\n2. mcp__orchestrator-tools__startWorkflow({ workflowType: \"...\", prompt: \"...\" })\n3. Follow the nextStep returned by startWorkflow\n\nThe workflow-guard hook blocks all writes to src/ and tests/ without an active workflow."}}'
+exit 0

package/templates/base/claude/settings.json

@@ -37,6 +37,32 @@
     "NODE_ENV": "development"
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/session-orchestrator.sh",
+            "timeout": 10000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/prompt-orchestrator.sh",
+            "timeout": 10000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Task",
@@ -59,6 +85,17 @@
             "on_failure": "warn"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/workflow-guard.sh",
+            "timeout": 10000,
+            "on_failure": "warn"
+          }
+        ]
       }
     ],
     "PostToolUse": [