feat: bounded native subagent dispatch MVP (pilot) — follow-up to #350 - #355
Merged
Conversation
…ce + binding + tests Owner-approved bounded carve-out (2026-09-02) for "supervised AI-OS subagent dispatch (pilot)". Pilot-only; not a standard workflow; does not generalize. Governance clarification: - ChatGPT/[AI OS]/Knowledge/AGENT_LOOP_PLAYBOOK.md: new allowed loop type + a "Supervised AI-OS Subagent Dispatch (Pilot)" section with all mandatory bounds (hub-and-spoke, root-only routing, no child->child, one execution_id, reuse AES continuation/route_trace/guards, bounded project-context, no new authority, unchanged gates, no framework/runtime/DB, .gitignore unchanged, shared-fs risk, no timeout primitive, observable evidence). - AGENTS.md / CURRENT_STATUS.md: annotate the "agentic workflows" blocked item with the single bounded exception; add a status line. - Regenerated AIOS_05 bundle + provenance audit. Runtime binding (Option 1, native built-in subagents only): - PROJECT_CAPABILITIES.yaml: additive semantic executor block per capability (backend claude_code_subagent, agent_type Plan / general-purpose, context_loader project-context, write_capable, child_dispatch forbidden). Registry stays the only capability registry; no AES-record schema change. - .agents/skills/ai-os-orchestrator/SKILL.md: "Native subagent dispatch (pilot)" subsection — dispatch preconditions, bounded prompt, root-only route_trace + guard handling, failure -> AES defect. - .agents/skills/project-context/SKILL.md: one line binding it as the child context loader. Tests: tests/test_project_capabilities_executor.py (8 deterministic invariants); tests/test_aios_dual_surface.py updated for the new executor key. Checks: 6 canonical scripts + provenance audit + pytest (215) all pass. No behavioral pilot has run yet — evidence doc follows in the next commit. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…t PASS Ran the bounded pilot end-to-end on the Claude Code surface: - Pilot A: Thinking -> root -> Analytics -> root -> Thinking (exec-pilotA) - Pilot B: AI OS -> root -> LLM -> root -> Codex (read-only) (exec-pilotB) - Pilot C: multi-hop; loop guard exercised both ways (exec-pilotC) — bare repeat route refused (repeat_route_refused_missing_evidence_delta), repeat route allowed after a material evidence_delta. 9 real native subagent dispatches. One execution_id per pilot, root-only routing, bounded project-context per child, no child->child, Closure Review against the original goal, one final result each. All 14 owner acceptance criteria + the Pilot C guard check observed. Defects registered (not hidden): - DEF-001 external_dependency: children inherit the parent cwd/branch (shared filesystem) and read a stale tree; domain reasoning unaffected; logged as a design risk for standardization. - DEF-002 contract: orchestrator subsection lacked a "root after-child step is mechanical, not discretionary" constraint (AES 2.1 boundary). Fixed — closed-trigger wording added to ai-os-orchestrator/SKILL.md (one fix). Evidence: docs/evidence/NATIVE_SUBAGENT_DISPATCH_PILOT_2026-09-02.md Pointers: docs/evidence/README.md, MASTER_STATUS.md. Verdict: PASS. Recommendation: keep pilot-only; standardization needs a separate owner decision gated on DEF-001 fix, structural hub-and-spoke for the write path, 2-3 more executions to calibrate guard thresholds, and a cost owner. Checks: 6 canonical scripts + provenance audit + pytest (215) all pass. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
github-actions
Bot
added
the
needs-human-review
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
sergstack
added a commit
that referenced
this pull request
Sep 2, 2026
…ow-up to #355 (#356) * feat(orchestrator): harden dispatch — mandatory worktree isolation + structural no-nesting Closes the two standardization blockers from PR #355's DEF-001 / residual risks, using native runtime enforcement, not prompt text. Blocker 1 (DEF-001, workspace isolation): - Every executor gains workspace: isolated_worktree. The orchestrator MUST dispatch with Agent isolation: "worktree" — child works in a clean, locked git worktree at a deterministic revision, never the parent working tree. Audit: observed a probe child land in .claude/worktrees/agent-<id> on a clean HEAD, isolated from the parent branch. Blocker 2 (structural no-nesting on the write path): - Audit finding: a general-purpose child CAN spawn a nested sub-agent (probe did it). Plan/Explore agent types are defined "All tools except Agent, ... Write, Edit" -> structurally cannot nest and cannot write. - Every executor.agent_type is now Plan (was general-purpose for codex). write_capable is false for all. An implementation slice returns a patch + validation commands; the ROOT applies and validates. Root is the only agent holding Agent + Write. Files: PROJECT_CAPABILITIES.yaml (executor: +workspace, agent_type Plan, write_capable false), ai-os-orchestrator/SKILL.md (structural invariants + mandatory isolation + patch-return flow + bounded failure recovery), AGENT_LOOP_PLAYBOOK.md bounds (+ regenerated AIOS_05 + provenance), tests/test_project_capabilities_executor.py (DEF-001 regression + non-nesting + no-write-capable-child invariants). Checks: 6 canonical scripts + provenance audit + pytest (216) pass. Additional observed executions + measurement evidence + decision memo follow. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(evidence): standardization decision memo — 3 more executions, verdict STANDARDIZE BOUNDED (conditional) Native enforcement audit + Pilots D/E/F on the hardened dispatch: - Pilot D (runtime failure): Plan child structurally lacks Write -> honest failure, no workaround -> DEF-P D-001 -> bounded recovery (patch-return, root applied + validated), no silent retry. - Pilot E (write path): Plan child in isolated worktree returned a clean 2-file unified diff + validation commands; root applied and validated. subagent_tokens 41558, tool_uses 11, duration 93s. - Pilot F (long multi-hop): 5 owner transitions ai_os->thinking->analytics->codex->ai_os, one execution_id exec-pilotF-2026-09-02, root-only routing, guard-gated repeat, Closure Review. Pilot's own multi-owner verdict: STANDARDIZE BOUNDED WITH CONDITIONS. Measurement evidence: 16 total dispatches (7 hardened), isolated-worktree landing 7/7=100%, structural write refusal 1/1, nested spawn by non-nesting executor 0, silent retries 0, latency captured n=2 (93s/149s), telemetry captured opportunistically only. Risks CLOSED (native, not prompt): DEF-001 workspace isolation (mandatory isolation:"worktree", registry + test + fail-closed SKILL wording); structural no-nesting (all executors Plan = no Agent tool; write-capable child removed; patch-return + root applies). Risks REMAINING: R1 unverified live spawn args (irreducible for a prompt-level controller); R2 thin measurement base; R3 worktree isolates VCS state only; R7 no cost owner. SKILL.md gains fail-closed spawn wording. No AES-record schema change, no ROUTING_RULES/registry-role/authority/gate change, no framework. Recommendation: STANDARDIZE BOUNDED (conditional) on a 4-item punch-list (fail-closed evidence linter, telemetry schema, >=15-dispatch sample, cost owner); else KEEP PILOT-ONLY until it lands. Checks: 6 canonical scripts + provenance audit + pytest (216) pass. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Code <sstegancev@gmail.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
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
1 participant
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
Follow-up to #350. On the Claude Code surface the native subagent primitive is real (unlike the ChatGPT/Codex surface #350 audited), so this wires
Invoke AI-OSto it as a bounded, owner-approved, pilot-only capability. Verdict from 3 real multi-owner executions: PASS. Recommendation: keep pilot-only; standardization is a separate owner decision.Governance: the owner granted a bounded carve-out on 2026-09-02 ("Supervised AI-OS subagent dispatch (pilot)") — pilot-only, does not generalize, not a standard workflow.
What changed (2 commits)
54d4d97— governance + binding + testsAGENT_LOOP_PLAYBOOK.md: new allowed loop type + "Supervised AI-OS Subagent Dispatch (Pilot)" section carrying every mandatory bound (hub-and-spokeroot→child→root, root is sole router, nochild→child, oneexecution_id, reuse AEScontinuation/route_trace/guards/handoff/authority-provenance with no parallel model,PROJECT_CAPABILITIES.yamlstays sole registry, boundedproject-contextper child, no new authority, unchanged merge/deploy/production/destructive/external gates, no framework/runtime/DB,.gitignoreunchanged, shared-fs risk, no timeout primitive, observable-evidence rule).AGENTS.md/CURRENT_STATUS.md: the "agentic workflows" blocked item annotated with the single bounded exception; status line added.AIOS_05bundle + provenance audit regenerated.PROJECT_CAPABILITIES.yaml: additive semanticexecutorblock per capability (backend: claude_code_subagent,agent_typePlan/general-purpose,context_loader: project-context,write_capable,child_dispatch: forbidden). No AES-record schema change.ai-os-orchestrator/SKILL.md: "Native subagent dispatch (pilot)" subsection — preconditions, bounded prompt, root-onlyroute_trace+ guard handling, mechanical (non-discretionary) after-child step, failure → AES defect.project-context/SKILL.md: one line binding it as the child context loader.tests/test_project_capabilities_executor.py(new, 8 invariants) +test_aios_dual_surface.pyupdated for theexecutorkey.20390ed— pilot evidencedocs/evidence/NATIVE_SUBAGENT_DISPATCH_PILOT_2026-09-02.md— full FACT/architecture/traces/defects/verdict.docs/evidence/README.md,MASTER_STATUS.md.Pilot traces (observed)
exec-pilotA-2026-09-02exec-pilotB-2026-09-02bounded_context_checkspec + verified minimal repo placement, zero writesexec-pilotC-2026-09-02Pilot C loop guard: repeat route to
ai_oswithoutevidence_delta→repeat_route_refused_missing_evidence_delta(not dispatched); with a materialevidence_delta→ allowed. All 14 owner acceptance criteria + the guard check pass (table in the evidence doc).Defects (registered, not hidden)
external_dependency— dispatched children inherit the parent cwd/branch (shared FS) and read a stale local tree; domain reasoning was sound, decision outputs unaffected (later slices re-verified). Logged as a standardization blocker.contract— orchestrator subsection lacked a "root after-child step is mechanical" constraint (AES §2.1). Fixed in this PR (one corrective fix).Checks
6 canonical scripts +
audit_bundle_provenance.py --check+pytest tests/ -q(215 passed, +8 new).Rollback
git revertthe two commits.executorblock is inert data once the orchestrator subsection reverts; no schema migration, no runtime store, no.gitignorechange. Prompt-levelInvoke AI-OS, Goal Mode, AES records, existing routing unaffected.AES statuses
execution_state: completed·overall_delivery: pass·qa_status: pass·judge_verdict: not_run·authority_status: owner_review_pending·merge_status: open·production_status: not_applicableRecommendation
Keep pilot-only. Standardization → separate owner decision, gated on: DEF-001 fixed (deterministic child checkout / mandatory worktree isolation); structural hub-and-spoke for the write path (
codexexecutor currentlygeneral-purpose, can nest — prompt-enforced only); 2–3 more executions incl. a runtime-failure case to calibrate the four guard thresholds; a named cost/latency owner.🤖 Generated with Claude Code