@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "gaia-security",
       "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
-      "version": "4.4.0",
+      "version": "4.7.2",
       "source": "./dist/gaia-security"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,15 +1,24 @@
 {
   "name": "gaia-ops",
-  "version": "4.4.0",
+  "version": "4.7.2",
   "description": "Security-first orchestrator with specialized agents, hooks, and governance for AI coding",
   "author": {
     "name": "jaguilar87"
   },
   "repository": "https://github.com/metraton/gaia-ops",
   "license": "MIT",
-  "keywords": ["security", "devops", "orchestrator", "governance"],
+  "keywords": [
+    "security",
+    "devops",
+    "orchestrator",
+    "governance"
+  ],
   "engines": {
     "claude-code": ">=2.1.0"
   },
-  "categories": ["devops", "security", "orchestration"]
+  "categories": [
+    "devops",
+    "security",
+    "orchestration"
+  ]
 }

package/ARCHITECTURE.md

@@ -25,7 +25,8 @@ User request
     v
 user_prompt_submit.py  (UserPromptSubmit hook)
     |  Inject orchestrator identity via ops_identity.py
-    |  Skills loaded on-demand: project-dispatch, agent-response
+    |  Inject surface routing recommendation (deterministic)
+    |  Skills loaded on-demand: agent-response
     v
 Orchestrator dispatches to agent
     |  Routes by surface classification
@@ -49,7 +50,7 @@ subagent_stop.py  (SubagentStop hook)
     v
 Orchestrator processes json:contract (via agent-response skill)
     |  COMPLETE -> summarize to user
-    |  AWAITING_APPROVAL -> get approval -> resume via SendMessage
+    |  REVIEW (with approval_id) -> get approval -> resume via SendMessage
     |  NEEDS_INPUT -> ask user -> resume via SendMessage
     |  BLOCKED -> report blocker
 ```
@@ -170,7 +171,7 @@ Nonce-based T3 approval lifecycle:
 3. BashValidator generates 128-bit nonce via generate_nonce()
 4. write_pending_approval() saves pending-{nonce}.json to .claude/cache/approvals/
 5. Hook returns corrective deny (exit 0) with NONCE:{hex} in message
-6. Agent includes NONCE:{hex} in PENDING_APPROVAL status to orchestrator
+6. Agent includes NONCE:{hex} in REVIEW status to orchestrator
 7. Orchestrator presents plan to user, asks for approval
 8. User approves -> orchestrator resumes agent with "APPROVE:{nonce}"
 9. pre_tool_use.py detects APPROVE: prefix, calls activate_pending_approval()
@@ -182,7 +183,7 @@ Nonce-based T3 approval lifecycle:
 
 Every agent response must end with a `json:contract` block containing `agent_status`. The contract validator (`hooks/modules/agents/contract_validator.py`) enforces:
 
-- **AGENT_STATUS**: PLAN_STATUS (from 6 valid states: COMPLETE, NEEDS_INPUT, REVIEW, AWAITING_APPROVAL, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
+- **AGENT_STATUS**: PLAN_STATUS (from 5 valid states: COMPLETE, NEEDS_INPUT, REVIEW, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
 - **EVIDENCE_REPORT**: required for all valid states. Seven fields: PATTERNS_CHECKED, FILES_CHECKED, COMMANDS_RUN, KEY_OUTPUTS, VERBATIM_OUTPUTS, CROSS_LAYER_IMPACTS, OPEN_GAPS
 - **CONSOLIDATION_REPORT**: required when multi-surface or cross-check. Fields: OWNERSHIP_ASSESSMENT (enum), CONFIRMED_FINDINGS, SUSPECTED_FINDINGS, CONFLICTS, OPEN_GAPS, NEXT_BEST_AGENT
 
@@ -256,12 +257,12 @@ The adapter layer connects Claude Code's hook protocol to gaia-ops business logi
 | **Adapter methods called** | `ClaudeCodeAdapter.format_validation_response()` |
 | **Business logic modules** | None (pure formatting bridge) |
 
-### CP-5: `templates/settings.template.json` / `hooks/hooks.json` -- Hook Configuration
+### CP-5: `hooks/hooks.json` -- Hook Configuration
 
 | Attribute | Value |
 |-----------|-------|
-| **File (npm channel)** | `templates/settings.template.json` -- paths use `.claude/hooks/` prefix |
 | **File (plugin channel)** | `hooks/hooks.json` -- paths use `${CLAUDE_PLUGIN_ROOT}/hooks/` prefix |
+| **File (npm channel)** | `hooks/hooks.json` (symlinked into `.claude/hooks/`) |
 | **What it does** | Maps Claude Code hook events to handler scripts. Defines which events fire which entry points, the tool matchers (Bash, Task, Agent, `*`), and permissions (allow/deny lists). |
 | **Events configured** | PreToolUse (Bash, Task, Agent, SendMessage), PostToolUse, SubagentStop, SessionStart, Stop, TaskCompleted, SubagentStart, UserPromptSubmit (identity injection) |
 
@@ -292,7 +293,7 @@ To add support for a new Claude Code hook event (e.g., a future `PreCompact` eve
 2. **Add adapter method** to `ClaudeCodeAdapter` in `hooks/adapters/claude_code.py` -- implement `adapt_<event_name>(raw: dict) -> <ResultType>` and the corresponding `format_<result>_response()` if a new result type is needed.
 3. **Add extract/format methods** for the event type -- the extract method pulls typed data from the raw payload, the format method builds the CLI response JSON.
 4. **Create hook script entry point** -- a new `hooks/<event_name>.py` file that reads stdin, calls `adapter.parse_event()`, delegates to business logic, and writes the response to stdout.
-5. **Add entry to `hooks/hooks.json`** (plugin channel) and `templates/settings.template.json` (npm channel) mapping the event name to the new script.
+5. **Add entry to `hooks/hooks.json`** mapping the event name to the new script.
 
 **Zero changes to business logic modules required.** The adapter is the only layer that touches CLI-specific JSON.
 
@@ -311,7 +312,7 @@ To support a CLI other than Claude Code (e.g., a hypothetical Cursor or Windsurf
 | File | Purpose |
 |------|---------|
 | `hooks/modules/identity/ops_identity.py` | Orchestrator identity (injected by UserPromptSubmit) |
-| `skills/project-dispatch/SKILL.md` | Agent routing table and dispatch rules (on-demand) |
+| `config/surface-routing.json` | Surface routing config (agent table, signals, dispatch) |
 | `skills/agent-response/SKILL.md` | Contract status handling protocol (on-demand) |
 | `hooks/pre_tool_use.py` | PreToolUse hook entry point |
 | `hooks/subagent_stop.py` | SubagentStop hook entry point |

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to the gaia-ops orchestration system are documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.5.0] - 2026-03-24
+
+### Settings Architecture Redesign + Multi-Cloud Security
+
+Unified approach for permissions across NPM and plugin installation modes. Permissions now live in `settings.local.json` (union merge, preserves user config). `settings.json` contains only hooks.
+
+#### Added
+- **Azure deny rules** — 39 rules covering resource groups, networking, AKS, Key Vault, CosmosDB, Service Bus, and more
+- **Generic wildcard deny rules** — 20 rules that catch all present and future cloud services (`aws * delete-*`, `az * delete`, `gcloud * delete`, etc.)
+- **Indirect execution detection** — Catches `bash -c`, `eval`, `python3 -c`, `node -e`, `ruby -e`, `perl -e` wrappers that bypass regex patterns
+- **Managed settings template** — `templates/managed-settings.template.json` for enterprise deployment via Claude.ai Admin Console
+- **`updateLocalPermissions()`** in `gaia-update.js` — NPM postinstall now merges permissions into `settings.local.json` (same approach as plugin SessionStart)
+- **Plugin mode detection via `plugin.json`** — `plugin_setup.py` and `plugin_mode.py` now read `.claude-plugin/plugin.json` for reliable name/version/mode detection with `--plugin-dir`
+- **First-run welcome message** — `user_prompt_submit.py` detects first run and injects a welcome explaining that restart is needed to activate permissions
+
+#### Changed
+- **`settings.template.json`** — Removed permissions block; template now contains only hooks + environment
+- **`_DENY_RULES` centralized in Python** — Single source of truth in `plugin_setup.py`, shared by both OPS and SECURITY modes
+- **T3 approval flow** — All T3 mutative operations now use native `ask` dialog (both ops and security mode). Nonce workflow removed from direct conversation; kept for subagent use via skills.
+- **`approval_messages.py`** — Simplified T3 block message to minimal data (tier + nonce). Workflow instructions live in skills, not hook messages.
+- **`pre_tool_use.py`** — Simplified: passes through `block_response` from `bash_validator` directly, no more mode-specific branching
+- **`bash_validator.py`** — T3 mutative returns `ask` response directly (no nonce generation, no pending files)
+- **`session_start.py`** — Uses `mark_done=False` so `user_prompt_submit.py` can detect first-run and show welcome before marking initialized
+- **`gaia-update.js` registry path** — Fixed to write `plugin-registry.json` in `.claude/` (same path Python hooks expect)
+- **`gaia-doctor.js`** — Now checks permissions in `settings.local.json` (not just `settings.json`). Updated agent and config file lists.
+- **`gaia-update.js` health check** — Updated config files (`surface-routing.json`) and agent list (`gaia-system.md`, `speckit-planner.md`)
+
+#### Fixed
+- **Registry path mismatch** — `gaia-update.js` wrote to `.claude/project-context/`, Python read from `.claude/`. Now both use `.claude/`.
+- **Orphaned nonce files** — `bash_validator` no longer writes pending approval files for `ask` responses
+- **Plugin mode detection** — `--plugin-dir` now correctly detects `gaia-ops` vs `gaia-security` via `plugin.json` instead of path parsing
+- **First-run welcome race condition** — `SessionStart` no longer marks initialized; `UserPromptSubmit` marks after showing welcome
+- **`_build_welcome()` framing** — Rewritten to explain WHY the user needs to restart (permissions not active yet), making Claude naturally relay the message
+
 ## [4.4.0-rc.5] - 2026-03-19
 
 ### Identity Redesign

package/README.md

@@ -14,14 +14,17 @@ Multi-agent DevOps system that classifies every operation by risk, routes work t
 
 ### Features
 
-- **Multi-cloud support** - GCP, AWS
-- **6 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, devops-developer, speckit-planner, gaia (meta-agent)
+- **Multi-cloud support** - GCP, AWS, Azure
+- **6 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, devops-developer, speckit-planner, gaia-system (meta-agent)
 - **Contracts as SSOT** - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)
 - **Dynamic identity** - Orchestrator identity injected by UserPromptSubmit hook; skills loaded on-demand
-- **Approval gates** for T3 operations via nonce-based workflow
+- **Dual-barrier security** - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)
+- **Indirect execution detection** - Catches `bash -c`, `eval`, `python -c` wrappers that bypass regex patterns
+- **Approval gates** for T3 operations via native `ask` dialog
 - **Git commit validation** with Conventional Commits
-- **20 skills** - Injected procedural knowledge modules for agents
+- **21 skills** - Injected procedural knowledge modules for agents
 - **Plugin + npm** - Distributable as Claude Code native plugin or npm package
+- **Enterprise ready** - Managed settings template for organization-wide deployment
 
 ## Installation
 
@@ -56,12 +59,24 @@ gaia-scan
 
 This will:
 1. Auto-detect your project structure (GitOps, Terraform, AppServices)
-2. Install Claude Code if not present
-3. Create `.claude/` directory with symlinks to this package
-4. Generate `project-context.json` and `settings.json`
+2. Create `.claude/` directory with symlinks to this package
+3. Generate `project-context.json`
+4. Create `settings.json` with hooks only (no permissions in settings.json)
+5. Merge deny rules + allow permissions into `settings.local.json` (preserves existing user config)
 
 No `CLAUDE.md` is generated -- orchestrator identity is injected dynamically by the UserPromptSubmit hook.
 
+### Settings Architecture
+
+Gaia-Ops separates hooks from permissions:
+
+| File | Content | Strategy |
+|------|---------|----------|
+| `settings.json` | Hooks only (9 hook types) | Overwritten from template on each update |
+| `settings.local.json` | Permissions (allow + deny rules) | Union merge — never removes user config |
+
+This ensures your personal customizations (MCP servers, extra permissions) survive updates.
+
 ### Manual Installation
 
 ```bash
@@ -100,17 +115,34 @@ npx gaia-skills-diagnose
 npx gaia-skills-diagnose --run-tests
 ```
 
+## Security
+
+Gaia-Ops enforces a 6-layer security pipeline:
+
+| Layer | Mechanism | Bypassable? |
+|-------|-----------|-------------|
+| Indirect execution detection | `bash -c`, `eval`, `python -c` wrappers | No (hook-level) |
+| Blocked commands (regex) | 85+ regex patterns | No (symlink to npm package) |
+| Blocked commands (semantic) | 70+ ordered-token rules | No (symlink to npm package) |
+| Cloud pipe validator | Credential piping detection | No (hook-level) |
+| Mutative verb detection | `ask` dialog for state-changing ops | User approves via native dialog |
+| Settings deny rules | 147 deny rules in `settings.local.json` | Self-healing (restored each session) |
+
+### Enterprise Deployment
+
+For organization-wide enforcement, deploy `templates/managed-settings.template.json` as a managed settings policy via Claude.ai Admin Console. Managed settings have the highest precedence and cannot be overridden.
+
 ## Project Structure
 
 ```
 node_modules/@jaguilar87/gaia-ops/
 ├── agents/              # Agent definitions (6 agents)
-├── skills/              # Skill modules (20 skills)
+├── skills/              # Skill modules (21 skills)
 ├── tools/               # Orchestration tools
 ├── hooks/               # Claude Code hooks (modular architecture)
 ├── commands/            # Slash commands (5 speckit + scan-project)
 ├── config/              # Configuration (contracts, git standards, rules)
-├── templates/           # Installation templates (settings, governance)
+├── templates/           # Installation templates (settings, governance, managed-settings)
 ├── speckit/             # Spec-Kit framework (templates)
 ├── bin/                 # CLI utilities (11 scripts)
 └── tests/               # Test suite
@@ -133,7 +165,7 @@ This package follows [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features
 - **PATCH:** Bug fixes
 
-Current version: **4.4.0-rc.5**
+Current version: **4.5.0**
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
@@ -169,7 +201,7 @@ git clone git@bitbucket.org:yourorg/your-project-context.git project-context
 
 - **Issues:** [GitHub Issues](https://github.com/metraton/gaia-ops/issues)
 - **Repository:** [github.com/metraton/gaia-ops](https://github.com/metraton/gaia-ops)
-- **Author:** Jorge Aguilar <jaguilar1897@gmail.com>
+- **Author:** Jorge Aguilar <jorge.aguilar88@gmail.com>
 
 ## License
 

package/agents/terraform-architect.md

@@ -19,7 +19,7 @@ skills:
 
 1. **Triage first**: When checking infrastructure state, run the fast-queries Terraform or cloud triage script before running plan/apply.
 2. **Deep analysis**: When investigating drift or complex module dependencies, follow the investigation phases.
-3. **Before T3 operations**: When `terragrunt apply` is needed, present a REVIEW plan first. If a hook blocks it, follow the AWAITING_APPROVAL flow.
+3. **Before T3 operations**: When `terragrunt apply` is needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
 4. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
 
 ## Identity

package/bin/README.md

@@ -27,7 +27,7 @@ Configure symlinks  Remove files
 | Script | Description |
 |--------|-------------|
 | `gaia-scan` | Project scanner and installer (Python) |
-| `gaia-update.js` | Configuration updater (postinstall hook) |
+| `gaia-update.js` | Configuration updater (postinstall hook) — updates hooks template, merges permissions into settings.local.json, ensures plugin-registry |
 
 ### Diagnostics and Monitoring
 
@@ -146,4 +146,4 @@ npx gaia-scan --non-interactive
 
 ---
 
-**Version:** 4.4.0-rc.5 | **Updated:** 2026-03-19 | **Scripts:** 11
+**Version:** 4.5.0 | **Updated:** 2026-03-24 | **Scripts:** 11

package/bin/gaia-doctor.js

@@ -102,17 +102,30 @@ async function checkSettingsJson() {
       if (!hookTypes.includes('PostToolUse')) issues.push('Missing PostToolUse hook');
     }
 
-    // Check permissions exist
-    if (!data.permissions) {
-      issues.push('No permissions configured');
+    // Check permissions — now live in settings.local.json (not settings.json)
+    const localPath = join(CWD, '.claude', 'settings.local.json');
+    let permCount = 0;
+    if (existsSync(localPath)) {
+      try {
+        const localData = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+        if (localData.permissions) {
+          permCount = Object.values(localData.permissions).flat().length;
+        }
+      } catch { /* ignore parse errors */ }
+    }
+    // Also count permissions in settings.json (legacy installs)
+    if (data.permissions) {
+      permCount += Object.values(data.permissions).flat().length;
+    }
+    if (permCount === 0) {
+      issues.push('No permissions configured (check settings.local.json)');
     }
 
     if (issues.length > 0) {
-      return { name: 'settings.json', ok: false, detail: issues.join('; '), fix: 'Run gaia-scan' };
+      return { name: 'settings.json', ok: false, detail: issues.join('; '), fix: 'Run gaia-scan or npx gaia-update' };
     }
 
     const hookCount = data.hooks ? Object.keys(data.hooks).length : 0;
-    const permCount = data.permissions ? Object.values(data.permissions).flat().length : 0;
     return { name: 'settings.json', ok: true, detail: `${hookCount} hook types, ${permCount} rules` };
   } catch {
     return { name: 'settings.json', ok: false, detail: 'Invalid JSON', fix: 'Delete and run gaia-scan' };

package/bin/gaia-history.js

@@ -125,7 +125,6 @@ function colorStatus(status) {
   if (s === 'NEEDS_INPUT') return chalk.yellow(s.padEnd(8));
   if (s === 'IN_PROGRESS') return chalk.cyan(s.padEnd(8));
   if (s === 'REVIEW') return chalk.magenta(s.padEnd(8));
-  if (s === 'AWAITING_APPROVAL') return chalk.yellow(s.padEnd(8));
   return chalk.gray(s.padEnd(8));
 }
 

package/bin/gaia-metrics.js

@@ -450,7 +450,7 @@ function calculateAgentInvocations(workflowMetrics) {
 
 /**
  * Agent outcome distribution from plan_status field.
- * Counts COMPLETE, BLOCKED, NEEDS_INPUT, IN_PROGRESS, REVIEW, AWAITING_APPROVAL, and others.
+ * Counts COMPLETE, BLOCKED, NEEDS_INPUT, IN_PROGRESS, REVIEW, and others.
  * Returns null if no entries have the plan_status field (older data).
  */
 function calculateAgentOutcomes(workflowMetrics) {
@@ -874,7 +874,7 @@ function displayMetrics(
   // ── Agent Outcomes ───────────────────────────────────
   if (agentOutcomes) {
     console.log(chalk.bold(`\n📋 Agent Outcomes  (${agentOutcomes.total} sessions with status)`));
-    const outcomeColor = { COMPLETE: chalk.green, BLOCKED: chalk.red, NEEDS_INPUT: chalk.yellow, IN_PROGRESS: chalk.cyan, REVIEW: chalk.magenta, AWAITING_APPROVAL: chalk.yellow };
+    const outcomeColor = { COMPLETE: chalk.green, BLOCKED: chalk.red, NEEDS_INPUT: chalk.yellow, IN_PROGRESS: chalk.cyan, REVIEW: chalk.magenta };
     for (const { status, count, percentage } of agentOutcomes.distribution) {
       const bar = makeBar(percentage, 10);
       const pct = percentage.toFixed(1).padStart(5);

package/bin/gaia-scan.py

@@ -205,6 +205,7 @@ def _mode_fresh(project_root: Path, scan_config: ScanConfig, args) -> int:
         generate_governance,
         generate_project_context,
         install_git_hooks,
+        merge_hooks_to_settings_local,
     )
     from tools.scan.ui import (
         RailUI,
@@ -238,11 +239,15 @@ def _mode_fresh(project_root: Path, scan_config: ScanConfig, args) -> int:
 
     # Step 4: INSTALL (automatic, no prompts)
     skip_claude = getattr(args, "skip_claude_install", False)
+    npm_postinstall = getattr(args, "npm_postinstall", False)
     ensure_claude_code(skip_install=skip_claude)
-    ensure_gaia_ops_package(project_root)
+    if not npm_postinstall:
+        # Skip when called from npm postinstall to avoid re-entrance
+        ensure_gaia_ops_package(project_root)
     create_claude_directory(project_root)
     copy_claude_md(project_root)
     copy_settings_json(project_root)
+    merge_hooks_to_settings_local(project_root)
     install_git_hooks(project_root)
     generate_project_context(project_root, config, scan_context=output.context)
     generate_governance(project_root, config)
@@ -284,6 +289,7 @@ def _mode_existing(project_root: Path, scan_config: ScanConfig, args) -> int:
         copy_settings_json,
         create_claude_directory,
         install_git_hooks,
+        merge_hooks_to_settings_local,
     )
     from tools.scan.ui import (
         RailUI,
@@ -314,6 +320,7 @@ def _mode_existing(project_root: Path, scan_config: ScanConfig, args) -> int:
     # Step 4: SYNC
     copy_claude_md(project_root)
     copy_settings_json(project_root)
+    merge_hooks_to_settings_local(project_root)
     create_claude_directory(project_root)
     install_git_hooks(project_root)
 
@@ -496,6 +503,13 @@ def main(argv: list = None) -> int:
         dest="skip_claude_install",
         help="Skip Claude Code CLI installation",
     )
+    parser.add_argument(
+        "--npm-postinstall",
+        action="store_true",
+        default=False,
+        dest="npm_postinstall",
+        help="Called from npm postinstall: skip Claude Code install and npm package install to avoid re-entrance",
+    )
 
     args = parser.parse_args(argv)
 
@@ -544,11 +558,19 @@ def main(argv: list = None) -> int:
                 print(json.dumps(result), file=sys.stdout)
                 return 0
 
+        # --npm-postinstall implies --skip-claude-install and skips ensure_gaia_ops_package
+        if args.npm_postinstall:
+            args.skip_claude_install = True
+
         # Mode selection
         # --json or --scan-only: scan-only mode
         if args.json or args.scan_only:
             return _mode_scan_only(project_root, scan_config, args)
 
+        # --npm-postinstall: fresh install mode with re-entrance protection
+        if args.npm_postinstall:
+            return _mode_fresh(project_root, scan_config, args)
+
         # Detect mode based on .claude/ existence
         claude_dir = project_root / ".claude"
         if claude_dir.is_dir():