[Feature]: Subagent governance gaps — hook enforcement, schema compliance, and installer distribution

[alessandrovarela]

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:

• color field missing in all 29 agents (cosmetic but part of spec)
• squad-chief.md is empty (no frontmatter, no content) — broken agent
• Task tool 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 color field to all 29 agents
• Fix or remove squad-chief.md (currently empty/broken)
• Remove Task tool 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

[github-actions]

Welcome to aiox-core! Thanks for opening your first issue.

What happens next?

• A maintainer will triage this and add appropriate labels
• We'll respond as soon as possible
• Feel free to join Community Discussions

Helpful Resources:

• Contributing Guide
• Documentation

Looking to contribute? Check issues labeled community: good first issue.