@connexum/ai-governance 1.0.0-beta.11

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "@connexum/ai-governance",
+  "version": "1.0.0-beta.11",
+  "description": "Enterprise AI agent governance framework. Hook-based enforcement, compliance packs (SOC 2, HIPAA, GDPR, PCI DSS, DORA, EU AI Act, ISO 27001), audit trails, multi-LLM adapter architecture (Claude production today; additional providers on roadmap).",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/esm/llm-adapters/exports.js",
+      "require": "./dist/llm-adapters/exports.js",
+      "types": "./dist/llm-adapters/exports.d.ts"
+    },
+    "./hooks/*": "./src/hooks/*",
+    "./orchestrators": {
+      "import": "./dist/esm/orchestrator-adapters/exports.js",
+      "require": "./dist/orchestrator-adapters/exports.js",
+      "types": "./dist/orchestrator-adapters/exports.d.ts"
+    },
+    "./ide": {
+      "import": "./dist/esm/ide-adapters/exports.js",
+      "require": "./dist/ide-adapters/exports.js",
+      "types": "./dist/ide-adapters/exports.d.ts"
+    },
+    "./retention": {
+      "import": "./dist/esm/retention/index.js",
+      "require": "./dist/retention/index.js",
+      "types": "./dist/retention/index.d.ts"
+    },
+    "./reporting": {
+      "import": "./dist/esm/audit/reporting-exports.js",
+      "require": "./dist/audit/reporting-exports.js",
+      "types": "./dist/audit/reporting-exports.d.ts"
+    },
+    "./tenant": {
+      "import": "./dist/esm/tenant/index.js",
+      "require": "./dist/tenant/index.js",
+      "types": "./dist/tenant/index.d.ts"
+    }
+  },
+  "bin": {
+    "ai-governance": "dist/cli/index.js"
+  },
+  "scripts": {
+    "prebuild": "npm run build --workspace @connexum/database --if-present && npm run build --workspace @connexum/auth --if-present && npm run build --workspace @connexum/mcp-server-trust --if-present && npm run build --workspace @connexum/trust-api --if-present",
+    "build": "tsc && tsc -p tsconfig.esm.json",
+    "postbuild": "node scripts/copy-hooks.mjs && node scripts/copy-shim-templates.mjs && node scripts/fix-esm-imports.mjs",
+    "build:cjs": "tsc",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:whitepaper": "node scripts/build-whitepaper.mjs",
+    "test": "npx tsx --test tests/*.test.ts tests/**/*.test.ts",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "node scripts/snapshot-vault-public-keys.mjs && npm run build",
+    "start": "node server.mjs",
+    "start:api": "ENABLE_API=true node server.mjs",
+    "benchmark": "node scripts/run-benchmarks.mjs --output bench-results.json",
+    "benchmark:compare": "node .github/benchmarks/compare.mjs --baseline .github/benchmarks/baseline.json --current bench-results.json",
+    "verify-claims": "node scripts/verify-claims.mjs",
+    "check-plan-drift": "node scripts/check-plan-drift.mjs",
+    "check-step-0": "node scripts/check-step-0-evidence.mjs",
+    "migrate": "node scripts/migrate.mjs",
+    "migrate:prisma": "node scripts/migrate.mjs prisma",
+    "migrate:trust": "node scripts/migrate.mjs trust",
+    "migrate:verify": "node scripts/migrate.mjs verify",
+    "demo:start": "DEMO_SEED_ENABLED=true npm run start",
+    "demo:seed": "node scripts/dev-seed-demo-data.mjs"
+  },
+  "files": [
+    "dist/",
+    "src/hooks/*.sh",
+    "src/hooks/powershell/*.ps1"
+  ],
+  "keywords": [
+    "ai-governance",
+    "ai-agents",
+    "compliance",
+    "security",
+    "hooks",
+    "audit",
+    "enterprise",
+    "soc2",
+    "hipaa",
+    "gdpr",
+    "pci-dss",
+    "dora",
+    "eu-ai-act",
+    "iso-27001",
+    "claude",
+    "openai",
+    "llm-governance"
+  ],
+  "author": "Connexum Network Inc.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://my-cc.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/glasgowlad/AI-Agents-GS.git"
+  },
+  "bugs": {
+    "url": "https://github.com/glasgowlad/AI-Agents-GS/issues"
+  },
+  "workspaces": [
+    "packages/governance-server",
+    "packages/governance-proxy",
+    "packages/auth",
+    "packages/database",
+    "packages/license-server",
+    "packages/python-sdk",
+    "packages/typescript-sdk",
+    "packages/endpoint-scanner",
+    "packages/browser-extension",
+    "packages/trust-api",
+    "packages/connector-sdk",
+    "packages/admin-dashboard",
+    "packages/mcp-server-trust",
+    "packages/compliance-agent-runtime"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "c8": "^11.0.0",
+    "ioredis-mock": "^8.13.1",
+    "puppeteer": "^24.42.0",
+    "tsx": "^4.22.0",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "@connexum/trust-api": "*",
+    "@types/ioredis": "^4.28.10",
+    "ioredis": "^5.10.1",
+    "pg": "^8.20.0"
+  }
+}

package/src/hooks/audit-dir-picker.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# audit-dir-picker.sh -- Vendor-neutral audit directory selection.
+#
+# Source this file then call pick_audit_dir; the picked path is
+# echoed to stdout. Caller captures it:
+#   AUDIT_DIR=$(pick_audit_dir)
+#
+# Selection order (highest to lowest priority):
+#   1. CXNI_AUDIT_DIR env var (operator override; always wins).
+#   2. Active-IDE detection: scan CWD for IDE marker dirs in
+#      preference order. First match wins. Each maps to its
+#      conventional dir under the IDE namespace.
+#        .claude/    -> .claude/governance/audit/    (Claude Code)
+#        .cursor/    -> .cursor/governance/audit/    (Cursor)
+#        .continue/  -> .continue/governance/audit/  (Continue)
+#        .cody/      -> .cody/governance/audit/      (Sourcegraph Cody)
+#        .aider/     -> .aider/governance/audit/     (Aider)
+#        .gemini/    -> .gemini/governance/audit/    (Gemini Code Assist)
+#   3. Vendor-neutral fallback: .governance/audit/
+#   4. Legacy alias: GOVERNANCE/audit/ (only if it already exists,
+#      so existing customers do not lose their history; new installs
+#      never get this).
+#
+# F-NEW-CRIT-39g foundation: closes the Claude-Code-specific lock-in
+# in audit-logger.sh / file-boundary-guard.sh / destructive-command-
+# guard.sh so non-Claude IDEs can install governance without a
+# stray .claude/ dir polluting their project.
+#
+# @connexum/ai-governance F-NEW-CRIT-39g
+
+# IDE marker dirs in preference order. First match in CWD wins.
+# Order rationale: Claude Code first because it is the most-deployed
+# adapter today; the rest in alphabetical order so the choice is
+# predictable when multiple IDE markers are present.
+_CXNI_IDE_MARKERS=(
+  ".claude"
+  ".cursor"
+  ".continue"
+  ".cody"
+  ".aider"
+  ".gemini"
+)
+
+pick_audit_dir() {
+  # 1. Operator override.
+  if [ -n "${CXNI_AUDIT_DIR:-}" ]; then
+    printf '%s\n' "$CXNI_AUDIT_DIR"
+    return 0
+  fi
+
+  # 2. Active-IDE detection.
+  local marker
+  for marker in "${_CXNI_IDE_MARKERS[@]}"; do
+    if [ -d "$marker" ]; then
+      printf '%s/governance/audit\n' "$marker"
+      return 0
+    fi
+  done
+
+  # 4. Legacy alias: only if it already has content. Prevents new
+  # installs from creating GOVERNANCE/ while letting existing customers
+  # keep writing to it.
+  if [ -d "GOVERNANCE/audit" ]; then
+    printf 'GOVERNANCE/audit\n'
+    return 0
+  fi
+
+  # 3. Vendor-neutral fallback.
+  printf '.governance/audit\n'
+}

package/src/hooks/audit-logger.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+# audit-logger.sh -- PostToolUse hook
+# Logs every tool call to a structured audit log.
+# Never blocks (always exits 0). Audit trail for compliance.
+#
+# Part of @connexum/ai-governance
+
+# AIAG-019: use -e so silent failures in audit-pipeline commands surface
+# as a nonzero exit rather than corrupting the log. PostToolUse hooks
+# still should not block a tool that has already run, so the final
+# `exit 0` at the bottom is preserved and failing sub-commands are
+# guarded with `|| true` where best-effort is correct.
+set -euo pipefail
+
+INPUT=$(cat)
+
+# AIAG-018: enforce 1MB input size limit (matches hook-utils.sh MAX_INPUT_BYTES)
+if [ "${#INPUT}" -gt 1048576 ]; then
+  echo "BLOCKED: Hook input exceeds 1MB (${#INPUT} bytes). Possible injection attempt." >&2
+  exit 0  # PostToolUse hook: never block the tool itself, just skip logging.
+fi
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+
+# F-NEW-CRIT-38b: Claude Code does not pass .agent_name in the hook
+# payload. Read it from the payload first (legacy / synthesized callers
+# still work), then fall back to CXNI_AGENT_NAME env var (operator
+# pins identity per session), then to "unknown" as the safe default.
+AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // empty' 2>/dev/null || true)
+if [ -z "$AGENT_NAME" ]; then
+  AGENT_NAME="${CXNI_AGENT_NAME:-unknown}"
+fi
+
+# F-NEW-CRIT-39a: capture user identity for the regulator-grade audit
+# trail. Same operator-knob pattern as CXNI_AGENT_NAME: payload field
+# first (synthesized callers), then CXNI_USER_ID env var (operator
+# pins identity per session), then "unknown" safe default. The
+# regulator answer to "who did what when" requires this field.
+USER_ID=$(echo "$INPUT" | jq -r '.user_id // empty' 2>/dev/null || true)
+if [ -z "$USER_ID" ]; then
+  USER_ID="${CXNI_USER_ID:-unknown}"
+fi
+
+# F-NEW-CRIT-39b: capture LLM model for the regulator-grade audit trail.
+# Same operator-knob pattern: payload field first, then CXNI_LLM_MODEL
+# env var (operator pins per session), then "unknown" safe default.
+# The regulator answer to "which model was used" requires this field.
+LLM_MODEL=$(echo "$INPUT" | jq -r '.llm_model // empty' 2>/dev/null || true)
+if [ -z "$LLM_MODEL" ]; then
+  LLM_MODEL="${CXNI_LLM_MODEL:-unknown}"
+fi
+
+TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input // {}' 2>/dev/null || echo "{}")
+TOOL_RESULT=$(echo "$INPUT" | jq -r '.tool_result // ""' 2>/dev/null | head -c 200 || echo "")
+
+# F-NEW-CRIT-39d: capture truncated full tool input + tool response
+# for the regulator-grade audit trail. The 100-char `target` summary
+# alone is insufficient for "what data did the agent process."
+#
+# Truncation policy:
+# - inputCapture / responseCapture: max 1024 bytes (UTF-8 safe via jq's
+#   .[0:1024]). Truncated values are appended with "...truncated" so
+#   readers know the value is partial.
+# - inputBytes / responseBytes: original byte count of the JSON-stringified
+#   value (so reviewers can see truncation occurred).
+# - scrubbed: false. This hook does NOT scrub secrets inline. Customers
+#   relying on regulator-grade non-leaked audit logs MUST configure
+#   secret-leak-scanner (PreToolUse, blocks at the source) AND/OR a
+#   downstream redaction layer. Documenting the scrubbed=false flag
+#   makes the layered design explicit so a regulator review knows
+#   what guarantee the field carries.
+INPUT_JSON=$(echo "$INPUT" | jq -c '.tool_input // null' 2>/dev/null || echo "null")
+RESPONSE_JSON=$(echo "$INPUT" | jq -c '.tool_response // null' 2>/dev/null || echo "null")
+
+INPUT_BYTES=${#INPUT_JSON}
+RESPONSE_BYTES=${#RESPONSE_JSON}
+
+if [ "$INPUT_JSON" = "null" ]; then
+  INPUT_CAPTURE_JSON='null'
+  INPUT_BYTES=0
+elif [ "$INPUT_BYTES" -gt 1024 ]; then
+  TRUNCATED=$(printf '%s' "$INPUT_JSON" | head -c 1024)
+  INPUT_CAPTURE_JSON=$(jq -nc --arg s "${TRUNCATED}...truncated" '$s' 2>/dev/null || echo '"...truncate-error"')
+else
+  INPUT_CAPTURE_JSON=$(jq -nc --arg s "$INPUT_JSON" '$s' 2>/dev/null || echo '"...stringify-error"')
+fi
+
+if [ "$RESPONSE_JSON" = "null" ]; then
+  RESPONSE_CAPTURE_JSON='null'
+  RESPONSE_BYTES=0
+elif [ "$RESPONSE_BYTES" -gt 1024 ]; then
+  TRUNCATED=$(printf '%s' "$RESPONSE_JSON" | head -c 1024)
+  RESPONSE_CAPTURE_JSON=$(jq -nc --arg s "${TRUNCATED}...truncated" '$s' 2>/dev/null || echo '"...truncate-error"')
+else
+  RESPONSE_CAPTURE_JSON=$(jq -nc --arg s "$RESPONSE_JSON" '$s' 2>/dev/null || echo '"...stringify-error"')
+fi
+
+# F-NEW-CRIT-39d-2: inline secret scrubber for inputCapture / responseCapture.
+# CRIT-39d shipped scrubbed=false flag as caller documentation. This block
+# closes the leak surface: any matched secret span is replaced with
+# [REDACTED:type] before the entry is written. When any redaction happens
+# SCRUBBED is flipped to "true" and the entry's scrubbed key reflects it.
+#
+# Operator opt-out: CXNI_AUDIT_NO_SCRUB=true preserves verbatim capture
+# (forensic / offline-redaction workflows).
+#
+# Pattern set mirrors src/hooks/secret-leak-scanner.sh:
+#   AKIA[0-9A-Z]{16}                      -> [REDACTED:aws-key]
+#   eyJ...eyJ...sig 3-segment JWT         -> [REDACTED:jwt]
+#   -----BEGIN ... PRIVATE KEY----- block -> [REDACTED:private-key]
+#
+# `sed -E` for portability (POSIX ERE supported on GNU + BusyBox).
+SCRUBBED="false"
+# Scrub via direct in-shell parameter expansion + sed pipes. Function
+# would run in a subshell ($()), losing the SCRUBBED state, so the
+# logic stays inline here.
+if [ "${CXNI_AUDIT_NO_SCRUB:-}" != "true" ]; then
+  INPUT_BEFORE="$INPUT_CAPTURE_JSON"
+  RESPONSE_BEFORE="$RESPONSE_CAPTURE_JSON"
+  INPUT_CAPTURE_JSON=$(printf '%s' "$INPUT_CAPTURE_JSON" \
+    | sed -E 's/AKIA[0-9A-Z]{16}/[REDACTED:aws-key]/g' \
+    | sed -E 's/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/[REDACTED:jwt]/g' \
+    | sed -E 's/-----BEGIN[^-]{0,30}PRIVATE KEY-----[^"]*-----END[^-]{0,30}PRIVATE KEY-----/[REDACTED:private-key]/g' \
+    | sed -E 's/-----BEGIN[^-]{0,30}PRIVATE KEY-----[^"]{0,2000}/[REDACTED:private-key]/g')
+  RESPONSE_CAPTURE_JSON=$(printf '%s' "$RESPONSE_CAPTURE_JSON" \
+    | sed -E 's/AKIA[0-9A-Z]{16}/[REDACTED:aws-key]/g' \
+    | sed -E 's/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/[REDACTED:jwt]/g' \
+    | sed -E 's/-----BEGIN[^-]{0,30}PRIVATE KEY-----[^"]*-----END[^-]{0,30}PRIVATE KEY-----/[REDACTED:private-key]/g' \
+    | sed -E 's/-----BEGIN[^-]{0,30}PRIVATE KEY-----[^"]{0,2000}/[REDACTED:private-key]/g')
+  if [ "$INPUT_CAPTURE_JSON" != "$INPUT_BEFORE" ] || [ "$RESPONSE_CAPTURE_JSON" != "$RESPONSE_BEFORE" ]; then
+    SCRUBBED="true"
+  fi
+fi
+
+# F-NEW-CRIT-39c: capture tool outcome (success/exitCode/errorSummary)
+# from .tool_response. Three shapes supported:
+#   1. Bash-style: { stdout, stderr, exit_code }   -> success=(exit_code==0)
+#   2. Edit/Write-style: { success: true|false, error?, ... }  -> success direct
+#   3. Absent .tool_response (or string): success=null (cannot determine)
+# The outcome object always exists in the entry so downstream consumers can
+# rely on the key being present.
+HAS_TOOL_RESPONSE=$(echo "$INPUT" | jq -r 'has("tool_response")' 2>/dev/null || echo "false")
+if [ "$HAS_TOOL_RESPONSE" = "true" ]; then
+  OUTCOME_JSON=$(echo "$INPUT" | jq -c '
+    (.tool_response // null) as $tr |
+    if ($tr | type) != "object" then
+      { success: null, exitCode: null, errorSummary: null }
+    elif ($tr | has("exit_code")) then
+      ($tr.exit_code) as $ec |
+      { success: ($ec == 0),
+        exitCode: $ec,
+        errorSummary: (($tr.stderr // "") | tostring | .[0:200] // null) }
+    elif ($tr | has("success")) then
+      { success: $tr.success,
+        exitCode: null,
+        errorSummary: (($tr.error // "") | tostring | .[0:200] // null) }
+    else
+      { success: null, exitCode: null, errorSummary: null }
+    end
+  ' 2>/dev/null || echo '{"success":null,"exitCode":null,"errorSummary":null}')
+else
+  OUTCOME_JSON='{"success":null,"exitCode":null,"errorSummary":null}'
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SESSION_ID="${CXNI_SESSION_ID:-$(date +%s)}"
+
+# F-NEW-CRIT-39g: vendor-neutral audit dir picker. Honors
+# CXNI_AUDIT_DIR override, then detects active IDE marker (.claude,
+# .cursor, .continue, .cody, .aider, .gemini), falls back to
+# .governance/audit/. Old hardcoded ".claude/governance/audit" first-
+# priority loop is gone.
+SCRIPT_DIR_AUDIT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=audit-dir-picker.sh
+source "$SCRIPT_DIR_AUDIT/audit-dir-picker.sh"
+AUDIT_DIR="$(pick_audit_dir)"
+mkdir -p "$AUDIT_DIR" 2>/dev/null || exit 0
+
+AUDIT_FILE="$AUDIT_DIR/audit-$(date -u +%Y-%m-%d).jsonl"
+
+# Extract relevant details based on tool type
+case "$TOOL_NAME" in
+  Edit|Write|NotebookEdit)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.file_path // .path // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  Bash)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.command // "unknown"' 2>/dev/null | head -c 100 || echo "unknown")
+    ;;
+  Read)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.file_path // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  Glob|Grep)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.pattern // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  Agent)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.description // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  WebSearch)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.query // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  WebFetch)
+    TARGET=$(echo "$TOOL_INPUT" | jq -r '.url // "unknown"' 2>/dev/null || echo "unknown")
+    ;;
+  *)
+    TARGET="n/a"
+    ;;
+esac
+
+# Write structured JSONL entry
+# F-NEW-CRIT-38b: use `jq -c` (compact) so each entry is a single line.
+# Without this, jq pretty-prints across multiple lines and the .jsonl
+# file violates the JSON-lines spec (one record per line) - any
+# downstream reader that splits on newlines breaks.
+ENTRY=$(jq -nc \
+  --arg ts "$TIMESTAMP" \
+  --arg sid "$SESSION_ID" \
+  --arg user "$USER_ID" \
+  --arg agent "$AGENT_NAME" \
+  --arg tool "$TOOL_NAME" \
+  --arg target "$TARGET" \
+  --arg llmModel "$LLM_MODEL" \
+  --argjson outcome "$OUTCOME_JSON" \
+  --argjson inputCapture "$INPUT_CAPTURE_JSON" \
+  --argjson responseCapture "$RESPONSE_CAPTURE_JSON" \
+  --argjson inputBytes "$INPUT_BYTES" \
+  --argjson responseBytes "$RESPONSE_BYTES" \
+  --argjson scrubbed "$SCRUBBED" \
+  '{timestamp: $ts, session: $sid, user: $user, agent: $agent, tool: $tool, target: $target, llmModel: $llmModel, outcome: $outcome, inputCapture: $inputCapture, responseCapture: $responseCapture, inputBytes: $inputBytes, responseBytes: $responseBytes, scrubbed: $scrubbed}' 2>/dev/null || echo "")
+
+if [ -n "$ENTRY" ]; then
+  # Pack-driven SHA-256 chained append.
+  # Thomas directive 2026-05-17 evening: "It must start up and report
+  # findings to a local database on the compliance and company packs,
+  # including what they are allowed and not allowed to do. It must have
+  # SHA-256 installed."
+  #
+  # Try the Node-based audit-chain-append first — it merges in the
+  # bound packs' verdict + triggeringPackIds and SHA-256-chains each
+  # entry (previousHash + currentHash) so the local audit trail is
+  # tamper-evident.
+  #
+  # If the helper is missing (e.g. .governance.json absent, runtime not
+  # initialised, or Node not available) fall back to the legacy plain-
+  # JSONL append so the hook never blocks an agent (Invariant 2 advisory).
+  CHAIN_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/cli/audit-chain-append.js"
+  if [ -f "$CHAIN_HELPER" ] && command -v node >/dev/null 2>&1; then
+    node "$CHAIN_HELPER" \
+      --tool="$TOOL_NAME" \
+      --input="${TOOL_INPUT:-{\}}" \
+      --base-entry="$ENTRY" \
+      --audit-file="$AUDIT_FILE" \
+      --cwd="$(pwd)" >/dev/null 2>&1 \
+      || echo "$ENTRY" >> "$AUDIT_FILE" 2>/dev/null
+  else
+    echo "$ENTRY" >> "$AUDIT_FILE" 2>/dev/null
+  fi
+fi
+
+# F-NEW-CUSTOMER-JOURNEY-001 (2026-05-13): best-effort push to gov-server.
+#
+# Pre-fix the hook wrote the JSONL entry locally and stopped there — the
+# gov-server's audit chain never saw a single tool-call signal from any
+# customer's runtime. The credit-agency layer was structurally blind to
+# actual agent behavior; the only events that reached the chain were
+# manual cluster-event POSTs from the SDK that customers had no way to
+# trigger from a hook context.
+#
+# Now: if the project's .governance.json carries a `runtime` block with
+# govServerUrl + orgId + agentId + serviceToken, the hook fires a
+# fire-and-forget curl to POST /api/v1/cluster-events/self-registration
+# with kind=AGENT_TOOL_OBSERVED. The local JSONL file remains the
+# source-of-truth and the safety net — if the push fails (timeout,
+# unreachable, missing config, jq absent) the hook still exits 0 and the
+# tool call is never blocked by us.
+#
+# Auth contract: ServiceToken is a JWT obtained at CLI init time and
+# stored in .governance.json (mode 0600). The /cluster-events route
+# validates the JWT and enforces tenant binding (Invariant 7 — body
+# orgId MUST match the token's `org` claim).
+PROJECT_ROOT=""
+SEARCH_DIR="$AUDIT_DIR"
+while [ "$SEARCH_DIR" != "/" ] && [ -n "$SEARCH_DIR" ]; do
+  if [ -f "$SEARCH_DIR/.governance.json" ]; then
+    PROJECT_ROOT="$SEARCH_DIR"
+    break
+  fi
+  SEARCH_DIR="$(dirname "$SEARCH_DIR")"
+done
+
+if [ -n "$PROJECT_ROOT" ] && command -v jq >/dev/null 2>&1 && command -v curl >/dev/null 2>&1; then
+  GOV_URL="$(jq -r '.runtime.govServerUrl // empty' "$PROJECT_ROOT/.governance.json" 2>/dev/null)"
+  GOV_ORG="$(jq -r '.runtime.orgId // empty' "$PROJECT_ROOT/.governance.json" 2>/dev/null)"
+  GOV_AGENT="$(jq -r '.runtime.agentId // empty' "$PROJECT_ROOT/.governance.json" 2>/dev/null)"
+  GOV_TOKEN="$(jq -r '.runtime.serviceToken // empty' "$PROJECT_ROOT/.governance.json" 2>/dev/null)"
+
+  if [ -n "$GOV_URL" ] && [ -n "$GOV_ORG" ] && [ -n "$GOV_AGENT" ] && [ -n "$GOV_TOKEN" ]; then
+    PUSH_BODY=$(jq -nc \
+      --arg agent "$GOV_AGENT" \
+      --arg org "$GOV_ORG" \
+      --arg tool "${TOOL_NAME:-unknown}" \
+      --arg ts "$TIMESTAMP" \
+      '{
+        kind: "AGENT_TOOL_OBSERVED",
+        agentId: $agent,
+        orgId: $org,
+        tool: $tool,
+        timestamp: $ts,
+        manifest: { agentId: $agent, tools: [$tool] }
+      }' 2>/dev/null)
+    if [ -n "$PUSH_BODY" ]; then
+      curl --silent --show-error --max-time 2 --connect-timeout 1 \
+        --output /dev/null \
+        -X POST "${GOV_URL%/}/api/v1/cluster-events/self-registration" \
+        -H "Authorization: Bearer $GOV_TOKEN" \
+        -H "Content-Type: application/json" \
+        --data "$PUSH_BODY" >/dev/null 2>&1 &
+      # Detach the background curl so this script exits immediately.
+      # The local JSONL row was written above; if the push fails, the
+      # next hook fire or a periodic batch sweep can replay from disk.
+      disown 2>/dev/null || true
+    fi
+  fi
+fi
+
+exit 0

package/src/hooks/cost-budget-gate.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# cost-budget-gate.sh -- PreToolUse hook
+# Blocks LLM calls when agent has exceeded its per-session token budget.
+# Exit code 2 = block. Exit code 0 = allow.
+#
+# Part of @connexum/ai-governance
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# AIAG-018: enforce 1MB input size limit
+if [ "${#INPUT}" -gt 1048576 ]; then
+  echo "BLOCKED: Hook input exceeds 1MB. Possible injection attempt." >&2
+  exit 2
+fi
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# Only gate Agent tool (which spawns LLM calls)
+case "$TOOL_NAME" in
+  Agent) ;;
+  *) exit 0 ;;
+esac
+
+# Check if budget tracking is enabled
+BUDGET_FILE=""
+for candidate in \
+  ".claude/governance/token-budget.json" \
+  ".claude/cost-tracking/budget.json" \
+  "GOVERNANCE/token-budget.json"; do
+  if [ -f "$candidate" ]; then
+    BUDGET_FILE="$candidate"
+    break
+  fi
+done
+
+# F-NEW-MED-18: emit a one-time runtime advisory so the customer SEES
+# that cost-budget-gate is dormant. Without this, an install ships
+# cost-budget-gate.sh wired into Claude Code, the hook returns 0 on
+# every PreToolUse, and the customer believes per-session token / cost
+# limits are enforced when they are not. Same operator-knob pattern as
+# F-NEW-MED-17 (file-boundary-guard advisory). Backward compat: still
+# exit 0.
+if [ -z "$BUDGET_FILE" ]; then
+  if [ -z "${CXNI_BUDGET_NOOP_WARNED:-}" ]; then
+    echo "[CXNI_BUDGET_NOOP] cost-budget-gate is installed but DORMANT: no token-budget.json found. Create one at .claude/governance/token-budget.json with {\"max_session_tokens\": <int>, \"max_session_cost_usd\": <number>} to enable enforcement. Set CXNI_BUDGET_NOOP_WARNED=true in your shell to silence this advisory after acknowledgement." >&2
+  fi
+  exit 0
+fi
+
+# Read budget limits
+MAX_TOKENS=$(jq -r '.max_session_tokens // 0' "$BUDGET_FILE" 2>/dev/null)
+CURRENT_TOKENS=$(jq -r '.current_session_tokens // 0' "$BUDGET_FILE" 2>/dev/null)
+MAX_COST_USD=$(jq -r '.max_session_cost_usd // 0' "$BUDGET_FILE" 2>/dev/null)
+CURRENT_COST_USD=$(jq -r '.current_session_cost_usd // 0' "$BUDGET_FILE" 2>/dev/null)
+
+# Check token budget
+if [ "$MAX_TOKENS" -gt 0 ] 2>/dev/null && [ "$CURRENT_TOKENS" -ge "$MAX_TOKENS" ] 2>/dev/null; then
+  echo "BLOCKED: Token budget exceeded. Used $CURRENT_TOKENS / $MAX_TOKENS tokens this session." >&2
+  echo "Increase budget in $BUDGET_FILE or start a new session." >&2
+  exit 2
+fi
+
+# Check cost budget (compare as strings since bash doesn't do float math well)
+if [ "$MAX_COST_USD" != "0" ] 2>/dev/null; then
+  OVER_BUDGET=$(echo "$CURRENT_COST_USD >= $MAX_COST_USD" | bc -l 2>/dev/null || echo "0")
+  if [ "$OVER_BUDGET" = "1" ]; then
+    echo "BLOCKED: Cost budget exceeded. Spent \$$CURRENT_COST_USD / \$$MAX_COST_USD this session." >&2
+    exit 2
+  fi
+fi
+
+exit 0