Compare provider revisions and approve a guarded document edit¶
examples/cloud-documents/humagen.yaml uses existing signed-in account
connections on this host. The history agent runs on Codex apps to read actual
Drive revision text. The documents agent runs on Claude Code's native Google
Docs tools to apply an approved edit with the expected Docs revision. No new
API key is needed when those two programs already have the intended account
connections. No existing document is selected by the example.
Connect and start¶
Sign in to Codex and Claude Code on this host and connect the intended Drive and Docs accounts in those programs. Set both model directories to one existing absolute work folder, then start:
humagen config check -f examples/cloud-documents/humagen.yaml
humagen start -f examples/cloud-documents/humagen.yaml
The example enables Codex's apps feature and ignores its user config; its
local filesystem sandbox is read-only. Claude Code exposes only ToolSearch as
a built-in tool and allows the exact native Docs read/update names in the
file. Its user settings, hooks and account connections still load. Existing
account tools and connected apps are not confined to one document by this
configuration: exact resource selection and approval remain necessary. Opened
content enters the programs' model providers and consumes their account usage.
Read the requested history¶
Select history and provide the exact Google Doc ID and requested provider
revision IDs. For example:
For Google Doc EXACT_DOCUMENT_ID, list every page of provider revisions and
fetch actual text of requested revisions REVISION_IDS. Compare the text with
the current native document and give its Docs write revision token. Report
missing revisions and unread content. Do not change anything or read another
resource.
It uses the app tools list_file_revisions, fetch_file_revision and
get_document. Drive history IDs and Docs write tokens are different values.
A list of revision metadata, a cached local copy or the current document is
not historical content. Provider history can coalesce: an ID seen earlier
may later return 404, and the workflow must report that content as unknown.
It cannot reconstruct a missing provider revision.
Approve an edit to the same document¶
Read the comparison, then select documents. Supply the exact document ID,
change and expected current Docs write token. The agents do not hand off
automatically; the person passes the selected comparison and approves the
scoped change. For example:
Approved for EXACT_DOCUMENT_ID: replace only OLD_TEXT with NEW_TEXT, using
writeControl.requiredRevisionId EXACT_DOCS_WRITE_TOKEN. Preserve the original
ID, tabs, formatting and all unrelated content. Stop on a stale token or
permission error; do not retry with a fresh token. Read back the changed area
and retained controls once.
The exact native tool names are mcp__claude_ai_Google_Docs__read_doc and
mcp__claude_ai_Google_Docs__update_doc. Discover those names explicitly.
The update takes top-level writeControl.requiredRevisionId and native
requests. Use the required token to fail on a concurrent change;
targetRevisionId allows a merge and is a different operation. Read all
requested tabs before editing their structure. Native range indexes are
UTF-16 code units and requests in a batch execute in order.
Checked on an approved private fixture¶
On 17 November 2026, the person explicitly approved one new private folder and one non-personal native Google Doc. It had four plain-text control lines; no existing document, sharing permission or other account object was changed.
- Humagen's Claude Code path read the native tab and write token, changed one exact marker with that required token, then read it back at the same ID.
- The final combined profile changed only Value: baseline to Value: approved with the exact required token, preserving the marker, control line, ID and tab. Its history agent then fetched all currently listed revisions 1 and 4.
- An actual stale-token write returned a provider revision-mismatch error. It was not retried, and the control text remained unchanged.
- Humagen's Codex-apps path listed the actual provider history and fetched revisions 1 and 3: the former was empty apart from a byte-order mark, and the latter contained the four current lines. Revision 2 had appeared in an earlier list, then was coalesced out; its fetch returned 404. Its old contents were reported as unknown, rather than replaced with a snapshot.
The supplied document is a generated fixture in a real connected account. Paired provider-exported PDF pages were opened around the final Value edit; the earlier marker edit was not captured as a rendered before/after pair, and the native Google Docs web interface was not opened.
This does not establish a real user's document, complex formatting, every historical revision or OneDrive support. Preserve snapshots separately if exhaustive history is required. A new account still needs its own connection and consent.
Connector limits observed¶
Claude Code's native Drive download_file_content exposed a revisionId
argument but actually refused historical downloads with "not yet supported."
The working history path therefore uses Codex's connected Drive app.
Codex's noninteractive cloud write attempt was refused by the installed
program's default approval policy. Only its local filesystem mode is pinned
by this profile; cloud-tool approvals follow the program and app settings on
the host. The history instruction requests reads, and the existing permitted
native Docs path handles approved guarded writes. Recheck those runtime
settings when using this path. The example does not disable approval review
or broaden local permissions. A similarly named Claude Docs connector was not
in the allow list and was refused; the explicit Google_Docs tool names avoid
that ambiguous discovery path.