@orchestrator-claude/definitions 3.17.1 → 3.18.0

package/hooks/user-prompt.ts

@@ -0,0 +1,95 @@
+/**
+ * user-prompt.ts — UserPromptSubmit hook (RFC-022 Phase 2)
+ * Replaces prompt-orchestrator.sh
+ * Detects workflow type and injects hints by confidence tiers.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getNextAction,
+  detectWorkflow,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "USER-PROMPT";
+
+async function main(): Promise<void> {
+  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");
+    if (!prompt) {
+      log(HOOK, "empty prompt, silence");
+      return;
+    }
+
+    const detection = await detectWorkflow(prompt);
+    if (!detection) {
+      log(HOOK, "detect API failed/timeout, silence (fail-open)");
+      return;
+    }
+
+    const { workflowType, confidence, suggestedMode } = detection;
+    log(HOOK, `detected type=${workflowType} confidence=${confidence} mode=${suggestedMode}`);
+
+    // Tier 1: interactive_analysis
+    if (workflowType === "interactive_analysis") {
+      outputContext(
+        "UserPromptSubmit",
+        [
+          "[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")
+      );
+      return;
+    }
+
+    // Tier 2: high confidence (>= 0.7)
+    if (confidence >= 0.7) {
+      const mode = suggestedMode || "standard";
+      outputContext(
+        "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;
+    }
+
+    // Tier 3: medium confidence (0.5-0.69)
+    if (confidence >= 0.5) {
+      outputContext(
+        "UserPromptSubmit",
+        `[ORCHESTRATOR] Hint: this might be a ${workflowType} task. Consider starting a workflow if you plan to write code.`
+      );
+      return;
+    }
+
+    // Tier 4: low confidence — silence
+    log(HOOK, `Tier 4 silence (confidence=${confidence} < 0.5)`);
+    return;
+  }
+
+  // Active workflow — inject state
+  const action = await getNextAction(workflow.id);
+  let context: string;
+
+  if (action?.hasAction && action.pendingAction) {
+    context = `[ORCHESTRATOR] Active workflow: ${workflow.id}. Next: invoke '${action.pendingAction.agent}' (${action.pendingAction.status}).`;
+  } else {
+    context = `[ORCHESTRATOR] Active workflow: ${workflow.id}. No pending actions.`;
+  }
+
+  log(HOOK, `workflow=${workflow.id} hasAction=${action?.hasAction}`);
+  outputContext("UserPromptSubmit", context);
+}
+
+main().catch(() => process.exit(0));

package/hooks/workflow-guard.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getWorkflowMode,
+  outputPreToolUse,
+} from "./lib/api-client.js";
+
+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");
+
+  log(HOOK, `file_path=${filePath}`);
+
+  // Explicit bypass
+  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.",
+    });
+    return;
+  }
+
+  // Only guard src/ and tests/ paths
+  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)");
+    return;
+  }
+
+  // Check for active workflow
+  const workflow = await getActiveWorkflow();
+
+  if (workflow) {
+    const mode = await getWorkflowMode(workflow.id);
+    log(HOOK, `workflow=${workflow.id} mode=${mode || "legacy"}`);
+
+    if (mode === "quick") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id} (mode: quick). Direct writes allowed in quick mode.`,
+      });
+      return;
+    }
+
+    if (mode === "interactive") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id} (mode: interactive). Note: code writes are unexpected in interactive/analysis workflows.`,
+      });
+      return;
+    }
+
+    // Check if running inside a sub-agent
+    const agentId = getField(stdin, "agent_id");
+    if (agentId) {
+      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.`,
+      });
+      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})`);
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
+      });
+      return;
+    }
+
+    // Main agent direct write — DENY
+    log(HOOK, `DENY (main agent direct write, mode=${mode || "legacy"})`);
+    outputPreToolUse({
+      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.",
+      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).",
+    });
+    return;
+  }
+
+  // No active workflow — DENY
+  log(HOOK, "DENY (no active workflow)");
+  outputPreToolUse({
+    decision: "deny",
+    reason: "Workflow Guard: No active workflow. Direct implementation is not allowed.",
+    context: [
+      "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"),
+  });
+}
+
+main().catch(() => process.exit(0));

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "orchestrator-definitions/v1",
   "namespace": "orchestrator",
-  "version": "3.17.1",
-  "generatedAt": "2026-03-20T19:11:53.058Z",
+  "version": "3.18.0",
+  "generatedAt": "2026-03-24T00:26:43.809Z",
   "definitions": {
     "agents": [
       {
@@ -65,7 +65,7 @@
         "slug": "orchestrator",
         "file": "agents/orchestrator.md",
         "version": "1.0.0",
-        "checksum": "sha256:b7a5cd4da196355be0a406dbc61d524462eb7fdcfb764fbbc88c54f067252192",
+        "checksum": "sha256:026d1bee4f40979b281f9372972e54b8538b8c4bde032fbd142cc15cc3f80cdc",
         "supersedes": null,
         "metadata": {}
       },
@@ -232,88 +232,7 @@
         "metadata": {}
       }
     ],
-    "hooks": [
-      {
-        "slug": "approval-guardian",
-        "file": "hooks/approval-guardian.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:5d9c1080926610cd3dd1babc3815ec82c93f46177758a5a921f65a717196bd83",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "dangling-workflow-guard",
-        "file": "hooks/dangling-workflow-guard.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:34b195e03357e1d264328d7345832845beae11d2846c8e22810e427b20c75a0c",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "gate-guardian",
-        "file": "hooks/gate-guardian.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:1631a7be326e1099698f6492caead2f05423582869bba0f69a50754055e1be2d",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "orch-helpers",
-        "file": "hooks/orch-helpers.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:906d72e990592bcac675d01c8e8f7ea2df42794b59492992fd8a15975b50608d",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "ping-pong-enforcer",
-        "file": "hooks/ping-pong-enforcer.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:d2a5a10ea253da2ead5e203d64690129a56f377ecabe7ea4d43cd9c99d4cad95",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "post-phase-checkpoint",
-        "file": "hooks/post-phase-checkpoint.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:f75c815334e371bf508642b9591d94a548e1221c65ff7f34af9e430ec6e88722",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "prompt-orchestrator",
-        "file": "hooks/prompt-orchestrator.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:93835c7798185a9c8f8bf84a029c660b2bbe34801cd34c5be6b2b7a1f07a0b8b",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "session-orchestrator",
-        "file": "hooks/session-orchestrator.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:143024a68b8438a0724fd93dd9b6eb1688bcc89c1a846ae7f6c389361b469f65",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "track-agent-invocation",
-        "file": "hooks/track-agent-invocation.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:6a9343b032dd72e391fc4c476af480ee3055a5a25ec60d3524b0b0d804a80c6d",
-        "supersedes": null,
-        "metadata": {}
-      },
-      {
-        "slug": "workflow-guard",
-        "file": "hooks/workflow-guard.sh",
-        "version": "1.0.0",
-        "checksum": "sha256:170a15396a61c537df4c8adc093d7ac36faab6e7de761ff8d283828c53e4a332",
-        "supersedes": null,
-        "metadata": {}
-      }
-    ],
+    "hooks": [],
     "workflows": [
       {
         "slug": "bug-fix",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/definitions",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
   "type": "module",
   "main": "dist/index.js",

package/hooks/approval-guardian.sh

@@ -1,62 +0,0 @@
-#!/bin/bash
-# approval-guardian.sh — TD-128 F-09 Hook
-# Trigger: PreToolUse on mcp__orchestrator-tools__approveAction and mcp__orchestrator-extended__completeWorkflow
-# Purpose: Block auto-approve and auto-complete when workflow is awaiting_approval.
-#          Requires explicit human confirmation before proceeding.
-#
-# Output: JSON with permissionDecision (deny/allow)
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/orch-helpers.sh"
-
-STDIN_DATA=$(orch_read_stdin)
-TOOL_NAME=$(orch_json_field "$STDIN_DATA" "tool_name")
-orch_log "APPROVAL-GUARDIAN: PreToolUse $TOOL_NAME triggered"
-
-# Extract workflow ID from tool_input
-WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
-[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
-
-if [ -z "$WORKFLOW_ID" ]; then
-  # No workflow ID — allow (fail-open for non-workflow calls)
-  orch_log "APPROVAL-GUARDIAN: ALLOW (no workflowId)"
-  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"No workflowId found, allowing."}}'
-  exit 0
-fi
-
-# Get auth token
-TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
-if [ -z "$TOKEN" ]; then
-  # Can't check status — fail-open (auth issues shouldn't block workflow completion)
-  orch_log "APPROVAL-GUARDIAN: ALLOW (auth failed, fail-open)"
-  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Auth failed, allowing."}}'
-  exit 0
-fi
-
-# Get workflow status
-STATUS=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || STATUS=""
-
-if [ -z "$STATUS" ]; then
-  orch_log "APPROVAL-GUARDIAN: ALLOW (could not fetch workflow status)"
-  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Could not fetch workflow status, allowing."}}'
-  exit 0
-fi
-
-WORKFLOW_STATUS=$(orch_json_field "$STATUS" "status")
-orch_log "APPROVAL-GUARDIAN: workflow=$WORKFLOW_ID status=$WORKFLOW_STATUS tool=$TOOL_NAME"
-
-# Block approveAction AND completeWorkflow when awaiting_approval
-if [ "$WORKFLOW_STATUS" = "awaiting_approval" ]; then
-  orch_log "APPROVAL-GUARDIAN: DENY (workflow awaiting_approval — human confirmation required for $TOOL_NAME)"
-  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Approval Guardian: Workflow is awaiting human approval. You MUST ask the user for explicit confirmation before calling ${TOOL_NAME}.\",\"additionalContext\":\"Present the workflow summary to the user and ask: 'Do you approve advancing to IMPLEMENT?' Wait for their response. Do NOT auto-approve or auto-complete.\"}}"
-  exit 0
-fi
-
-# All other statuses: ALLOW
-orch_log "APPROVAL-GUARDIAN: ALLOW ($TOOL_NAME, status=$WORKFLOW_STATUS)"
-echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"${TOOL_NAME} allowed (status=${WORKFLOW_STATUS}).\"}}"
-exit 0

package/hooks/dangling-workflow-guard.sh

@@ -1,57 +0,0 @@
-#!/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

@@ -1,84 +0,0 @@
-#!/bin/bash
-# gate-guardian.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
-# Trigger: PreToolUse on mcp__orchestrator-tools__advancePhase
-# Purpose: Guard IMPLEMENT phase advance (requires human approval). ALLOWs all other phases.
-# Note: POST /gate/evaluate endpoint removed (TD-127). Phase transitions are now handled
-# atomically by setPendingAction() via the ping-pong-enforcer hook.
-#
-# 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"
-
-# ADR-013 Phase 6: Check workflow mode before gate evaluation
-# quick and interactive modes skip gate evaluation entirely
-if [ -n "$WORKFLOW_ID" ]; then
-  MODE=$(orch_get_workflow_mode "$WORKFLOW_ID" 2>/dev/null) || MODE=""
-  orch_log "GATE-GUARDIAN: workflow=$WORKFLOW_ID mode=${MODE:-legacy}"
-
-  if [ "$MODE" = "quick" ]; then
-    orch_log "GATE-GUARDIAN: ALLOW (quick mode skips gate evaluation)"
-    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Gate to '${TARGET_PHASE}' allowed: quick mode skips gate evaluation.\"}}"
-    exit 0
-  fi
-
-  if [ "$MODE" = "interactive" ]; then
-    orch_log "GATE-GUARDIAN: ALLOW (interactive mode skips gate evaluation, artifact gates not required)"
-    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Gate to '${TARGET_PHASE}' allowed: interactive mode skips artifact gate evaluation.\"}}"
-    exit 0
-  fi
-fi
-
-# 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
-
-# Non-IMPLEMENT phases: ALLOW directly.
-# Phase transitions are handled atomically by setPendingAction() via ping-pong-enforcer.
-orch_log "GATE-GUARDIAN: ALLOW (non-IMPLEMENT phase, no gate evaluation required)"
-echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Gate to '${TARGET_PHASE}' allowed.\"}}"
-exit 0

package/hooks/orch-helpers.sh

@@ -1,135 +0,0 @@
-#!/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
-}
-
-# ADR-013 Phase 6: Get the mode of a workflow (quick/standard/full/interactive)
-# Returns the mode string, or empty string for legacy workflows (mode=null)
-# Returns exit code 1 on network/auth error
-orch_get_workflow_mode() {
-  local workflow_id="$1"
-  local token
-  token=$(orch_get_token) || return 1
-
-  local resp
-  resp=$(curl -sf --max-time 3 "${API_URL}/api/v1/workflows/${workflow_id}/status" \
-    -H "Authorization: Bearer $token" \
-    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || return 1
-
-  orch_json_field "$resp" "mode"
-}
-
-# 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
-}