docs: ADR 32 — safe-push wrapper binary for sandboxed agents

[maruiz93]

Summary

• Adds ADR 0032: specifies safe-push, a Go wrapper binary that provides mandatory policy enforcement for git push operations inside OpenShell sandboxes
• Extends ADR 0025's Tier 2 wrapper binary pattern with concrete binary design, L7 enforcement model, three-category enforcement analysis, and policy delivery constraints
• Documents coexistence with Tier 1 post-script push (post-script preferred for public/high-risk repos; safe-push for private/low-risk environments)
• Related "Push" robustness. #252

Key design decisions

• Scoped to push only — analysis shows push is the only git network operation where L7 cannot distinguish behavioral variants (force vs regular, branch targeting, deletion)
• Policy baked into image — runtime config (env vars, writable files) is not viable because the agent controls all writable state inside the sandbox; Landlock-protected paths can only be populated at image build time
• fork+exec, not direct exec — preserves safe-push as parent in process tree for L7 ancestry tracking
• Git config is insufficient — agent can bypass via -c flags, env var redirection, --no-verify, and local config overrides

Test plan

• make lint passes (ADR status, frontmatter, numbers, gitleaks)
• Team reviews the three-category enforcement model and push-only scoping
• Team reviews policy delivery constraints and future customization options (multiple images vs ephemeral layering)

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://134e67e4-site.fullsend-ai.workers.dev

Commit: 93a1f49c3b67a1e2ebea40072bb0819b28e2c850

[fullsend-ai-review]

Review: #716

Head SHA: 2c591a4
Timestamp: 2026-05-08T00:00:00Z
Outcome: approve

Summary

This PR adds ADR 0032, a well-structured design document for the safe-push wrapper binary that extends ADR 0025's Tier 2 credential delivery model. The ADR thoroughly analyzes the push enforcement problem across three categories (coarse network access, fine-grained push semantics, local operations), correctly scopes safe-push to category 2 only, and documents the full enforcement chain (Landlock + L7 process-tree tracking + policy file tamper resistance). The design properly maintains credential separation — safe-push never sees credentials — and explicitly frames Tier 2 as a scoped relaxation of the security threat model's constraint that agents cannot take forge actions directly, with Tier 1 post-script push remaining the default for public/high-risk repos. The bundled workflow fix (adding templates/shim-workflow.yaml to the repo-maintenance push trigger) is a small, correct change ensuring shim template updates propagate to enrolled repos, with a corresponding test that validates the trigger paths.

Findings

No critical, high, medium, low, or info findings.

Footer

Outcome: approve
This review applies to SHA 2c591a4cc36909b35d3bc5d98ddeed3881c8e373. Any push to the PR head clears this review and requires a new evaluation.

Previous run

Review: #716

Head SHA: 2268ad4
Timestamp: 2026-05-07T00:00:00Z
Outcome: approve

Summary

This ADR specifies safe-push, a Go wrapper binary for mandatory push policy enforcement inside OpenShell sandboxes. The document is well-structured, technically sound, and appropriately scoped. It extends ADR 0025's Tier 2 wrapper binary pattern with concrete binary design, L7 enforcement integration, policy delivery constraints, and coexistence with Tier 1 post-script push. The three-category enforcement model (coarse network access, fine-grained push semantics, local operations) correctly identifies the enforcement gap that L7 filtering alone cannot address. No critical, high, or medium findings were identified across all six review dimensions.

Findings

Info

• [style-convention] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md — The ADR number 0032 skips 0029–0031 relative to the highest merged ADR (0028). Open PRs exist for 0029, 0030, and 0031, so this is expected, but if any of those PRs are abandoned, the gap will persist. The renumber-adr skill can address this before merge if needed. The lint checks only validate uniqueness, not contiguity, so this passes CI.

• [intent-alignment] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md — The PR body says "Related "Push" robustness. #252" rather than "Closes "Push" robustness. #252" or "Fixes "Push" robustness. #252". This is appropriate since the ADR is a design document and does not implement the solution — the issue should remain open until safe-push is implemented.

• [correctness] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md:135-140 — The default policy YAML example denies tags: deny but the Consequences section does not mention tag push restrictions. Minor documentation gap; no behavioral impact since this is a design doc.

• [correctness] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md:152-155 — The coexistence section notes that "the same image may be used in both high-risk (Tier 1) and low-risk (Tier 2) environments" and that "The L7 policy — not the image — determines whether the agent can actually reach the remote." This is a sound design choice that keeps the image uniform, but it means a Tier 1 environment with safe-push in the image but no L7 route to git-receive-pack is secure by default. Worth validating in integration tests when implemented.

Footer

Outcome: approve
This review applies to SHA 2268ad4e93adf70f1cf88ad969a01844c454d3f6. Any push to the PR head clears this review and requires a new evaluation.

Previous run (2)

Review: #716

Head SHA: a985993
Timestamp: 2026-05-07T00:00:00Z
Outcome: approve

Summary

This PR adds ADR 0032, specifying the safe-push wrapper binary design for sandboxed agents. The ADR is well-structured, technically thorough, and directly extends ADR 0025's Tier 2 credential delivery model with concrete binary design, enforcement categorization, and policy delivery analysis. The three-category enforcement model (coarse network, fine-grained push semantics, local operations) is a clear contribution that clarifies where each enforcement mechanism applies and — critically — where mandatory enforcement is not possible. The ADR aligns with issue #252's goal of improving push robustness and correctly scopes itself to the push operation where L7 cannot distinguish behavioral variants. No correctness, security, or injection concerns were found.

Findings

Medium

• [style/conventions] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md:22 — The Status section uses Proposed (extends ADR 0025) with a parenthetical note. All existing ADRs in the repo use bare status values (Proposed, Accepted, etc.) without parenthetical annotations in the Status section body. The relationship to ADR 0025 is already captured in the frontmatter relates_to field and in the Context section's opening sentence. Consider using just Proposed for consistency with the template and other ADRs, and keeping the "extends" note in the Context where it already appears.
  Remediation: Change line 22 from Proposed (extends [ADR 0025](...)) to Proposed.

Info

• [correctness] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md — ADR numbering: this is ADR 0032 while the highest merged ADR is 0028. ADRs 0029, 0030, and 0031 exist as open PRs (Add agent execution sandbox architecture ADR #659, docs: ADR 30 — OpenShell sandbox interaction model #715/docs: ADR 0031 — reusable workflows for action-installed distribution #688, docs: ADR 0033 — per-repo installation mode #707). The numbering is correct assuming those PRs merge first or concurrently. Note that there are two competing PRs for ADR 0030 (docs: ADR 30 — OpenShell sandbox interaction model #715 and docs: ADR 0031 — reusable workflows for action-installed distribution #688) — those will need to be reconciled separately.

• [style/conventions] docs/ADRs/0032-safe-push-wrapper-for-sandboxed-agents.md — The ADR template includes an optional "Options" section. This ADR discusses alternatives inline (git config insufficiency in Context, policy delivery options A/B/C in Decision) rather than in a dedicated section. This is a reasonable choice given the alternatives are tightly coupled to their respective subsections, but worth noting for consistency awareness.

Footer

Outcome: approve
This review applies to SHA a9859931711bbf166b50dce4a075754104af7823. Any push to the PR head clears this review and requires a new evaluation.

[ralphbean]

Solid ADR — the three-category enforcement model is well-reasoned and the push-only scoping is convincing. The analysis of git config bypass vectors and Landlock policy delivery constraints is thorough. A few notes inline for future iterations, nothing blocking.

Strategic question: Is the wrapper binary pattern (process-tree–gated policy enforcement) useful enough to be a first-class OpenShell feature rather than something fullsend builds on top? If OpenShell natively supported "policy gate binary → child binary" with process-tree L7 matching as a primitive, safe-push would be a thin configuration layer rather than a custom binary. Worth exploring upstream.

[github-actions]

fullsend review is working on this — view logs

[github-actions]

fullsend review is working on this — view logs