feat(mcp): add bounded Gmail exports and scoped Calendar tools

[salmonumbrella]

What changed

• Add bounded exact Gmail message/attachment exports with immutable snapshot handles, byte ranges, SHA-256 metadata and private storage. Include an atomic client example that verifies every chunk and the final digest.
• Add compact thread search and metadata-only message-ID paging, typed Calendar reads/actions, and Gmail label/filter tools. Reuse the existing draft, label, mailbox, send and delete implementations.
• Keep stdio and default readonly discovery. Calendar notifications, Calendar deletion and Gmail settings deletion have separate grants; destructive calls also need operator-supplied startup force. New mutations return bounded receipts and do not retry writes.
• Preserve explicit false/empty fields and literal arrays. Add Calendar search continuation, source PATCH fields and an explicit RSVP notification mode.

Why

Large MIME messages and attachments need an exact byte path that can be reconstructed without truncated JSON or normalized content. Clients also need compact thread enumeration and typed Calendar/settings actions without a generic command runner or broader send/delete permission.

Usage

# Save the exact decoded MIME bytes, atomically.
gog --account user@example.com gmail export raw MESSAGE_ID --out message.eml

# Default stdio server exposes reads.
gog --account user@example.com mcp

# Opt in to one ordinary Calendar write; notifications still default to none.
gog --account user@example.com mcp --allow-write --allow-tool calendar_create_event

Exports are capped at 50 MiB decoded; snapshots expire 900 seconds after publication. New bounded tools require an output budget of at least 4096 bytes. The migration guide documents native envelope/schema changes and removal of overlapping sidecar registrations.

Validation:

• Local make ci TEST_FLAGS=-timeout=60m: all Go packages, lint, generated docs/skills and 19 Node script tests pass at ab06e95. Subsequent revisions change only tests and release-note references; exact-head upstream CI is also green.
• Expanded race suite: passes in 276 seconds, including 20 MiB stdio reassembly, actual export-child cancellation and live-waiter recovery.
• Encoding/range/cursor fuzzing and Python integrity/error fixtures pass. An external native CLI/MCP fixture enumerates exactly 2,000 threads across 21 calls, including an empty page with a continuation token and one provider search page per call.
• Windows lint and Windows/macOS cross-builds pass. Upstream CI also passes Linux, minimum Go, Windows runtime, macOS runtime with CGO, tracking-worker CI and the Docker image build.

Saved-policy upgrade evidence (TestMCPSavedPolicyUpgrade):

Existing saved policy	Before	After	Guarded/denied RPCs
Global or account * + write	23 tools	37 tools	8 per policy, zero provider calls
Exact two-name account replacement	2 tools	2 tools	13, zero provider calls
Readonly account or root ceiling	11 reads	20 reads	13 per policy, zero provider calls

The same old-format JSON fixture ran against pinned upstream and this branch.
Broad selectors intentionally gain five ordinary writes: Calendar create/update/
move, label rename and filter creation. Narrow account policies replace the
global policy; new notification/delete grants remain absent, and existing Gmail
send/delete stays gated. The committed regression and its race run pass (1.430s).
Pin exact tool names to retain an existing reviewed write surface.

Maintainer review remains required for that broad-selector expansion. All
mutation proofs use isolated fixtures; live Google mutation/readback and
production rollout were outside this contribution task. The upstream review's
request for live provider proof remains a pre-merge decision for maintainers.
Both Unreleased entries now link to this PR.

Roborev passed the full original implementation and each subsequent correction with zai/glm-5.3-flash at max. Deferred follow-ups: a distinct typed-read overflow code, redacted debug events, and a bounded iterative budget for abandoned-fetch retries under hostile churn.

Refs #1173. This adds an exact export path; it does not change the documented full-payload MIME projection or claim to fix that report.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed October 1, 2026, 6:26 AM ET / 10:26 UTC (Revision 4).

ClawSweeper review

What this changes

The PR adds bounded Gmail byte exports and paged metadata reads, typed Calendar and Gmail settings tools, separate sensitive-action grants, private snapshots, and mutation receipts.

Merge readiness

⛔ Blocked before merge - 6 items remain

This PR remains useful and is not already implemented on main. The previous changelog finding is resolved; permission-expansion approval and production behavior proof remain outstanding.

Priority: P2
Reviewed head: 3a6a5e0fb35ca4b93d862f58bb4f27628109c5a0
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	Useful implementation and extensive fixtures remain limited by real-provider proof and an unresolved persisted-authority upgrade contract.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Authority-chain proof required: demonstrate allowed writes and saved narrow-account or missing notification/delete grants rejecting calls before final provider I/O through production startup and dispatch. Native export-child, stdio reassembly and Calendar HTTP fixtures are substantial supplemental coverage, but the external contribution still lacks real Google-account export integrity and mutation readback. Existing-state policy compatibility remains unverified beyond catalog and substitute-handler tests. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: Authority-chain proof required: demonstrate allowed writes and saved narrow-account or missing notification/delete grants rejecting calls before final provider I/O through production startup and dispatch. Native export-child, stdio reassembly and Calendar HTTP fixtures are substantial supplemental coverage, but the external contribution still lacks real Google-account export integrity and mutation readback. Existing-state policy compatibility remains unverified beyond catalog and substitute-handler tests. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	9 items	Pinned introduction and necessity: The introduced delta adds 85 files' worth of changes against pinned main. Main's MCP catalog lacks the exact export, metadata-paging and new Calendar/settings tools; the inspected v0.43.0 catalog also lacks them. The merged Gmail mutation work is adjacent prior capability, not a replacement for this contribution. Release comparison: The latest release's catalog retains the previous tools and does not contain the new bounded export or typed Calendar/settings registrations. Intentional saved-policy expansion awaits acceptance: The documentation and captured PR body explicitly state that existing broad write selectors gain Calendar create/update/move, label rename and filter creation. The contributor requests maintainer review of that expansion; no maintainer acceptance appears in the supplied discussion or fetched reviews.
Findings	None	None.
Security	Needs attention	Approve expansion of persisted write authority: Old wildcard write policies gain Calendar create/update/move, label rename and filter creation. Documentation acknowledges this behavior, but contributor intent does not establish operator or maintainer acceptance.

How this fits together

gog's MCP server exposes selected Google Workspace operations to agent clients over stdio. It applies account and capability policies before dispatching native commands or returning private export snapshots.

flowchart TD
 A[Agent tool request] --> B[MCP server]
 C[Account and saved policy] --> B
 B --> D[Permission and input checks]
 D --> E[Native Google operations]
 E --> F[Google Workspace APIs]
 F --> G[Private snapshots or mutation receipts]
 G --> H[Bounded client response]

Loading

Decision needed

Question	Recommendation
Should existing broad saved write policies automatically authorize the five new Calendar and Gmail settings mutations?	Require explicit authorization: Keep existing saved policies on their reviewed mutation surface until operators explicitly enable the new writes.

Why: The expansion is intentional and documented, but accepting a broader persisted authorization surface requires maintainer intent.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Authority-chain proof required: demonstrate allowed writes and saved narrow-account or missing notification/delete grants rejecting calls before final provider I/O through production startup and dispatch. Native export-child, stdio reassembly and Calendar HTTP fixtures are substantial supplemental coverage, but the external contribution still lacks real Google-account export integrity and mutation readback. Existing-state policy compatibility remains unverified beyond catalog and substitute-handler tests. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve security concern: Approve expansion of persisted write authority - Old wildcard write policies gain Calendar create/update/move, label rename and filter creation. Documentation acknowledges this behavior, but contributor intent does not establish operator or maintainer acceptance.
• Resolve merge risk (P1) - Existing saved wildcard write policies gain five new mutation tools without fresh operator authorization; maintainers have not accepted that upgrade behavior.
• Resolve merge risk (P1) - Saved-policy tests substitute RPC handlers, leaving allowed and nearest-forbidden account/capability cases unverified through production dispatch to the final provider transport.
• Complete next step (P2) - Resolve saved-policy expansion and add real behavior proof before merge: redacted Google-account export hashes and mutation readback, plus production fresh-start/upgrade permission negatives before provider I/O. Terminal output, logs or diagnostic recordings count; redact credentials, private identifiers and endpoints. Update the PR body to trigger re-review, or ask a maintainer to comment @clawsweeper re-review.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [medium] Approve expansion of persisted write authority — docs/mcp.md:370

Agent review details

Security

Needs attention: The unresolved security question is expansion of existing persisted mutation authority; no concrete supply-chain regression was found.

Review metrics

Metric	Value	Why it matters
Code growth	production +3070 net lines, tests +2826 net lines	The stated export, bounded-runtime and typed-tool capabilities justify the growth, while widening the review surface.
Saved broad write permissions	5 new mutation tools	Existing wildcard policies authorize these additions without an operator changing saved configuration.

Merge-risk options

Maintainer options:

1. Preserve saved authorization (recommended)
   Choose an explicit opt-in path for new mutations and verify old global/account policies through production dispatch.
2. Approve broader wildcard permissions
   Accept the documented expansion only after allowed and denied production-path evidence establishes the intended boundary.

Technical review

Best possible solution:

Preserve previously reviewed mutation permissions during upgrade unless operators explicitly enable the additions, with verified fresh-start and saved-policy behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature request; source and fixtures establish the proposed paths, but no real Google-account after-fix run is supplied.

Is this the best way to solve the issue?

Unclear. Reusing native commands behind typed bounded tools is sensible, but saved-policy authorization expansion needs an approved compatibility contract.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 414e2ff8afa2.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This is a useful bounded Workspace integration improvement without evidence of an urgent current-user regression.
• merge-risk: 🚨 compatibility: Existing saved broad write policies expose a larger tool surface after upgrade.
• merge-risk: 🚨 security-boundary: Persisted authorization gains new provider side effects, and production account/capability rejection proof remains incomplete.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Authority-chain proof required: demonstrate allowed writes and saved narrow-account or missing notification/delete grants rejecting calls before final provider I/O through production startup and dispatch. Native export-child, stdio reassembly and Calendar HTTP fixtures are substantial supplemental coverage, but the external contribution still lacks real Google-account export integrity and mutation readback. Existing-state policy compatibility remains unverified beyond catalog and substitute-handler tests. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

Security concerns:

• [medium] Approve expansion of persisted write authority — docs/mcp.md:370
  Old wildcard write policies gain Calendar create/update/move, label rename and filter creation. Documentation acknowledges this behavior, but contributor intent does not establish operator or maintainer acceptance.
  Confidence: 0.98

What I checked:

• Pinned introduction and necessity: The introduced delta adds 85 files' worth of changes against pinned main. Main's MCP catalog lacks the exact export, metadata-paging and new Calendar/settings tools; the inspected v0.43.0 catalog also lacks them. The merged Gmail mutation work is adjacent prior capability, not a replacement for this contribution. (internal/cmd/mcp_tools.go:14, 3a6a5e0fb35c)
• Release comparison: The latest release's catalog retains the previous tools and does not contain the new bounded export or typed Calendar/settings registrations. (internal/cmd/mcp_tools.go:14, 3b5122f4c81c)
• Intentional saved-policy expansion awaits acceptance: The documentation and captured PR body explicitly state that existing broad write selectors gain Calendar create/update/move, label rename and filter creation. The contributor requests maintainer review of that expansion; no maintainer acceptance appears in the supplied discussion or fetched reviews. (docs/mcp.md:370, 3a6a5e0fb35c)
• Production permission checks: The bounded runtime checks readonly, sensitive grants, startup force, command policy and input before dispatch. Account/client identity and capability policy are frozen at startup, and snapshot hits pass through these checks. (internal/cmd/mcp_runtime.go:106, 3a6a5e0fb35c)
• Saved-policy coverage boundary: The upgrade regression reads old-format persisted JSON and verifies catalogs and rejected hidden RPCs, but registers substitute handlers. Its zero provider-call counter therefore does not exercise production routing and final Google transport under those saved policies. (internal/cmd/mcp_policy_upgrade_test.go:73, 3a6a5e0fb35c)
• Substantial fixture validation, limited live coverage: Runtime tests exercise native export-child arguments against a local Gmail HTTP fixture, cancellation recovery and private snapshots; stdio tests reassemble a synthetic 20 MiB export. Calendar tests exercise native handlers and real HTTP clients against isolated endpoints. The captured body expressly states that live Google mutation/readback was outside the contribution task, and supplies no real-account export transcript. (internal/cmd/mcp_runtime_test.go:127, 3a6a5e0fb35c)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• auroracapital: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Provide redacted real-account CLI/MCP export reassembly hashes and Calendar/settings mutation readback.
• Show fresh-start and saved global/account policies through production dispatch, including allowed effects and nearest-forbidden calls rejected before provider I/O.
• Obtain maintainer acceptance of wildcard expansion or revise upgrades to require explicit authorization.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-10-01T09:39:20.348Z sha ab06e95 :: needs real behavior proof before merge. :: [P3] Add the source PR reference to the Unreleased notes
• reviewed 2026-10-01T10:04:50.183Z sha 8ba2104 :: needs real behavior proof before merge. :: [P3] Add the source PR reference to the Unreleased notes
• reviewed 2026-10-01T10:17:31.337Z sha 3a6a5e0 :: needs real behavior proof before merge. :: none