[Feature]: Subagent governance gaps — hook enforcement, schema compliance, and installer distribution #604
Description
Summary
The .claude/agents/ subagent files exist in the repository but have three categories of gaps: governance hooks are not registered at runtime, schema compliance issues against Anthropic's official spec, and subagent files are not distributed by the installer.
Problem Statement
1. Governance Hook Not Registered (CRITICAL)
enforce-git-push-authority.sh exists at .claude/hooks/ and is referenced in 10 subagent frontmatters as a PreToolUse hook, but .claude/settings.json does not register any PreToolUse hook. The hook never fires at runtime.
Impact: Agent Authority (Constitution Article II) is enforced only at prompt-level (soft). If an agent ignores prompt instructions, nothing blocks git push. Defense-in-depth has a missing layer.
Verification performed: Spawned aiox-dev subagent and confirmed the hook does NOT fire on Bash commands. Agent refused git push only because of prompt instructions, not runtime enforcement.
2. 19 Agents Missing Hooks
Only the 10 AIOX core agents define the enforce-git-push-authority.sh hook. The 19 other agents (chiefs, design, mind clones, utilities) have permissionMode: bypassPermissions but no hooks, meaning they can execute any Bash command without governance.
3. Schema Compliance Issues
Compared against the official Anthropic schema at https://code.claude.com/docs/pt/sub-agents:
colorfield missing in all 29 agents (cosmetic but part of spec)squad-chief.mdis empty (no frontmatter, no content) — broken agentTasktool listed in 3 subagents (aiox-dev,brad-frost,design-system) but Anthropic docs state "subagents cannot spawn other subagents"
4. Installer Does Not Distribute Subagents
The installer copies agents to .claude/commands/AIOX/agents/ (persona swap / slash commands) but NOT to .claude/agents/ (native Claude Code subagents). Users who install AIOX via npx aiox-core install cannot use workflow engine mode with real subagent spawning.
Proposed Solution
AC1: Register governance hook in settings.json
Add PreToolUse hook to .claude/settings.json referencing enforce-git-push-authority.sh. Hook should fire on ALL Bash commands containing git push, gh pr create, gh pr merge.
AC2: Add hooks to all agents with bypassPermissions
All 19 agents with permissionMode: bypassPermissions that lack hooks should get the enforce-git-push-authority.sh hook added to their frontmatter. Agents without Bash tool access (e.g., pedro-valerio) can be excluded with documented justification.
AC3: Fix schema compliance
- Add
colorfield to all 29 agents - Fix or remove
squad-chief.md(currently empty/broken) - Remove
Tasktool from 3 subagent frontmatters (subagents cannot spawn sub-subagents)
AC4: Include subagents in installer
Update packages/installer/src/config/ide-configs.js and ide-config-generator.js to copy .claude/agents/ files during Claude Code installation. Include files in npm package.
AC5: Add validation test
Create a Jest test that validates all .claude/agents/*.md frontmatter against required schema fields and verifies all bypassPermissions agents have a PreToolUse hook.
Willingness to Contribute
I'm willing to implement this as a PR. I have a detailed story (CONTRIB-2) with file lists, color suggestions, and the exact settings.json configuration needed.
Additional Context
- Related PR: fix: resolve fresh-clone test failure, 236 lint warnings, and dead code #603 (fresh-clone quality fixes — first community contribution)
- Defense-in-depth architecture target: prompt-level → subagent frontmatter hooks → project settings.json hook → git pre-push hook
- Currently only layer 1 (prompt-level) is active
🤖 Generated with Claude Code