fix: enforce native subagent governance

[rafaelscosta]

Summary

• Fixes [Feature]: Subagent governance gaps — hook enforcement, schema compliance, and installer distribution #604 by adding a cross-platform PreToolUse authority hook for remote GitHub operations.
• Normalizes all Claude native subagent frontmatter with supported fields, color metadata, and no Task tool usage.
• Ships native subagents through the installer and registers the authority hook in generated Claude settings.

Validation

• npm test -- packages/installer/tests/unit/artifact-copy-pipeline/artifact-copy-pipeline.test.js tests/claude/subagent-governance.test.js tests/unit/wizard/ide-config-generator.test.js --runInBand
• npm run test:ci
• npm run validate:manifest
• npm run lint -- --quiet
• npm run typecheck
• npm run validate:publish
• git diff --check
• local npm pack + installer smoke for .claude/agents and authority hook registration

Summary by CodeRabbit

• Chores

  • Bumped version from 5.1.4 to 5.1.5.
  • Updated package distribution to include agent configuration files.

• New Features

  • Added Git operation enforcement to restrict sensitive commands to authorized roles.
  • Enhanced agent configurations with visual theming.

• Documentation

  • Added governance documentation for subagent distribution and control.
  • Expanded hook configuration reference guide.

• Tests

  • Added comprehensive test coverage for subagent governance rules and Git enforcement.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aiox-core	Ready	Preview, Comment	May 7, 2026 0:12am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0427ae26-1a21-48d3-848c-65cd1f310c24

📥 Commits

Reviewing files that changed from the base of the PR and between 2dac962 and f88f58d.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (41)

• .aiox-core/install-manifest.yaml
• .claude/agents/aiox-analyst.md
• .claude/agents/aiox-architect.md
• .claude/agents/aiox-data-engineer.md
• .claude/agents/aiox-dev.md
• .claude/agents/aiox-devops.md
• .claude/agents/aiox-pm.md
• .claude/agents/aiox-po.md
• .claude/agents/aiox-qa.md
• .claude/agents/aiox-sm.md
• .claude/agents/aiox-ux.md
• .claude/agents/brad-frost.md
• .claude/agents/copy-chief.md
• .claude/agents/cyber-chief.md
• .claude/agents/dan-mall.md
• .claude/agents/data-chief.md
• .claude/agents/dave-malouf.md
• .claude/agents/db-sage.md
• .claude/agents/design-chief.md
• .claude/agents/design-system.md
• .claude/agents/legal-chief.md
• .claude/agents/nano-banana-generator.md
• .claude/agents/oalanicolas.md
• .claude/agents/pedro-valerio.md
• .claude/agents/sop-extractor.md
• .claude/agents/squad-chief.md
• .claude/agents/squad.md
• .claude/agents/story-chief.md
• .claude/agents/tools-orchestrator.md
• .claude/agents/traffic-masters-chief.md
• .claude/hooks/README.md
• .claude/hooks/enforce-git-push-authority.cjs
• .claude/hooks/enforce-git-push-authority.sh
• .claude/settings.json
• docs/stories/epic-123/STORY-123.7-subagent-governance-distribution.md
• package.json
• packages/installer/src/config/ide-configs.js
• packages/installer/src/wizard/ide-config-generator.js
• packages/installer/tests/unit/artifact-copy-pipeline/artifact-copy-pipeline.test.js
• tests/claude/subagent-governance.test.js
• tests/unit/wizard/ide-config-generator.test.js

---

Walkthrough

This PR implements subagent governance enforcement and distribution for issue #604. It converts the existing Bash enforce-git-push-authority hook to a Node.js implementation, registers it in project settings, updates 29 agent definitions for schema compliance, extends the installer to distribute native agents, and adds comprehensive validation tests.

Changes

Subagent Governance Enforcement Implementation

Layer / File(s)	Summary
Hook Implementation .claude/hooks/enforce-git-push-authority.cjs, .claude/hooks/enforce-git-push-authority.sh	New Node.js CommonJS hook with stdin parsing, remote operation detection (git push, gh pr create, gh pr merge), and active agent checking against DEVOPS_AGENT_ALIASES. Bash wrapper now delegates to Node entry point.
Agent Configuration .claude/agents/*.md (29 files)	Update all agents to reference Node-based hook in PreToolUse Bash matcher; add color field to comply with Anthropic schema; add permissionMode: bypassPermissions and hooks to chief/role agents; remove Task tool from 3 agents (aiox-dev, brad-frost, design-system).
Project Settings & Metadata .claude/settings.json, .claude/hooks/README.md, .aiox-core/install-manifest.yaml, package.json	Register PreToolUse hook in settings with Bash matcher and 10s timeout; document hook in README; bump versions to 5.1.5; include .claude/agents/ in npm package files array.
IDE Configuration packages/installer/src/config/ide-configs.js	Add nativeAgentFolder: '.claude/agents' property to Claude Code IDE config.
Installer & Hook Distribution packages/installer/src/wizard/ide-config-generator.js	Add copyClaudeNativeAgentsFolder(projectRoot) helper to copy agent .md files from framework to project; register hook in HOOK_EVENT_MAP with PreToolUse event, Bash matcher, and 10s timeout; invoke native agent copy during Claude Code IDE setup.
Installer Tests packages/installer/tests/unit/artifact-copy-pipeline/artifact-copy-pipeline.test.js	Update free/pro tier hook expectations to account for both code-intel-pretool.cjs and enforce-git-push-authority.cjs; add HOOK_EVENT_MAP assertion for new hook; extend "covers all known hooks" test to expect 4 entries.
Governance Validation Tests tests/claude/subagent-governance.test.js	New Jest suite validating agent schema (name format, color values, required fields), ensuring non-devops agents with bypassPermissions and Bash tools have the enforcement hook, verifying hook registration in settings.json, and executing hook behavior tests (denies remote ops for non-devops agents, allows for devops).
IDE Config Generator Tests tests/unit/wizard/ide-config-generator.test.js	Add Claude Code IDE test case verifying agent file generation, hook presence, settings.local.json wiring, and HOOK_EVENT_MAP entry.
Documentation docs/stories/epic-123/STORY-123.7-subagent-governance-distribution.md	Story document for issue #604 with context, acceptance criteria (hook registration, hook loading in agents, schema validation, installer distribution, automated tests), tasks, and dev notes.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• SynkraAI/aiox-core#654: Modifies hook-copy and tier-aware registration logic in ide-config-generator.js alongside this PR's native agent copy addition.
• SynkraAI/aiox-core#637: Adds helper exports (generateCodexSkills) to the same ide-config-generator.js file pattern as copyClaudeNativeAgentsFolder.
• SynkraAI/aiox-core#649: Touches installer surface and manifest/package.json versioning alongside this PR's distribution and version bump changes.

Suggested labels

area: agents, area: installer, type: test, area: docs, area: devops

Suggested reviewers

• Pedrovaleriolopez
• oalanicolas

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-604-subagent-governance-20260507

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

---

Generated by PR Automation (Story 6.1)