Rectify: Fixed-set join contract and Claude team-dispatch isolation (#4575, #4520)

docs/README.md

@@ -2,7 +2,7 @@
 
 AutoSkillit is a Claude Code plugin that runs YAML recipes through a
 multi-level orchestrator. The bundled recipes implement issue → plan → worktree
-→ tests → PR → merge pipelines using 74 MCP tools and 141 bundled skills.
+→ tests → PR → merge pipelines using 75 MCP tools and 141 bundled skills.
 
 ## Start here
 

docs/execution/README.md

@@ -7,6 +7,6 @@ merge gates.
 - [claude-startup-readiness.md](claude-startup-readiness.md) — bounded MCP addressability and conformance evidence
 - [explorer-agents.md](explorer-agents.md) — bounded specialized repository exploration agents
 - [fleet-effect-provenance.md](fleet-effect-provenance.md) — dispatch effect receipts and retry disposition
-- [tool-access.md](tool-access.md) — visibility and authority across all 74 MCP tools
+- [tool-access.md](tool-access.md) — visibility and authority across all 75 MCP tools
 - [orchestration.md](orchestration.md) — orchestration levels, retry reasons, merge decision tree
 - [orchestration-levels.md](../orchestration-levels.md) — L0–L3 level definitions, mapping table

docs/execution/architecture.md

@@ -4,7 +4,7 @@ How AutoSkillit runs a recipe end to end: orchestrator, kitchen gating, clone an
 
 ## Overview
 
-AutoSkillit is a Claude Code plugin that orchestrates automated workflows using headless sessions. It provides 74 MCP tools and 141 bundled skills, organized into a gated visibility system.
+AutoSkillit is a Claude Code plugin that orchestrates automated workflows using headless sessions. It provides 75 MCP tools and 141 bundled skills, organized into a gated visibility system.
 
 ## Core Concepts
 
@@ -39,8 +39,8 @@ AutoSkillit uses several overlapping tool visibility surfaces:
   `mcp.enable({'headless'})` — `test_check`, `unlock_agent_pack`, `commit_files`,
   `write_audit_semantic_result`, `write_standalone_audit_evidence`,
   `write_audit_disposition_bundle`, `post_pr_review`, and `delegate_evidence_reader`.
-- **Kitchen-tagged tools (51 tools total)**: Gated behind `open_kitchen` — `run_skill`,
-  `run_cmd`, `run_python`, `merge_worktree`, `clone_repo`, `push_to_remote`, and 45 more.
+- **Kitchen-tagged tools (52 tools total)**: Gated behind `open_kitchen` — `run_skill`,
+  `run_cmd`, `run_python`, `merge_worktree`, `clone_repo`, `push_to_remote`, and 46 more.
   Seven kitchen tools also carry the `headless` tag and are
   additionally pre-enabled in headless sessions. `post_pr_review` is headless-only and
   deliberately not application-gated.
@@ -102,15 +102,15 @@ AutoSkillit supports four session modes with different tool and skill visibility
 
 - **`$ claude` (plugin, no kitchen)**: Regular Claude Code session with the AutoSkillit plugin
   loaded. Sees the 8 Free Range MCP tools and Tier 1 skills only
-  (`open-kitchen`, `close-kitchen`). After calling `/open-kitchen`, all 51 kitchen-tagged MCP
+  (`open-kitchen`, `close-kitchen`). After calling `/open-kitchen`, all 52 kitchen-tagged MCP
   tools become available.
 
 - **`$ autoskillit cook`**: Interactive development session. Sees all three skill tiers
   (Tier 1+2+3) via an ephemeral session directory. MCP tools are initially ungated (same as
   `$ claude`); `/open-kitchen` reveals kitchen tools.
 
 - **`$ autoskillit order`**: Pipeline orchestrator session. Kitchen is pre-opened at startup.
-  The authenticated evidence-reader brokers remain hidden among the 74 registered MCP tools
+  The authenticated evidence-reader brokers remain hidden among the 76 registered MCP tools
   because only a separately launched reader child receives their binding. All skill tiers are
   accessible. The orchestrator delegates work through `run_skill` (headless sessions) and
   `run_cmd` (shell commands).
@@ -123,6 +123,23 @@ AutoSkillit supports four session modes with different tool and skill visibility
 This prevents recursive session nesting and keeps the orchestrator as a pure routing engine.
 See **[Skill Visibility](../skills/visibility.md)** for the full tier breakdown and configuration.
 
+## Join Contract and Batch Admission
+
+A skill that declares `semantic_requirements.join.required: true` enters a join-bound session the moment Claude loads it. The hook layer carries the join policy and the batch ledger:
+
+1. **`declare_join_batch`** opens one parent/wave with resolved assignment labels, validates the loaded skill's `join.required` and `child_spawn_cardinality` against the projection manifest, and returns a fresh `join_batch_id`.
+2. **JoinLedger** keys membership and outcomes by `(session_id, top_level_parent, join_batch_id, assignment, tool_use_id)`. Persistence uses `fcntl.flock` + atomic `os.replace` (`hooks/_join_ledger.py`).
+3. **Claim → Settle → Stop lifecycle** —
+   * `join_claim_guard` (PreToolUse, matcher `Agent`) atomically claims one declared assignment per top-level direct `Agent` `tool_use_id`.
+   * `join_settle_guard` (PostToolUse + PostToolUseFailure) maps the upstream event to one of `success / failure / timeout / cancelled / interruption / missing` and records the outcome on the claimed handle. Empty results are mapped to `missing`, never `success`.
+   * `join_followup_guard` (matcherless PreToolUse) denies non-`Agent` side-effecting calls while a wave is unresolved.
+   * `join_stop_guard` (Stop, exit code 2) blocks Claude from completing until the wave is `complete`.
+4. **Backend admission** — `BackendCapabilities.fixed_set_join_capable` is statically `True` only for Claude Code, and only when the full guard set is registered in the same commit. Codex returns `unsupported_operation(REQUIRED_JOIN)` at admission; current Codex has wait-any/mailbox semantics, not fixed-set fan-in.
+5. **Session binding monotonicity** — `skill_load_post_hook.py` writes a JSON envelope with OR-accumulated `join_required`. A later join-false Skill load does not downgrade an established binding. A missing or unreadable projection manifest fails closed by forcing `join_required: true` so dispatch guards refuse all join-bearing work.
+6. **Repository force-inactive option** — `agent_backend.force_claude_agent_teams_inactive` (default False) neutralizes `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` and detects conflicting entries in the target repository's `.claude/settings.json` / `.claude/settings.local.json`. Repositories with the option disabled remain byte-for-byte unchanged.
+
+The session flag carries join policy; the manifest carries projection identity; the ledger carries wave state. Each is read by the matching hook family. None of them is a duplicate authority — they are three projections of one decision.
+
 ## Durable Codex Cook Sessions
 
 Codex cook history uses a per-attempt view rather than exposing the complete

docs/execution/tool-access.md

@@ -1,6 +1,6 @@
 # MCP Tool Access Control
 
-AutoSkillit provides 74 MCP tools across overlapping visibility surfaces that control which
+AutoSkillit provides 75 MCP tools across overlapping visibility surfaces that control which
 session types can see each tool. Visibility determines addressability; each tool still enforces
 its own authority contract.
 
@@ -140,7 +140,7 @@ missing kitchen visibility.
 
 ## Complete MCP Tool Access Control Map
 
-All 74 tools with their access level, tags, source file, and functional category.
+All 75 tools with their access level, tags, source file, and functional category.
 
 **Tag abbreviations**: AS = `autoskillit`, K = `kitchen`, HL = `headless`,
 ER = `evidence-reader`, GH = `github`, CI = `ci`, CL = `clone`,
@@ -159,7 +159,8 @@ TL = `telemetry`, FL = `fleet`
 | `reload_session` | AS | `server/tools_kitchen.py` |
 | `configure_fleet` | AS | `server/tools_config.py` |
 | `configure_order` | AS | `server/tools_config.py` |
-| `lock_ingredients` | AS | `server/tools_config.py` |
+| `lock_ingredients` | AS | `server/tools_kitchen.py` |
+| `declare_join_batch` | AS, K | `server/tools_kitchen.py` | Opens one declared-batch JoinLedger for the next wave; see `JoinLedger` lifecycle. Claude-only when `fixed_set_join_capable`. |
 
 ---
 
@@ -299,7 +300,7 @@ dynamically gated until opening completes. The bounded client snapshot and
 fresh/resume behavior are documented in
 [Claude startup readiness](claude-startup-readiness.md).
 
-**Total: 74 registered tools**. The 51 kitchen-tagged tools include seven of the eight
+**Total: 75 registered tools**. The 51 kitchen-tagged tools include seven of the eight
 headless tools. The two authenticated evidence-reader brokers are excluded from the
 kitchen, free-range, and fleet counts.
 

docs/faq.md

@@ -101,3 +101,63 @@ Open an issue in the GitHub repository. AutoSkillit also has a built-in
 `report_bug` MCP tool that the `pipeline-summary` skill calls automatically
 when an overnight pipeline surfaces a bug. The tool deduplicates against
 existing open issues by fingerprint.
+
+### Does AutoSkillit force Claude agent teams off?
+
+No, not by default. The `agent_backend.force_claude_agent_teams_inactive`
+configuration option defaults to **false**, scoped per-repository (project
+configuration overrides user-level `.claude/settings.json`). When the
+operator sets it to **true** on a target repo, AutoSkillit strips
+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` from the launch environment before
+every Claude launch (interactive, resume, skill-session, and food-truck
+builders) and rewrites any conflicting `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+entry in the target repo's `.claude/settings.json` or `.claude/settings.local.json`.
+The pre-spawn checkpoint fail-closes: when the effective environment still
+carries a truthy team value, the launch refuses with an explicit reason.
+
+### When do teams help, and when is the join contract required?
+
+The force-inactive policy is **not** a global rule — it exists because
+join-bearing skills need an unguarded, declared-batch surface that
+team-mode routing defeats. Legitimate team workflows (named teammate
+dispatch, team-name routing, background tasks) continue to work in any
+session that has not loaded a join-bearing skill. A session that loads a
+join-bearing skill is permanently bound for the rest of its lifetime: a
+later load of a non-join skill cannot downgrade the binding. To re-enable
+team workflows in a session, the operator must start a fresh session after
+the join-bearing load.
+
+### Can Codex run join-bearing skills?
+
+Not today. Codex's static capability attestation reports
+`fixed_set_join_capable=False`. When a skill declares
+`semantic_requirements.join.required: true`, the `declare_join_batch` MCP
+tool refuses with `unsupported_operation(REQUIRED_JOIN)` and the skill
+cannot be admitted. Codex support requires the harness to expose a
+fixed-set fan-in primitive; until then, the backend gate is the single
+honest source.
+
+### What happens when I try a named Claude dispatch in a join-bound session?
+
+It is denied before child creation. The `background_exec_guard`
+PreToolUse hook reads the session binding and rejects any Agent call with
+`name`, `team_name`, or `run_in_background` selectors while
+`join_required=true`. The denial names the rejected selectors and points
+the operator at the `declare_join_batch` gateway — declare a wave with
+resolved assignment labels and re-dispatch as ordinary unnamed foreground
+Agent calls. The `ScheduleWakeup` deferral hook is denied for the same
+reason: deferral cannot produce the declared-batch evidence the join
+contract requires.
+
+### What's the difference between `join_required` and `team_name`?
+
+`join_required` is the semantic authority over the **parent's** dispatch
+boundary: a parent that loads a join-bearing skill must use the
+declared-batch fan-in path; the join contract gates its child routing.
+`team_name` is a Claude-only runtime selector that names a teammate under
+agent teams. They are not interchangeable: a join-bearing parent cannot
+dispatch via `team_name` (the dispatch guard denies it), and a non-join
+parent that names a teammate under agent teams is not bound by the join
+contract at all — it is the legitimate team workflow path described
+above. The two surfaces never overlap in the same session.
+

docs/safety/hooks.md

@@ -1,13 +1,13 @@
 # Hooks
 
-AutoSkillit registers 46 Claude Code hook scripts: 35 PreToolUse, 9 PostToolUse,
-and 2 SessionStart. Every script is stdlib-only Python so it can run before the
+AutoSkillit registers 51 Claude Code hook scripts: 37 PreToolUse, 11 PostToolUse,
+2 SessionStart, and 1 Stop. Every script is stdlib-only Python so it can run before the
 project virtualenv is on the path. Scripts live in `src/autoskillit/hooks/`
 and are bound to event types in `src/autoskillit/hook_registry.py` via the
 `HOOK_REGISTRY` list of `HookDef` entries; `generate_hooks_json()` then
 materializes the canonical `hooks.json` that Claude Code reads.
 
-## PreToolUse hooks (35)
+## PreToolUse hooks (37)
 
 ### `branch_protection_guard.py`
 **Guarded tools:** `merge_worktree`, `push_to_remote`
@@ -413,7 +413,7 @@ closed when their identity is malformed or the record cannot be written, while
 malformed JSON and unrelated tools remain fail-open. Codex and headless terminal
 authority do not use this bridge.
 
-## PostToolUse hooks (9)
+## PostToolUse hooks (10)
 
 ### `pretty_output_hook.py`
 **Guarded tools:** all AutoSkillit MCP tools

scripts/check_tool_annotations.py

@@ -12,7 +12,10 @@
 from pathlib import Path
 
 TOOLS_DIR = Path(__file__).resolve().parent.parent / "src" / "autoskillit" / "server" / "tools"
-READ_ONLY_EXCEPTIONS = {"open_kitchen": False}
+# REQ-ARCH-ANNOTATION-E1: open_kitchen and declare_join_batch are the only
+# effectful tools; the former opens the kitchen session and the latter opens
+# a join batch ledger entry. Every other tool must remain readOnlyHint=True.
+READ_ONLY_EXCEPTIONS = {"open_kitchen": False, "declare_join_batch": False}
 
 
 def check() -> list[str]:

src/autoskillit/agents/plan-registry-tracer.md

@@ -49,7 +49,7 @@ LSP tracks typed references but misses field names embedded as **string literals
 `tree-sitter-python` (v0.25) and `tree-sitter-language-pack` are installed as project dev dependencies. Run via `python3` in Bash. Example — find a field name inside registry dicts/frozensets:
 
 ```python
-python3 << 'PYEOF'
+python3 << "PYEOF"
 import tree_sitter_python as tspython
 from tree_sitter import Language, Parser
 from pathlib import Path
@@ -58,25 +58,30 @@ import os
 FIELD = "TARGET_FIELD_NAME"  # replace with actual field
 parser = Parser(Language(tspython.language()))
 
+
 def find_in_file(fpath):
     source = fpath.read_bytes()
     tree = parser.parse(source)
     hits = []
+
     def walk(node):
         if node.type == "string":
             text = node.text.decode().strip('"').strip("'")
             if FIELD in text:
                 ctx = node.parent.type if node.parent else "?"
-                hits.append((node.start_point[0]+1, text, ctx))
+                hits.append((node.start_point[0] + 1, text, ctx))
         if node.type == "keyword_argument":
             name = node.child_by_field_name("name")
             if name and FIELD in name.text.decode():
-                hits.append((node.start_point[0]+1, name.text.decode(), "keyword_argument"))
-        for c in node.children: walk(c)
+                hits.append((node.start_point[0] + 1, name.text.decode(), "keyword_argument"))
+        for c in node.children:
+            walk(c)
+
     walk(tree.root_node)
     for line, text, ctx in hits:
         print(f"  {fpath}:{line} — '{text}' (inside {ctx})")
 
+
 root = os.environ.get("CODEBASE_ROOT", ".")
 for f in Path(root, "src").rglob("*.py"):
     find_in_file(f)

src/autoskillit/cli/session/_session_launch.py

@@ -90,6 +90,7 @@ def prepare_interactive_launch(
     tools: Sequence[str] = (),
     add_dirs: Sequence[Path | str | ValidatedAddDir] = (),
     generated_home: Path | None = None,
+    force_inactive_agent_teams: bool = False,
 ) -> PreparedInteractiveLaunch:
     """Probe an exact executable before sealing the capability-complete session env."""
 
@@ -122,6 +123,7 @@ def prepare_interactive_launch(
         add_dirs=add_dirs,
         generated_home=generated_home,
         tools=tools,
+        force_inactive_agent_teams=force_inactive_agent_teams,
     )
     final = resolve_executable_launch_binding(
         binary_name=backend.binary_name(),

src/autoskillit/config/_config_dataclasses.py

@@ -671,6 +671,12 @@ class AgentBackendConfig:
     backend: str = "claude-code"
     step_overrides: dict[str, str] = field(default_factory=dict)
     recipe_overrides: dict[str, dict[str, str]] = field(default_factory=dict)
+    # Repository-scoped toggle: when True, the Claude launcher neutralizes
+    # CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in both the process env and the
+    # target repository's .claude/settings*.json files before spawn. Defaults
+    # to False — repositories with the option disabled remain byte-for-byte
+    # unchanged. Independent from join.required. Refs #4575.
+    force_claude_agent_teams_inactive: bool = False
 
     def __post_init__(self) -> None:
         if not self.backend:

src/autoskillit/config/ingredient_defaults.py

@@ -137,6 +137,7 @@
             "configure_fleet",
             "configure_order",
             "lock_ingredients",
+            "declare_join_batch",
         ),
     ),
 )

src/autoskillit/core/tool_registry.py

@@ -83,6 +83,7 @@
         "configure_order",
         "create_and_publish_branch",
         "create_unique_branch",
+        "declare_join_batch",
         "disable_quota_guard",
         "dispatch_food_truck",
         "enable_exploration",
@@ -678,6 +679,12 @@ def _run_skill() -> ToolDef:
         roles={"_autoskillit_exploration_request_token": ToolParamRole.ORCHESTRATOR_SCOPING},
     ),
     _tool("lock_ingredients", ("locked", "pipeline_id", "unlock")),
+    _tool(
+        "declare_join_batch",
+        ("skill_name", "assignments", "session_id", "top_level_parent"),
+        required=("skill_name", "assignments", "session_id"),
+        wire_types={"assignments": ToolWireType.ARRAY},
+    ),
     _tool("reload_session"),
     _tool("record_pipeline_step", ("pipeline_id", "op", "dependencies", "step_name")),
     _tool("get_pr_reviews", ("pr_number", "cwd", "repo"), required=("pr_number", "cwd")),

src/autoskillit/core/types/_type_backend.py

@@ -236,6 +236,16 @@ class BackendCapabilities:
     # Interactive hook trust behavior. Automated builders retain their explicit
     # bypass policy; interactive launchers translate this policy into CLI flags.
     hook_trust_policy: HookTrustPolicy = HookTrustPolicy.AUTOMATED
+    # True only when the backend natively provides fixed-set join semantics:
+    # a declared batch declaration tool, an Agent PreToolUse claim guard,
+    # PostToolUse and PostToolUseFailure settlers, an unresolved-follow-up
+    # gate, and a Stop completion gate are all installed and capability-attested.
+    # This is a static declaration that must be paired with unconditional
+    # registration of every required hook in HOOK_REGISTRY in the same commit.
+    # Codex does NOT satisfy this contract — its wait-any/mailbox semantics
+    # cannot realize exact-set fixed membership, so its `fixed_set_join_capable`
+    # must remain False until the active harness exposes a real fixed-set primitive.
+    fixed_set_join_capable: bool = False
 
 
 ALL_PROJECT_LOCAL_SKILL_SEARCH_DIRS: tuple[str, ...] = (
@@ -406,6 +416,7 @@ def model_class(model: str) -> str:
     protected_recipe_delivery_capable=False,
     recipe_delivery_budget=None,
     hook_trust_policy=HookTrustPolicy.AUTOMATED,
+    fixed_set_join_capable=True,
 )
 
 
@@ -498,6 +509,7 @@ class SkillSessionConfig:
     native_shell_capture_decision: NativeShellCaptureDecision | None = None
     managed_lineage_ref: ManagedHeadlessSessionLineageRef | None = None
     managed_attempt_id: str | None = None
+    force_inactive_agent_teams: bool = False
 
     def __post_init__(self) -> None:
         managed_values = (

src/autoskillit/core/types/_type_constants_registries.py

@@ -211,6 +211,7 @@
         "configure_fleet",
         "configure_order",
         "lock_ingredients",  # NEW (#3357)
+        "declare_join_batch",  # NEW (REQ-JOIN-001 — REQ-JOIN-002, #4575)
     }
 )