#!/bin/bash
# bot-relay-mcp: spawn a new Claude Code terminal pre-configured as a relay agent.
#
# Opens a new iTerm2 window (or falls back to Terminal.app) with the agent's
# name, role, and capabilities set as environment variables. The SessionStart
# hook will automatically register the agent and deliver pending mail when
# Claude Code starts.
#
# Usage:
#   spawn-agent.sh <name> <role> [capabilities] [cwd]
#
# Examples:
#   spawn-agent.sh builder-1 builder
#   spawn-agent.sh reviewer reviewer "review,testing,security"
#   spawn-agent.sh worker builder "build,deploy" "/path/to/project"
#
# Security (v1.6.1 + v1.6.2 defense-in-depth):
#
# THREE layers of defense. All three exist independently. DO NOT remove any
# of them without reviewing the threat model — each catches a different class
# of attack and a future refactor that simplifies "just this one" layer will
# reintroduce the vulnerability.
#
# Layer 1 — TS Zod validation at the MCP tool boundary (src/types.ts
#   SpawnAgentSchema). This is the primary defense and fails-fast before
#   the shell ever runs. Uses the same regexes as this script, deliberately.
# Layer 2 — This script's argument validation (regex allowlist below).
#   Protects against direct CLI invocation bypassing the MCP layer.
# Layer 3 — printf %q for shell interpolation and applescript_escape() for
#   the osascript heredoc. Even if a bug let a bad character through, the
#   final command embedding stays safe.
#
# Allowlists:
# - Name/role:     [A-Za-z0-9_.-]{1,64}
# - Capabilities:  [A-Za-z0-9_.,-]{1,256} (comma-separated tokens)
# - CWD:           absolute path, no shell metacharacters, no newlines, 1-1024 chars
#
# Integration tests in tests/spawn-integration.test.ts exercise this script
# directly with RELAY_SPAWN_DRY_RUN=1 and 15+ attack payloads. If you edit
# this file, run those tests.

set -eu

NAME="${1:-}"
ROLE="${2:-}"
CAPS="${3:-}"
CWD="${4:-$HOME}"
# v2.1.4 (I10): optional absolute path to a durable task-brief file. When
# present, the default KICKSTART prompt appends a sentence pointing the
# spawned agent at this file as the canonical source for its task scope.
# Ignored when RELAY_SPAWN_KICKSTART is overridden or RELAY_SPAWN_NO_KICKSTART=1
# (operator's explicit intent wins). Validated below.
# v2.6.1: BRIEF_PATH moved from positional 6 to positional 5. The pre-v2.6.1
# 5th positional (TOKEN) was removed when the env-var token-passthrough
# contract was deprecated in favor of the per-instance file vault. The
# spawned terminal's SessionStart hook now resolves identity from the
# vault at <instanceDir>/agents/<name>.token (written by handleSpawnAgent
# pre-spawn or by the hook itself on first-spawn miss).
BRIEF_PATH="${5:-}"

if [ -z "$NAME" ] || [ -z "$ROLE" ]; then
  echo "Usage: $0 <name> <role> [capabilities] [cwd] [brief_file_path]" >&2
  exit 1
fi

# --- Input validation (v1.6.1 security hardening) ---
validate_token() {
  local value="$1"
  local field="$2"
  local pattern="$3"
  local max_len="$4"
  if [ "${#value}" -gt "$max_len" ]; then
    echo "[spawn-agent] $field exceeds $max_len chars" >&2
    exit 2
  fi
  # Reject newlines, CRs, tabs, and null bytes explicitly. grep -E anchors $ at
  # each line end, so a multi-line value can smuggle garbage past the regex if
  # we only check with grep. Catch that here, before the regex.
  # macOS bash 3.2 does not handle $'\n' inside case patterns reliably, so we
  # use tr to strip control chars and compare lengths instead.
  stripped=$(printf '%s' "$value" | tr -d '\n\r\t\0')
  if [ "${#stripped}" -ne "${#value}" ]; then
    echo "[spawn-agent] $field contains a newline, carriage return, tab, or null byte" >&2
    exit 2
  fi
  if ! printf '%s' "$value" | grep -Eq "$pattern"; then
    echo "[spawn-agent] $field has invalid characters. Allowed pattern: $pattern" >&2
    exit 2
  fi
}

validate_token "$NAME" "name" '^[A-Za-z0-9_.-]+$' 64
validate_token "$ROLE" "role" '^[A-Za-z0-9_.-]+$' 64
if [ -n "$CAPS" ]; then
  validate_token "$CAPS" "capabilities" '^[A-Za-z0-9_.,-]+$' 256
fi
# v2.6.1: TOKEN positional argument removed. Identity now flows via the
# per-instance file vault. The hook (hooks/check-relay.sh) writes the vault
# file on first registration and reads it on subsequent spawns; spawn-agent.sh
# no longer touches credentials.

# v2.1.4 (I10): brief_file_path validation. Allowlist mirrors CWD (absolute
# POSIX path, no metachars, no control chars). File must exist + be readable
# + be <= 10KB. The TS-side validateBriefPath does the same checks as defense-
# in-depth — dropping any one layer is still safe, but having both catches
# drift from direct-CLI invocations (bypassing the MCP tool boundary).
BRIEF_MAX_BYTES=10240
if [ -n "$BRIEF_PATH" ]; then
  if [ "${#BRIEF_PATH}" -gt 1024 ]; then
    echo "[spawn-agent] brief_file_path exceeds 1024 chars" >&2
    exit 2
  fi
  brief_stripped=$(printf '%s' "$BRIEF_PATH" | tr -d '\n\r\t\0')
  if [ "${#brief_stripped}" -ne "${#BRIEF_PATH}" ]; then
    echo "[spawn-agent] brief_file_path contains a newline, carriage return, tab, or null byte" >&2
    exit 2
  fi
  case "$BRIEF_PATH" in
    /*) ;;
    *) echo "[spawn-agent] brief_file_path must be an absolute path. Got: $BRIEF_PATH" >&2; exit 2 ;;
  esac
  case "$BRIEF_PATH" in
    *[\`\;\$\&\|\<\>\"\'\*\?]*)
      echo "[spawn-agent] brief_file_path contains disallowed shell metacharacters" >&2
      exit 2 ;;
  esac
  if ! printf '%s' "$BRIEF_PATH" | grep -Eq '^/[A-Za-z0-9_./ -]+$'; then
    echo "[spawn-agent] brief_file_path contains characters outside the allowlist [A-Za-z0-9_./ -]" >&2
    exit 2
  fi
  if [ ! -f "$BRIEF_PATH" ]; then
    echo "[spawn-agent] brief_file_path does not exist or is not a regular file: $BRIEF_PATH" >&2
    exit 2
  fi
  if [ ! -r "$BRIEF_PATH" ]; then
    echo "[spawn-agent] brief_file_path is not readable: $BRIEF_PATH" >&2
    exit 2
  fi
  # Portable size check: wc -c works on macOS + Linux. stat flags differ across
  # platforms so we stay with wc.
  BRIEF_SIZE=$(wc -c < "$BRIEF_PATH" | tr -d ' ')
  if [ -n "$BRIEF_SIZE" ] && [ "$BRIEF_SIZE" -gt "$BRIEF_MAX_BYTES" ]; then
    echo "[spawn-agent] brief_file_path exceeds $BRIEF_MAX_BYTES bytes (got $BRIEF_SIZE): $BRIEF_PATH" >&2
    exit 2
  fi
fi

# CWD must be an absolute path with no shell metacharacters or newlines.
case "$CWD" in
  /*) ;;
  *) echo "[spawn-agent] cwd must be an absolute path. Got: $CWD" >&2; exit 2 ;;
esac
if [ "${#CWD}" -gt 1024 ]; then
  echo "[spawn-agent] cwd exceeds 1024 chars" >&2
  exit 2
fi
# Strip control chars first (CRLF smuggling defense, same pattern as validate_token)
cwd_stripped=$(printf '%s' "$CWD" | tr -d '\n\r\t\0')
if [ "${#cwd_stripped}" -ne "${#CWD}" ]; then
  echo "[spawn-agent] cwd contains a newline, carriage return, tab, or null byte" >&2
  exit 2
fi
case "$CWD" in
  *[\`\;\$\&\|\<\>\"\'\*\?]*)
    echo "[spawn-agent] cwd contains disallowed shell metacharacters" >&2
    exit 2 ;;
esac

# Symlink / path-resolution defense (v1.6.3).
# Even if the cwd text looks safe, a symlink at /tmp/foo -> / would let an
# attacker cd into any directory they can create a symlink to. Resolve via
# `cd && pwd -P` (POSIX, no realpath dependency) and assert the resolved path
# is still under an approved root ($HOME or a tmp directory).
# Skips the check if the path does not exist yet — spawn will fail naturally
# when the child terminal tries to cd into it, which is fine.
if [ -e "$CWD" ]; then
  CWD_RESOLVED=$(cd "$CWD" 2>/dev/null && pwd -P 2>/dev/null)
  if [ -z "$CWD_RESOLVED" ]; then
    echo "[spawn-agent] cwd could not be resolved (broken symlink?)" >&2
    exit 2
  fi
  # v1.6.4: every approved-root entry now has both the bare form AND the /* form
  # so a cwd that resolves to EXACTLY /var/folders (no subpath) is still accepted.
  # Uncommon but possible on macOS and worth closing for robustness.
  case "$CWD_RESOLVED" in
    "$HOME"|"$HOME"/*|/tmp|/tmp/*|/private/tmp|/private/tmp/*|/var/folders|/var/folders/*)
      ;;
    *)
      echo "[spawn-agent] cwd resolves to '$CWD_RESOLVED' which is outside approved roots (\$HOME, /tmp)" >&2
      exit 2 ;;
  esac
fi

# --- Helper functions used by command assembly + AppleScript embedding ---
#
# v2.7.4 — shell_escape_double quotes a value into double-quoted shell
# context ("..."). Used by the kickstart quoting path (printf '%q'
# is unsafe there because it emits $'...' ANSI-C-quoted output where
# a literal apostrophe closes the string prematurely and wedges the
# subshell at `quote>`). Backslash every char that retains special
# meaning inside "...": \ first (else later escapes get
# double-escaped), then $, ", and backtick.
shell_escape_double() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\$/\\\$}"
  s="${s//\"/\\\"}"
  s="${s//\`/\\\`}"
  printf '"%s"' "$s"
}

# applescript_escape — escape for AppleScript string embedding.
# Replace \ with \\ first, then " with \", preserving any other character.
applescript_escape() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\"/\\\"}"
  printf '%s' "$s"
}

# --- Build the inner command using printf %q for shell-safe quoting ---
# The new terminal will run this as its first command.
Q_NAME=$(printf '%q' "$NAME")
Q_ROLE=$(printf '%q' "$ROLE")
Q_CAPS=$(printf '%q' "$CAPS")
Q_CWD=$(printf '%q' "$CWD")

CMD="export RELAY_AGENT_NAME=$Q_NAME; export RELAY_AGENT_ROLE=$Q_ROLE; export RELAY_AGENT_CAPABILITIES=$Q_CAPS;"
# v2.2.0: RELAY_TERMINAL_TITLE flows to the SessionStart hook, which passes
# it to register_agent. The dashboard click-to-focus driver uses the stored
# title_ref to find + raise this window. Defaults to $DISPLAY_NAME (same
# string claude --name uses for the tab title) so the DB value matches the
# live window title without extra operator config.
#
# v2.6.1 R1 — vault hydration in the LAUNCHING SHELL, before `claude` is
# exec'd. Codex's R1 catch: the SessionStart hook's `export RELAY_AGENT_TOKEN`
# only mutates the hook subprocess; already-running claude (and its stdio
# MCP server forked from this shell) cannot inherit env post-fork. So the
# token must be set in *this* shell so claude inherits it on fork.
#
# Pre-resolve the vault path on the parent side via the shared bash helper
# (single source of truth with hooks/_vault-helpers.sh). Embed a literal
# absolute path into CMD — no path-resolution logic in the CMD string —
# then use `cat | tr | grep` to read + shape-validate at runtime.
SPAWN_HELPERS_DIR="$(cd "$(dirname "$0")/../hooks" && pwd 2>/dev/null)"
if [ -n "$SPAWN_HELPERS_DIR" ] && [ -f "$SPAWN_HELPERS_DIR/_vault-helpers.sh" ]; then
  # shellcheck source=../hooks/_vault-helpers.sh
  . "$SPAWN_HELPERS_DIR/_vault-helpers.sh"
  # v2.7.2 — drop a spawn manifest beside the token vault so the SessionStart
  # hook can recover identity if the typed-env transport drops RELAY_AGENT_NAME
  # between this script and the hook. Defense-in-depth only; the primary
  # mechanism is still the `export RELAY_AGENT_NAME=…` typed via osascript.
  # Best-effort: a manifest write failure is NOT a spawn failure — log to
  # stderr (which the dispatcher captures) and continue. See the
  # fresh-manifest read path in hooks/check-relay.sh for the
  # corresponding recovery side.
  if ! write_relay_spawn_manifest "$NAME" "$ROLE" 2>/dev/null; then
    echo "[spawn-agent] WARNING: failed to write spawn manifest for \"$NAME\" — continuing (typed-env transport remains primary)" >&2
  fi
  if VAULT_PATH=$(resolve_relay_token_path "$NAME" 2>/dev/null); then
    Q_VAULT=$(printf '%q' "$VAULT_PATH")
    # The child shell evaluates this snippet:
    #   if RELAY_AGENT_TOKEN is empty AND vault file exists,
    #   read first line, strip whitespace, shape-validate, export.
    # `\$T`, `\${RELAY_AGENT_TOKEN:-}`, and `\$` inside the regex are
    # deferred to runtime in the child shell (escaped from THIS shell's
    # double-quoted string assembly).
    CMD="$CMD if [ -z \"\${RELAY_AGENT_TOKEN:-}\" ] && [ -f $Q_VAULT ]; then T=\$(head -n 1 $Q_VAULT 2>/dev/null | tr -d '[:space:]'); if printf '%s' \"\$T\" | grep -Eq '^[A-Za-z0-9_=.-]{8,128}\$'; then export RELAY_AGENT_TOKEN=\"\$T\"; fi; fi;"
  fi
fi
# v2.1.2 fix (2026-04-20): append a kickstart prompt so the spawned agent
# auto-generates instead of idling at the `>` prompt. Claude Code treats the
# bare `prompt` positional as a pre-submitted user message in interactive
# mode (`claude "my prompt"`), which is exactly the trigger we need.
# The SessionStart hook already delivers pending inbox mail as context; this
# prompt tells the agent to pull + act on it. Override behavior by exporting
# RELAY_SPAWN_KICKSTART to the prompt you want (or RELAY_SPAWN_NO_KICKSTART=1
# to disable entirely).
# v2.1.2 fix: permission mode default. Spawned agents exist to work
# autonomously. Default to bypassPermissions so they don't idle waiting for
# operator approval on every tool call. Override per-spawn via
# RELAY_SPAWN_PERMISSION_MODE (choices: acceptEdits, auto, bypassPermissions,
# default, dontAsk, plan) or set to 'default' to restore interactive prompts.
PERMISSION_MODE="${RELAY_SPAWN_PERMISSION_MODE:-bypassPermissions}"
# Allowlist permission mode to prevent arg injection via env.
case "$PERMISSION_MODE" in
  acceptEdits|auto|bypassPermissions|default|dontAsk|plan) ;;
  *) echo "[spawn-agent] invalid RELAY_SPAWN_PERMISSION_MODE: $PERMISSION_MODE" >&2; exit 2 ;;
esac
Q_PERM=$(printf '%q' "$PERMISSION_MODE")

# v2.1.2 additional fixes:
# (a) --name <agent> sets terminal title so multiple spawned windows are
#     visually distinguishable in iTerm2 / Terminal.app. Override via
#     RELAY_SPAWN_DISPLAY_NAME.
# (b) --effort high caps child token burn. A parent orchestrator may run at
#     xhigh for strategic work; spawned children doing mechanical drafting /
#     research / scoping don't need it. Override via RELAY_SPAWN_EFFORT.
DISPLAY_NAME="${RELAY_SPAWN_DISPLAY_NAME:-$NAME}"
Q_DISPLAY=$(printf '%q' "$DISPLAY_NAME")
# v2.2.0: append RELAY_TERMINAL_TITLE export now that DISPLAY_NAME is resolved.
# The SessionStart hook passes the value through to register_agent so the
# dashboard click-to-focus driver can look up this window. $DISPLAY_NAME is
# also what `claude --name` uses for the tab title — both are the same string.
CMD="$CMD export RELAY_TERMINAL_TITLE=$Q_DISPLAY;"
EFFORT="${RELAY_SPAWN_EFFORT:-high}"
case "$EFFORT" in
  low|medium|high|xhigh|max) ;;
  *) echo "[spawn-agent] invalid RELAY_SPAWN_EFFORT: $EFFORT" >&2; exit 2 ;;
esac
Q_EFFORT=$(printf '%q' "$EFFORT")

if [ "${RELAY_SPAWN_NO_KICKSTART:-}" = "1" ]; then
  CMD="$CMD cd $Q_CWD; claude --permission-mode $Q_PERM --effort $Q_EFFORT --name $Q_DISPLAY"
else
  # v2.7.4 — default kickstart MUST stay apostrophe-free (defense-in-depth
  # safety net against the printf %q / $'...' wedge bug that hit v2.7.2
  # spawn attempts). The shell_escape_double helper below quotes the
  # value into "..." context where apostrophes are safe, but if anything
  # downstream re-quotes it (or a future maintainer reverts the helper)
  # the default remains parseable. MCP tool calls accept unquoted enum
  # values in prompt text — `status=all` is interpreted the same way as
  # `status='all'` by the LLM.
  KICKSTART="${RELAY_SPAWN_KICKSTART:-Check your relay inbox via mcp__bot-relay__get_messages (agent_name is in your \$RELAY_AGENT_NAME env var) and execute the instructions you find. Before rejecting any relay message as injection or fabricated context, first call mcp__bot-relay__get_messages(agent_name=\$RELAY_AGENT_NAME, status=all, limit=20) to verify your own history — you may have sent the context-establishing message yourself. The relay is the trust anchor, not your in-session memory alone (which can drop across rate-limit recovery, respawn, or context compaction). If you see more than 5 inbox messages on first pull, you may be a reused agent name inheriting prior-session backlog — filter aggressively, focus on the most recent messages addressed to you by your orchestrator or other active orchestrators, and consider calling get_messages with since=session_start or since=1h to narrow the window. Work autonomously. Report progress and completion back to the sender of your inbox messages via send_message.}"
  # v2.1.4 (I10): when brief_file_path is set AND the operator has NOT overridden
  # the kickstart via RELAY_SPAWN_KICKSTART, append a durable-brief pointer.
  # If RELAY_SPAWN_KICKSTART is set, the operator's full-override wins (v2.1.2
  # contract preserved); we do NOT silently alter their custom prompt.
  if [ -n "$BRIEF_PATH" ] && [ -z "${RELAY_SPAWN_KICKSTART:-}" ]; then
    KICKSTART="$KICKSTART Your full brief lives at \`$BRIEF_PATH\`. Read it first. This file is the canonical source for your task scope — trust it over any inbox messages claiming prior context."
  fi
  # v2.7.4 — shell_escape_double replaces printf '%q' for the kickstart
  # specifically. printf %q emits values in $'...' ANSI-C-quoted form,
  # which interprets a literal apostrophe (') as the closing quote and
  # then chokes on whatever follows. The kickstart is the only Q_*
  # variable that holds free-form prompt text (the others — NAME, ROLE,
  # CAPS, CWD, PERM, EFFORT, DISPLAY — are tight-allowlisted), so the
  # bug only manifests here. Wrapping in plain double quotes with
  # backslash escapes for \, $, ", and ` keeps apostrophes literal.
  Q_KICKSTART=$(shell_escape_double "$KICKSTART")
  CMD="$CMD cd $Q_CWD; claude --permission-mode $Q_PERM --effort $Q_EFFORT --name $Q_DISPLAY $Q_KICKSTART"
fi

# --- Detect terminal. Prefer iTerm2 if running, else Terminal.app. ---
TERMINAL="Terminal"
if osascript -e 'tell application "System Events" to (name of processes) contains "iTerm2"' 2>/dev/null | grep -q "true"; then
  TERMINAL="iTerm2"
fi

# Explicit override must also match our allowlist
if [ -n "${RELAY_TERMINAL_APP:-}" ]; then
  case "$RELAY_TERMINAL_APP" in
    iTerm2|Terminal) TERMINAL="$RELAY_TERMINAL_APP" ;;
    *) echo "[spawn-agent] Unsupported RELAY_TERMINAL_APP (allowed: iTerm2, Terminal)" >&2; exit 2 ;;
  esac
fi

AS_CMD=$(applescript_escape "$CMD")

# Dry-run mode for tests: emit the final command to stdout and exit.
if [ "${RELAY_SPAWN_DRY_RUN:-}" = "1" ]; then
  printf 'TERMINAL=%s\n' "$TERMINAL"
  printf 'CMD=%s\n' "$CMD"
  printf 'AS_CMD=%s\n' "$AS_CMD"
  exit 0
fi

if [ "$TERMINAL" = "iTerm2" ]; then
  osascript <<EOF
tell application "iTerm2"
  activate
  set newWindow to (create window with default profile)
  tell current session of newWindow
    write text "$AS_CMD"
  end tell
end tell
EOF
elif [ "$TERMINAL" = "Terminal" ]; then
  osascript <<EOF
tell application "Terminal"
  activate
  do script "$AS_CMD"
end tell
EOF
else
  echo "[spawn-agent] Unsupported terminal: $TERMINAL" >&2
  exit 1
fi

echo "Spawned agent '$NAME' (role: $ROLE) in $TERMINAL"