feat: add fail-closed subagent delegation gates (Closes #266) #291

2026-07-06T23:29:33-05:00

jcwalker3 commented

2026-07-06 23:29:33 -05:00

Closes #266

Summary

New subagent_gate.py policy module (author_proofs/review_proofs pure-function pattern) making subagent delegation an explicit, fail-closed decision:

assess_subagent_delegation — deterministic write tasks (issue claim, branch creation, code edits, commits, PR creation, review, merge, cleanup, close) are blocked for subagents unless explicitly allowed and justified and the full gate context is inherited (issue lock, branch/worktree path, identity/profile, allowed tool class, command deny list, validation ledger requirement, final report schema). Read-only delegation (search, inventory, summarize) needs no explicit authorization. Unknown task types fail closed. (AC1–AC3)
validate_subagent_report — subagent output accepted only when it carries parent-grade proof fields (identity/profile, worktree path, branch, changed files, validation results, workspace mutations). (AC4)
Operator guide: subagent_delegation rule added to _GUIDE_RULES so MCP clients discover the policy via mcp_get_control_plane_guide.

Validation

pytest tests/test_subagent_gate.py -q — 13 passed, exit 0 (AC5 scenarios: blocked write delegation, missing justification, missing/blank inherited context, allowed read-only delegation, unknown task, invalid subagent final reports)
Full suite (pytest tests/ --ignore=tests/integration) in the issue worktree — 1020 passed, 0 failed (integration suite excluded, consistent with repo practice)
git diff --check — clean; secret-pattern scan of diff — 0 hits
Validated at head e09df4a

Risk

Low. Pure additive module + one additive operator-guide key; no existing gate, tool, or permission path modified. Known mechanical merge overlap: PR #281 also appends to the _GUIDE_RULES tail — whichever lands second needs a trivial rebase of that hunk.

Worktree

/Users/jasonwalker/Development/Gitea-Tools/branches/feat-issue-266-subagent-gate-inheritance (branch feat/issue-266-subagent-gate-inheritance; main checkout stayed on master, untouched)

Closes #266 ## Summary New `subagent_gate.py` policy module (author_proofs/review_proofs pure-function pattern) making subagent delegation an explicit, fail-closed decision: - `assess_subagent_delegation` — deterministic write tasks (issue claim, branch creation, code edits, commits, PR creation, review, merge, cleanup, close) are blocked for subagents unless explicitly allowed **and** justified **and** the full gate context is inherited (issue lock, branch/worktree path, identity/profile, allowed tool class, command deny list, validation ledger requirement, final report schema). Read-only delegation (search, inventory, summarize) needs no explicit authorization. Unknown task types fail closed. (AC1–AC3) - `validate_subagent_report` — subagent output accepted only when it carries parent-grade proof fields (identity/profile, worktree path, branch, changed files, validation results, workspace mutations). (AC4) - Operator guide: `subagent_delegation` rule added to `_GUIDE_RULES` so MCP clients discover the policy via `mcp_get_control_plane_guide`. ## Validation - `pytest tests/test_subagent_gate.py -q` — 13 passed, exit 0 (AC5 scenarios: blocked write delegation, missing justification, missing/blank inherited context, allowed read-only delegation, unknown task, invalid subagent final reports) - Full suite (`pytest tests/ --ignore=tests/integration`) in the issue worktree — **1020 passed, 0 failed** (integration suite excluded, consistent with repo practice) - `git diff --check` — clean; secret-pattern scan of diff — 0 hits - Validated at head `e09df4a` ## Risk Low. Pure additive module + one additive operator-guide key; no existing gate, tool, or permission path modified. Known mechanical merge overlap: PR #281 also appends to the `_GUIDE_RULES` tail — whichever lands second needs a trivial rebase of that hunk. ## Worktree `/Users/jasonwalker/Development/Gitea-Tools/branches/feat-issue-266-subagent-gate-inheritance` (branch `feat/issue-266-subagent-gate-inheritance`; main checkout stayed on `master`, untouched)

jcwalker3 added 1 commit 2026-07-06 23:29:33 -05:00

feat: add fail-closed subagent delegation gates (#266 ) e09df4a348

Adds subagent_gate.py following the author_proofs/review_proofs pure-policy
pattern:

- assess_subagent_delegation: deterministic write tasks (issue claim,
  branch creation, code edits, commits, PR creation, review, merge,
  cleanup) are blocked for subagents unless explicitly allowed with a
  recorded justification and the full inherited gate context (issue lock,
  branch/worktree path, identity/profile, allowed tool class, command
  deny list, validation ledger requirement, final report schema);
  read-only delegation stays allowed; unknown task types fail closed.
- validate_subagent_report: subagent output is accepted only when it
  carries the same proof fields as a parent workflow final report.
- Operator guide: new subagent_delegation rule in _GUIDE_RULES so MCP
  clients discover the policy.
- tests/test_subagent_gate.py: 13 tests covering blocked write
  delegation, justification requirement, missing/blank inherited
  context, allowed read-only delegation, unknown tasks, and invalid
  subagent final reports.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

sysadmin added 1 commit 2026-07-07 00:56:33 -05:00

Merge branch 'master' into feat/issue-266-subagent-gate-inheritance a4736a2346

jcwalker3 referenced this pull request

2026-07-07 01:30:23 -05:00

Reviewer queue selection must prove ordering before selecting next PR #321

jcwalker3 added 1 commit 2026-07-07 01:56:20 -05:00

Merge prgs/master into feat/issue-266-subagent-gate-inheritance 096bb878d5

Resolve _GUIDE_RULES conflict by keeping both operator guide keys:
shell_spawn_hard_stop (#258, landed on master via PR #281) and
subagent_delegation (#266, this branch).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

jcwalker3 commented

2026-07-07 01:56:59 -05:00

Continuation update (lease owner): resolved the predicted _GUIDE_RULES merge conflict after #281 and other PRs landed on master.

What changed:

Adopted the sync merge a4736a2 (another session merged then-master into this branch; my commit e09df4a preserved as ancestor — thanks).
Merged current prgs/master (a534168) at 096bb87; single conflict in gitea_mcp_server.py _GUIDE_RULES resolved by keeping both keys: shell_spawn_hard_stop (#258, from master) and subagent_delegation (#266, this branch).
No feature-code changes; subagent_gate.py and its tests untouched by the resolution.

Revalidation at 096bb87 (issue worktree branches/feat-issue-266-subagent-gate-inheritance):

pytest tests/test_subagent_gate.py tests/test_operator_guide.py -q — 37 passed
Full suite (pytest tests/ --ignore=tests/integration) — 1057 tests, 1 failed: TestIssueLockArtifactWarning::test_lock_success_includes_artifact_warning
Baseline proof (per the branches-only baseline rule): fresh detached worktree branches/baseline-master-pr291 at clean master a534168 fails the same test with the identical assertion (tests/test_agent_temp_artifacts.py:81) — pre-existing master failure from the #261/#277 line, not introduced by this branch. Needs its own fix on master.
git diff --check — clean

PR is mergeable again. Ready for independent review.

Continuation update (lease owner): resolved the predicted `_GUIDE_RULES` merge conflict after #281 and other PRs landed on master. **What changed:** - Adopted the sync merge `a4736a2` (another session merged then-master into this branch; my commit `e09df4a` preserved as ancestor — thanks). - Merged current `prgs/master` (`a534168`) at `096bb87`; single conflict in `gitea_mcp_server.py` `_GUIDE_RULES` resolved by keeping **both** keys: `shell_spawn_hard_stop` (#258, from master) and `subagent_delegation` (#266, this branch). - No feature-code changes; `subagent_gate.py` and its tests untouched by the resolution. **Revalidation at `096bb87` (issue worktree `branches/feat-issue-266-subagent-gate-inheritance`):** - `pytest tests/test_subagent_gate.py tests/test_operator_guide.py -q` — 37 passed - Full suite (`pytest tests/ --ignore=tests/integration`) — 1057 tests, 1 failed: `TestIssueLockArtifactWarning::test_lock_success_includes_artifact_warning` - **Baseline proof** (per the branches-only baseline rule): fresh detached worktree `branches/baseline-master-pr291` at clean master `a534168` fails the same test with the identical assertion (`tests/test_agent_temp_artifacts.py:81`) — pre-existing master failure from the #261/#277 line, not introduced by this branch. Needs its own fix on master. - `git diff --check` — clean PR is mergeable again. Ready for independent review.

sysadmin approved these changes 2026-07-07 02:55:32 -05:00

sysadmin left a comment

PR #291 implements fail-closed subagent delegation gates, satisfying the acceptance criteria of issue #266. All targeted and full-suite test results are clean.

sysadmin merged commit 7fdf803a50 into master

2026-07-07 02:56:01 -05:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#291