#89 - Refactor spawn gate to capability-based gating — remove Explore agent gate - ldraney/claude-custom

forgejo_admin commented

2026-03-14 17:04:10 +00:00

Contributor

Lineage

plan-pal-e-agency → Phase 8a (Capability-based spawn gate)

Repo

forgejo_admin/claude-custom

User Story

As Betty Sue
I want to spawn Explore agents for research without needing an issue reference
So that discovery work isn't blocked by scoping requirements meant for execution agents

Context

The check-agent-spawn.sh hook currently gates ALL agent types:

Explore: requires #N or Issue — but Explore agents are READ-ONLY (no Edit/Write/Bash)
general-purpose: requires plan- — but research agents don't modify docs
dev/QA: requires #N or Issue — correct, these write code

DORA principle: gate on capability (write access), not agent type. Read-only agents cannot cause failures. Gating them blocks discovery flow without reducing change failure rate.

Observed this session: 2 of 3 Explore agents blocked for pgvector research. One passed accidentally because the prompt contained #5 from an unrelated memory reference — proving the regex check is both too strict (blocks research) and too loose (matches incidental #N).

File Targets

Files the agent should modify:

hooks/check-agent-spawn.sh — refactor the gating logic

Current logic (approximate):

case "$agent_type" in
  dev|qa|Explore) require_pattern '#[0-9]+|[Ii]ssue' ;;
  general-purpose|dottie) require_pattern 'plan-' ;;
esac

Target logic:

case "$agent_type" in
  dev|qa) require_pattern '#[0-9]+|[Ii]ssue|Forgejo issue' ;;
  Explore) pass_through ;;  # read-only by architecture
  general-purpose|dottie) require_pattern 'plan-' ;;
esac

Files the agent should NOT touch:

settings.json — hook registration is correct
Other hooks — unrelated

Acceptance Criteria

Explore agents spawn without any issue/plan reference requirement
Dev agents still require issue reference
QA agents still require issue reference
general-purpose/dottie agents still require plan reference
Hook still outputs clear error messages for blocked agents explaining what's required

Test Expectations

Manual test: spawn Explore agent with research prompt (no #N) — should pass
Manual test: spawn dev agent without issue ref — should block
Manual test: spawn QA agent without issue ref — should block

Constraints

Hooks are hardlinked to ~/.claude/hooks/ — changes are live immediately after commit
Keep the hook fail-open (exit 0 on errors) per existing convention
Don't over-engineer the research bypass for general-purpose — that can be a future iteration. Just fix Explore for now.

Checklist

PR opened
Tests pass
No unrelated changes

pal-e-agency — project this affects

### Lineage `plan-pal-e-agency` → Phase 8a (Capability-based spawn gate) ### Repo `forgejo_admin/claude-custom` ### User Story As Betty Sue I want to spawn Explore agents for research without needing an issue reference So that discovery work isn't blocked by scoping requirements meant for execution agents ### Context The `check-agent-spawn.sh` hook currently gates ALL agent types: - Explore: requires `#N` or `Issue` — but Explore agents are READ-ONLY (no Edit/Write/Bash) - general-purpose: requires `plan-` — but research agents don't modify docs - dev/QA: requires `#N` or `Issue` — correct, these write code DORA principle: gate on capability (write access), not agent type. Read-only agents cannot cause failures. Gating them blocks discovery flow without reducing change failure rate. Observed this session: 2 of 3 Explore agents blocked for pgvector research. One passed accidentally because the prompt contained `#5` from an unrelated memory reference — proving the regex check is both too strict (blocks research) and too loose (matches incidental `#N`). ### File Targets Files the agent should modify: - `hooks/check-agent-spawn.sh` — refactor the gating logic Current logic (approximate): ```bash case "$agent_type" in dev|qa|Explore) require_pattern '#[0-9]+|[Ii]ssue' ;; general-purpose|dottie) require_pattern 'plan-' ;; esac ``` Target logic: ```bash case "$agent_type" in dev|qa) require_pattern '#[0-9]+|[Ii]ssue|Forgejo issue' ;; Explore) pass_through ;; # read-only by architecture general-purpose|dottie) require_pattern 'plan-' ;; esac ``` Files the agent should NOT touch: - `settings.json` — hook registration is correct - Other hooks — unrelated ### Acceptance Criteria - [ ] Explore agents spawn without any issue/plan reference requirement - [ ] Dev agents still require issue reference - [ ] QA agents still require issue reference - [ ] general-purpose/dottie agents still require plan reference - [ ] Hook still outputs clear error messages for blocked agents explaining what's required ### Test Expectations - [ ] Manual test: spawn Explore agent with research prompt (no `#N`) — should pass - [ ] Manual test: spawn dev agent without issue ref — should block - [ ] Manual test: spawn QA agent without issue ref — should block ### Constraints - Hooks are hardlinked to `~/.claude/hooks/` — changes are live immediately after commit - Keep the hook fail-open (exit 0 on errors) per existing convention - Don't over-engineer the research bypass for general-purpose — that can be a future iteration. Just fix Explore for now. ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `pal-e-agency` — project this affects