Hooks

Where it lives

• hooks/foundry-cli-guard.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  #
  # foundry-cli-guard.sh
  #
  # PreToolUse hook that flags Foundry CLI commands missing --no-prompt,
  # flags manual directory/file creation that should use the CLI, and
  # reminds Claude to confirm resource names with the user before creating.
  #
  # Prevents common failures:
  # 1. Running Foundry CLI commands without --no-prompt (causes Error: EOF)
  # 2. Running foundry apps deploy without --change-type (causes 500 error)
  # 3. Running ui extensions create without --sockets (interactive picker hangs)
  # 4. Using mkdir/touch to create app structure (causes invalid manifests)
  # 5. Creating resources without user confirmation of the name
  # 6. Deleting an AI agent or knowledge base without user confirmation
  #
  # Receives JSON on stdin with hook_event_name and tool-specific fields.
  # Outputs JSON with additionalContext (advisory nudge, not blocking).
  #
  # Environment variables:
  #   FOUNDRY_SKIP_NAME_CONFIRM=1  Bypass name confirmation (for automated tests)
  #
  # Note: foundry-skill-router.sh also fires on `api-integrations create` for
  # OpenAPI spec adaptation. Both hooks produce independent advisories.
  
  set -euo pipefail
  
  # shellcheck disable=SC1091
  source "$(dirname "${BASH_SOURCE[0]}")/host-output.sh"
  
  INPUT=$(cat)
  
  HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
  case "$HOOK_EVENT" in
    preToolUse) HOOK_EVENT=PreToolUse ;;
  esac
  
  if [ "$HOOK_EVENT" != "PreToolUse" ]; then
    exit 0
  fi
  
  TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
  
  # Claude's shell tool is Bash. Cursor's is Shell.
  if [ "$TOOL_NAME" != "Bash" ] && [ "$TOOL_NAME" != "Shell" ]; then
    exit 0
  fi
  
  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
  
  # The parts of COMMAND that actually invoke the Foundry CLI: heredoc bodies and
  # quoted strings are blanked, the rest is split on ; & | ( ) ` and newlines, and
  # only pieces whose first word is `foundry` are kept. Subcommand checks match
  # against this, so `git commit -m "... foundry apps create ..."` doesn't trigger them.
  FOUNDRY_CMDS=$(printf '%s' "$COMMAND" | jq -Rrs "$(cat <<'JQ'
  gsub("<<-?[[:space:]]*[\"']?(?<w>[A-Za-z_][A-Za-z0-9_]*)[\"']?[^\n]*\n(?:.*?\n)??[[:space:]]*\\k<w>(?=[[:space:]]|\\)|$)"; ""; "s")
  | gsub("\"(?:\\\\.|[^\"\\\\])*\""; "\"\"")
  | gsub("'[^']*'"; "''")
  | [splits("[\n;&|()\\x60]+")
     | sub("^[[:space:]]*(?:[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*"; "")
     | select(test("^(?:[^[:space:]]*/)?foundry(?:[[:space:]]|$)"))]
  | join("\n")
  JQ
  )")
  
  # The same foundry pieces with their argument values intact, for reading --name,
  # --sockets, and schema paths. Flag-presence checks use FOUNDRY_CMDS, so a quoted
  # "--no-prompt" in a commit message can't satisfy a real foundry command.
  FOUNDRY_RAW=$(printf '%s\n' "$COMMAND" | awk '{ gsub(/&&|\|\||;|\|/, "\n"); print }' |
    sed -E 's/^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*//' |
    grep -E '^([^[:space:]]*/)?foundry([[:space:]]|$)' || true)
  
  # A --help or -h call only prints usage, so it never needs --no-prompt, --sockets,
  # or any other flag the checks below look for.
  HELP_RE='(^|[[:space:]])(-h|--help)([[:space:]]|$)'
  FOUNDRY_CMDS=$(printf '%s\n' "$FOUNDRY_CMDS" | grep -vE "$HELP_RE" || true)
  FOUNDRY_RAW=$(printf '%s\n' "$FOUNDRY_RAW" | grep -vE "$HELP_RE" || true)
  
  # True when a Foundry invocation matching $1 lacks flag $2. Each line of
  # FOUNDRY_CMDS is one invocation, so a flag on one command in a chain can't
  # satisfy another.
  missing_flag() {
    printf '%s\n' "$FOUNDRY_CMDS" | grep -E "$1" | grep -vqF -- "$2"
  }
  
  # Set by reminders that must not short-circuit a later, more important advisory.
  # Whichever advisory fires next prepends it; if none does, it is flushed at the end.
  PENDING_REMINDER=""
  
  # Check for Foundry CLI commands that need --no-prompt
  # Nearly all Foundry CLI commands support --no-prompt:
  #   apps create/validate/release/delete/logs, functions create, collections create,
  #   workflows create, api-integrations create, agents create/delete,
  #   knowledge-bases create/delete (alias: kb), ui pages create, ui extensions create,
  #   rtr-scripts create, profile create/delete
  #   functions exec (incl. exec list / exec status), functions logs, functions test
  if missing_flag 'foundry\s+apps\b.*\b(create|validate|release|delete|logs)\b|foundry\s+(functions|collections|workflows|api-integrations|rtr-scripts)\b.*\bcreate\b|foundry\s+(agents|knowledge-bases|kb)\b.*\b(create|delete)\b|foundry\s+functions\s+(exec|logs|test)\b|foundry\s+profile\b.*\b(create|delete)\b|foundry\s+ui\s+(pages|extensions)\b.*\bcreate\b' '--no-prompt'; then
    emit_advisory "PreToolUse" "The command is missing --no-prompt. Foundry CLI commands (create/validate/release/delete, functions exec/logs/test) run non-interactively in coding assistants and will hang with Error: EOF without it. Add --no-prompt before retrying. Example: foundry apps create --name \"app-name\" --no-prompt"
    exit 0
  fi
  
  # Check for foundry apps deploy without --change-type
  # Omitting --change-type causes a 500 error (server-side panic) because the
  # Foundry API requires a change_type field in deploy requests.
  if echo "$FOUNDRY_CMDS" | grep -qE 'foundry\s+apps\s+deploy\b'; then
    if missing_flag 'foundry\s+apps\s+deploy\b' '--change-type'; then
      emit_advisory "PreToolUse" "The command is missing --change-type. Foundry apps deploy requires --change-type and --change-log to avoid a 500 error. Add both flags before retrying. Example: foundry apps deploy --change-type Patch --change-log \"description of changes\" --no-prompt"
      exit 0
    fi
    if missing_flag 'foundry\s+apps\s+deploy\b' '--change-log'; then
      emit_advisory "PreToolUse" "The command is missing --change-log. Foundry apps deploy requires --change-type and --change-log. Add both flags before retrying. Example: foundry apps deploy --change-type Patch --change-log \"description of changes\" --no-prompt"
      exit 0
    fi
  fi
  
  # Check for foundry knowledge-bases create without --files
  # A knowledge base must ship at least one file. With -

• hooks/foundry-session-start.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  #
  # foundry-session-start.sh — SessionStart hook
  #
  # 1. Check Foundry CLI version and warn if below minimum required
  # 2. Set FOUNDRY_UI_HEADLESS_MODE=true for CLIs below 2.0.1 (older versions
  #    need this env var to suppress the TUI; 2.0.1+ auto-detects headless)
  #
  set -euo pipefail
  
  # shellcheck disable=SC1091
  source "$(dirname "${BASH_SOURCE[0]}")/host-output.sh"
  
  # Claude Code shows hook stderr to the model. Cursor only injects
  # additional_context from stdout, so the same warning has to be emitted both ways.
  emit_user_warning() {
    if cursor_hooks; then
      emit_advisory "SessionStart" "$1"
    else
      printf '%s\n' "$1" >&2
    fi
  }
  
  # --- Version check ---
  MINIMUM_VERSION="2.1.0"
  NEEDS_UPGRADE=0
  
  if CLI_OUTPUT=$(foundry version 2>/dev/null); then
    CLI_VERSION=$(echo "$CLI_OUTPUT" | awk '{print $2}')
  
    # Compare semver: split into major.minor.patch
    IFS='.' read -r CUR_MAJ CUR_MIN CUR_PAT <<< "$CLI_VERSION"
    IFS='.' read -r MIN_MAJ MIN_MIN MIN_PAT <<< "$MINIMUM_VERSION"
  
    if [ "${CUR_MAJ:-0}" -lt "${MIN_MAJ:-0}" ]; then
      NEEDS_UPGRADE=1
    elif [ "${CUR_MAJ:-0}" -eq "${MIN_MAJ:-0}" ]; then
      if [ "${CUR_MIN:-0}" -lt "${MIN_MIN:-0}" ]; then
        NEEDS_UPGRADE=1
      elif [ "${CUR_MIN:-0}" -eq "${MIN_MIN:-0}" ] && [ "${CUR_PAT:-0}" -lt "${MIN_PAT:-0}" ]; then
        NEEDS_UPGRADE=1
      fi
    fi
  
    if [ "$NEEDS_UPGRADE" -eq 1 ]; then
      emit_user_warning "IMPORTANT: Foundry CLI $CLI_VERSION is below the minimum required $MINIMUM_VERSION. Before proceeding with any Foundry work, you MUST inform the user and offer to upgrade:
  
    - macOS/Linux: brew upgrade crowdstrike/foundry-cli/foundry
    - Windows: Download https://assets.foundry.crowdstrike.com/cli/latest/foundry_Windows_x86_64.zip
  
  Feature unavailable below $MINIMUM_VERSION: function execution and debugging (foundry functions exec, test, logs), non-interactive output for actions view and triggers view with multiple matches, and automatic headless mode detection.
  
  Ask the user whether to upgrade now. If the user declines, Foundry commands may fail or behave unexpectedly."
    fi
  fi
  
  # --- Env vars for older CLIs ---
  # CLIs below 2.0.1 need FOUNDRY_UI_HEADLESS_MODE=true to suppress the TUI.
  # 2.0.1+ auto-detects headless environments, so this is only needed as a fallback.
  if [ "$NEEDS_UPGRADE" -eq 1 ]; then
    if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
      echo 'export FOUNDRY_UI_HEADLESS_MODE=true' >> "$CLAUDE_ENV_FILE"
    else
      emit_user_warning "IMPORTANT: Foundry CLI $CLI_VERSION requires FOUNDRY_UI_HEADLESS_MODE=true to suppress the TUI in non-interactive environments. You MUST run this export before ANY foundry CLI command (deploy, release, validate, etc.), or those commands will fail with \"could not open a new TTY\":
  
    export FOUNDRY_UI_HEADLESS_MODE=true
  
  Run this silently at the start of any shell command that uses the foundry CLI. Do not ask the user — just prepend it."
    fi
  fi
  
  exit 0
  

• hooks/foundry-skill-router.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  #
  # foundry-skill-router.sh
  #
  # Two-hook system for Foundry skill routing:
  # 1. UserPromptSubmit: Detects specific Foundry keywords → writes marker file + injects context
  # 2. PreToolUse (all tools): Reads marker → injects advisory reminder to use
  #    the Foundry development workflow skill (non-blocking)
  #
  # The marker file bridges the two hooks since they run at different times.
  # It is scoped to the session, reset on every prompt, and removed after the
  # first reminder (or when the Skill tool is invoked), so one detected prompt
  # produces one reminder instead of one per tool call.
  #
  # Receives JSON on stdin with hook_event_name and event-specific fields.
  # Outputs JSON with additionalContext or permissionDecision (deny blocks the call).
  
  set -euo pipefail
  
  # shellcheck disable=SC1091
  source "$(dirname "${BASH_SOURCE[0]}")/host-output.sh"
  
  INPUT=$(cat)
  
  HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
  # Cursor names these beforeSubmitPrompt and preToolUse, and sends conversation_id.
  case "$HOOK_EVENT" in
    beforeSubmitPrompt) HOOK_EVENT=UserPromptSubmit ;;
    preToolUse) HOOK_EVENT=PreToolUse ;;
  esac
  SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .conversation_id // empty')
  MARKER="/tmp/.foundry-skill-router-active${SESSION_ID:+-$SESSION_ID}"
  
  # Best-effort cross-host check. Claude Code records installed plugins in JSON;
  # Codex records enabled marketplace plugins in config.toml; Antigravity in
  # config.json; Cursor keeps a marketplace install in its plugin cache.
  codex_plugin_enabled() {
    local plugin="$1"
    [ -f "$HOME/.codex/config.toml" ] || return 1
    # Only the plugin's own table counts, not a nested one such as
    # [plugins."<id>@<marketplace>".mcp_servers.x].
    awk -v prefix="[plugins.\"$plugin@" '
      /^\[/ { in_plugin = (index($0, prefix) == 1 && substr($0, length(prefix) + 1) ~ /^[^".]*"\][[:space:]]*(#.*)?$/); next }
      in_plugin && /^enabled[[:space:]]*=[[:space:]]*true[[:space:]]*(#.*)?$/ { found = 1 }
      END { exit found ? 0 : 1 }
    ' "$HOME/.codex/config.toml" 2>/dev/null
  }
  
  plugin_is_enabled() {
    local plugin="$1"
    # Cursor sets CURSOR_PLUGIN_ROOT. Codex sends turn_id. Check only that host
    # so a Claude registry on the same machine cannot mark a Codex-disabled
    # sibling as installed.
    if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
      [ -d "$HOME/.cursor/plugins/cache/cursor-public/$plugin" ]
      return
    fi
    if printf '%s' "$INPUT" | jq -e 'has("turn_id")' >/dev/null 2>&1; then
      codex_plugin_enabled "$plugin"
      return
    fi
    if [ -f "$HOME/.claude/plugins/installed_plugins.json" ] &&
       grep -q "$plugin" "$HOME/.claude/plugins/installed_plugins.json" 2>/dev/null; then
      return 0
    fi
    if codex_plugin_enabled "$plugin"; then
      return 0
    fi
    if [ -d "$HOME/.gemini/config/plugins/$plugin" ]; then
      if [ ! -f "$HOME/.gemini/config/config.json" ] || ! python3 -c '
  import json, os, sys
  try:
      c = json.load(open(os.path.expanduser("~/.gemini/config/config.json")))
      if c.get("plugins", {}).get(sys.argv[1], {}).get("enabled") is False:
          sys.exit(1)
  except Exception:
      pass
  sys.exit(0)
  ' "$plugin" 2>/dev/null; then
        return 0
      fi
    fi
    if [ -d "$HOME/.cursor/plugins/cache/cursor-public/$plugin" ]; then
      return 0
    fi
    return 1
  }
  
  case "$HOOK_EVENT" in
    UserPromptSubmit)
      # Each prompt is classified on its own; never carry a detection forward.
      rm -f "$MARKER"
      USER_PROMPT=$(echo "$INPUT" | jq -r '.prompt // .user_prompt // empty')
      PROMPT_LOWER=$(echo "$USER_PROMPT" | tr '[:upper:]' '[:lower:]')
  
      FOUNDRY_MATCH=false
  
      # Require an action verb + Foundry noun to detect real development intent.
      # "create a foundry app" triggers; "if we were in a foundry app" does not.
      # The verb and noun must be at most five words apart, so a prompt that
      # fixes one thing and mentions Falcon Foundry later in the sentence doesn't match,
      # while "connect the OpenRouter API to a Foundry app" still does.
      VERBS="create|build|set up|make|need|want|write|connect|deploy|release|scaffold|add|update|fix|debug|configure|audit|review|scan"
      NOUNS="foundry app|foundry function|foundry collection|foundry workflow|foundry ui|foundry page|foundry api|falcon foundry|falcon app|crowdstrike app|foundry extension|foundry agent|foundry knowledge base"
      GAP="([[:space:]]+[^[:space:]]+){0,5}[[:space:]]+"
  
      if echo "$PROMPT_LOWER" | grep -qE "\b(${VERBS})\b${GAP}(${NOUNS})"; then
        FOUNDRY_MATCH=true
      elif echo "$PROMPT_LOWER" | grep -qE "(${NOUNS})${GAP}(${VERBS})\b"; then
        # Also catch "foundry app ... deploy" word order
        FOUNDRY_MATCH=true
      fi
  
      # A verb anywhere in the prompt is enough to ask the Fusion classifier,
      # which only redirects standalone Fusion work: "Create a Falcon Fusion
      # workflow, no Foundry app" puts the verb far from the noun.
      LOOSE_MATCH=false
      if echo "$PROMPT_LOWER" | grep -qE "\b(${VERBS})\b.*(${NOUNS})|(${NOUNS}).*\b(${VERBS})\b"; then
        LOOSE_MATCH=true
      fi
  
      # Explicit CLI commands always trigger
      for cmd in "foundry apps create" "foundry apps deploy" "foundry apps release" \
                 "foundry apps run" "foundry login"; do
        if echo "$PROMPT_LOWER" | grep -qF "$cmd"; then
          FOUNDRY_MATCH=true
          break
        fi
      done
  
      # Explicit skill requests always trigger
      if echo "$PROMPT_LOWER" | grep -qE "(use|invoke|run) foundry (skill|plugin)"; then
        FOUNDRY_MATCH=true
      fi
  
      if [ "$FOUNDRY_MATCH" = true ] || [ "$LOOSE_MATCH" = true ]; then
        # Standalone Fusion workflow? Advise the sibling plugin instead of
        # steering into app scaffolding. Without this the classifier is never
        # consulted at runtime and the agent tends to quietly author the workflow
        # itself, never telling the user a better-suited plugin exists.
        REDIRECT_SCRIPT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/skills/development-workflow/scripts/detect_fusion_red

• hooks/host-output.shGitHub ↗
  Read the script

  # shellcheck shell=bash
  # host-output.sh — JSON shape the current host actually injects.
  #
  # Sourced by the hook scripts. Cursor sets CURSOR_PLUGIN_ROOT and injects
  # top-level additional_context; it does not inject Claude's nested
  # hookSpecificOutput.additionalContext. Claude Code also reads additional_context,
  # so emitting both duplicates the advisory there. Deny decisions use Cursor's
  # permission/agent_message fields on Cursor and Claude's permissionDecision
  # everywhere else. Codex and Copilot keep the Claude shape.
  
  cursor_hooks() {
    [ -n "${CURSOR_PLUGIN_ROOT:-}" ]
  }
  
  emit_advisory() {
    local event="$1"
    local text="$2"
    if cursor_hooks; then
      jq -n --arg text "$text" '{additional_context: $text}'
    else
      jq -n --arg event "$event" --arg text "$text" '{
        hookSpecificOutput: {
          hookEventName: $event,
          additionalContext: $text
        }
      }'
    fi
  }
  
  emit_deny() {
    local event="$1"
    local reason="$2"
    if cursor_hooks; then
      jq -n --arg reason "$reason" '{
        permission: "deny",
        agent_message: $reason,
        user_message: $reason
      }'
    else
      jq -n --arg event "$event" --arg reason "$reason" '{
        hookSpecificOutput: {
          hookEventName: $event,
          permissionDecision: "deny",
          permissionDecisionReason: $reason
        }
      }'
    fi
  }
  

• hooks/superpowers-foundry-bridge.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  #
  # superpowers-foundry-bridge.sh
  #
  # PreToolUse hook on the Skill tool. When superpowers:brainstorming is invoked,
  # it advises switching to development-workflow if the task is Foundry app work
  # and continuing with brainstorming otherwise. Advisory context is injected for
  # other superpowers planning skills. It has no project-directory check, so it
  # fires on every matching Skill call and the wording stays conditional.
  #
  # Receives JSON on stdin with tool_input.skill (the skill being invoked).
  # Outputs JSON with additionalContext; it never blocks.
  
  set -euo pipefail
  
  # shellcheck disable=SC1091
  source "$(dirname "${BASH_SOURCE[0]}")/host-output.sh"
  
  INPUT=$(cat)
  
  SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
  
  # Redirect brainstorming to the Foundry development workflow skill.
  # Uses additionalContext for a clean UX (no error messages).
  # ~75% reliable — when it misses, the model still has Foundry skills in its
  # available skills list. deny is 100% reliable but shows ugly duplicate errors.
  case "$SKILL_NAME" in
    superpowers:brainstorming|brainstorming)
      emit_advisory "PreToolUse" "FOUNDRY PLUGIN INSTALLED: If this task is Falcon Foundry app development, stop brainstorming and invoke crowdstrike-falcon-foundry:development-workflow instead. It handles requirements gathering, CLI scaffolding, and manifest coordination, while brainstorming plans hand-written manifest.yml files that fail to deploy. For any other task, continue with brainstorming."
      exit 0
      ;;
  esac
  
  # Advisory context for other superpowers planning skills
  case "$SKILL_NAME" in
    superpowers:writing-plans|writing-plans|\
    superpowers:executing-plans|executing-plans|\
    superpowers:subagent-driven-development|subagent-driven-development)
      CONTEXT=$(cat <<'FOUNDRY_CONTEXT'
  FOUNDRY PLUGIN INSTALLED: If this task involves Falcon Foundry, invoke crowdstrike-falcon-foundry:development-workflow BEFORE this skill. That skill owns Foundry app creation — it uses CLI commands (foundry apps create, foundry api-integrations create, etc.) that generate manifest.yml and wire up capability IDs correctly. Hand-writing manifest.yml or workflow YAML without the CLI causes deploy failures.
  FOUNDRY_CONTEXT
      )
      emit_advisory "PreToolUse" "$CONTEXT"
      exit 0
      ;;
  esac
  

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.