feat(zerocommands): add typed SandboxGrantSnapshot contract

[gnanam1990]

Summary

The merged permission and verification event contracts added typed snapshots for config, providers, models, and sessions, but the persistent sandbox grant store (internal/sandbox/grants.go) still exposes only sandbox.Grant directly. The TUI render path, the headless zero sandbox command, and PR/CI automation all need a typed snapshot so they do not hand-roll map[string]any payloads and do not accidentally leak grant reasons that contain API keys or tokens.

This commit adds SandboxGrantSnapshot alongside the existing ProviderSnapshot, ModelSnapshot, SessionSnapshot, and SessionTreeSnapshot in internal/zerocommands. The snapshot mirrors the format of the existing typed contracts:

• ToolName, Decision, MaxAutonomy, ApprovedAt are copied verbatim from the underlying grant. They are non-secret metadata.
• Reason is run through the standard redaction pipeline before it is copied, so any secret material the user typed when granting is masked before the snapshot leaves the runtime.
• All string fields are trimmed. An empty or whitespace-only Reason becomes an empty Reason in the snapshot so JSON output omits the field.

Two constructors are provided:

• SandboxGrantSnapshotFromGrant(grant) for a single grant.
• SandboxGrantSnapshots(grants) for a slice. Output is sorted alphabetically by ToolName so consumers (TUI, headless, JSON output) see a deterministic ordering. An empty input returns a non-nil empty slice so JSON output is always [] and never null.

A matched/unmatched helper is also added:

• SandboxGrantMatchSnapshotFromLookup(toolName, lookup) pairs the typed snapshot with a Matched boolean. When the lookup did not match, the returned snapshot has Matched=false and a nil Grant pointer, so consumers can render the absence without inspecting an error or a typed zero value.

Tests

• TestSandboxGrantSnapshotFromGrantRedactsReasonAndTrimsFields: verifies the secret in the reason is masked and the surrounding fields are trimmed.
• TestSandboxGrantSnapshotFromGrantEmptyReasonBecomesEmpty: verifies whitespace-only reasons normalize to the empty string.
• TestSandboxGrantSnapshotsSortsByToolNameAndReturnsEmptySliceForEmptyInput: verifies alphabetical sort and that nil input returns a non-nil empty slice whose JSON encoding is [].
• TestSandboxGrantMatchSnapshotFromLookupMatchedAndUnmatched: verifies the matched and unmatched code paths.
• TestSandboxGrantSnapshotJSONShapeIsStable: verifies every JSON key is present so downstream consumers can rely on the shape.

Verification

• go build ./...
• go vet ./...
• go test -count=1 -p 1 ./internal/zerocommands/... ./internal/sandbox/... ./internal/redaction/...

DRI

Gnanam (runtime core owner per docs/WORK_SPLIT_PRD.md §4). Connects zero sandbox command rendering, the TUI grants panel, and PR/CI automation consumers to the persistent grant store without leaking grant reasons.

Out of scope

This PR only adds the typed contract and the constructors. The TUI render path, the zero sandbox headless command, and the PR/CI automation consumer are follow-up work in their respective owners' lanes.

Summary by CodeRabbit

• Tests

  • Added comprehensive test coverage for sandbox grant snapshot behavior, including field trimming, reason redaction, sorting, and JSON serialization.

• Chores

  • Added internal snapshot export helper functions and data structures.

[github-actions]

Zero automated PR review

Verdict: No blockers found

Blockers

• None found.

Validation

• [pass] Diff hygiene: git diff --check
• [pass] Typecheck: bun run typecheck
• [pass] Tests: bun run test
• [pass] Build: bun run build
• [pass] Smoke build: bun run smoke:build

Scope

Head: 4af8faaf1215
Changed files (2): internal/zerocommands/sandbox_snapshot.go, internal/zerocommands/sandbox_snapshot_test.go

This deterministic review checks validation status and basic diff hygiene. A human reviewer still owns product judgment and design quality.

[coderabbitai]

Looking for one thing? Review this PR in Change Stack to search files, summaries, diffs, and code without losing your place.

Walkthrough

New module internal/zerocommands/sandbox_snapshot.go exports typed snapshot structs and three helper functions for converting sandbox grants to JSON-ready representations. Functions trim whitespace, redact sensitive reason text via the redaction pipeline, sort results deterministically, and handle both grant conversion and lookup-result wrapping. Comprehensive test coverage validates trimming, redaction, sorting, empty-slice behavior, and JSON stability.

Changes

Sandbox Grant Snapshot Export

Layer / File(s)	Summary
Snapshot type definitions internal/zerocommands/sandbox_snapshot.go	SandboxGrantSnapshot and SandboxGrantMatchSnapshot types provide JSON-annotated contracts for exporting grant data with optional redacted Reason and match metadata.
Snapshot conversion functions internal/zerocommands/sandbox_snapshot.go	SandboxGrantSnapshotFromGrant trims whitespace, redacts reason, and maps enums; SandboxGrantSnapshots sorts by tool name and guarantees non-nil empty slice; SandboxGrantMatchSnapshotFromLookup wraps lookup results with match flag.
Snapshot tests internal/zerocommands/sandbox_snapshot_test.go	Five tests cover field trimming and reason redaction, whitespace normalization, deterministic sorting with empty-slice handling, matched and unmatched lookup scenarios, and JSON marshal/unmarshal stability.

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• anandh8x
• Vasanthdev2004

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% 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 directly summarizes the main change: introduction of typed SandboxGrantSnapshot structs and helpers, which matches the core addition of two new types and three helper functions in the changeset.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sandbox-grant-snapshot-contract

---

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

[coderabbitai]

🧹 Nitpick comments (1)

internal/zerocommands/sandbox_snapshot.go (1)

47-48: ⚡ Quick win

Trim enum-backed strings before exporting the snapshot.

Decision and MaxAutonomy are copied without trimming, so whitespace from persisted/corrupted values can leak into output and break the “trimmed string fields” contract.

Suggested patch

 	return SandboxGrantSnapshot{
 		ToolName:    strings.TrimSpace(grant.ToolName),
-		Decision:    string(grant.Decision),
-		MaxAutonomy: string(grant.MaxAutonomy),
+		Decision:    strings.TrimSpace(string(grant.Decision)),
+		MaxAutonomy: strings.TrimSpace(string(grant.MaxAutonomy)),
 		ApprovedAt:  strings.TrimSpace(grant.ApprovedAt),
 		Reason:      redaction.RedactString(strings.TrimSpace(grant.Reason), redaction.Options{}),
 	}

🤖 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 `@internal/zerocommands/sandbox_snapshot.go` around lines 47 - 48, When
building the snapshot, trim whitespace from enum-backed fields so
persisted/corrupted values don't leak; update the assignments that set Decision
and MaxAutonomy (currently using string(grant.Decision) and
string(grant.MaxAutonomy)) to use strings.TrimSpace(string(grant.Decision)) and
strings.TrimSpace(string(grant.MaxAutonomy)); import strings if needed and keep
the rest of the snapshot construction (the grant variable and surrounding export
logic) unchanged.

🤖 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.

Nitpick comments:
In `@internal/zerocommands/sandbox_snapshot.go`:
- Around line 47-48: When building the snapshot, trim whitespace from
enum-backed fields so persisted/corrupted values don't leak; update the
assignments that set Decision and MaxAutonomy (currently using
string(grant.Decision) and string(grant.MaxAutonomy)) to use
strings.TrimSpace(string(grant.Decision)) and
strings.TrimSpace(string(grant.MaxAutonomy)); import strings if needed and keep
the rest of the snapshot construction (the grant variable and surrounding export
logic) unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 39f8dc68-0463-4214-82a3-e7e6b5da76a2

📥 Commits

Reviewing files that changed from the base of the PR and between 4f4f965 and 4af8faa.

📒 Files selected for processing (2)

• internal/zerocommands/sandbox_snapshot.go
• internal/zerocommands/sandbox_snapshot_test.go

[Vasanthdev2004]

Blockers

None found.

Non-Blocking

• The PR head is based behind current main, but I test-merged 4af8faaf12151180c109e43feed2c56adca3d6b9 into latest origin/main (ce8dec087d7db354f49ffa7e9572b3b7a7d2ab19) and it merged cleanly with the same validation passing.

Looks Good

• The new SandboxGrantSnapshot contract trims fields and runs grant reasons through the shared redaction path before exposing them to downstream JSON/TUI/automation consumers.
• Slice conversion returns a non-nil empty slice and sorts snapshots by tool name, so consumers get deterministic [] output instead of null.
• The lookup snapshot cleanly separates matched vs. unmatched results with a nil grant pointer for misses, avoiding ambiguous zero-value grant handling.
• Local validation passed: go build ./..., go vet ./..., targeted go test -count=1 -p 1 ./internal/zerocommands/... ./internal/sandbox/... ./internal/redaction/..., full go test -count=1 ./..., git diff --check, and a runtime redaction probe confirming an assembled OpenAI-shaped key in Reason is emitted as [REDACTED].
• GitHub checks are green on the reviewed head.