feat(runtime): enforce subagent write scopes behind the mutating policy

[OBenner]

Context — Phase A / PR-1 of "mutating subagents → safe"

Per the agreed plan (4 phases, 7 PRs), the subagent merge contract today is descriptive only: merge_policy/write_scope are metadata, children run text_only, the parser hard-rejects anything but read_only, and build_subagent_merge_plan describes a transactional_parent_merge nobody executes. This PR makes the contract enforced by construction — the prerequisite for ever letting children mutate.

What changes

1. New requirements tier — RuntimeRequirements.mutating_subagent(): workspace-edit surface without shell (opaque commands can't be scope-confined) plus the subagents capability, which only RuntimePolicy.mutating_subagents_enabled grants. So transactional_write children stay behind the autonomy policy: bold today, safe after the merge-execution (Phase B) and evidence (Phase C) PRs land.

2. Parser accepts the mutating contract — run_subagents tasks may declare merge_policy: "transactional_write" with a required, bounded, workspace-relative write_scope (≤16 paths, normalized; ../absolute/Windows-drive rejected). read_only tasks may NOT declare a scope. Unknown policies are rejected naming the supported set.

3. Policy-aware support resolution — computed from the strictest task: a mutating task on an ungated session is refused up front, naming the missing subagents capability; the child session factory is never invoked.

4. Runtime-enforced write scope — GenericEditRuntimeSession(write_scope_guard=...): path-bearing mutations outside the scope and all run_command actions fail with write_scope_violation before execution (same pre-execution guard pattern as the opaque-batch check). Recovery tools (rollback/repair/abort) keep working on previously validated targets. create_runtime_session threads the guard so factories can build confined children.

5. Orchestrator confinement check — a mutating child only runs on a session whose write_scope_guard is present and no broader than the task's declared scope; otherwise the child errors without running.

What this PR intentionally does NOT do

• No changeset export (Phase A / PR-2), no merge-plan execution (Phase B), no evidence probe (Phase C), and no safe flip (Phase D). safe behavior is unchanged; read_only children are byte-for-byte unchanged.

Tests

7 new tests: path normalization + scope matching (prefix-trick srcx vs src covered), parser contract, policy gating of support, unconfined/overbroad child refusal, policy-refused action (factory never invoked), bold end-to-end mutating child producing a transactional_parent_merge plan, and an in-loop guard test (in-scope write lands, out-of-scope write + run_command blocked with write_scope_violation).

Full affected surface green: 447 passed (agent_runtime, runtime_capabilities, runtime_modes, QA integration, provider smoke, autonomy level/policy).

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added write scope guards to confine child session write operations to declared file paths
  • Introduced transactional write merge policy for child sessions with automatic enforcement
  • Write operations and shell commands outside declared scopes are now blocked

• Tests

  • Added comprehensive validation tests for write scope handling and enforcement

[coderabbitai]

Warning

Review limit reached

@OBenner, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 32 minutes and 52 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ebb17b01-f249-445b-92d3-1bc768dd3cb1

📥 Commits

Reviewing files that changed from the base of the PR and between 1804470 and 118fa18.

📒 Files selected for processing (3)

• apps/backend/agents/runtime/adapters/generic_edit.py
• apps/backend/agents/runtime/subagents.py
• tests/test_agent_runtime.py

📝 Walkthrough

Walkthrough

This PR introduces a write-scope guard mechanism for confining mutating subagent writes to declared directory scopes. It adds a transactional-write merge policy, path normalization utilities, session-level enforcement, policy-aware orchestrator gating, and comprehensive unit/integration tests covering the entire feature.

Changes

Transactional Write Subagent Confinement

Layer / File(s)	Summary
Write-Scope Guard API and Merge Policy Constants apps/backend/agents/runtime/subagents.py, apps/backend/agents/runtime/__init__.py	Introduces TRANSACTIONAL_WRITE_SUBAGENT_MERGE_POLICY, SUPPORTED_SUBAGENT_MERGE_POLICIES, and is_mutating_subagent_task predicate to classify tasks as mutating or read-only; exports them for public use.
Mutating Subagent Capability Requirements apps/backend/agents/runtime/capabilities.py, apps/backend/agents/runtime/local_actions.py	Adds RuntimeRequirements.mutating_subagent() mode requiring text, structured output, filesystem read/edit, and subagents (without shell); defines MAX_SUBAGENT_WRITE_SCOPE_PATHS and MAX_SUBAGENT_WRITE_SCOPE_CHARS sizing limits.
Write-Scope Path Normalization and Validation apps/backend/agents/runtime/adapters/generic_edit.py	Implements normalize_write_scope_path (rejects absolute/Windows/escaped paths), normalize_write_scope_entries (deduplicates), and path_within_write_scope (subtree containment); uses regex to detect Windows drives.
Runtime Factory and Session Parameter Wiring apps/backend/agents/runtime/adapters/__init__.py, apps/backend/agents/runtime/adapters/generic_edit.py	create_runtime_session accepts optional write_scope_guard and threads it into GenericEditRuntimeSession and DirectApiAutonomousRuntimeSession constructors.
Generic Edit Session Enforcement apps/backend/agents/runtime/adapters/generic_edit.py	Session stores normalized write_scope_guard on initialization; _execute_action pre-checks scope violations; _write_scope_violation_result blocks run_command and out-of-scope writes with structured error results.
Subagent Task Parsing and Requirements apps/backend/agents/runtime/adapters/generic_edit.py	Task parsing validates merge_policy against supported set, derives RuntimeRequirements (mutating vs text-only) based on policy, and parses/validates task-level write_scope for transactional-write tasks with normalization and deduplication.
Subagent Runtime Pipeline apps/backend/agents/runtime/adapters/generic_edit.py	run_subagents selects between mutating_subagent and text-only capability modes; prompt text describes transactional-write children as restricted to declared scope with runtime enforcement.
Policy-Aware Orchestrator Support apps/backend/agents/runtime/subagents.py	RuntimeSubagentOrchestrator.support_for and resolve_runtime_subagent_support accept optional policy for capability gating; mutating_child_confinement_error validates session write_scope_guard covers no paths outside task's write_scope; _run_attempt pre-checks confinement.
Unit Tests - Path and Task Validation tests/test_agent_runtime.py	Tests verify path normalization rejects absolute/Windows/escaped paths and correctly handles workspace-relative paths; scope containment checks match subtrees; task parsing enforces merge-policy validation, write-scope normalization, and mutating-subagent requirements.
Integration Tests - Runtime Confinement tests/test_agent_runtime.py	Tests confirm mutating subagents are gated by policy default; generic-edit refuses mutating subagents without grant; write_scope_guard blocks out-of-scope writes and command mutations; direct-api autonomy enables end-to-end confined mutating subagent execution with transactional merge.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• OBenner/Auto-Coding#263: Both PRs modify create_runtime_session to route into DirectApiAutonomousRuntimeSession; #263 adds the allow_direct_api_autonomous gate, while this PR adds write_scope_guard wiring to that same code path.

Suggested labels

area/backend, feature, size/L

Poem

🐰 A rabbit hops through scopes so neat,
Write-scope guards keep mutations sweet.
Transactional writes stay in their place,
No escaping paths in cyberspace!
Policy gates guard the way,
Mutating subagents play today. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(runtime): enforce subagent write scopes behind the mutating policy' accurately and concisely summarizes the main feature being added: enforcing write scope constraints for subagent tasks behind a mutating subagents policy gate.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/subagent-write-scope-enforcement

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/backend/agents/runtime/adapters/generic_edit.py (1)

1802-1808: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Enforce write-scope violations before batch-isolation errors.

With current ordering, run_command inside an open batch returns a batch-boundary error instead of write_scope_violation. The guarded-session contract says guarded run_command should always fail as write-scope violation.

Suggested ordering fix

-        isolation_error = self._opaque_batch_mutation_result(action)
-        if isolation_error is not None:
-            return isolation_error
-
-        scope_error = self._write_scope_violation_result(action)
+        scope_error = self._write_scope_violation_result(action)
         if scope_error is not None:
             return scope_error
+
+        isolation_error = self._opaque_batch_mutation_result(action)
+        if isolation_error is not None:
+            return isolation_error

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/backend/agents/runtime/adapters/generic_edit.py` around lines 1802 -
1808, In run_command (in apps/backend/agents/runtime/adapters/generic_edit.py)
the call order should check write-scope violations before batch/isolation
errors: call self._write_scope_violation_result(action) first and return its
result if non-None, then call self._opaque_batch_mutation_result(action); i.e.,
swap the two checks so guarded run_command inside an open batch returns
write_scope_violation via _write_scope_violation_result instead of a
batch-boundary/_opaque_batch_mutation_result error.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/backend/agents/runtime/adapters/generic_edit.py`:
- Around line 74-77: The prompt for run_subagents contains contradictory
guidance: earlier text describes supporting transactional_write children with
enforced write_scope, but the later instruction still mandates read-only-only
usage and thus blocks the mutating path; update the run_subagents prompt text to
consistently allow transactional_write when policy permits and to explicitly
state that write operations must be restricted to the declared write_scope
enforced by the runtime (keep the read_only behavior for children without
transactional_write), ensure the prompt no longer contains any line that says
"read-only-only" or otherwise forbids writes, and keep references to
run_subagents, transactional_write, read_only, and write_scope so the intended
behavior is unambiguous.
- Around line 2908-2915: The current branch handling merge_policy ==
DEFAULT_SUBAGENT_MERGE_POLICY incorrectly treats an explicitly declared empty
list write_scope (raw_scope == []) as equivalent to no scope; update the logic
in the run_subagents handling to only accept raw_scope if it is truly
absent/unspecified (e.g., raw_scope is None or raw_scope == ()), and treat any
other explicit declaration (including []) as a violation: raise
GenericEditRuntimeError with the existing message using index, merge_policy, and
raw_scope context; keep the early return only for the truly unspecified case.

In `@apps/backend/agents/runtime/subagents.py`:
- Line 36: The type annotation on the function is_mutating_subagent_task uses a
quoted forward reference; remove the quotes so the parameter reads task:
RuntimeSubagentTask instead of task: "RuntimeSubagentTask". Update the function
signature in subagents.py accordingly (ensure RuntimeSubagentTask is imported or
available in scope).

---

Outside diff comments:
In `@apps/backend/agents/runtime/adapters/generic_edit.py`:
- Around line 1802-1808: In run_command (in
apps/backend/agents/runtime/adapters/generic_edit.py) the call order should
check write-scope violations before batch/isolation errors: call
self._write_scope_violation_result(action) first and return its result if
non-None, then call self._opaque_batch_mutation_result(action); i.e., swap the
two checks so guarded run_command inside an open batch returns
write_scope_violation via _write_scope_violation_result instead of a
batch-boundary/_opaque_batch_mutation_result error.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 70b3b402-1c96-4301-af91-227e30368ad6

📥 Commits

Reviewing files that changed from the base of the PR and between 7e5cd91 and 1804470.

📒 Files selected for processing (7)

• apps/backend/agents/runtime/__init__.py
• apps/backend/agents/runtime/adapters/__init__.py
• apps/backend/agents/runtime/adapters/generic_edit.py
• apps/backend/agents/runtime/capabilities.py
• apps/backend/agents/runtime/local_actions.py
• apps/backend/agents/runtime/subagents.py
• tests/test_agent_runtime.py

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud