@orchestrator-claude/definitions 3.5.0

package/hooks/post-agent-artifact-relay.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# Post-Agent Artifact Relay Hook
+# TD-039: Automatically relays artifacts from staging to MinIO after agent completion.
+#
+# Called as a PostToolUse hook on the Task matcher.
+# Reads stdin JSON with structure:
+#   { "tool_name": "Task", "tool_input": { "subagent_type": "...", ... } }
+#
+# Flow:
+# 1. Extract subagent_type from stdin
+# 2. Skip non-artifact agents (orchestrator, reviewer, docs-guardian, etc.)
+# 3. Get active workflow from API
+# 4. Login to get JWT token
+# 5. Call DELETE /api/v1/workflows/:id/pending-action to trigger relay
+# 6. Log result
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+LOG_FILE="$STATE_DIR/relay-hook.log"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# Log rotation: max 1MB
+MAX_LOG_SIZE=1048576
+if [ -f "$LOG_FILE" ]; then
+  LOG_SIZE=$(stat -f%z "$LOG_FILE" 2>/dev/null || stat -c%s "$LOG_FILE" 2>/dev/null || echo 0)
+  if [ "$LOG_SIZE" -gt "$MAX_LOG_SIZE" ]; then
+    [ -f "${LOG_FILE}.1" ] && mv "${LOG_FILE}.1" "${LOG_FILE}.2"
+    mv "$LOG_FILE" "${LOG_FILE}.1"
+  fi
+fi
+
+log() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$LOG_FILE"
+}
+
+# Configuration
+API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
+AUTH_EMAIL="${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}"
+AUTH_PASSWORD="${ORCHESTRATOR_AUTH_PASSWORD:-admin123}"
+
+# Read stdin
+STDIN_DATA=""
+if [ ! -t 0 ]; then
+  STDIN_DATA=$(cat)
+fi
+
+if [ -z "$STDIN_DATA" ]; then
+  log "SKIP: No stdin data"
+  exit 0
+fi
+
+# Extract agent type from stdin JSON
+AGENT_TYPE=$(echo "$STDIN_DATA" | node -e "
+  let data = '';
+  process.stdin.on('data', chunk => data += chunk);
+  process.stdin.on('end', () => {
+    try {
+      const json = JSON.parse(data);
+      const type = json.tool_input?.subagent_type
+                || json.subagent_type
+                || json.tool_input?.type
+                || '';
+      console.log(type);
+    } catch { console.log(''); }
+  });
+" 2>/dev/null)
+
+if [ -z "$AGENT_TYPE" ]; then
+  log "SKIP: Could not extract agent type"
+  exit 0
+fi
+
+# TD-039 Phase 3: Inverted whitelist → blacklist.
+# All agents produce artifacts EXCEPT orchestrator (coordinator only).
+case "$AGENT_TYPE" in
+  orchestrator)
+    log "SKIP: Agent '$AGENT_TYPE' is a coordinator, not an artifact producer"
+    exit 0
+    ;;
+  *)
+    log "RELAY: Agent '$AGENT_TYPE' completed, starting relay..."
+    ;;
+esac
+
+# Get active workflow status
+STATUS_RESPONSE=$(curl -s -f "${API_URL}/api/v1/workflows/status" 2>/dev/null) || {
+  log "SKIP: Could not reach API at ${API_URL}/api/v1/workflows/status"
+  exit 0
+}
+
+WORKFLOW_ID=$(echo "$STATUS_RESPONSE" | node -e "
+  let data = '';
+  process.stdin.on('data', chunk => data += chunk);
+  process.stdin.on('end', () => {
+    try {
+      const json = JSON.parse(data);
+      // Support both { id } and { data: { id } } shapes
+      const id = json.data?.id || json.id || '';
+      console.log(id);
+    } catch { console.log(''); }
+  });
+" 2>/dev/null)
+
+if [ -z "$WORKFLOW_ID" ]; then
+  log "SKIP: No active workflow found"
+  exit 0
+fi
+
+log "RELAY: Active workflow=$WORKFLOW_ID"
+
+# Login to get JWT token
+LOGIN_PAYLOAD=$(node -e "console.log(JSON.stringify({email:'${AUTH_EMAIL}',password:'${AUTH_PASSWORD}'}))")
+LOGIN_RESPONSE=$(curl -s -f -X POST "${API_URL}/api/v1/auth/login" \
+  -H "Content-Type: application/json" \
+  -d "$LOGIN_PAYLOAD" 2>/dev/null) || {
+  log "ERROR: Login failed"
+  exit 0
+}
+
+TOKEN=$(echo "$LOGIN_RESPONSE" | node -e "
+  let data = '';
+  process.stdin.on('data', chunk => data += chunk);
+  process.stdin.on('end', () => {
+    try {
+      const json = JSON.parse(data);
+      console.log(json.data?.accessToken || json.accessToken || json.token || '');
+    } catch { console.log(''); }
+  });
+" 2>/dev/null)
+
+if [ -z "$TOKEN" ]; then
+  log "ERROR: Could not extract token from login response"
+  exit 0
+fi
+
+# Call relay endpoint: DELETE /api/v1/workflows/:id/pending-action
+RELAY_RESPONSE=$(curl -s -w "\n%{http_code}" -X DELETE \
+  "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/pending-action" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -d '{}' 2>/dev/null)
+
+HTTP_CODE=$(echo "$RELAY_RESPONSE" | tail -1)
+BODY=$(echo "$RELAY_RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "204" ]; then
+  log "SUCCESS: Relay completed for workflow=$WORKFLOW_ID agent=$AGENT_TYPE http=$HTTP_CODE"
+else
+  log "ERROR: Relay failed for workflow=$WORKFLOW_ID agent=$AGENT_TYPE http=$HTTP_CODE body=$BODY"
+fi
+
+exit 0

package/hooks/post-artifact-generate.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Post-Artifact Generate Hook
+# Executado apos geracao de um artefato
+# Valida artefato, atualiza indice, cria checkpoint
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Recebe evento via stdin ou argumento
+if [ -n "$1" ]; then
+    EVENT="$1"
+else
+    EVENT=$(cat)
+fi
+
+# Verifica se temos o handler compilado
+HANDLER="$PROJECT_ROOT/dist/hook.js"
+
+if [ ! -f "$HANDLER" ]; then
+    echo '{"success": false, "error": "Hook handler not compiled. Run npm run build first."}' >&2
+    exit 1
+fi
+
+# Executa o handler TypeScript
+echo "$EVENT" | node "$HANDLER" post-artifact
+
+EXIT_CODE=$?
+
+# Log do resultado
+if [ $EXIT_CODE -eq 0 ]; then
+    echo "[post-artifact-generate] Artifact processed successfully" >&2
+else
+    echo "[post-artifact-generate] Warning: Artifact processing had issues" >&2
+fi
+
+# Este hook nao bloqueia, apenas avisa
+exit 0

package/hooks/post-implement-validate.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# Post-Implement Validation Hook
+# Validates orchestrator-index.json consistency after IMPLEMENT phase
+# Detects possible delegation bypass where code was written directly
+# instead of through the implementer subagent
+#
+# Exit codes:
+#   0 = Validation passed or skipped (jq not available)
+#   1 = Warning detected (possible delegation bypass)
+#
+# Author: Orchestrator System
+# Version: 1.0.0
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+INDEX_FILE="$PROJECT_ROOT/.orchestrator/orchestrator-index.json"
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[post-implement-validate]${NC} $1" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[post-implement-validate] WARNING:${NC} $1" >&2
+}
+
+log_error() {
+    echo -e "${RED}[post-implement-validate] ERROR:${NC} $1" >&2
+}
+
+log_debug() {
+    if [ "${DEBUG:-false}" = "true" ]; then
+        echo -e "${CYAN}[post-implement-validate] DEBUG:${NC} $1" >&2
+    fi
+}
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+    log_warn "jq not found, skipping validation (install jq for full validation)"
+    exit 0
+fi
+
+# Check if orchestrator-index.json exists
+if [ ! -f "$INDEX_FILE" ]; then
+    log_debug "orchestrator-index.json not found at $INDEX_FILE, skipping validation"
+    exit 0
+fi
+
+# Read statistics from orchestrator-index.json
+TASKS_COMPLETED=$(jq -r '.statistics.tasksCompleted // 0' "$INDEX_FILE" 2>/dev/null || echo "0")
+TASKS_PENDING=$(jq -r '.statistics.tasksPending // 0' "$INDEX_FILE" 2>/dev/null || echo "0")
+CURRENT_PHASE=$(jq -r '.activeWorkflow.currentPhase // "unknown"' "$INDEX_FILE" 2>/dev/null || echo "unknown")
+STATUS=$(jq -r '.activeWorkflow.status // "unknown"' "$INDEX_FILE" 2>/dev/null || echo "unknown")
+
+# Count TypeScript files in src/ (if directory exists)
+TS_FILES_COUNT=0
+if [ -d "$PROJECT_ROOT/src" ]; then
+    TS_FILES_COUNT=$(find "$PROJECT_ROOT/src" -name "*.ts" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+fi
+
+# Count test files
+TEST_FILES_COUNT=0
+if [ -d "$PROJECT_ROOT/tests" ]; then
+    TEST_FILES_COUNT=$(find "$PROJECT_ROOT/tests" -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+fi
+
+log_info "Validating IMPLEMENT phase consistency..."
+log_info "  Current Phase: $CURRENT_PHASE"
+log_info "  Status: $STATUS"
+log_info "  Tasks Completed: $TASKS_COMPLETED"
+log_info "  Tasks Pending: $TASKS_PENDING"
+log_info "  TypeScript Files: $TS_FILES_COUNT"
+log_info "  Test Files: $TEST_FILES_COUNT"
+
+# Detection logic
+WARNINGS=0
+MESSAGES=()
+
+# Check 1: Few tasks completed but many pending (primary indicator)
+if [ "$TASKS_COMPLETED" -le 1 ] && [ "$TASKS_PENDING" -gt 5 ]; then
+    MESSAGES+=("Only $TASKS_COMPLETED task(s) completed but $TASKS_PENDING pending.")
+    MESSAGES+=("This suggests the implementer agent may not have been properly invoked.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 2: Many source files but few tasks completed
+if [ "$TS_FILES_COUNT" -gt 10 ] && [ "$TASKS_COMPLETED" -lt 5 ]; then
+    MESSAGES+=("Found $TS_FILES_COUNT TypeScript files but only $TASKS_COMPLETED tasks completed.")
+    MESSAGES+=("Code may have been generated without proper task tracking.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 3: Status still "ready_for_implementation" after code exists
+if [ "$STATUS" = "ready_for_implementation" ] && [ "$TS_FILES_COUNT" -gt 5 ]; then
+    MESSAGES+=("Status is still 'ready_for_implementation' but $TS_FILES_COUNT code files exist.")
+    MESSAGES+=("Workflow state may not have been updated correctly.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 4: Source files exist but no test files (TDD violation)
+if [ "$TS_FILES_COUNT" -gt 5 ] && [ "$TEST_FILES_COUNT" -eq 0 ]; then
+    MESSAGES+=("Found $TS_FILES_COUNT source files but no test files.")
+    MESSAGES+=("TDD methodology may not have been followed.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Summary
+if [ "$WARNINGS" -gt 0 ]; then
+    echo "" >&2
+    log_warn "============================================"
+    log_warn "Detected $WARNINGS potential issue(s):"
+    log_warn "============================================"
+    for msg in "${MESSAGES[@]}"; do
+        log_warn "  - $msg"
+    done
+    echo "" >&2
+    log_warn "Possible causes:"
+    log_warn "  1. Implementer agent was not invoked via Task tool"
+    log_warn "  2. Code was written directly instead of through delegation"
+    log_warn "  3. orchestrator-index.json was not updated during implementation"
+    echo "" >&2
+    log_warn "Recommended actions:"
+    log_warn "  1. Review CLAUDE.md section: MANDATORY: IMPLEMENT Phase Delegation"
+    log_warn "  2. Ensure Task tool is used with subagent_type='implementer'"
+    log_warn "  3. Update orchestrator-index.json with correct task progress"
+    echo "" >&2
+    exit 1
+else
+    log_info "Validation passed. No issues detected."
+    exit 0
+fi

package/hooks/post-phase-checkpoint.sh

@@ -0,0 +1,322 @@
+#!/bin/bash
+# Post-Phase Checkpoint Hook
+# Automatically creates git checkpoints when workflow phases complete
+#
+# Triggered by: PostToolUse on Task tool (after agent completes)
+# Behavior: Detects phase transitions and creates git commits
+#
+# Requirements:
+#   - jq (for JSON parsing)
+#   - git (for checkpoint commits)
+#
+# Debug mode: ORCH_CHECKPOINT_DEBUG=1 to enable verbose logging
+
+set -e
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+INDEX_FILE="$PROJECT_ROOT/.orchestrator/orchestrator-index.json"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+LOG_FILE="$STATE_DIR/checkpoint-hook.log"
+LAST_PHASE_FILE="$STATE_DIR/last-checkpointed-phase"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# Debug mode
+DEBUG="${ORCH_CHECKPOINT_DEBUG:-0}"
+
+# Logging functions
+log_debug() {
+  if [ "$DEBUG" = "1" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [DEBUG] $1" >> "$LOG_FILE"
+    echo "[DEBUG] $1" >&2
+  fi
+}
+
+log_info() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [INFO] $1" >> "$LOG_FILE"
+  if [ "$DEBUG" = "1" ]; then
+    echo "[INFO] $1" >&2
+  fi
+}
+
+log_warn() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [WARN] $1" >> "$LOG_FILE"
+  echo "[WARN] $1" >&2
+}
+
+log_error() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [ERROR] $1" >> "$LOG_FILE"
+  echo "[ERROR] $1" >&2
+}
+
+# Check prerequisites
+check_prerequisites() {
+  # Check jq
+  if ! command -v jq &> /dev/null; then
+    log_error "jq is not installed. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check git
+  if ! command -v git &> /dev/null; then
+    log_error "git is not installed. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check if we're in a git repo
+  if ! git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree &> /dev/null; then
+    log_warn "Not a git repository. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check index file
+  if [ ! -f "$INDEX_FILE" ]; then
+    log_debug "No orchestrator-index.json found. Skipping."
+    return 1
+  fi
+
+  return 0
+}
+
+# Get current phase from orchestrator-index.json
+get_current_phase() {
+  local phase
+  phase=$(jq -r '.activeWorkflow.currentPhase // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$phase"
+}
+
+# Get workflow ID
+get_workflow_id() {
+  local wf_id
+  wf_id=$(jq -r '.activeWorkflow.id // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$wf_id"
+}
+
+# Get workflow status
+get_workflow_status() {
+  local status
+  status=$(jq -r '.activeWorkflow.status // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$status"
+}
+
+# Get last checkpointed phase from checkpoints array (one with commitHash)
+get_last_checkpointed_phase() {
+  local phase
+  # Find the most recent checkpoint that has a commitHash (indicating it was git-committed)
+  phase=$(jq -r '
+    [.checkpoints[] | select(.commitHash != null and .commitHash != "")]
+    | sort_by(.createdAt)
+    | last
+    | .phase // empty
+  ' "$INDEX_FILE" 2>/dev/null)
+  echo "$phase"
+}
+
+# Determine completed phase based on current phase
+# When we see currentPhase = PLAN, it means SPECIFY just completed
+get_completed_phase() {
+  local current_phase="$1"
+  local workflow_status="$2"
+
+  case "$workflow_status" in
+    "completed")
+      echo "IMPLEMENT"
+      return
+      ;;
+  esac
+
+  case "$current_phase" in
+    "PLAN")
+      echo "SPECIFY"
+      ;;
+    "TASKS")
+      echo "PLAN"
+      ;;
+    "IMPLEMENT")
+      echo "TASKS"
+      ;;
+    *)
+      echo ""
+      ;;
+  esac
+}
+
+# Create git checkpoint
+create_git_checkpoint() {
+  local phase="$1"
+  local commit_hash=""
+
+  log_info "Creating git checkpoint for phase: $phase"
+
+  # Stage all changes
+  git -C "$PROJECT_ROOT" add -A 2>/dev/null || {
+    log_warn "Failed to stage changes"
+    return 1
+  }
+
+  # Check if there are staged changes
+  if git -C "$PROJECT_ROOT" diff --cached --quiet 2>/dev/null; then
+    log_info "No changes to commit for phase: $phase"
+    echo ""
+    return 0
+  fi
+
+  # Create commit with standard message
+  local commit_msg="[orchestrator] ${phase}: Auto-checkpoint after ${phase} phase"
+
+  if git -C "$PROJECT_ROOT" commit -m "$commit_msg" --no-verify 2>/dev/null; then
+    commit_hash=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null)
+    log_info "Checkpoint commit created: $commit_hash"
+    echo "$commit_hash"
+  else
+    log_warn "Failed to create commit"
+    echo ""
+    return 1
+  fi
+}
+
+# Update orchestrator-index.json with checkpoint
+update_orchestrator_index() {
+  local workflow_id="$1"
+  local phase="$2"
+  local commit_hash="$3"
+  local created_at
+
+  created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  local checkpoint_id="cp_${workflow_id}_$(date +%s)"
+  local description="Auto-checkpoint after ${phase} phase"
+
+  log_debug "Updating index with checkpoint: $checkpoint_id"
+
+  # Create temp file for atomic update
+  local temp_file="${INDEX_FILE}.tmp.$$"
+
+  # Use jq to add checkpoint and update statistics
+  if jq --arg id "$checkpoint_id" \
+       --arg wfId "$workflow_id" \
+       --arg phase "$phase" \
+       --arg hash "$commit_hash" \
+       --arg date "$created_at" \
+       --arg desc "$description" '
+    # Add checkpoint to array
+    .checkpoints += [{
+      id: $id,
+      workflowId: $wfId,
+      phase: $phase,
+      commitHash: $hash,
+      createdAt: $date,
+      description: $desc
+    }] |
+    # Update statistics
+    .statistics.totalCheckpoints = (.checkpoints | length) |
+    .statistics.lastActivity = $date
+  ' "$INDEX_FILE" > "$temp_file" 2>/dev/null; then
+
+    # Validate JSON
+    if jq empty "$temp_file" 2>/dev/null; then
+      mv "$temp_file" "$INDEX_FILE"
+      log_info "Index updated with checkpoint: $checkpoint_id"
+      return 0
+    else
+      log_error "Generated invalid JSON"
+      rm -f "$temp_file"
+      return 1
+    fi
+  else
+    log_error "Failed to update index with jq"
+    rm -f "$temp_file"
+    return 1
+  fi
+}
+
+# Save last checkpointed phase
+save_last_phase() {
+  local phase="$1"
+  echo "$phase" > "$LAST_PHASE_FILE"
+}
+
+# Get saved last phase (from state file, not index)
+get_saved_last_phase() {
+  if [ -f "$LAST_PHASE_FILE" ]; then
+    cat "$LAST_PHASE_FILE"
+  else
+    echo ""
+  fi
+}
+
+# Main execution
+main() {
+  log_debug "Hook triggered"
+
+  # Check prerequisites
+  if ! check_prerequisites; then
+    log_debug "Prerequisites not met, exiting"
+    exit 0  # Don't fail the hook
+  fi
+
+  # Get current state
+  local current_phase
+  current_phase=$(get_current_phase)
+
+  if [ -z "$current_phase" ]; then
+    log_debug "No active workflow phase found"
+    exit 0
+  fi
+
+  local workflow_id
+  workflow_id=$(get_workflow_id)
+
+  local workflow_status
+  workflow_status=$(get_workflow_status)
+
+  log_debug "Current phase: $current_phase, Status: $workflow_status, Workflow: $workflow_id"
+
+  # Determine which phase just completed
+  local completed_phase
+  completed_phase=$(get_completed_phase "$current_phase" "$workflow_status")
+
+  if [ -z "$completed_phase" ]; then
+    log_debug "No completed phase detected from current phase: $current_phase"
+    exit 0
+  fi
+
+  # Check if we already checkpointed this phase
+  local last_checkpointed
+  last_checkpointed=$(get_last_checkpointed_phase)
+
+  local saved_last_phase
+  saved_last_phase=$(get_saved_last_phase)
+
+  log_debug "Completed phase: $completed_phase, Last checkpointed: $last_checkpointed, Saved: $saved_last_phase"
+
+  # Skip if already checkpointed
+  if [ "$completed_phase" = "$last_checkpointed" ] || [ "$completed_phase" = "$saved_last_phase" ]; then
+    log_debug "Phase $completed_phase already checkpointed, skipping"
+    exit 0
+  fi
+
+  # Create checkpoint
+  local commit_hash
+  commit_hash=$(create_git_checkpoint "$completed_phase")
+
+  # Update index (even if no commit, to track the checkpoint)
+  if [ -n "$commit_hash" ]; then
+    if update_orchestrator_index "$workflow_id" "$completed_phase" "$commit_hash"; then
+      save_last_phase "$completed_phase"
+      log_info "Checkpoint complete for phase: $completed_phase (commit: $commit_hash)"
+    else
+      log_error "Failed to update index for phase: $completed_phase"
+    fi
+  else
+    log_info "No changes to checkpoint for phase: $completed_phase"
+    save_last_phase "$completed_phase"
+  fi
+
+  exit 0
+}
+
+# Run main function
+main "$@"

package/hooks/pre-agent-invoke.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Pre-Agent Invoke Hook
+# Executado antes de invocar um subagent
+# Valida contexto e injeta informacoes da KB
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Recebe evento via stdin ou argumento
+if [ -n "$1" ]; then
+    EVENT="$1"
+else
+    EVENT=$(cat)
+fi
+
+# Verifica se temos o handler compilado
+HANDLER="$PROJECT_ROOT/dist/hook.js"
+
+if [ ! -f "$HANDLER" ]; then
+    echo '{"success": false, "error": "Hook handler not compiled. Run npm run build first."}' >&2
+    exit 1
+fi
+
+# Executa o handler TypeScript
+echo "$EVENT" | node "$HANDLER" pre-agent-invoke
+
+EXIT_CODE=$?
+
+# Exit code determina se agente pode prosseguir
+# 0 = permitido
+# 1 = bloqueado
+exit $EXIT_CODE