@aporthq/aport-agent-guardrails 1.0.23 → 1.0.24

package/README.md

@@ -124,6 +124,9 @@ Install via `npx @aporthq/aport-agent-guardrails <framework>` (or choose when pr
 ```bash
 npx @aporthq/aport-agent-guardrails
 # or: npx @aporthq/aport-agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n
+# optional mode flags (all frameworks):
+#   --mode=api --api-url=https://api.aport.io
+#   --mode=local
 ```
 
 **Python (LangChain, CrewAI, or DeerFlow):** Use the Python CLI directly via `uvx` or an installed package:
@@ -141,6 +144,8 @@ Then install the framework-specific Python package and follow the printed integr
 
 This runs the **passport wizard** and writes config for your framework. Follow the **next steps** printed at the end (e.g. restart Cursor; or for CrewAI: by default install `aport-agent-guardrails-crewai` for released CrewAI, or opt into native-provider mode if your CrewAI build supports it).
 
+**Guardrail mode (local vs API)** — On the **Node** installer (`npx @aporthq/aport-agent-guardrails …` / `bin/agent-guardrails`), every framework accepts the same flags: `--mode=api` (with optional `--api-url`, default `https://api.aport.io`) or `--mode=local`, and an optional hosted `ap_<hex>` argument (API mode, no local passport). That flow writes `…/aport/guardrail-mode.env` where the hooks/generic installers need it. The **Python** `aport setup` CLI does not parse those flags yet; use the Node command above for API/local mode during setup, or set mode in your framework `config.yaml` per the framework doc.
+
 **2. Hosted passport (optional)** — If you already have an agent_id from [aport.io](https://aport.io), use it to skip the wizard: `npx @aporthq/aport-agent-guardrails openclaw <agent_id>`. See [Hosted passport setup](docs/HOSTED_PASSPORT_SETUP.md).
 
 **3. Test that policy runs** — After setup, the guardrail runs automatically when your agent uses tools (Cursor hook, LangChain callback, OpenClaw plugin, etc.). To try allow/deny from the command line (any framework), use the installed `aport-guardrail` command (Node) or call the evaluator from Python; both use your existing passport from the framework config dir (e.g. `~/.cursor/aport/`, `~/.aport/langchain/aport/`).

package/bin/aport-claude-code-hook.sh

@@ -8,11 +8,21 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
 
 # Path resolver: probes ~/.claude, ~/.cursor, ~/.openclaw, etc.
 # shellcheck source=bin/aport-resolve-paths.sh
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
+# shellcheck source=bin/lib/guardrail-mode.sh
+. "$ROOT_DIR/bin/lib/guardrail-mode.sh"
+load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.claude}"
+
+GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
+if [ "${APORT_GUARDRAIL_MODE:-local}" = "api" ]; then
+    GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-api.sh"
+    if [ -n "${APORT_API_URL:-}" ]; then
+        export APORT_API_URL
+    fi
+fi
 
 # Read stdin
 INPUT=""

package/bin/aport-cursor-hook.sh

@@ -12,11 +12,21 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
 
 # Passport/config: resolver probes ~/.cursor, ~/.openclaw, ~/.aport/*, etc.
 # shellcheck source=bin/aport-resolve-paths.sh
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
+# shellcheck source=bin/lib/guardrail-mode.sh
+. "$ROOT_DIR/bin/lib/guardrail-mode.sh"
+load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.cursor}"
+
+GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
+if [ "${APORT_GUARDRAIL_MODE:-local}" = "api" ]; then
+    GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-api.sh"
+    if [ -n "${APORT_API_URL:-}" ]; then
+        export APORT_API_URL
+    fi
+fi
 
 # Read stdin (single JSON object; Cursor sends one payload per invocation)
 INPUT=""

package/bin/frameworks/claude-code.sh

@@ -12,21 +12,43 @@ source "$LIB/passport.sh"
 source "$LIB/config.sh"
 # shellcheck source=../lib/framework-setup.sh
 source "$LIB/framework-setup.sh"
+# shellcheck source=../lib/guardrail-mode.sh
+source "$LIB/guardrail-mode.sh"
 
 run_setup() {
+    parse_guardrail_mode_args "$@"
+
     log_info "Setting up APort guardrails for Claude Code..."
     config_dir="$(ensure_aport_dir_secure claude-code)"
 
     export APORT_FRAMEWORK=claude-code
 
-    # Check AGENTS.md for enforcement config — skip wizard if already configured
-    # shellcheck source=../lib/agentsmd.sh
-    source "$LIB/agentsmd.sh"
-    setup_from_agentsmd_or_wizard "$@"
+    local hosted_agent_id=""
+    if [[ -n "${APORT_HOSTED_AGENT_ID_CLI:-}" ]]; then
+        hosted_agent_id="$APORT_HOSTED_AGENT_ID_CLI"
+        export APORT_AGENT_ID="$hosted_agent_id"
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    else
+        # Check AGENTS.md for enforcement config — skip wizard if already configured
+        # shellcheck source=../lib/agentsmd.sh
+        source "$LIB/agentsmd.sh"
+        setup_from_agentsmd_or_wizard "${APORT_FRAMEWORK_ARGS[@]}"
+    fi
 
     # Harden permissions on passport (contains policy/capabilities)
     [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
 
+    if [[ -z "$hosted_agent_id" && -n "${APORT_AGENT_ID:-}" ]]; then
+        hosted_agent_id="$APORT_AGENT_ID"
+    fi
+
+    select_guardrail_mode "claude-code" "$hosted_agent_id"
+    select_guardrail_api_url "$APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        export APORT_API_URL="${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    MODE_FILE="$(write_guardrail_mode_file "$config_dir" "$APORT_SELECTED_GUARDRAIL_MODE" "${APORT_SELECTED_API_URL:-}" "$hosted_agent_id")"
+
     # Resolve absolute path to hook script (works from repo or npx package)
     HOOK_SCRIPT="$(resolve_hook_script_path "${APORT_CLAUDE_CODE_HOOK_SCRIPT:-}" "aport-claude-code-hook.sh" "$LIB")"
     if [ ! -f "$HOOK_SCRIPT" ]; then
@@ -48,8 +70,13 @@ run_setup() {
     echo "  ─────────────────────────"
     echo "  1. Settings written to: $SETTINGS_FILE"
     echo "  2. Hook script: $HOOK_SCRIPT"
-    echo "  3. Restart Claude Code so the PreToolUse hook is picked up."
-    echo "  4. Tool use will be checked by APort policy (exit 2 = block)."
+    echo "  3. Guardrail mode: $APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        echo "     API URL: ${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    echo "  4. Mode config: $MODE_FILE"
+    echo "  5. Restart Claude Code so the PreToolUse hook is picked up."
+    echo "  6. Tool use will be checked by APort policy (exit 2 = block)."
     echo ""
     echo "  Audit log: $config_dir/aport/audit.log"
     echo ""

package/bin/frameworks/cursor.sh

@@ -12,22 +12,44 @@ source "$LIB/passport.sh"
 source "$LIB/config.sh"
 # shellcheck source=../lib/framework-setup.sh
 source "$LIB/framework-setup.sh"
+# shellcheck source=../lib/guardrail-mode.sh
+source "$LIB/guardrail-mode.sh"
 
 run_setup() {
+    parse_guardrail_mode_args "$@"
+
     log_info "Setting up APort guardrails for Cursor..."
     # Passport and data live under Cursor's config dir (~/.cursor/aport/ by default).
     config_dir="$(ensure_aport_dir_secure cursor)"
 
     export APORT_FRAMEWORK=cursor
 
-    # Check AGENTS.md for enforcement config — skip wizard if already configured
-    # shellcheck source=../lib/agentsmd.sh
-    source "$LIB/agentsmd.sh"
-    setup_from_agentsmd_or_wizard "$@"
+    local hosted_agent_id=""
+    if [[ -n "${APORT_HOSTED_AGENT_ID_CLI:-}" ]]; then
+        hosted_agent_id="$APORT_HOSTED_AGENT_ID_CLI"
+        export APORT_AGENT_ID="$hosted_agent_id"
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    else
+        # Check AGENTS.md for enforcement config — skip wizard if already configured
+        # shellcheck source=../lib/agentsmd.sh
+        source "$LIB/agentsmd.sh"
+        setup_from_agentsmd_or_wizard "${APORT_FRAMEWORK_ARGS[@]}"
+    fi
 
     # Harden permissions on passport (contains policy/capabilities)
     [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
 
+    if [[ -z "$hosted_agent_id" && -n "${APORT_AGENT_ID:-}" ]]; then
+        hosted_agent_id="$APORT_AGENT_ID"
+    fi
+
+    select_guardrail_mode "cursor" "$hosted_agent_id"
+    select_guardrail_api_url "$APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        export APORT_API_URL="${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    MODE_FILE="$(write_guardrail_mode_file "$config_dir" "$APORT_SELECTED_GUARDRAIL_MODE" "${APORT_SELECTED_API_URL:-}" "$hosted_agent_id")"
+
     # Resolve absolute path to hook script (works from repo or npx package)
     HOOK_SCRIPT="$(resolve_hook_script_path "${APORT_CURSOR_HOOK_SCRIPT:-}" "aport-cursor-hook.sh" "$LIB")"
     if [ ! -f "$HOOK_SCRIPT" ]; then
@@ -72,8 +94,13 @@ run_setup() {
     echo "  ────────────────────"
     echo "  1. Hooks config written to: $CURSOR_HOOKS_FILE"
     echo "  2. Hook script: $HOOK_SCRIPT"
-    echo "  3. Restart Cursor (or reload window) so hooks are picked up."
-    echo "  4. Shell commands and tool use will be checked by APort policy (exit 2 = block)."
+    echo "  3. Guardrail mode: $APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        echo "     API URL: ${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    echo "  4. Mode config: $MODE_FILE"
+    echo "  5. Restart Cursor (or reload window) so hooks are picked up."
+    echo "  6. Shell commands and tool use will be checked by APort policy (exit 2 = block)."
     echo ""
     echo "  Same script works for VS Code + Copilot. For Claude Code use the dedicated integration: docs/frameworks/claude-code.md"
     echo ""

package/bin/frameworks/generic.sh

@@ -17,31 +17,48 @@ source "$LIB/passport.sh"
 source "$LIB/runtime.sh"
 # shellcheck source=../lib/config.sh
 source "$LIB/config.sh"
+# shellcheck source=../lib/guardrail-mode.sh
+source "$LIB/guardrail-mode.sh"
 
 framework="${APORT_FRAMEWORK:?APORT_FRAMEWORK must be set by the dispatcher}"
 crewai_integration_mode="${APORT_CREWAI_INTEGRATION_MODE:-compat}"
+hosted_agent_id=""
 
+parse_guardrail_mode_args "$@"
 FORWARD_ARGS=()
-while [[ $# -gt 0 ]]; do
-    case "$1" in
+if [[ -n "${APORT_FRAMEWORK_ARGS+x}" ]]; then
+    remaining_args=("${APORT_FRAMEWORK_ARGS[@]}")
+else
+    remaining_args=()
+fi
+while [[ ${#remaining_args[@]} -gt 0 ]]; do
+    arg="${remaining_args[0]}"
+    remaining_args=("${remaining_args[@]:1}")
+    case "$arg" in
         --integration-mode=*)
-            crewai_integration_mode="${1#--integration-mode=}"
+            crewai_integration_mode="${arg#--integration-mode=}"
             ;;
         --integration-mode)
-            if [[ $# -lt 2 ]]; then
+            if [[ ${#remaining_args[@]} -lt 1 ]]; then
                 log_error "--integration-mode requires compat or native"
                 exit 1
             fi
-            crewai_integration_mode="$2"
-            shift
+            crewai_integration_mode="${remaining_args[0]}"
+            remaining_args=("${remaining_args[@]:1}")
+            ;;
+        ap_[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])
+            hosted_agent_id="$arg"
             ;;
         *)
-            FORWARD_ARGS+=("$1")
+            FORWARD_ARGS+=("$arg")
             ;;
     esac
-    shift
 done
 
+if [[ -n "${APORT_HOSTED_AGENT_ID_CLI:-}" ]]; then
+    hosted_agent_id="$APORT_HOSTED_AGENT_ID_CLI"
+fi
+
 case "$crewai_integration_mode" in
     compat | native) ;;
     *)
@@ -65,6 +82,75 @@ resolve_next_steps_file() {
     echo "$FRAMEWORKS_DIR/next-steps.d/$framework.txt"
 }
 
+_yaml_quote() {
+    local value="${1//\'/\'\'}"
+    printf "'%s'" "$value"
+}
+
+_config_replace_or_append() {
+    local file="$1"
+    local key="$2"
+    local value="$3"
+    local tmpfile
+
+    tmpfile="$(mktemp "${file}.XXXXXX")"
+    awk -v key="$key" -v value="$value" '
+        BEGIN { done = 0 }
+        $0 ~ "^[[:space:]]*" key ":" {
+            if (!done) {
+                print key ": " value
+                done = 1
+            }
+            next
+        }
+        { print }
+        END {
+            if (!done) {
+                print key ": " value
+            }
+        }
+    ' "$file" > "$tmpfile" && mv "$tmpfile" "$file"
+}
+
+_config_remove_key() {
+    local file="$1"
+    local key="$2"
+    local tmpfile
+
+    tmpfile="$(mktemp "${file}.XXXXXX")"
+    awk -v key="$key" '$0 !~ "^[[:space:]]*" key ":" { print }' "$file" > "$tmpfile" && mv "$tmpfile" "$file"
+}
+
+persist_python_framework_config() {
+    local config_file="$1"
+    local selected_mode="$2"
+    local selected_api_url="$3"
+    local hosted_id="$4"
+    local local_passport_path="$5"
+
+    touch "$config_file"
+    _config_replace_or_append "$config_file" "framework" "$(_yaml_quote "$framework")"
+    _config_replace_or_append "$config_file" "mode" "$selected_mode"
+
+    if [[ "$selected_mode" == "api" ]]; then
+        _config_replace_or_append "$config_file" "api_url" "$(_yaml_quote "${selected_api_url:-$DEFAULT_APORT_API_URL}")"
+        if [[ -n "$hosted_id" ]]; then
+            _config_replace_or_append "$config_file" "agent_id" "$(_yaml_quote "$hosted_id")"
+            _config_remove_key "$config_file" "passport_path"
+        elif [[ -n "$local_passport_path" ]]; then
+            _config_replace_or_append "$config_file" "passport_path" "$(_yaml_quote "$local_passport_path")"
+            _config_remove_key "$config_file" "agent_id"
+        fi
+    else
+        if [[ -n "$local_passport_path" ]]; then
+            _config_replace_or_append "$config_file" "passport_path" "$(_yaml_quote "$local_passport_path")"
+        fi
+        _config_remove_key "$config_file" "agent_id"
+    fi
+
+    chmod 600 "$config_file" 2> /dev/null || true
+}
+
 run_setup() {
     log_info "Setting up APort guardrails for $framework..."
     config_dir="$(write_config_template "$framework")"
@@ -72,10 +158,15 @@ run_setup() {
     chmod 700 "$config_dir/aport"
     install_runtime_tree "$config_dir"
     export APORT_FRAMEWORK="$framework"
+    if [[ -n "$hosted_agent_id" ]]; then
+        export APORT_AGENT_ID="$hosted_agent_id"
+    fi
     if [[ "$framework" == "crewai" ]]; then
         log_info "CrewAI integration mode: $crewai_integration_mode"
     fi
-    if ((${#FORWARD_ARGS[@]} > 0)); then
+    if [[ -n "$hosted_agent_id" ]]; then
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    elif ((${#FORWARD_ARGS[@]} > 0)); then
         run_passport_wizard "${FORWARD_ARGS[@]}"
     else
         run_passport_wizard
@@ -83,6 +174,27 @@ run_setup() {
     # Harden permissions on passport (contains policy/capabilities)
     [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
     log_info "Local runtime installed at: $config_dir/aport/runtime"
+    select_guardrail_mode "$framework" "$hosted_agent_id"
+    select_guardrail_api_url "$APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        export APORT_API_URL="${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    mode_file="$(write_guardrail_mode_file "$config_dir" "$APORT_SELECTED_GUARDRAIL_MODE" "${APORT_SELECTED_API_URL:-}" "$hosted_agent_id")"
+    local_passport_path=""
+    if [[ -f "$config_dir/aport/passport.json" ]]; then
+        local_passport_path="$config_dir/aport/passport.json"
+    fi
+    persist_python_framework_config \
+        "$config_dir/config.yaml" \
+        "$APORT_SELECTED_GUARDRAIL_MODE" \
+        "${APORT_SELECTED_API_URL:-}" \
+        "$hosted_agent_id" \
+        "$local_passport_path"
+    log_info "Guardrail mode: $APORT_SELECTED_GUARDRAIL_MODE"
+    if [[ "$APORT_SELECTED_GUARDRAIL_MODE" = "api" ]]; then
+        log_info "Guardrail API URL: ${APORT_SELECTED_API_URL:-$DEFAULT_APORT_API_URL}"
+    fi
+    log_info "Mode config: $mode_file"
 
     # Print framework-specific next steps from data file
     next_steps="$(resolve_next_steps_file)"

package/bin/lib/guardrail-mode.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Shared guardrail mode helpers for hook-based integrations (Cursor/Claude Code).
+# Stores runtime mode under <config_dir>/aport/guardrail-mode.env so hooks can
+# select local vs API evaluator consistently across sessions.
+
+DEFAULT_APORT_API_URL="${DEFAULT_APORT_API_URL:-https://api.aport.io}"
+
+parse_guardrail_mode_args() {
+    APORT_GUARDRAIL_MODE_CLI="${APORT_GUARDRAIL_MODE_CLI:-}"
+    APORT_GUARDRAIL_API_URL_CLI="${APORT_GUARDRAIL_API_URL_CLI:-}"
+    APORT_HOSTED_AGENT_ID_CLI="${APORT_HOSTED_AGENT_ID_CLI:-}"
+    APORT_FRAMEWORK_ARGS=()
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --mode=*)
+                APORT_GUARDRAIL_MODE_CLI="${1#--mode=}"
+                ;;
+            --mode)
+                if [[ -z "${2:-}" ]]; then
+                    echo "[aport] ERROR: --mode requires a value (local|api)" >&2
+                    return 1
+                fi
+                APORT_GUARDRAIL_MODE_CLI="$2"
+                shift
+                ;;
+            --api-url=*)
+                APORT_GUARDRAIL_API_URL_CLI="${1#--api-url=}"
+                ;;
+            --api-url)
+                if [[ -z "${2:-}" ]]; then
+                    echo "[aport] ERROR: --api-url requires a value" >&2
+                    return 1
+                fi
+                APORT_GUARDRAIL_API_URL_CLI="$2"
+                shift
+                ;;
+            ap_[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])
+                APORT_HOSTED_AGENT_ID_CLI="$1"
+                ;;
+            *)
+                APORT_FRAMEWORK_ARGS+=("$1")
+                ;;
+        esac
+        shift
+    done
+
+    export APORT_GUARDRAIL_MODE_CLI APORT_GUARDRAIL_API_URL_CLI APORT_HOSTED_AGENT_ID_CLI
+    return 0
+}
+
+select_guardrail_mode() {
+    local framework="$1"
+    local hosted_agent_id="${2:-}"
+    local noninteractive="${APORT_NONINTERACTIVE:-${CI:-}}"
+    local selected_mode="${APORT_GUARDRAIL_MODE_CLI:-${APORT_GUARDRAIL_MODE:-}}"
+
+    if [[ -n "$hosted_agent_id" ]]; then
+        APORT_SELECTED_GUARDRAIL_MODE="api"
+        export APORT_SELECTED_GUARDRAIL_MODE
+        return 0
+    fi
+
+    if [[ -n "$selected_mode" ]]; then
+        selected_mode="$(echo "$selected_mode" | tr '[:upper:]' '[:lower:]')"
+        case "$selected_mode" in
+            local | api) ;;
+            *)
+                echo "[aport] ERROR: Unsupported --mode value: $selected_mode (expected local|api)" >&2
+                return 1
+                ;;
+        esac
+        APORT_SELECTED_GUARDRAIL_MODE="$selected_mode"
+        export APORT_SELECTED_GUARDRAIL_MODE
+        return 0
+    fi
+
+    if [[ -n "$noninteractive" ]]; then
+        # Keep non-interactive deterministic and offline-friendly unless explicitly overridden.
+        APORT_SELECTED_GUARDRAIL_MODE="local"
+        export APORT_SELECTED_GUARDRAIL_MODE
+        return 0
+    fi
+
+    echo ""
+    echo "  Guardrail mode:"
+    echo "    1. local  - Use local evaluator (offline, no network)"
+    echo "    2. api    - Use APort API evaluator"
+    echo ""
+    read -r -p "  Mode [1=local, 2=api]: " mode_choice
+    mode_choice="${mode_choice:-2}"
+    if [[ "$mode_choice" = "2" ]]; then
+        APORT_SELECTED_GUARDRAIL_MODE="api"
+    else
+        APORT_SELECTED_GUARDRAIL_MODE="local"
+    fi
+    export APORT_SELECTED_GUARDRAIL_MODE
+    return 0
+}
+
+select_guardrail_api_url() {
+    local mode="$1"
+    local noninteractive="${APORT_NONINTERACTIVE:-${CI:-}}"
+    local configured_url="${APORT_GUARDRAIL_API_URL_CLI:-${APORT_API_URL:-$DEFAULT_APORT_API_URL}}"
+
+    APORT_SELECTED_API_URL=""
+    if [[ "$mode" != "api" ]]; then
+        export APORT_SELECTED_API_URL
+        return 0
+    fi
+
+    if [[ -n "$noninteractive" ]]; then
+        APORT_SELECTED_API_URL="$configured_url"
+        export APORT_SELECTED_API_URL
+        return 0
+    fi
+
+    read -r -p "  APort API URL [$configured_url]: " api_url_input
+    APORT_SELECTED_API_URL="${api_url_input:-$configured_url}"
+    export APORT_SELECTED_API_URL
+    return 0
+}
+
+write_guardrail_mode_file() {
+    local config_dir="$1"
+    local mode="$2"
+    local api_url="$3"
+    local hosted_agent_id="${4:-}"
+
+    local aport_dir="$config_dir/aport"
+    local mode_file="$aport_dir/guardrail-mode.env"
+    mkdir -p "$aport_dir"
+
+    {
+        echo "APORT_GUARDRAIL_MODE=$mode"
+        if [[ "$mode" = "api" ]]; then
+            echo "APORT_API_URL=${api_url:-$DEFAULT_APORT_API_URL}"
+        fi
+        if [[ -n "$hosted_agent_id" ]]; then
+            echo "APORT_AGENT_ID=$hosted_agent_id"
+        fi
+    } > "$mode_file"
+    chmod 600 "$mode_file" 2> /dev/null || true
+    echo "$mode_file"
+}
+
+load_guardrail_mode_for_hooks() {
+    local config_dir="$1"
+    local mode_file="$config_dir/aport/guardrail-mode.env"
+    if [[ -f "$mode_file" ]]; then
+        # shellcheck disable=SC1090
+        source "$mode_file"
+    fi
+}