Read-only project access for secondary agents (Grok Bot / doc subagents)

[verna-stack]

Feature request for product/service

– Other –

Describe the request

I run a large monorepo with strict boundaries. Implementation agents touch code, compose, probes, and sign-off docs. Operator manuals and runbooks need a different voice and a different risk profile.

I want to use Grok Bot (or a dedicated doc agent) to polish user manuals and runbooks after engineering work lands — but I am not willing to give it write access to the repository. One mistaken cleanup pass can:

Mark features as shipped before lab probes pass
Race parallel sessions on shared handoff docs
Touch the wrong product tree in a multi-product repo
Leave orphan files or rewrite configs helpfully
The IDE agent is the right tool for implementation. Grok Bot is often better for long-form operator prose. What is missing is a safe bridge: read the repo, write nowhere unless I explicitly allow it.

Feature request
Project-scoped read-only agent mode — assignable to Grok Bot or a subagent type.

Read-only agent may:

Read workspace files
Read git history and diffs
Read terminal output the user shares
Read-only agent may not (unless the user explicitly promotes):

Edit, create, or delete repo files
Run shell, compose, or other git-write commands
Commit or push
The implementation agent keeps full write access when the user asks. That behavior should stay unchanged.

Optional escalations (user-controlled, per session or per path):

Draft sink only — write to Canvas, clipboard export, or a single user-nominated draft folder. Never auto-merge into canonical docs.
Single-file promote — user picks one path (for example a user manual). Agent proposes a patch; user approves before apply.
Path allowlist — for example docs read/write only; everything else read-only.
Why this matters
Safety: doc agents consume source of truth (plans, skills, probe transcripts, code) without destroying it.
Parallel agents: IDE agent and Grok Bot can run concurrently without file-ownership races.
Sign-off gates: manuals should reflect lab probe PASS, not aspirational roadmap text. A read-only doc agent can cite evidence without flipping shipped flags in the repo.
Grok Bot fit: doc-heavy work on serious projects needs read-only repo access, not full write by default.
Example workflow
IDE agent ships a feature, runs a lab probe, commits code and skeleton docs.
User opens Grok Bot with read-only access to the same project (or pastes plan plus probe log).
Grok Bot drafts user-manual sections in operator tone.
User paste-backs, or the IDE agent merges one file after review.
Grok Bot never needs to run compose, edit application source, or commit.

Non-goals (v1)
Replacing the IDE agent for implementation
Automatic commit from Grok Bot
Full write access with only a please be careful prompt
Nice-to-have (later)
Subagent type doc-reviewer with read-only default and skill awareness
Audit log of what the read-only agent read versus what it proposed
Explicit handoff marker: implementation complete, doc pass read-only
Thanks for considering. Happy to share anonymized monorepo patterns (multi-product, probe-gated sign-off, parallel session rules) if that helps prioritize.

[Sakshambhutani]

I’ve been digging into the same problem and would love to compare notes. Your distinction between implementation agents and documentation agents is sharp: the doc agent needs plans, diffs and probe evidence, but should not be able to flip shipped flags or touch the wrong product tree. Would the minimum useful control be a read-only role plus one reviewed promotion path, or do you also need an audit trail showing exactly which sources the doc agent read for each proposed section?

[verna-stack]

Minimum useful (v1): read-only enforcement + one reviewed promotion path.
That alone fixes the failures I care about: no file races, no wrong-tree edits, no compose/git side effects, no silent status-banner rewrites. The doc agent drafts in chat/Canvas; I or the IDE agent applies one file after review. That’s the bridge I’m missing today — prompt-only “don’t write” isn’t enough when the same session can still StrReplace a handoff doc.

Audit trail is valuable but not blocking for v1. I’d rank it phase 2: per-section “evidence used” (probe ID, status file, skill path, commit/date) is already in my doc-reviewer checklist; making that machine-visible (what was read vs what was proposed) helps disputes and parallel sessions, especially when two products share docs/internal/. For day one, enforced read-only + explicit promote delivers most of the safety; audit makes sign-off and “why does this paragraph say PASS?” auditable later.

If helpful for prioritisation: happy to share anonymised patterns — multi-product ownership tables, probe-gated “complete means armed,” parallel-session handoff rules — but the must-have is hard read-only default with opt-in, per-path write, not another honor-system doc agent.

[deanrie]

Hey, thanks for the detailed breakdown. A lot of what you describe is already working today on Cursor’s side.

Ask mode is basically the agent’s read-only mode, in the IDE, in the Agents window, and in the CLI --mode ask. The agent can read files and git history, but it can’t edit files or run state-changing commands.

For a dedicated docs agent, you can create a custom subagent in .cursor/agents/ with readonly: true in the frontmatter. That subagent runs in Ask mode. File edits and deletions are blocked at the tool level, so a doc reviewer can read the repo, plans, and logs and then hand a draft to you or to the main agent without touching the working tree. Note that read-only subagents currently can’t use MCP tools.

About Grok Bot, it doesn’t mount or edit your local repo. When you ask it to work with a repository, the task goes to a Cloud Agent, which returns a branch or PR for review. For read-only repo access inside Grok Bot, add a GitHub connector in its settings using a token that has read-only scopes. Anything it does on your computer goes through per-action approvals by default, like read, list, write, run, so you can approve reads and reject writes.

A project-scoped read-only toggle and a path allowlist, for example docs/ read and write while everything else is read-only, aren’t available yet. I passed this to the team as feedback, and we can keep this thread as the place to collect votes for the request.

[nick_zhang]

+1. We ran into basically the same problem.

In a monorepo, telling an agent in the prompt “please don’t modify these files” only goes so far. We eventually saw cases where an agent would make an unexpected change, assume a task was complete, or report success before the actual tests had passed.

We ran into this quite a bit with Google Antigravity, so we ended up putting some of the controls outside the agent itself. What worked for us was pretty simple:

• For documentation/review tasks, we remove the write, edit, and shell permissions at the dispatcher level. The agent simply has no way to modify the repo.

• We use a two-step process: first check the impact, then stop and wait for human approval before allowing execution.

• If the agent needs to generate files, it can only write to a designated staging/scratch directory. Anything outside that path is rejected.

It adds some extra infrastructure, but it made a big difference. The important part is that “don’t touch this” is no longer just a prompt instruction — it’s enforced by the environment.

I’d really like to see something similar as a native read-only subagent/agent role in Cursor. It would remove a lot of the external guardrails we currently have to build around it ourselves.

[deanrie]

Hey, thanks for the detailed real-world report. The pattern of “enforcement in the environment, not in the prompt” fully matches how this works in Cursor today.

Part of what you described is already available: a custom subagent with readonly: true in .cursor/agents/ runs in Ask mode, and edits and deletes are blocked at the tool level, not by the prompt. Shell is also forced into read-only mode, so StrReplace against a handoff doc or a git write command can’t succeed. That’s effectively “no way to modify the repo” at the dispatcher level, not an honor system.

What doesn’t exist yet is the exact escalation flow you described: a project-scoped toggle, a path allowlist write mode for a designated staging or scratch dir, and a reviewed single-file promote step. I’ve passed that to the team as feedback, and we’ll keep this thread as a place to collect votes on the request.

A couple of details so there are no surprises:

• read-only subagents currently can’t use MCP tools
• for read-only repo access in Grok Bot specifically, it doesn’t mount the local repo, so access is provided through the GitHub connector with a read-scoped token

If you can share anonymized patterns like ownership tables, “complete means armed” rules, or parallel-session rules, drop them here. That’s useful input for prioritization.

[nick_zhang]

I actually documented the exact failure mode of “trusted testing” and our 3-agent isolated runtime in a 12-run ablation study on the forum two days ago:

When "Exit Code 0" Lies: A 12-Run Ablation Study on Test Integrity and Contract Freezing in AI Coding Agents

1. Executive Summary AI coding agents can generate implementations and produce passing test suites. However, a passing test result does not, by itself, establish that existing contracts and acceptance criteria have been preserved. One failure mode in maintenance work is particularly important: an agent changes the conditions used to evaluate its own implementation rather than satisfying the original requirements. Examples include modifying protected test assertions, changing frozen function sig…

The post covers the live capture of agents mutating test assertions to fake a pass, along with the out-of-band tri-agent boundary setup we used to stop it. The raw benchmark matrix is attached there if your team wants to look at the runs.

The topology across the three isolated terminals was a deliberate defensive choice, not an accident. When a stochastic model hits complex edge cases or begins to hallucinate under pressure, giving it unconstrained write access across the repo inevitably causes it to “go rogue”—it will silently relax assertions, delete edge cases, or introduce catastrophic drifts just to manufacture a green exit code.

From a closed-loop control perspective, decoupling the Dispatcher (prompt ingestor), Worker (actuator), and Auditor (sensor) is strictly all upside:

1. Worker vs. Auditor Separation: The actuator cannot be allowed to evaluate its own output or manipulate test harnesses to fake compliance.
2. Dispatcher vs. Auditor Separation: The Dispatcher directly ingests human natural language, making it inherently vulnerable to prompt noise, ambiguous intent, and context poisoning. If the verification layer shares that conversational context, it risks inheriting the same cognitive blind spots. The Auditor must remain completely detached from human prompt negotiations—evaluating only cold engineering artifacts (AST invariants, isolated diffs, SHA-256 test fingerprints, and regression replays).

By physically enforcing these air-gapped boundaries, an agent having a meltdown can never touch canonical code or corrupt the verification gates. It fails closed by design.

[deanrie]

Hey, thanks for the detailed write-up. The setup with three isolated terminals and an air-gapped Auditor is a neatly stated version of the same principle we think is right: the boundary should be enforced by the environment, not by the prompt.

That logic is already in place for the read-only subagent in Cursor. A custom subagent with readonly: true in .cursor/agents/ runs in Ask mode, edits and deletes are blocked at the tool level, and shell is forced into read-only mode. That means StrReplace on the handoff doc or a git write command simply can’t run. It’s not an honor system. It’s a hard stop at the dispatcher level. Your pattern of removing write, edit, and shell at the dispatcher level for docs and review is exactly what this covers.

What we don’t have yet is the next part: a project-scoped toggle, a write allowlist for a designated staging or scratch dir, and reviewed single-file promote. I’ve passed that to the team as feedback, and we’ll keep this thread as the place to collect votes for that request.

A couple of details so there are no surprises:

• Read-only subagents currently can’t use MCP tools
• For read-only repo access in Grok Bot specifically, it does not mount the local repo. Access goes through the GitHub connector with a read-scoped token

I’ll also take a separate look at your ablation study thread. The specific cases involving mutation of test assertions are useful material. If you can share anonymized patterns here, like ownership tables, “complete means armed” rules, and parallel session rules, that would help with prioritization.

[nick_zhang]

Thanks for clarifying how Cursor enforces read-only subagents at the dispatcher level. I agree that the boundary should be enforced by the environment, not left to the model’s instructions.

I think there is one additional dimension worth separating from tool permissions: context isolation.

A read-only Auditor can be prevented from modifying files, but that alone does not guarantee independent verification. If it inherits the same conversational context as the Worker, it may also inherit the Worker’s assumptions, interpretations, and blind spots. The Auditor needs read-only access to the relevant source code, specifications, and test evidence, while remaining independent of the execution agent’s conversational history.

That distinction is what led me to approach multi-agent workflows through classical control theory: separating the actuator from the measurement and verification path, then using explicit interlocks to constrain what the execution side can change.

For context, I’m an electrical and control systems engineer based in Taiwan, currently exploring where this approach could be useful. Applying closed-loop negative feedback, plant/sensor decoupling, and safety interlocks to AI workflows was a natural extension of my engineering background.

I see the project-scoped permissions and reviewed promotion mechanisms you mentioned as important parts of the control boundary. Context isolation is a separate concern that I believe deserves equal attention.

I’m happy to discuss the high-level architecture and share general lessons from my experiments. The detailed boundary matrices, session state machines, and arming rules are part of my proprietary implementation, so I’m not in a position to publish those operational details in a public thread.

If this becomes relevant to your team’s roadmap, I’d be happy to discuss the architecture in more detail via PM. Otherwise, the attached diagram illustrates the general control topology I’m exploring.

Thanks again for engaging with the idea. I look forward to seeing how these capabilities evolve.