Implementation Plan: T5-P4-A3-WP3 Ensure every guard hook in a launched session can dispatch on AUTOSKILLIT_AGENT_BACKEND (#4095)

## Summary

Inject `AGENT_BACKEND_ENV_VAR` (flat form: `AUTOSKILLIT_AGENT_BACKEND`)
into `CmdSpec.env` for `build_interactive_cmd` and `build_resume_cmd` in
both the Claude Code and Codex backends. Currently, only
`build_skill_session_cmd` and `build_food_truck_cmd` set this variable.
Guard hooks launched in interactive and resume sessions cannot dispatch
on backend identity without reading `os.environ`, which creates an
implicit cross-layer contract. This plan closes that gap, updates the
`CODEX_INTERACTIVE_REQUIRED_ENV` validation gate to include the newly
injected var, and adds two parametrized arch tests to enforce the
invariant across all four builder methods for every registered backend.

## Requirements


## Conflict Resolution Decisions

The following files had merge conflicts that were automatically
resolved.


Closes #4019

## Implementation Plan

Plan file:
`/home/talon/projects/autoskillit-runs/impl-20260612-113600-305738/.autoskillit/temp/make-plan/t5-p4-a3-wp3-ensure-every-guard-hook-in-a-launched-session-c_plan_2026-06-12_114500.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code) via
AutoSkillit
<!-- autoskillit:pipeline-signature
steps=prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr
-->

## Token Usage Summary

| Step | Model | count | uncached | output | cache_read | peak_ctx |
turns | cache_write | time |

|------|-------|-------|----------|--------|------------|----------|-------|-------------|------|
| plan* | opus[1m] | 1 | 78 | 20.2k | 1.9M | 103.5k | 58 | 82.3k | 13m
49s |
| verify* | sonnet | 1 | 1.2k | 19.1k | 485.6k | 73.4k | 27 | 52.5k | 9m
55s |
| implement* | MiniMax-M3 | 1 | 2.1M | 9.3k | 0 | 0 | 63 | 0 | 11m 55s |
| audit_impl* | sonnet | 1 | 44 | 10.8k | 167.0k | 42.1k | 14 | 33.1k |
4m 2s |
| prepare_pr* | MiniMax-M3 | 1 | 198.3k | 3.9k | 0 | 0 | 14 | 0 | 1m 20s
|
| compose_pr* | MiniMax-M3 | 1 | 213.0k | 1.4k | 0 | 0 | 12 | 0 | 42s |
| **Total** | | | 2.6M | 64.7k | 2.5M | 103.5k | | 167.9k | 41m 45s |

\* *Step used a non-Anthropic provider; caching behavior may differ.*

## Token Efficiency

| Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC |
|------|-------------|----------------|-----------------|------------|
| plan | 0 | — | — | — |
| verify | 0 | — | — | — |
| implement | 84 | 0.0 | 0.0 | 111.2 |
| audit_impl | 0 | — | — | — |
| prepare_pr | 0 | — | — | — |
| compose_pr | 0 | — | — | — |
| **Total** | **84** | 30192.5 | 1998.8 | 770.7 |

## Model Usage Breakdown

| Model | steps | uncached | output | cache_read | cache_write | time |
|-------|-------|----------|--------|------------|-------------|------|
| opus[1m] | 1 | 78 | 20.2k | 1.9M | 82.3k | 13m 49s |
| sonnet | 2 | 1.2k | 29.9k | 652.6k | 85.6k | 13m 57s |
| MiniMax-M3 | 3 | 2.6M | 14.6k | 0 | 0 | 13m 58s |

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Trecek

src/autoskillit/core/types/_type_constants_env.py

@@ -158,6 +158,7 @@
 CODEX_INTERACTIVE_REQUIRED_ENV: frozenset[str] = frozenset(
     {
         MCP_CLIENT_BACKEND_ENV_VAR,
+        AGENT_BACKEND_ENV_VAR,
     }
 )
 

src/autoskillit/execution/backends/claude.py

@@ -461,6 +461,8 @@ def build_interactive_cmd(
         for t in tools:
             builder.variadic_pair(ClaudeFlags.TOOLS, t)
         merged: dict[str, str] = dict(SHARED_BASELINE_ENV)
+        merged[AGENT_BACKEND_ENV_VAR] = AGENT_BACKEND_CLAUDE_CODE
+        merged[AGENT_BACKEND_DYNACONF_ENV_VAR] = AGENT_BACKEND_CLAUDE_CODE
         if env_extras:
             merged.update(env_extras)
         interactive_base = {
@@ -500,6 +502,8 @@ def build_resume_cmd(
             case None:
                 pass
         merged: dict[str, str] = dict(SHARED_BASELINE_ENV)
+        merged[AGENT_BACKEND_ENV_VAR] = AGENT_BACKEND_CLAUDE_CODE
+        merged[AGENT_BACKEND_DYNACONF_ENV_VAR] = AGENT_BACKEND_CLAUDE_CODE
         if env_extras:
             merged.update(env_extras)
         env = dict(build_agent_env(base={}, extras=merged))

src/autoskillit/execution/backends/codex.py

@@ -888,6 +888,7 @@ def build_interactive_cmd(
                 "AUTOSKILLIT_HEADLESS": "",
                 "AUTOSKILLIT_HEADLESS_AUTO_GATE": "",
                 "AUTOSKILLIT_SESSION_TYPE": "",
+                AGENT_BACKEND_ENV_VAR: AGENT_BACKEND_CODEX,
                 AGENT_BACKEND_DYNACONF_ENV_VAR: AGENT_BACKEND_CODEX,
                 MCP_CLIENT_BACKEND_ENV_VAR: AGENT_BACKEND_CODEX,
                 FOOD_TRUCK_TOOL_TAGS_ENV_VAR: "",
@@ -926,7 +927,9 @@ def build_resume_cmd(
         cmd.append(resume_session_id)
         cmd.append(prompt)
         filtered_base = {k: v for k, v in os.environ.items() if k not in _HEADLESS_EXCLUSIVE_VARS}
-        resume_extras = _codex_exec_extras(session_type="", include_session_baseline=True)
+        resume_extras = _codex_exec_extras(
+            session_type="", include_session_baseline=True, include_agent_backend_flat=True
+        )
         if env_extras:
             resume_extras.update(env_extras)
         env = self.env_policy().build_env(

tests/arch/test_env_symmetry.py

@@ -158,3 +158,72 @@ def test_dynaconf_and_flat_backend_values_match() -> None:
             food_truck_spec.env["AUTOSKILLIT_AGENT_BACKEND__BACKEND"]
             == food_truck_spec.env["AUTOSKILLIT_AGENT_BACKEND"]
         ), f"{name}: nested and flat AGENT_BACKEND values differ in build_food_truck_cmd"
+
+
+_ALL_GUARD_BUILDERS: list[str] = [
+    "build_skill_session_cmd",
+    "build_food_truck_cmd",
+    "build_interactive_cmd",
+    "build_resume_cmd",
+]
+
+
+def _call_builder(backend: object, builder_name: str) -> object:
+    from autoskillit.core.types._type_plugin_source import DirectInstall
+
+    if builder_name == "build_skill_session_cmd":
+        return backend.build_skill_session_cmd(
+            "/autoskillit:investigate", "/repo", completion_marker="DONE"
+        )
+    if builder_name == "build_food_truck_cmd":
+        return backend.build_food_truck_cmd(
+            orchestrator_prompt="test prompt",
+            plugin_source=DirectInstall(plugin_dir=Path("/plugins")),
+            cwd="/repo",
+            completion_marker="DONE",
+        )
+    if builder_name == "build_interactive_cmd":
+        return backend.build_interactive_cmd()
+    if builder_name == "build_resume_cmd":
+        return backend.build_resume_cmd(resume_session_id="test-session", prompt="continue")
+    msg = f"Unknown builder: {builder_name}"
+    raise ValueError(msg)
+
+
+@pytest.mark.parametrize("builder_name", _ALL_GUARD_BUILDERS)
+def test_agent_backend_flat_env_var_in_all_guard_launch_builders(builder_name: str) -> None:
+    """AUTOSKILLIT_AGENT_BACKEND must appear in every builder's CmdSpec.env for every backend."""
+    from autoskillit.core.types._type_backend import CmdSpec
+    from autoskillit.execution.backends import BACKEND_REGISTRY
+
+    assert BACKEND_REGISTRY, "BACKEND_REGISTRY is empty — test provides no coverage"
+    for name, cls in BACKEND_REGISTRY.items():
+        backend = cls()
+        if builder_name == "build_resume_cmd" and not backend.capabilities.session_resume_capable:
+            continue
+        spec = _call_builder(backend, builder_name)
+        assert isinstance(spec, CmdSpec), f"{name}: {builder_name} did not return CmdSpec"
+        assert "AUTOSKILLIT_AGENT_BACKEND" in spec.env, (
+            f"{name}: AUTOSKILLIT_AGENT_BACKEND missing from {builder_name} env"
+        )
+
+
+def test_agent_backend_flat_and_dynaconf_values_match_in_interactive_and_resume() -> None:
+    """Nested and flat AGENT_BACKEND env vars must carry the same value in interactive and resume builders."""  # noqa: E501
+    from autoskillit.execution.backends import BACKEND_REGISTRY
+
+    assert BACKEND_REGISTRY, "BACKEND_REGISTRY is empty — test provides no coverage"
+    for name, cls in BACKEND_REGISTRY.items():
+        backend = cls()
+        interactive_spec = backend.build_interactive_cmd()
+        assert (
+            interactive_spec.env["AUTOSKILLIT_AGENT_BACKEND__BACKEND"]
+            == interactive_spec.env["AUTOSKILLIT_AGENT_BACKEND"]
+        ), f"{name}: nested and flat AGENT_BACKEND values differ in build_interactive_cmd"
+        if not backend.capabilities.session_resume_capable:
+            continue
+        resume_spec = backend.build_resume_cmd(resume_session_id="test-session", prompt="continue")
+        assert (
+            resume_spec.env["AUTOSKILLIT_AGENT_BACKEND__BACKEND"]
+            == resume_spec.env["AUTOSKILLIT_AGENT_BACKEND"]
+        ), f"{name}: nested and flat AGENT_BACKEND values differ in build_resume_cmd"

tests/arch/test_subpackage_isolation.py

@@ -985,7 +985,7 @@ def test_data_directories_are_not_python_packages() -> None:
         "dispatch gate add defense-in-depth checks",
     ),
     "execution/backends/codex.py": (
-        1062,
+        1066,
         "REQ-CNST-010-E9: Codex backend — skill_sigil capability threading adds multi-line "
         "keyword args to _ensure_skill_prefix call sites and _has_prefix guard; "
         "write_guard_tool_names env injection adds 7 lines to _codex_exec_extras; "
@@ -998,7 +998,10 @@ def test_data_directories_are_not_python_packages() -> None:
         "; session_log_path method added to CodexSessionLocator (+5 net lines)"
         "; process_idle_timeout_ms field wired through build_skill_session_cmd and "
         "build_food_truck_cmd CmdSpec constructors (+8 net lines)"
-        "; CapabilityNotSupportedError capability-gate in build_inspector_cmd (+1 net line)",
+        "; CapabilityNotSupportedError capability-gate in build_inspector_cmd (+1 net line); "
+        "AGENT_BACKEND_ENV_VAR injection in build_interactive_cmd merged_extras (+1 net line) "
+        "and build_resume_cmd _codex_exec_extras call expansion to multi-line (+2 net lines) "
+        "for T5-P4-A3-WP3 guard-hook backend dispatch",
     ),
 }