@cohortapp/agent-sdk 2.3.0

package/scripts/send-whatsapp.sh

@@ -0,0 +1,292 @@
+#!/bin/bash
+# send-whatsapp.sh — Send outbound WhatsApp message via Twilio REST API as the agent
+#
+# Supports two modes:
+#   1. Sandbox mode (default until production WABA is active):
+#      Uses Twilio sandbox number +14155238886
+#      Recipients must have joined the sandbox first
+#   2. Production mode (--production flag or WHATSAPP_MODE=production):
+#      Uses the agent's own Twilio number as WhatsApp Business sender
+#
+# Usage:
+#   ./scripts/send-whatsapp.sh --to "+971501234567" --body "Hello"
+#   ./scripts/send-whatsapp.sh --to "+971501234567" --body "Hello" --production
+#   ./scripts/send-whatsapp.sh --to "+971501234567" --template "intro_greeting" --vars "Var1,Var2"
+#
+# Environment variables (from .env):
+#   TWILIO_ACCOUNT_SID      — Twilio account SID
+#   TWILIO_AUTH_TOKEN        — Twilio auth token
+#   TWILIO_PHONE_NUMBER      — The agent's Twilio phone number
+#   WHATSAPP_MODE            — "sandbox" (default) or "production"
+#   WHATSAPP_SANDBOX_NUMBER  — Sandbox sender (default: +14155238886)
+set -e
+
+# Load environment
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(dirname "$SCRIPT_DIR")}"
+
+if [ -f "$AGENT_REPO_DIR/.env" ]; then
+  source "$AGENT_REPO_DIR/.env"
+fi
+
+# Defaults
+MODE="${WHATSAPP_MODE:-sandbox}"
+SANDBOX_NUMBER="${WHATSAPP_SANDBOX_NUMBER:-+14155238886}"
+PRODUCTION_NUMBER="${TWILIO_PHONE_NUMBER:-+16282656712}"
+TO=""
+BODY=""
+TEMPLATE=""
+TEMPLATE_VARS=""
+MEDIA_URL=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to)
+      TO="$2"
+      shift 2
+      ;;
+    --body)
+      BODY="$2"
+      shift 2
+      ;;
+    --template)
+      TEMPLATE="$2"
+      shift 2
+      ;;
+    --vars)
+      TEMPLATE_VARS="$2"
+      shift 2
+      ;;
+    --media)
+      MEDIA_URL="$2"
+      shift 2
+      ;;
+    --production)
+      MODE="production"
+      shift
+      ;;
+    --sandbox)
+      MODE="sandbox"
+      shift
+      ;;
+    -h|--help)
+      echo "Usage: send-whatsapp.sh --to \"+971501234567\" --body \"message text\""
+      echo ""
+      echo "Options:"
+      echo "  --to          Recipient phone number (E.164 format, required)"
+      echo "  --body        Message text (required unless --template is used)"
+      echo "  --template    WhatsApp message template name (for business-initiated messages)"
+      echo "  --vars        Comma-separated template variables (e.g. \"Name,Company\")"
+      echo "  --media       URL of media to attach (image, PDF, etc.)"
+      echo "  --production  Use production WhatsApp Business number"
+      echo "  --sandbox     Use Twilio WhatsApp sandbox (default)"
+      echo "  -h            Show this help"
+      echo ""
+      echo "Sandbox mode: Recipients must first join the sandbox by sending"
+      echo "  'join <sandbox-keyword>' to +1 415 523 8886 on WhatsApp."
+      echo ""
+      echo "Production mode: Requires approved WhatsApp Business Account."
+      echo "  Business-initiated messages need approved templates."
+      echo "  User-initiated (within 24h window): free-form messages allowed."
+      exit 0
+      ;;
+    *)
+      echo "ERROR: Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [ -z "$TO" ]; then
+  echo "ERROR: --to is required" >&2
+  exit 1
+fi
+
+if [ -z "$BODY" ] && [ -z "$TEMPLATE" ]; then
+  echo "ERROR: --body or --template is required" >&2
+  exit 1
+fi
+
+# Validate Twilio credentials
+if [ -z "$TWILIO_ACCOUNT_SID" ]; then
+  echo "ERROR: TWILIO_ACCOUNT_SID not set" >&2
+  exit 1
+fi
+
+if [ -z "$TWILIO_AUTH_TOKEN" ]; then
+  echo "ERROR: TWILIO_AUTH_TOKEN not set" >&2
+  exit 1
+fi
+
+# Determine sender number based on mode
+if [ "$MODE" = "production" ]; then
+  FROM_NUMBER="$PRODUCTION_NUMBER"
+else
+  FROM_NUMBER="$SANDBOX_NUMBER"
+fi
+
+# --- Outbound dedup: prevent concurrent sessions from sending the same WhatsApp ---
+DEDUP_ACQUIRED=""
+if [ -x "$SCRIPT_DIR/outbound-dedup.sh" ]; then
+  DEDUP_KEY=$("$SCRIPT_DIR/outbound-dedup.sh" generate-key whatsapp "$TO" "" "${BODY:-$TEMPLATE}" 2>/dev/null) || true
+  if [ -n "$DEDUP_KEY" ]; then
+    ACQUIRE_RESULT=$("$SCRIPT_DIR/outbound-dedup.sh" acquire whatsapp "$DEDUP_KEY" "${SOPHIE_SESSION_ID:-$$}" 2>/dev/null) || true
+    if [ "$ACQUIRE_RESULT" = "DEDUP_SKIP" ]; then
+      echo "DEDUP_SKIP: Another session is already sending this WhatsApp message"
+      exit 0
+    fi
+    if [ "$ACQUIRE_RESULT" = "CLAIMED" ]; then
+      DEDUP_ACQUIRED="1"
+    fi
+  fi
+fi
+
+# ── Pre-send factual validation ─────────────────────────────────
+# Checks relationship claims, AI disclosure, in-person scheduling, title accuracy
+# Blocks send if critical issues found. Fail-open on errors.
+if [ ! -f "$SCRIPT_DIR/validate_outbound.py" ]; then
+  echo "BLOCKED: outbound validator (validate_outbound.py) missing — refusing WhatsApp send (fail closed)." >&2
+  exit 1
+fi
+if [ -n "$BODY" ]; then
+  VALIDATION_RESULT=$(echo "$BODY" | python3 "$SCRIPT_DIR/validate_outbound.py" --type whatsapp --recipient "$TO" --quiet 2>/dev/null) || VALIDATION_EXIT=$?
+  VALIDATION_EXIT=${VALIDATION_EXIT:-0}
+  if [ "$VALIDATION_EXIT" = "1" ]; then
+    BLOCKERS=$(echo "$VALIDATION_RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('metadata',{}).get('blockers',0))" 2>/dev/null) || BLOCKERS=0
+    if [ "$BLOCKERS" -gt 0 ]; then
+      echo "VALIDATION_BLOCK: $BLOCKERS issue(s) found in WhatsApp message to $TO"
+      echo "$VALIDATION_RESULT" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+for i in d.get('issues',[]):
+    if i.get('severity')=='block':
+        print(f\"  [{i['type']}] {i['description']}\")
+        if i.get('suggestion'): print(f\"    -> {i['suggestion']}\")
+" 2>/dev/null || true
+      echo "Fix the above issues before sending." >&2
+      exit 1
+    fi
+  fi
+fi
+
+# ── Pre-send policy gate (shared send-gate chokepoint) ──────────────
+# Unified policy layer ABOVE validate_outbound.py (Layer 0): banned phrases,
+# AI-disclosure, information barriers, recipient allowlist — all in
+# lib/comms/send-gate.mjs. WhatsApp recipients are phone numbers (external), so
+# an unreadable policy fails CLOSED here.
+if [ -n "$BODY" ]; then
+  SEND_GATE="$AGENT_REPO_DIR/lib/comms/send-gate.mjs"
+  if [ ! -f "$SEND_GATE" ]; then
+    SEND_GATE="$AGENT_REPO_DIR/node_modules/@cohortapp/agent-sdk/lib/comms/send-gate.mjs"
+  fi
+  if [ -f "$SEND_GATE" ]; then
+    NODE_BIN="${MAESTRO_NODE_BIN:-/opt/homebrew/bin/node}"
+    command -v "$NODE_BIN" >/dev/null 2>&1 || NODE_BIN="node"
+    # Replies by default; MAESTRO_SEND_FIRST_CONTACT=true for first contact. The
+    # truthfulness invariant (never deny being an AI) applies regardless.
+    GATE_REASON=$(printf '%s' "$BODY" | AGENT_DIR="$AGENT_REPO_DIR" "$NODE_BIN" "$SEND_GATE" \
+      --channel whatsapp --recipient "$TO" --agent-root "$AGENT_REPO_DIR" \
+      --first-contact "${MAESTRO_SEND_FIRST_CONTACT:-false}" 2>&1) || GATE_EXIT=$?
+    GATE_EXIT=${GATE_EXIT:-0}
+    if [ "$GATE_EXIT" != "0" ]; then
+      echo "SEND_GATE_BLOCK: WhatsApp message to $TO blocked by policy gate" >&2
+      echo "$GATE_REASON" >&2
+      exit 1
+    fi
+  fi
+fi
+
+# Build the Twilio API request
+# WhatsApp messages use the same Messages API but with "whatsapp:" prefix on numbers
+WHATSAPP_TO="whatsapp:${TO}"
+WHATSAPP_FROM="whatsapp:${FROM_NUMBER}"
+
+# Build curl arguments
+CURL_ARGS=(
+  -s -w "\n%{http_code}"
+  -X POST "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Messages.json"
+  -u "${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}"
+  --data-urlencode "To=${WHATSAPP_TO}"
+  --data-urlencode "From=${WHATSAPP_FROM}"
+)
+
+if [ -n "$BODY" ]; then
+  CURL_ARGS+=(--data-urlencode "Body=${BODY}")
+fi
+
+if [ -n "$MEDIA_URL" ]; then
+  CURL_ARGS+=(--data-urlencode "MediaUrl=${MEDIA_URL}")
+fi
+
+# For template messages in production mode, use ContentSid if available
+# Otherwise templates are sent as Body with template syntax
+# (Twilio Content API for templates is separate; for now we use Body-based approach)
+
+# Send WhatsApp message via Twilio REST API
+RESPONSE=$(curl "${CURL_ARGS[@]}")
+
+# Split response body and HTTP status code
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+RESPONSE_BODY=$(echo "$RESPONSE" | sed '$d')
+
+# Extract message SID and status from response
+MESSAGE_SID=$(echo "$RESPONSE_BODY" | grep -o '"sid": *"[^"]*"' | head -1 | sed 's/"sid": *"//' | sed 's/"//')
+STATUS=$(echo "$RESPONSE_BODY" | grep -o '"status": *"[^"]*"' | head -1 | sed 's/"status": *"//' | sed 's/"//')
+ERROR_CODE=$(echo "$RESPONSE_BODY" | grep -o '"code": *[0-9]*' | head -1 | sed 's/"code": *//')
+ERROR_MSG=$(echo "$RESPONSE_BODY" | grep -o '"message": *"[^"]*"' | head -1 | sed 's/"message": *"//' | sed 's/"//')
+
+# Log to WhatsApp log
+LOG_DIR="$AGENT_REPO_DIR/logs/whatsapp/$(date +%Y-%m-%d)"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d)-whatsapp.jsonl"
+
+BODY_PREVIEW=$(echo "${BODY:-template:$TEMPLATE}" | head -c 200 | sed 's/"/\\"/g' | tr '\n' ' ')
+
+LOG_ENTRY=$(cat <<LOGEOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","direction":"outbound","messageSid":"${MESSAGE_SID}","from":"${FROM_NUMBER}","to":"${TO}","body":"${BODY_PREVIEW}","mode":"${MODE}","http_code":"${HTTP_CODE}","status":"${STATUS}","logged_at":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"}
+LOGEOF
+)
+echo "$LOG_ENTRY" >> "$LOG_FILE"
+
+# Log to audit trail
+AUDIT_DIR="$AGENT_REPO_DIR/logs/audit"
+mkdir -p "$AUDIT_DIR"
+AUDIT_FILE="$AUDIT_DIR/$(date +%Y-%m-%d)-actions.jsonl"
+
+AUDIT_ENTRY=$(cat <<AUDITEOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","agent":"send-whatsapp","action":"whatsapp_sent","to":"${TO}","from":"${FROM_NUMBER}","mode":"${MODE}","body_preview":"$(echo "${BODY:-template:$TEMPLATE}" | head -c 100 | sed 's/"/\\"/g' | tr '\n' ' ')","messageSid":"${MESSAGE_SID}","http_code":"${HTTP_CODE}","status":"${STATUS}"}
+AUDITEOF
+)
+echo "$AUDIT_ENTRY" >> "$AUDIT_FILE"
+
+# Output result
+if [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "200" ]; then
+  # Post-send: confirm the dedup lock
+  if [ -n "$DEDUP_ACQUIRED" ] && [ -n "$DEDUP_KEY" ] && [ -x "$SCRIPT_DIR/outbound-dedup.sh" ]; then
+    PREVIEW=$(printf '%s' "${BODY:-template:$TEMPLATE}" | head -c 200)
+    "$SCRIPT_DIR/outbound-dedup.sh" confirm whatsapp "$DEDUP_KEY" "To:$TO SID:$MESSAGE_SID $PREVIEW" 2>/dev/null || true
+  fi
+  echo "WhatsApp message sent successfully (${MODE} mode)"
+  echo "  To: $TO"
+  echo "  From: $FROM_NUMBER (whatsapp:${FROM_NUMBER})"
+  echo "  SID: $MESSAGE_SID"
+  echo "  Status: $STATUS"
+  echo "  Mode: $MODE"
+  exit 0
+else
+  echo "ERROR: WhatsApp send failed (HTTP $HTTP_CODE)" >&2
+  if [ -n "$ERROR_CODE" ]; then
+    echo "  Error code: $ERROR_CODE" >&2
+    echo "  Error message: $ERROR_MSG" >&2
+  fi
+  if [ "$MODE" = "sandbox" ] && [ "$ERROR_CODE" = "63007" ]; then
+    echo "" >&2
+    echo "HINT: The recipient has not joined the Twilio WhatsApp sandbox." >&2
+    echo "Ask them to send 'join <keyword>' to +1 415 523 8886 on WhatsApp." >&2
+    echo "Check Twilio Console > Messaging > Try it Out > WhatsApp for the keyword." >&2
+  fi
+  echo "$RESPONSE_BODY" >&2
+  exit 1
+fi

package/scripts/session-start.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# Session Start — Called at the beginning of every Claude Code session
+# Sets up intra-session inbox polling via CronCreate, reads dashboards,
+# and checks for pending decisions.
+#
+# Usage: source scripts/session-start.sh  (or called automatically)
+# This script is idempotent — safe to run multiple times.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOPHIE_AI_DIR="$(dirname "$SCRIPT_DIR")"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TODAY=$(date -u +"%Y-%m-%d")
+SESSION_ID="session-$(date +%s)"
+LOG_DIR="$SOPHIE_AI_DIR/logs/sessions"
+LOG_FILE="$LOG_DIR/${TODAY}-sessions.jsonl"
+
+mkdir -p "$LOG_DIR"
+mkdir -p "$SOPHIE_AI_DIR/state/triggers/priority"
+mkdir -p "$SOPHIE_AI_DIR/state/inbox/slack"
+mkdir -p "$SOPHIE_AI_DIR/state/inbox/internal"
+
+# ─── 1. Log session start ───────────────────────────────────────────
+echo "{\"event\":\"session_start\",\"session_id\":\"$SESSION_ID\",\"timestamp\":\"$TIMESTAMP\"}" >> "$LOG_FILE"
+echo "[session-start] Session $SESSION_ID started at $TIMESTAMP"
+
+# ─── 2. Check emergency stop ────────────────────────────────────────
+if [ -f "$SOPHIE_AI_DIR/.emergency-stop" ]; then
+    echo "[session-start] EMERGENCY STOP ACTIVE — halting session start"
+    echo "{\"event\":\"session_blocked\",\"session_id\":\"$SESSION_ID\",\"reason\":\"emergency_stop\",\"timestamp\":\"$TIMESTAMP\"}" >> "$LOG_FILE"
+    exit 1
+fi
+
+# ─── 3. Read executive summary dashboard ────────────────────────────
+DASHBOARD="$SOPHIE_AI_DIR/state/dashboards/executive-summary.yaml"
+if [ -f "$DASHBOARD" ]; then
+    echo "[session-start] Executive summary loaded"
+    # Extract key metrics for session log
+    OPEN_ITEMS=$(grep "total_open_items:" "$DASHBOARD" 2>/dev/null | awk '{print $2}' || echo "?")
+    CRITICAL=$(grep "critical_items:" "$DASHBOARD" 2>/dev/null | awk '{print $2}' || echo "?")
+    SLA_BREACHES=$(grep "sla_breaches:" "$DASHBOARD" 2>/dev/null | awk '{print $2}' || echo "?")
+    echo "[session-start] Open: $OPEN_ITEMS | Critical: $CRITICAL | SLA breaches: $SLA_BREACHES"
+else
+    echo "[session-start] WARNING: Executive summary dashboard not found"
+fi
+
+# ─── 4. Check for pending decisions ─────────────────────────────────
+DECISION_QUEUE="$SOPHIE_AI_DIR/state/queues/decision-queue.yaml"
+if [ -f "$DECISION_QUEUE" ]; then
+    PENDING=$(grep -c "status: open" "$DECISION_QUEUE" 2>/dev/null || echo "0")
+    if [ "$PENDING" -gt 0 ]; then
+        echo "[session-start] $PENDING pending decisions in queue"
+    fi
+fi
+
+# ─── 5. Check state/inbox/ for unprocessed items ────────────────────
+UNPROCESSED=0
+for svc_dir in "$SOPHIE_AI_DIR/state/inbox/slack" "$SOPHIE_AI_DIR/state/inbox/gmail" "$SOPHIE_AI_DIR/state/inbox/calendar" "$SOPHIE_AI_DIR/state/inbox/sms" "$SOPHIE_AI_DIR/state/inbox/internal"; do
+    if [ -d "$svc_dir" ]; then
+        COUNT=$(find "$svc_dir" -name "*.yaml" -maxdepth 1 2>/dev/null | wc -l | tr -d ' ')
+        UNPROCESSED=$((UNPROCESSED + COUNT))
+    fi
+done
+if [ "$UNPROCESSED" -gt 0 ]; then
+    echo "[session-start] $UNPROCESSED unprocessed inbox items found"
+fi
+
+# ─── 6. Check for existing priority triggers ────────────────────────
+TRIGGER_DIR="$SOPHIE_AI_DIR/state/triggers/priority"
+TRIGGER_COUNT=$(find "$TRIGGER_DIR" -name "*.yaml" -maxdepth 1 2>/dev/null | wc -l | tr -d ' ')
+if [ "$TRIGGER_COUNT" -gt 0 ]; then
+    echo "[session-start] $TRIGGER_COUNT priority triggers pending — process immediately"
+fi
+
+# ─── 7. Output CronCreate instruction ───────────────────────────────
+# This section outputs the CronCreate command that the Claude Code session
+# should execute to set up 2-minute recurring inbox polling.
+# The actual CronCreate call must be made by Claude Code (not bash).
+cat <<'CRON_INSTRUCTION'
+
+════════════════════════════════════════════════════════════════════
+ INTRA-SESSION POLLING SETUP REQUIRED
+════════════════════════════════════════════════════════════════════
+ Execute the following CronCreate to enable 2-minute inbox polling:
+
+ CronCreate:
+   interval: "2m"
+   command: "Run intra-session inbox check"
+   instructions: |
+     1. Run: node scripts/poller/intra-session-check.mjs
+     2. Check state/inbox/ for new unprocessed items
+     3. Check state/triggers/priority/ for new trigger files
+     4. If a CEO message (from_ceo: true) is found:
+        - Create a priority trigger at state/triggers/priority/
+        - Interrupt current work to process the CEO message
+     5. Report: "[inbox-poll] N new items, M priority triggers"
+
+════════════════════════════════════════════════════════════════════
+CRON_INSTRUCTION
+
+# ─── 8. Final session start log entry ───────────────────────────────
+echo "{\"event\":\"session_ready\",\"session_id\":\"$SESSION_ID\",\"timestamp\":\"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",\"dashboard_loaded\":true,\"unprocessed_inbox\":$UNPROCESSED,\"pending_triggers\":$TRIGGER_COUNT,\"polling_setup\":\"pending_croncreate\"}" >> "$LOG_FILE"
+
+echo ""
+echo "[session-start] Session ready. Set up CronCreate polling (see above)."

package/scripts/setup/boot-claude-session.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# =============================================================================
+# boot-claude-session.sh — Launch interactive Claude Code session on boot
+# =============================================================================
+#
+# Opens Terminal.app with a Claude Code interactive session in the agent's
+# working directory. Called via launchd at login.
+#
+# This is separate from the maestro daemon (which runs headless as a Node.js
+# process for polling/dispatching). This script provides a visible, interactive
+# Claude Code session that the operator can observe and interact with.
+#
+# Usage:
+#   ./scripts/setup/boot-claude-session.sh <agent-dir>
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAESTRO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Agent directory required as first argument (e.g. ~/<firstname>-ai).
+AGENT_DIR="${1:?Agent directory required as first argument (e.g. ~/<firstname>-ai)}"
+if [ ! -d "$AGENT_DIR" ]; then
+  echo "ERROR: Agent directory does not exist: $AGENT_DIR" >&2
+  exit 1
+fi
+
+AGENT_NAME=$(basename "$AGENT_DIR")
+# Resolve the agent's display name from config/agent.json (SOT), falling
+# back to the directory basename. Used for the Terminal window banner.
+AGENT_DISPLAY="$AGENT_NAME"
+if [ -f "$AGENT_DIR/config/agent.json" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    fn=$(jq -r '.fullName // empty' "$AGENT_DIR/config/agent.json")
+    [ -n "$fn" ] && AGENT_DISPLAY="$fn"
+  fi
+fi
+LOG_FILE="$MAESTRO_DIR/logs/watchdog/$(date +%Y-%m-%d)-boot-session.log"
+mkdir -p "$(dirname "$LOG_FILE")"
+
+log() {
+  echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] $1" | tee -a "$LOG_FILE"
+}
+
+# Wait for the system to settle after login (network, services, etc.)
+log "Waiting 15s for system to settle..."
+sleep 15
+
+# Check for emergency stop
+if [ -f "$AGENT_DIR/.emergency-stop" ]; then
+  log "Emergency stop active — not starting Claude session"
+  exit 0
+fi
+
+if [ -f "$MAESTRO_DIR/.emergency-stop" ]; then
+  log "Emergency stop active in maestro — not starting Claude session"
+  exit 0
+fi
+
+# Check if claude CLI is available
+if ! command -v claude &>/dev/null; then
+  # Try common paths
+  CLAUDE_PATH=""
+  for p in "$HOME/.local/bin/claude" "/opt/homebrew/bin/claude" "/usr/local/bin/claude"; do
+    if [ -x "$p" ]; then
+      CLAUDE_PATH="$p"
+      break
+    fi
+  done
+
+  if [ -z "$CLAUDE_PATH" ]; then
+    log "ERROR: claude CLI not found"
+    exit 1
+  fi
+else
+  CLAUDE_PATH=$(which claude)
+fi
+
+log "Starting Claude Code session in $AGENT_DIR (claude: $CLAUDE_PATH)"
+
+# Open Terminal.app with Claude Code running in the agent directory
+osascript <<APPLESCRIPT
+tell application "Terminal"
+    activate
+    -- Open a new window with claude running in the agent directory
+    do script "cd '$AGENT_DIR' && clear && echo '╔══════════════════════════════════════════════════════════╗' && echo '║  $AGENT_DISPLAY — Boot Session ($(date +%Y-%m-%d))' && echo '╠══════════════════════════════════════════════════════════╣' && echo '║  Agent dir: $AGENT_DIR' && echo '║  Claude:    $CLAUDE_PATH' && echo '╚══════════════════════════════════════════════════════════╝' && echo '' && '$CLAUDE_PATH'"
+    -- Set the window title
+    set custom title of front window to "$AGENT_NAME — Claude Code"
+end tell
+APPLESCRIPT
+
+log "Terminal window opened with Claude Code session"