@orchestrator-claude/definitions 3.12.1 → 3.12.3

package/hooks/dangling-workflow-guard.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# dangling-workflow-guard.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: Stop
+# Purpose: Before conversation ends, check for workflows in in_progress state.
+#          Blocks stop and instructs LLM to call completeWorkflow.
+#
+# Output: JSON with decision: "block" + reason (forces LLM to continue)
+# Exit 0 with block JSON = prevent stop
+# Check stop_hook_active to prevent infinite loops
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+STDIN_DATA=$(orch_read_stdin)
+orch_log "DANGLING-GUARD: Stop hook triggered"
+
+# Prevent infinite loops
+STOP_ACTIVE=$(orch_json_field "$STDIN_DATA" "stop_hook_active")
+if [ "$STOP_ACTIVE" = "true" ]; then
+  orch_log "DANGLING-GUARD: stop_hook_active=true, allowing stop to prevent loop"
+  exit 0
+fi
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  orch_log "DANGLING-GUARD: No active workflow, clean exit"
+  exit 0
+fi
+
+# Get workflow status
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  orch_log "DANGLING-GUARD: Auth failed, allowing stop"
+  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")
+
+orch_log "DANGLING-GUARD: workflow=$WORKFLOW_ID status=$STATUS phase=$PHASE"
+
+if [ "$STATUS" = "in_progress" ] || [ "$STATUS" = "awaiting_agent" ] || [ "$STATUS" = "awaiting_approval" ]; then
+  orch_log "DANGLING-GUARD: BLOCK stop (workflow still active)"
+  echo "{\"decision\":\"block\",\"reason\":\"[DANGLING-GUARD] Workflow ${WORKFLOW_ID} is still ${STATUS} (phase: ${PHASE}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${WORKFLOW_ID}' }) before ending the session.\"}"
+  exit 0
+fi
+
+orch_log "DANGLING-GUARD: Workflow completed or not active, allowing stop"
+exit 0

package/hooks/gate-guardian.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# gate-guardian.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: PreToolUse on mcp__orchestrator-tools__advancePhase
+# Purpose: Evaluate gate before phase advance. FAIL-CLOSED: blocks when uncertain.
+#
+# 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)
+orch_log "GATE-GUARDIAN: PreToolUse advancePhase triggered"
+
+# Extract parameters
+WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
+TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "tool_input.targetPhase")
+[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
+[ -z "$TARGET_PHASE" ] && TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "targetPhase")
+
+orch_log "GATE-GUARDIAN: workflow=$WORKFLOW_ID targetPhase=$TARGET_PHASE"
+
+# FAIL-CLOSED: if we can't parse input, DENY
+if [ -z "$WORKFLOW_ID" ] || [ -z "$TARGET_PHASE" ]; then
+  orch_log "GATE-GUARDIAN: DENY (could not parse input)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Gate Guardian: Could not parse workflowId or targetPhase.","additionalContext":"Ensure you pass both workflowId and targetPhase to advancePhase."}}'
+  exit 0
+fi
+
+# Get auth token — FAIL-CLOSED on auth failure
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  orch_log "GATE-GUARDIAN: DENY (auth failed)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Gate Guardian: Authentication failed.","additionalContext":"Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars."}}'
+  exit 0
+fi
+
+# Special handling for IMPLEMENT phase: require approval
+TARGET_LOWER=$(echo "$TARGET_PHASE" | tr '[:upper:]' '[:lower:]')
+if [ "$TARGET_LOWER" = "implement" ]; then
+  orch_log "GATE-GUARDIAN: Checking approval for IMPLEMENT phase"
+
+  PENDING=$(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) || PENDING=""
+
+  if [ -n "$PENDING" ]; then
+    PENDING_STATUS=$(orch_json_field "$PENDING" "status")
+    if [ "$PENDING_STATUS" != "approved" ] && [ "$PENDING_STATUS" != "awaiting_agent" ]; then
+      orch_log "GATE-GUARDIAN: DENY (IMPLEMENT requires approval, status=$PENDING_STATUS)"
+      echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: IMPLEMENT requires human approval. Status: ${PENDING_STATUS}.\",\"additionalContext\":\"Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.\"}}"
+      exit 0
+    fi
+  fi
+fi
+
+# Evaluate gate via API — FAIL-CLOSED on failure
+GATE_RESULT=$(orch_evaluate_gate "$WORKFLOW_ID" "$TARGET_PHASE" 2>/dev/null) || GATE_RESULT=""
+if [ -z "$GATE_RESULT" ]; then
+  orch_log "GATE-GUARDIAN: DENY (gate evaluation failed)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: Gate evaluation failed for phase '${TARGET_PHASE}'.\",\"additionalContext\":\"Required artifacts may be missing. Complete the current phase before advancing.\"}}"
+  exit 0
+fi
+
+PASSED=$(orch_json_field "$GATE_RESULT" "passed")
+
+if [ "$PASSED" = "true" ]; then
+  orch_log "GATE-GUARDIAN: ALLOW (gate passed for $TARGET_PHASE)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Gate to '${TARGET_PHASE}' passed.\"}}"
+  exit 0
+fi
+
+# Gate failed
+REASONS=$(orch_json_field "$GATE_RESULT" "reasons")
+orch_log "GATE-GUARDIAN: DENY (gate failed: $REASONS)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: Gate to '${TARGET_PHASE}' did not pass.\",\"additionalContext\":\"Reasons: ${REASONS}. Complete current phase requirements before advancing.\"}}"
+exit 0

package/hooks/orch-helpers.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+# orch-helpers.sh — Shared helper functions for Orchestrator hooks
+# ADR-013: Deterministic Orchestration
+# Sourced by all hooks. NOT called directly.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+DEBUG_LOG="$STATE_DIR/hook-debug.log"
+
+# API Configuration (from .env or defaults)
+API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
+AUTH_EMAIL="${ORCHESTRATOR_ADMIN_EMAIL:-${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}}"
+AUTH_PASSWORD="${ORCHESTRATOR_ADMIN_PASSWORD:-${ORCHESTRATOR_AUTH_PASSWORD:-admin123}}"
+PROJECT_ID="${ORCHESTRATOR_PROJECT_ID}"
+
+mkdir -p "$STATE_DIR"
+
+orch_log() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+# Read stdin (Claude Code passes JSON via stdin)
+orch_read_stdin() {
+  if [ ! -t 0 ]; then
+    cat
+  else
+    echo ""
+  fi
+}
+
+# Get cached JWT token (login if expired)
+orch_get_token() {
+  local cached="$STATE_DIR/jwt-token"
+  if [ -f "$cached" ]; then
+    local age
+    age=$(( $(date +%s) - $(stat -c%Y "$cached" 2>/dev/null || stat -f%m "$cached" 2>/dev/null || echo 0) ))
+    if [ "$age" -lt 3500 ]; then
+      cat "$cached"
+      return
+    fi
+  fi
+
+  [ -z "$PROJECT_ID" ] && return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 -X POST "${API_URL}/api/v1/auth/login" \
+    -H "Content-Type: application/json" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"email\":\"${AUTH_EMAIL}\",\"password\":\"${AUTH_PASSWORD}\"}" 2>/dev/null) || return 1
+
+  local token
+  token=$(echo "$resp" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);console.log(j.accessToken||j.data?.accessToken||'')}catch{console.log('')}})" 2>/dev/null)
+
+  if [ -n "$token" ] && [ "$token" != "" ]; then
+    echo "$token" > "$cached"
+    echo "$token"
+  else
+    return 1
+  fi
+}
+
+# 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 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
+orch_get_next_action() {
+  local workflow_id="$1"
+  local token
+  token=$(orch_get_token) || return 1
+
+  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
+}
+
+# Call evaluateGate for a workflow
+orch_evaluate_gate() {
+  local workflow_id="$1"
+  local target_phase="$2"
+  local token
+  token=$(orch_get_token) || return 1
+
+  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" \
+    -d "{\"targetPhase\":\"${target_phase}\"}" 2>/dev/null
+}
+
+# Extract a field from JSON string using node
+orch_json_field() {
+  local json="$1"
+  local field="$2"
+  echo "$json" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const parts='${field}'.split('.');
+        let v=j;
+        for(const p of parts) v=v?.[p];
+        console.log(v||'');
+      } catch { console.log(''); }
+    });" 2>/dev/null
+}

package/hooks/ping-pong-enforcer.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# 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.
+#
+# 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"
+
+orch_log "PING-PONG: PostToolUse Agent triggered"
+
+# Find active workflow
+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) || 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
+
+# Extract key fields for the context message
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+PROMPT=$(orch_json_field "$NEXT_ACTION" "pendingAction.prompt")
+
+orch_log "PING-PONG: hasAction=$HAS_ACTION agent=$AGENT status=$STATUS"
+
+if [ "$HAS_ACTION" = "true" ]; then
+  if [ "$STATUS" = "awaiting_agent" ]; then
+    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
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} requires human approval before continuing. Ask the user to approve, then call mcp__orchestrator-tools__approveAction."
+  else
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} pending action: agent=${AGENT}, status=${STATUS}."
+  fi
+else
+  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