feat(agents-orchestration): subagent tool-scoping + optional review gates - #5
Closed
meshin-dev wants to merge 1 commit into
Closed
feat(agents-orchestration): subagent tool-scoping + optional review gates#5meshin-dev wants to merge 1 commit into
meshin-dev wants to merge 1 commit into
Conversation
…al review gates (subagent_review flag) Add an always-on subagent tool-scoping resilience rule to agents-orchestration.md: the Anthropic tool-use API rejects top-level oneOf/allOf/anyOf in a tool's input_schema, and a subagent's init advertises its whole tool surface in one request, so a single bad tool kills every subagent type at once and silently. Read-only fan-out agents (explore / plan / review) must declare a least-privilege tools allowlist (Read, Grep, Glob, Bash; WebFetch/WebSearch only for docs) so no connector schema reaches their init request; for owned MCP servers, strip top-level combinators from the advertised schema while keeping call-time validation (the mcp-github pattern); disable third-party connectors you cannot edit. Add two OPT-IN parallel-subagent review gates, gated by a new feature flag subagent_review: Gate 1 offers a plan-review before a non-trivial plan is confirmed; Gate 2 offers a conformance-review of the built work against the plan at merge-prep. Both ask the user each time and use the scoped ctxr-* agents; the foreground-only polling discipline is unchanged. Cross-link parallel-validation.md as the issue-tree specialization, and reference the gates from pr-loop.md and plan-to-issues.md. Wire the new subagent_review flag everywhere the existing flags appear (12 -> 13): FEATURE_NAMES in scripts/lib/config.mjs, the schema + flag-table + preset matrix in local-config.md, templates/config.local.md, index.md, and README.md. The flag conceptually requires agents_orchestration (stated in the flag-table row); it is on for single-issue and full, off for pr-only. No frontmatter requires.config is added; agents-orchestration.md keeps feature: agents_orchestration and gates the new section with an inline Skip callout. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR adds subagent_review as a new optional methodology feature and documents scoped subagent usage for more resilient fan-out workflows.
Changes:
- Adds
subagent_reviewto config parsing, templates, feature counts, and preset documentation. - Extends
agents-orchestration.mdwith subagent tool-scoping guidance and optional plan/conformance review gates. - Adds cross-links from PR loop, plan migration, and parallel validation docs to the new review-gate workflow.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/lib/config.mjs |
Registers the new subagent_review feature flag. |
templates/config.local.md |
Adds the new flag to the default local config template. |
local-config.md |
Updates feature counts, feature table, and preset matrix. |
README.md |
Updates feature count and install instructions for the new flag. |
agents-orchestration.md |
Documents scoped subagent allowlists and optional review gates. |
pr-loop.md |
Links merge-prep to the optional conformance-review gate. |
plan-to-issues.md |
Links plan confirmation to the optional plan-review gate. |
parallel-validation.md |
Frames issue-tree validation as a specialization of conformance review. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **MCP servers you own vs. connectors you do not.** For an MCP server you control, strip top-level combinators from the ADVERTISED schema while keeping call-time validation intact, so the public surface is flat but every call is still checked. That is the pattern `mcp-github` uses (`src/registry.ts` plus `src/validation/advertise.ts`): advertise a flattened schema, enforce the full schema when the tool runs. For a third-party connector you cannot edit, disable the unused ones rather than exposing them to fan-out agents. | ||
|
|
||
| **Scoped agents already exist for this.** The read-only project agents `ctxr-explore`, `ctxr-plan-reviewer`, and `ctxr-conformance-reviewer` (Claude Code project agents under `.claude/agents/`) are scoped to exactly such an allowlist. Use them for fan-out; they are the durable, immune-by-construction path. |
| @@ -157,7 +157,7 @@ Works with any agent that can run shell and edit files. **Copy this prompt and p | |||
| > > - **`single-issue`** - `pr-only` + issue lifecycle + canonical issue schema. Still no project board. | |||
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agents-orchestration.md: NEW "Subagent tool scoping (keep fan-out alive)" section (always-on) explaining the top-level oneOf/allOf/anyOf failure mode (whole subagent-init request fails -> all fan-out dies silently) and the rule that read-only fan-out agents declare a least-privilegetools:allowlist (no MCP connectors); plus NEW "Optional review gates" section (inline-gated bysubagent_review): Gate 1 plan-review before confirmation, Gate 2 conformance-review at merge-prep, both opt-in and foreground.subagent_review(requiresagents_orchestration) wired intoscripts/lib/config.mjsFEATURE_NAMES, the Features tables (local-config.md,templates/config.local.md), the preset matrix, and the 12 -> 13 counts (local-config.md,index.md,README.md).parallel-validation.md(issue-tree specialization),pr-loop.md(conformance gate at merge-prep),plan-to-issues.md(plan-review before migration).ctxr-explore/ctxr-plan-reviewer/ctxr-conformance-reviewership as Claude Code project agents (.claude/agents/) withRead, Grep, Glob, Bash(+ Web for the plan reviewer) allowlists, immune to a bad connector schema by construction.Notes
feat/pr-review-watch-discipline(PR feat(pr-loop): multi-reviewer foreground review-watch, 60s, mandatory resolve #3); merge that first, then this retargets to main.Test plan
node --check scripts/lib/config.mjs; FEATURE_NAMES length 13 incl.subagent_reviewperl -CSD).claude/agents/*register and advertise only their allowlist (nomcp__*)Closes #4