cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

feat(security): enforce read-only actions #436

Merged
hamza.khyari merged 2 commits from feature/m4-security-readonly into master 2026-02-26 21:25:14 +00:00
Conversation 4 Commits 2 Files Changed 11
+955 -4
hamza.khyari commented 2026-02-25 14:58:11 +00:00
Member
Copy Link
Copy Source

Summary

Closes #322. Tightens read-only enforcement across ToolRuntime, ChangeSet builder, and CLI commands.

  • ToolRuntime — fixed _enforce_capabilities() to block ANY tool with writes=True when plan_read_only is set, removing the not cap.read_only loophole. Tool name always included in error.
  • ChangeSetCapture — added read_only flag and ReadOnlyViolationError; write-capable tools are rejected when wrapping on a read-only plan
  • CLI fail-fast — plan execute and plan apply abort before calling the service layer if plan.read_only=True
  • SkillContext — enforce_write_guard() already correctly includes tool name; no changes needed

Files Changed

File Status Description
src/cleveragents/tool/lifecycle.py MODIFIED Fixed _enforce_capabilities() condition
src/cleveragents/tool/builtins/changeset.py MODIFIED ReadOnlyViolationError + read_only flag
src/cleveragents/cli/commands/plan.py MODIFIED Fail-fast guards on execute and apply
features/security_readonly.feature NEW 18 BDD scenarios
features/steps/security_readonly_steps.py NEW Step definitions (90 steps)
docs/reference/read_only_actions.md NEW Reference documentation
robot/security_readonly.robot NEW Integration smoke tests
robot/helper_security_readonly.py NEW Robot helper script
benchmarks/security_readonly_bench.py NEW ASV benchmarks

Quality

  • 18 scenarios, 90 steps — all passing
  • Pyright: 0 errors
  • Ruff: all checks passed

Dependencies

  • Blocks issue #322 (this PR must be merged before the issue can be closed)
## Summary Closes #322. Tightens read-only enforcement across ToolRuntime, ChangeSet builder, and CLI commands. - **ToolRuntime** — fixed `_enforce_capabilities()` to block ANY tool with `writes=True` when `plan_read_only` is set, removing the `not cap.read_only` loophole. Tool name always included in error. - **ChangeSetCapture** — added `read_only` flag and `ReadOnlyViolationError`; write-capable tools are rejected when wrapping on a read-only plan - **CLI fail-fast** — `plan execute` and `plan apply` abort before calling the service layer if `plan.read_only=True` - **SkillContext** — `enforce_write_guard()` already correctly includes tool name; no changes needed ## Files Changed | File | Status | Description | |------|--------|-------------| | `src/cleveragents/tool/lifecycle.py` | MODIFIED | Fixed _enforce_capabilities() condition | | `src/cleveragents/tool/builtins/changeset.py` | MODIFIED | ReadOnlyViolationError + read_only flag | | `src/cleveragents/cli/commands/plan.py` | MODIFIED | Fail-fast guards on execute and apply | | `features/security_readonly.feature` | NEW | 18 BDD scenarios | | `features/steps/security_readonly_steps.py` | NEW | Step definitions (90 steps) | | `docs/reference/read_only_actions.md` | NEW | Reference documentation | | `robot/security_readonly.robot` | NEW | Integration smoke tests | | `robot/helper_security_readonly.py` | NEW | Robot helper script | | `benchmarks/security_readonly_bench.py` | NEW | ASV benchmarks | ## Quality - 18 scenarios, 90 steps — all passing - Pyright: 0 errors - Ruff: all checks passed ## Dependencies - Blocks issue #322 (this PR must be merged before the issue can be closed)
hamza.khyari self-assigned this 2026-02-25 14:58:11 +00:00
hamza.khyari force-pushed feature/m4-security-readonly from a8a290e776 to 4bc7313a34 2026-02-25 15:29:11 +00:00 Compare
freemo added a new dependency 2026-02-25 18:10:07 +00:00
#322 feat(security): enforce read-only actions
freemo added the
Type
Feature
 label 2026-02-25 18:10:20 +00:00
freemo added this to the v3.3.0 milestone 2026-02-25 18:10:21 +00:00
brent.edwards approved these changes 2026-02-25 22:32:52 +00:00
Dismissed
brent.edwards commented 2026-02-25 23:25:10 +00:00
Member
Copy Link
Copy Source

Code Review — PR #436: feat(security): enforce read-only actions

Reviewer: @brent.edwards | Review type: Comment-only

Nice work on the multi-layer framing and the breadth of tests/benchmarks. I found a few issues that should be addressed before merge, plus some test/doc gaps.

P1:must-fix — Unrelated CLI regressions slipped into this PR

src/cleveragents/cli/commands/plan.py removes the plan errors and plan resume commands and strips DoD/resume metadata from CLI output (dod_evaluation, last_completed_step, last_checkpoint_id). These are breaking changes unrelated to read-only enforcement. Please restore them or move the removal into a separate, explicitly-scoped PR with docs/tests updated.

P1:must-fix — Read-only enforcement not wired to the execution path

The new enforcement lives in ToolRuntime._enforce_capabilities and ChangeSetCapture.read_only, but the production execute path doesn’t appear to propagate plan.read_only into either:

  • ToolRuntime._enforce_capabilities relies on ToolExecutionContext.plan_read_only (src/cleveragents/tool/lifecycle.py), but I can’t find any production instantiation of ToolExecutionContext with plan_read_only set (only tests create it).
  • ChangeSetCapture is created in src/cleveragents/application/services/plan_executor.py without read_only, so the new guard never triggers in runtime.

Net: the new guard logic is only exercised by unit tests, not by the plan execution path (PlanExecutionContext + ToolRunner). Please wire plan.read_only through the execution context or enforce at the service layer so this actually blocks writes in real execution.

P2:should-fix — Tests are stubbing the behavior instead of exercising code paths

features/steps/security_readonly_steps.py uses local exceptions instead of calling the real code paths in several scenarios:

  • CLI fail-fast: plan apply check is simulated with a manual BusinessRuleViolation, not by invoking plan lifecycle-apply or PlanLifecycleService.
  • Action→Skill compatibility: test raises a local ValueError, but I can’t find production validation enforcing this anywhere in src/cleveragents.
  • Plan→ToolExecutionContext propagation: test just constructs ToolExecutionContext directly; it doesn’t verify runtime wiring.

These tests will pass even if enforcement is missing. Consider replacing with integration tests that exercise the CLI/service and real validation paths.

P2:should-fix — Doc claims don’t match implementation

docs/reference/read_only_actions.md claims Action→Skill compatibility validation and propagation through ToolExecutionContext + ChangeSetCapture, but I don’t see those hooks in production code. Either implement the missing wiring or update the doc to reflect current behavior. Also, the test command uses raw python3 -m behave; repo convention is to run via nox sessions.

Happy to re-review after those are addressed.

## Code Review — PR #436: feat(security): enforce read-only actions **Reviewer:** @brent.edwards | **Review type:** Comment-only Nice work on the multi-layer framing and the breadth of tests/benchmarks. I found a few issues that should be addressed before merge, plus some test/doc gaps. --- ### P1:must-fix — Unrelated CLI regressions slipped into this PR `src/cleveragents/cli/commands/plan.py` removes the `plan errors` and `plan resume` commands and strips DoD/resume metadata from CLI output (`dod_evaluation`, `last_completed_step`, `last_checkpoint_id`). These are breaking changes unrelated to read-only enforcement. Please restore them or move the removal into a separate, explicitly-scoped PR with docs/tests updated. --- ### P1:must-fix — Read-only enforcement not wired to the execution path The new enforcement lives in `ToolRuntime._enforce_capabilities` and `ChangeSetCapture.read_only`, but the production execute path doesn’t appear to propagate `plan.read_only` into either: - `ToolRuntime._enforce_capabilities` relies on `ToolExecutionContext.plan_read_only` (`src/cleveragents/tool/lifecycle.py`), but I can’t find any production instantiation of `ToolExecutionContext` with `plan_read_only` set (only tests create it). - `ChangeSetCapture` is created in `src/cleveragents/application/services/plan_executor.py` without `read_only`, so the new guard never triggers in runtime. Net: the new guard logic is only exercised by unit tests, not by the plan execution path (`PlanExecutionContext` + `ToolRunner`). Please wire `plan.read_only` through the execution context or enforce at the service layer so this actually blocks writes in real execution. --- ### P2:should-fix — Tests are stubbing the behavior instead of exercising code paths `features/steps/security_readonly_steps.py` uses local exceptions instead of calling the real code paths in several scenarios: - **CLI fail-fast**: `plan apply` check is simulated with a manual `BusinessRuleViolation`, not by invoking `plan lifecycle-apply` or `PlanLifecycleService`. - **Action→Skill compatibility**: test raises a local `ValueError`, but I can’t find production validation enforcing this anywhere in `src/cleveragents`. - **Plan→ToolExecutionContext propagation**: test just constructs `ToolExecutionContext` directly; it doesn’t verify runtime wiring. These tests will pass even if enforcement is missing. Consider replacing with integration tests that exercise the CLI/service and real validation paths. --- ### P2:should-fix — Doc claims don’t match implementation `docs/reference/read_only_actions.md` claims Action→Skill compatibility validation and propagation through `ToolExecutionContext` + `ChangeSetCapture`, but I don’t see those hooks in production code. Either implement the missing wiring or update the doc to reflect current behavior. Also, the test command uses raw `python3 -m behave`; repo convention is to run via `nox` sessions. --- Happy to re-review after those are addressed.
hamza.khyari force-pushed feature/m4-security-readonly from 6c46ee37cb to 8578cfdead 2026-02-26 00:57:54 +00:00 Compare
hamza.khyari dismissed brent.edwards's review 2026-02-26 00:57:54 +00:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

hamza.khyari force-pushed feature/m4-security-readonly from 8578cfdead to 03677318c2 2026-02-26 14:35:13 +00:00 Compare
hamza.khyari commented 2026-02-26 15:04:57 +00:00
Author
Member
Copy Link
Copy Source

Thanks for the thorough review @brent.edwards. Pushed 17c5fe59 addressing all points.

P1 #1 — CLI regressions in plan.py

False positive. I re-examined the diff for plan.py and it is purely additive: +16 lines, 0 deletions. The plan errors command, plan resume command, and all DoD/resume metadata fields (dod_evaluation, last_completed_step, last_checkpoint_id) are present and unchanged. No lines were removed. The diff only adds the two read-only fail-fast guards. You may have been looking at a stale diff or a different branch state.

P1 #2 — Read-only enforcement not wired to execution path

Fixed. Added read_only: bool = False kwarg to ExecuteStubActor.execute(), which now passes read_only=read_only to the ChangeSetCapture constructor. PlanExecutor._run_execute_with_stub() reads plan.read_only via getattr(plan, "read_only", False) and forwards it. This wires the guard through the actual plan execution path.

P2 #1 — Tests stubbing behavior instead of exercising code paths

Fixed. Replaced the stubbed tests:

  • CLI fail-fast → Replaced with ExecuteStubActor integration test that uses unittest.mock.patch to spy on ChangeSetCapture.__init__ and verify read_only is propagated through real code.
  • Action→Skill compatibility → Removed the claim entirely since that validation doesn't exist in production code yet. Replaced scenarios with additional SkillContext.enforce_write_guard tests that exercise the real production code path.
  • Plan→ToolExecutionContext propagation tests remain (they construct from the plan model, which is the actual mechanism).

P2 #2 — Doc claims don't match implementation

Fixed. Updated docs/reference/read_only_actions.md:

  • Removed Layer 5 (Action-Skill Compatibility) — not implemented in production code yet.
  • Added ExecuteStubActor wiring description showing how plan.read_only propagates to ChangeSetCapture.
  • Updated the propagation diagram to reflect actual execution layers.
  • Fixed test command from python3 -m behave to nox -s unit_tests.

All 18 scenarios / 86 steps pass, lint clean. Ready for re-review.

Thanks for the thorough review @brent.edwards. Pushed `17c5fe59` addressing all points. --- ### P1 #1 — CLI regressions in `plan.py` **False positive.** I re-examined the diff for `plan.py` and it is purely additive: +16 lines, 0 deletions. The `plan errors` command, `plan resume` command, and all DoD/resume metadata fields (`dod_evaluation`, `last_completed_step`, `last_checkpoint_id`) are present and unchanged. No lines were removed. The diff only adds the two read-only fail-fast guards. You may have been looking at a stale diff or a different branch state. --- ### P1 #2 — Read-only enforcement not wired to execution path **Fixed.** Added `read_only: bool = False` kwarg to `ExecuteStubActor.execute()`, which now passes `read_only=read_only` to the `ChangeSetCapture` constructor. `PlanExecutor._run_execute_with_stub()` reads `plan.read_only` via `getattr(plan, "read_only", False)` and forwards it. This wires the guard through the actual plan execution path. --- ### P2 #1 — Tests stubbing behavior instead of exercising code paths **Fixed.** Replaced the stubbed tests: - **CLI fail-fast** → Replaced with `ExecuteStubActor` integration test that uses `unittest.mock.patch` to spy on `ChangeSetCapture.__init__` and verify `read_only` is propagated through real code. - **Action→Skill compatibility** → Removed the claim entirely since that validation doesn't exist in production code yet. Replaced scenarios with additional `SkillContext.enforce_write_guard` tests that exercise the real production code path. - **Plan→ToolExecutionContext** propagation tests remain (they construct from the plan model, which is the actual mechanism). --- ### P2 #2 — Doc claims don't match implementation **Fixed.** Updated `docs/reference/read_only_actions.md`: - Removed Layer 5 (Action-Skill Compatibility) — not implemented in production code yet. - Added `ExecuteStubActor` wiring description showing how `plan.read_only` propagates to `ChangeSetCapture`. - Updated the propagation diagram to reflect actual execution layers. - Fixed test command from `python3 -m behave` to `nox -s unit_tests`. --- All 18 scenarios / 86 steps pass, lint clean. Ready for re-review.
hamza.khyari force-pushed feature/m4-security-readonly from 17c5fe5979 to dd2a77f30a 2026-02-26 15:25:14 +00:00 Compare
hamza.khyari force-pushed feature/m4-security-readonly from dd2a77f30a to 09a485c4b4 2026-02-26 17:55:34 +00:00 Compare
brent.edwards approved these changes 2026-02-26 19:44:58 +00:00
brent.edwards left a comment
Member
Copy Link
Copy Source

Approved!

Approved!
hamza.khyari force-pushed feature/m4-security-readonly from 09a485c4b4 to 493e5cf8a1 2026-02-26 20:34:12 +00:00 Compare
hamza.khyari scheduled this pull request to auto merge when all checks succeed 2026-02-26 20:34:19 +00:00
hamza.khyari merged commit 13b1eb45a8 into master 2026-02-26 21:25:14 +00:00
freemo added the
State
Completed
 label 2026-03-04 00:58:37 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
brent.edwards
Labels
Clear labels
auto/needs-reevaluation
Controller deferred this PR; awaiting Phase 6+ scope-evaluator or operator re-enablement.
 controller-managed
Auto-agents controller manages this PR/issue (see tools/controller/deploy/RUNBOOK.md). Remove this label to abandon controller management.
 overdue
auto/blocked-by-deps
PR blocked by an open issue dependency. Operator must close the dep (or remove the dependency link) before the merge driver can act. Auto-cleared by merge_drive when no open deps remain.
 auto/ci-timeout
Most recent merge cycle hit CI timeout. Driver excludes this PR while last merge_cycle row is < 30 min old; label persists thereafter as visible history.
 auto/claimed-implementer
Currently being processed by an implementer worker.
 auto/claimed-merge
Currently being processed by the merge driver.
 auto/claimed-reviewer
Currently being processed by a reviewer worker.
 auto/driver-down
Merge driver heartbeat stale; pipeline halted. Closed automatically on next clean tick.
 auto/invariant-violation
Detected master commit violating the strict merge invariant. Tracked as an issue (not a PR label); kept here for label completeness.
 auto/last-attempt-tier-0
In-cycle escalation: most recent attempt ran at the Tier 0 slot (`tier-0`). Slot's model defined in .opencode/models/tiers.yaml.
 auto/last-attempt-tier-1
In-cycle escalation: most recent attempt ran at the Tier 1 slot (`tier-1`). Slot's model defined in .opencode/models/tiers.yaml.
 auto/last-attempt-tier-2
In-cycle escalation: most recent attempt ran at the Tier 2 slot (`tier-2`). Slot's model defined in .opencode/models/tiers.yaml. Gated behind IMPLEMENTER_ESCALATION_TIER2_ENABLED.
 auto/last-attempt-tier-min
In-cycle escalation: most recent attempt ran at the Tier -1 slot (`tier-min`). Slot's model defined in .opencode/models/tiers.yaml. Suffix is ``-min`` (not ``--1``) so the Forgejo UI reads naturally.
 Automation Tracking
Tracking issues used by the AI Automation system for agents to communicate and report.
 auto/needs-conflict-resolution
Rebase conflict needs LLM conflict-resolver.
 auto/needs-implementer
Failing CI needs implementer attention.
 auto/postmortem
Documenting a driver incident or rollback.
 auto/ready-to-merge
Reviewer has APPROVED this PR and no later REQUEST_CHANGES is outstanding. The merge driver requires this label to even consider a PR for merging. Set by the reviewer worker on APPROVE; cleared on REQUEST_CHANGES.
 auto/restart-throttled
Train repeatedly lost master-tempo races. Driver excludes via merge_cycle until cooldown elapses; label persists as visible history.
 auto/revert
Revert PR backing out an invariant violation. Fast-tracked through the merge driver.
 auto/sentinel
Sentinel PR duplicated from upstream into a personal fork by tools/duplicate_prs_to_fork.py for pipeline testing. Lives only in the fork; the canonical pipeline never sees it.
 auto/stale-inactivity
No implementer activity for N days. Flagged for human review. Auto-cleared on next push to head branch.
 auto/unstable
Repeatedly fails on current master (>= 3 ci-fail-on-rebased-sha releases in 12 h). Excluded from driver until human triage.
 Blocked
A ticket in a blocked state and unable to complete until some other task is completed first.
Bounty
$100
A bounty of $100 for any open-source contributor who provides a MR that solves this issue
Bounty
$1000
A bounty of $1000 for any open-source contributor who provides a MR that solves this issue
Bounty
$10000
A bounty of $10000 for any open-source contributor who provides a MR that solves this issue
Bounty
$20
A bounty of $20 for any open-source contributor who provides a MR that solves this issue
Bounty
$2000
A bounty of $2000 for any open-source contributor who provides a MR that solves this issue
Bounty
$250
A bounty of $250 for any open-source contributor who provides a MR that solves this issue
Bounty
$50
A bounty of $50 for any open-source contributor who provides a MR that solves this issue
Bounty
$500
A bounty of $500 for any open-source contributor who provides a MR that solves this issue
Bounty
$5000
A bounty of $5000 for any open-source contributor who provides a MR that solves this issue
Bounty
$750
A bounty of $750 for any open-source contributor who provides a MR that solves this issue
MoSCoW
Could have
Could have feature in order to satisfy the epic/legendary.
MoSCoW
Must have
Must have feature in order to satisfy the epic/legendary.
MoSCoW
Should have
Should have feature in order to satisfy the epic/legendary.
Needs Feedback
There are questions in the ticket that can not be completed until the project owner provides clarity.
Points
1
1 man-hours worth of work for an expert with no learning curve.
Points
13
13 man-hours worth of work for an expert with no learning curve.
Points
2
2 man-hours worth of work for an expert with no learning curve.
Points
21
21 man-hours worth of work for an expert with no learning curve.
Points
3
3 man-hours worth of work for an expert with no learning curve.
Points
34
34 man-hours worth of work for an expert with no learning curve.
Points
5
5 man-hours worth of work for an expert with no learning curve.
Points
55
55 man-hours worth of work for an expert with no learning curve.
Points
8
8 man-hours worth of work for an expert with no learning curve.
Points
88
88 man-hours worth of work for an expert with no learning curve.
Priority
Backlog
This ticket has backlogged priority and is not to be worked on yet
Priority
CI Blocker
Critical priority issue that blocks CI/CD pipeline and prevents PR merges
Priority
Critical
The priority is critical
Priority
High
The priority is high
Priority
Low
The priority is low
Priority
Medium
The priority is medium
Signed-off: Owner
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Signed-off: Scrum Master
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Signed-off: Tech Lead
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Spike
A ticket for learning a tool or technology that is needed to be able to do future planning and design.
State
Completed
The ticket has been fully implemented, completed, and merged with the source code. This label should only be applied once a ticket is closed.
State
Duplicate
A ticket that represents the same content as an existing ticket.
State
In Progress
A ticket that is actively being developed.
State
In Review
A ticket that has had some code completed to implement but is waiting to pass peer review and is not yet merged in.
State
Paused
This ticket's work started but wasn't finished. It's on hold (likely in a feature branch) and will be resumed later, either due to a blocker or a delay.
State
Unverified
All new tickets start in this state. A developer may set it to show the ticket is unverified. This means we haven't agreed to work on it. It will either move to a verified state or be closed as wontdo.
State
Verified
The issue has been verified by a developer as legitimate. It will be worked on and verified tickets are now considered part of the backlog.
State
Wont Do
This ticket has been decided it wont be done. This may mean the bug has been determined to not be real (cant verify) or the feature is one we have decided we dont want to adopt.
Type
Automation
Any edits or discussion about the AI automated coding system.
Type
Bug
Something that doesnt work as intended.
Type
Discussion
Anytime a ticket represents a discussion about a subject and doesnt fall into one of the other categories.
Type
Documentation
An error or improvement needed in the documentation.
Type
Epic
Any first tier epic. That is, an epic which contains only issues as children and will not have sub-epics.
Type
Feature
Some new functionality not present.
Type
Legendary
A type of Epic which will contain other Epics.
Type
Refactor
A code change that restructures existing code without changing its external behavior.
Type
Support
Someone needs help using the project.
Type
Task
A generic task that doesnt fit into the other type categories.
Type
Testing
Work exclusively focusing on fixing or expanding testing.
No Label
State
Completed
Type
Feature
Milestone
No items
No Milestone v3.3.0
Projects
Clear projects
No project
Assignees
Clear assignees
aditya (Aditya Chhabra) aleenaumair (Aleena Umair) brent.edwards (Brent Edwards) CoreRasurae (Luis Mendes) drew (Drew Morris) eugen.thaci (Eugen Thaci) freemo (Jeffrey Phillips Freeman) HAL9000 (HAL 9000) HAL9001 (HAL9001) hamza.khyari (Hamza Khyari) hurui200320 (Rui Hu) justin.morris khird (Kyle Hird) org.cleveragents
No Assignees hamza.khyari
3 Participants
Notifications
Due Date
No due date set.
Blocks
#322 feat(security): enforce read-only actions
cleveragents/cleveragents-core
Reference: cleveragents/cleveragents-core#436
Delete Branch "feature/m4-security-readonly"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?