docs(adr): ADR-015 AgentSH Integration for execution-layer security#769
docs(adr): ADR-015 AgentSH Integration for execution-layer security#769
Conversation
Research and plan integration with canyonroad/agentsh, an execution-layer security gateway for AI agents. Identifies 8 key architectural lessons (5-way decision model, redirect/steering, subprocess visibility, structured audit, workspace checkpoints, policy-as-code, session model, env security) and proposes a 4-phase integration plan from pattern adoption to enterprise features. https://claude.ai/code/session_016L7E3aAp1Z3xZVhdaAYF9m
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Props for pushing this forward! 👏 |
github-actions
bot
added
documentation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Adds a new architecture decision record (ADR-015) describing an optional integration of AgentSH as an execution-layer security gateway for Caro, plus updates the ADR index to include it.
Changes:
- Added
docs/adr/ADR-015-agentsh-integration.mdoutlining a two-track approach (core pattern adoption + optional agentsh backend) and a phased implementation plan. - Updated
docs/adr/README.mdto index ADR-015.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/adr/ADR-015-agentsh-integration.md | New ADR describing execution-layer security integration patterns, architecture, phases, and trade-offs. |
| docs/adr/README.md | Adds ADR-015 entry to the ADR index table. |
|
|
||
| ### Why This Matters Now | ||
|
|
||
| - ADR-010 proposed bubblewrap sandbox for execution isolation — agentsh is a more complete solution that subsumes sandboxing with runtime policy enforcement |
There was a problem hiding this comment.
The Context section says agentsh “subsumes sandboxing” (line 24), but later this ADR frames ADR-010 (bubblewrap) as complementary and a fallback. Consider rewording the earlier claim to avoid an internal contradiction (e.g., clarify that agentsh adds runtime governance while sandboxing still provides isolation).
| - ADR-010 proposed bubblewrap sandbox for execution isolation — agentsh is a more complete solution that subsumes sandboxing with runtime policy enforcement | |
| - ADR-010 proposed bubblewrap sandbox for execution isolation — agentsh complements sandboxing by adding runtime policy enforcement and governance, while sandboxing continues to provide process isolation and serves as a fallback when agentsh is unavailable |
| **Goal**: Adopt agentsh patterns into caro core | ||
|
|
||
| 1. **Decision enum**: Replace `ValidationResult.allowed: bool` with `Decision` enum | ||
| 2. **Redirect support**: When blocking a command, suggest safer alternatives that auto-execute |
There was a problem hiding this comment.
Phase 1 mentions redirect suggestions that “auto-execute”. Auto-executing a replacement command can bypass the human-approval step and could be unsafe for high-risk intents; consider specifying that redirects still require explicit user confirmation (or are represented as an Approve+Redirect flow) before execution.
| 2. **Redirect support**: When blocking a command, suggest safer alternatives that auto-execute | |
| 2. **Redirect support**: When blocking a command, suggest safer alternatives that the user can explicitly approve and execute (Approve+Redirect flow), never auto-execute |
| /// Execute but quarantine effects for rollback | ||
| SoftExecute { checkpoint_id: String }, |
There was a problem hiding this comment.
The decision model references AgentSH’s soft_delete, but the proposed Decision enum introduces SoftExecute. If this is an intentional divergence, it would help to explicitly document the mapping (AgentSH soft_delete → Caro SoftExecute) or align the naming to reduce confusion for implementers.
| /// Execute but quarantine effects for rollback | |
| SoftExecute { checkpoint_id: String }, | |
| /// Execute but quarantine effects for rollback (AgentSH `soft_delete`) | |
| SoftDelete { checkpoint_id: String }, |
| 1. **Detection**: Check for `agentsh` binary in PATH at startup | ||
| 2. **Session management**: Create agentsh session per caro invocation (or per agent loop) | ||
| 3. **Policy mapping**: Translate `SafetyLevel` → agentsh policy YAML | ||
| 4. **Execution routing**: `agentsh exec $SID -- <command>` instead of direct shell |
There was a problem hiding this comment.
Phase 2 includes a concrete agentsh invocation (agentsh exec $SID -- <command>). Since this ADR doesn’t cite agentsh’s actual CLI contract, consider labeling this as pseudocode and/or linking to the upstream docs for the exact command format to avoid documenting an incorrect interface.
| 4. **Execution routing**: `agentsh exec $SID -- <command>` instead of direct shell | |
| 4. **Execution routing**: Route commands through an agentsh execution session (pseudocode: `agentsh exec $SID -- <command>`; consult the [agentsh documentation](https://github.com/canyonroad/agentsh) for the exact CLI contract) instead of invoking the shell directly. |
| 2. **Platform coverage gap**: Full enforcement only on Linux initially (70-90% macOS, 85% Windows) | ||
| 3. **Added latency**: Session creation + policy evaluation adds ~50-200ms per execution |
There was a problem hiding this comment.
The trade-offs list includes specific platform-coverage percentages and a per-execution latency estimate (e.g., “70–90% macOS”, “~50–200ms”). If these numbers aren’t backed by measurements or an upstream reference, consider removing them or explicitly marking them as rough, unverified estimates with a citation link.
| 2. **Platform coverage gap**: Full enforcement only on Linux initially (70-90% macOS, 85% Windows) | |
| 3. **Added latency**: Session creation + policy evaluation adds ~50-200ms per execution | |
| 2. **Platform coverage gap**: Full enforcement only on Linux initially; macOS and Windows support are partial and may lag Linux features. | |
| 3. **Added latency**: Session creation and policy evaluation introduce additional latency per execution that must be measured and monitored. |
Website Claims Verification ReportRun ID: 22508530717 Platform Resultsclaims-report-macos-latest{
"suite": "website-claims",
"platform": "macos-latest",
"timestamp": "2026-02-28T00:02:52Z",
"passed": 84,
"skipped": 0,
"warnings": 1,
"run_id": "22508530717",
"sha": "f3d0c7ed431377d4f204f9c6f84953a430bafa1e"
}claims-report-ubuntu-latest{
"suite": "website-claims",
"platform": "ubuntu-latest",
"timestamp": "2026-02-28T00:01:13Z",
"passed": 84,
"skipped": 0,
"warnings": 1,
"run_id": "22508530717",
"sha": "f3d0c7ed431377d4f204f9c6f84953a430bafa1e"
}DocumentationNext Steps
|
Description
This PR introduces ADR-015, a comprehensive architecture decision record for integrating AgentSH—an execution-layer security gateway—into Caro's command execution pipeline. The ADR proposes a two-track approach: adopting agentsh's architectural patterns into Caro's core (regardless of agentsh availability) and optionally routing execution through agentsh when installed.
Motivation
Caro's current safety validation relies on 52+ regex patterns that catch known dangerous commands before execution. However, this approach has fundamental blind spots:
AgentSH addresses these gaps with syscall-level interception and a richer decision model (allow/deny/approve/redirect/soft_delete) that enables defense-in-depth security for AI agent workflows.
Changes Made
New file:
docs/adr/ADR-015-agentsh-integration.md(385 lines)Updated file:
docs/adr/README.mdKey Architectural Insights
The ADR proposes evolving Caro's binary
allowed: boolvalidation result into a five-wayDecisionenum:Allow: Execute directlyDeny: Block with reasonApprove: Require human confirmationRedirect: Suggest safer alternative (new)SoftExecute: Execute with checkpoint for rollback (new)This enables "steering" patterns where risky-but-legitimate commands are redirected to safer equivalents rather than blocked outright.
Type of Change
Checklist
Documentation
Related Issues and Specs
Additional Context
Technical Decisions
Future Work
By submitting this PR, I confirm that:
https://claude.ai/code/session_016L7E3aAp1Z3xZVhdaAYF9m
Summary by cubic
Adds ADR-015 proposing AgentSH as an optional execution backend and a phased plan to adopt execution-layer security patterns in Caro; updates the ADR index.
Written for commit 92c7d9f. Summary will update on new commits.