Agent spawn requirements schema (JSON + hook validation)

forgejo_admin commented

2026-03-07 17:26:10 +00:00

Contributor

Plan

plan-2026-02-26-tf-modularize-postgres -- Phase 7f-2

Repo

forgejo_admin/claude-custom

User Story

As Betty Sue (main session agent)
I want agent spawn requirements defined in a JSON schema validated by the hook
So that adding a new agent type means adding a JSON entry, not editing bash

Context

The check-agent-spawn.sh hook currently uses hardcoded regexes (issue #57 just merged). This works for 4 agent types but doesn't scale. A JSON schema makes the contract between Betty Sue (caller) and agents (callees) explicit, self-documenting, and extensible.

Inspired by data augmentation patterns where inputs and outputs are clearly defined to scope exactly where intelligence is needed. Each agent type has a structured contract: what must be in the prompt, what the agent produces, and whether it runs in isolation.

File Targets

Files to create:

schemas/agent-spawn-requirements.json -- the schema defining required_patterns, description, produces, isolation per agent type

Files to modify:

hooks/check-agent-spawn.sh -- read schema, validate prompt against required_patterns for the given subagent_type. Deny unknown types.

Files NOT to touch:

Agent definition files (agents/*.md)
Other hooks
settings.json

Acceptance Criteria

Schema file exists at schemas/agent-spawn-requirements.json with entries for: dev, qa, general-purpose, Explore
Hook reads schema and validates ALL required_patterns for the given subagent_type
Unknown subagent_type defaults to deny
Dev agent with issue reference passes
QA agent with issue + PR reference passes
General-purpose agent with plan reference passes
Bare prompt with no references denied
Adding a new agent type requires only a JSON entry change

Test Expectations

Manual: echo '{"tool_input":{"prompt":"Fix issue #100","subagent_type":"dev"}}' | bash hooks/check-agent-spawn.sh exits 0
Manual: echo '{"tool_input":{"prompt":"Review PR #101. Issue #100","subagent_type":"qa"}}' | bash hooks/check-agent-spawn.sh exits 0
Manual: echo '{"tool_input":{"prompt":"Update docs. plan-foo","subagent_type":"general-purpose"}}' | bash hooks/check-agent-spawn.sh exits 0
Manual: echo '{"tool_input":{"prompt":"Explore the codebase","subagent_type":"dev"}}' | bash hooks/check-agent-spawn.sh outputs deny JSON
Manual: echo '{"tool_input":{"prompt":"Do stuff","subagent_type":"new-unknown-type"}}' | bash hooks/check-agent-spawn.sh outputs deny JSON

Constraints

Keep it bash + jq — no new dependencies
Schema must be valid JSON parseable by jq
Hook should be ~50 lines max
Backward compatible with existing spawn patterns

Checklist

PR opened
Manual tests pass
No unrelated changes

phase-7f-2-agent-spawn-schema -- phase note
phase-7f-1-deprecate-issue-creator -- prerequisite (issue-gate hook)
agent-spawn-conventions -- convention to update after merge

### Plan `plan-2026-02-26-tf-modularize-postgres` -- Phase 7f-2 ### Repo `forgejo_admin/claude-custom` ### User Story As Betty Sue (main session agent) I want agent spawn requirements defined in a JSON schema validated by the hook So that adding a new agent type means adding a JSON entry, not editing bash ### Context The `check-agent-spawn.sh` hook currently uses hardcoded regexes (issue #57 just merged). This works for 4 agent types but doesn't scale. A JSON schema makes the contract between Betty Sue (caller) and agents (callees) explicit, self-documenting, and extensible. Inspired by data augmentation patterns where inputs and outputs are clearly defined to scope exactly where intelligence is needed. Each agent type has a structured contract: what must be in the prompt, what the agent produces, and whether it runs in isolation. ### File Targets Files to create: - `schemas/agent-spawn-requirements.json` -- the schema defining required_patterns, description, produces, isolation per agent type Files to modify: - `hooks/check-agent-spawn.sh` -- read schema, validate prompt against required_patterns for the given subagent_type. Deny unknown types. Files NOT to touch: - Agent definition files (`agents/*.md`) - Other hooks - settings.json ### Acceptance Criteria - [ ] Schema file exists at `schemas/agent-spawn-requirements.json` with entries for: dev, qa, general-purpose, Explore - [ ] Hook reads schema and validates ALL required_patterns for the given subagent_type - [ ] Unknown subagent_type defaults to deny - [ ] Dev agent with issue reference passes - [ ] QA agent with issue + PR reference passes - [ ] General-purpose agent with plan reference passes - [ ] Bare prompt with no references denied - [ ] Adding a new agent type requires only a JSON entry change ### Test Expectations - [ ] Manual: `echo '{"tool_input":{"prompt":"Fix issue #100","subagent_type":"dev"}}' | bash hooks/check-agent-spawn.sh` exits 0 - [ ] Manual: `echo '{"tool_input":{"prompt":"Review PR #101. Issue #100","subagent_type":"qa"}}' | bash hooks/check-agent-spawn.sh` exits 0 - [ ] Manual: `echo '{"tool_input":{"prompt":"Update docs. plan-foo","subagent_type":"general-purpose"}}' | bash hooks/check-agent-spawn.sh` exits 0 - [ ] Manual: `echo '{"tool_input":{"prompt":"Explore the codebase","subagent_type":"dev"}}' | bash hooks/check-agent-spawn.sh` outputs deny JSON - [ ] Manual: `echo '{"tool_input":{"prompt":"Do stuff","subagent_type":"new-unknown-type"}}' | bash hooks/check-agent-spawn.sh` outputs deny JSON ### Constraints - Keep it bash + jq — no new dependencies - Schema must be valid JSON parseable by jq - Hook should be ~50 lines max - Backward compatible with existing spawn patterns ### Checklist - [ ] PR opened - [ ] Manual tests pass - [ ] No unrelated changes ### Related - `phase-7f-2-agent-spawn-schema` -- phase note - `phase-7f-1-deprecate-issue-creator` -- prerequisite (issue-gate hook) - `agent-spawn-conventions` -- convention to update after merge