Skip to content

fix: add main-branch write restrictions for subagents #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 1 commit into from
Feb 5, 2026
Merged

fix: add main-branch write restrictions for subagents #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agent/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ Exit 0 = proceed. Exit 1 = STOP (on main). Exit 2 = create worktree. Exit 3 = wa

**Self-verification**: Your FIRST step before any Edit/Write MUST be to run this script. If you are about to edit a file and have not yet run pre-edit-check.sh in this session, STOP and run it now. No exceptions — including TODO.md and planning files (the script handles exception logic, not you).

**Subagent write restrictions**: Subagents invoked via the Task tool cannot run `pre-edit-check.sh` (many lack `bash: true`). When on `main`/`master`, subagents with `write: true` may ONLY write to: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`. All other writes must be returned as proposed edits for the calling agent to apply in a worktree.
Copy link

@gemini-code-assist gemini-code-assist bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better readability and consistency with the other updated files in this PR, consider restructuring this rule using a list format. This will make the allowed file paths easier to parse for both humans and agents.

Suggested change
**Subagent write restrictions**: Subagents invoked via the Task tool cannot run `pre-edit-check.sh` (many lack `bash: true`). When on `main`/`master`, subagents with `write: true` may ONLY write to: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`. All other writes must be returned as proposed edits for the calling agent to apply in a worktree.
**Subagent write restrictions**: Subagents invoked via the Task tool cannot run `pre-edit-check.sh` (many lack `bash: true`). When on `main`/`master`, subagents with `write: true` must follow these rules:
- **Allowed writes**: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`.
- **Other writes**: Must be returned as proposed edits for the calling agent to apply in a worktree.


---

## MANDATORY: File Discovery
Expand Down
6 changes: 6 additions & 0 deletions .agent/tools/build-agent/agent-review.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,12 @@ tools:

**Process**: Complete task first, cite evidence, check duplicates, propose specific fix, ask permission

**Write Restrictions (MANDATORY)**: This subagent has `write: true` but MUST respect branch protection. When the working directory is on `main`/`master`:

- **ALLOWED writes**: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`
- **BLOCKED writes**: All other files (agent definitions, scripts, configs, code)
- **For code changes**: Return proposed edits to the calling agent; do NOT write directly. The calling agent will apply them in a worktree.
Comment on lines +43 to +44
Copy link

@gemini-code-assist gemini-code-assist bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The distinction between BLOCKED writes and For code changes could be clearer. The term 'code changes' is a bit narrow, as blocked files also include configs and other non-code files. Combining these two points would make the instruction more concise and remove ambiguity.

Suggested change
- **BLOCKED writes**: All other files (agent definitions, scripts, configs, code)
- **For code changes**: Return proposed edits to the calling agent; do NOT write directly. The calling agent will apply them in a worktree.
- **BLOCKED writes**: For all other files (agent definitions, scripts, configs, code), return proposed edits to the calling agent; do NOT write directly. The calling agent will apply them in a worktree.


**Testing**: Use OpenCode CLI to test agent/config changes without restarting TUI:

```bash
Expand Down
9 changes: 9 additions & 0 deletions .agent/tools/build-agent/build-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,10 +241,19 @@ tools:

**Note on permissions**: Path-based permissions (e.g., restricting which files can be edited) are configured in `opencode.json` for OpenCode, not in markdown frontmatter. The frontmatter defines which tools are available; the JSON config defines granular restrictions.

**Main-branch write restrictions**: Subagents with `write: true` / `edit: true` that are invoked via the Task tool MUST respect the same branch protection as the primary agent. When the working directory is on `main`/`master`:

- **ALLOWED**: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*` (planning and documentation files)
- **BLOCKED**: All other files (code, scripts, configs, agent definitions)
Copy link

@gemini-code-assist gemini-code-assist bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The guidance for BLOCKED files is incomplete. It states which files are blocked but doesn't specify the alternative action the subagent should take, which is a key part of the rule. To make the guidance comprehensive, please include the instruction to return proposed edits.

Suggested change
- **BLOCKED**: All other files (code, scripts, configs, agent definitions)
- **BLOCKED**: All other files (code, scripts, configs, agent definitions). For these files, the subagent must return proposed edits to the calling agent instead of writing directly.

- **WORKTREE**: If a worktree is active, writes to the worktree path are unrestricted

Subagents cannot run `pre-edit-check.sh` (many lack `bash: true`), so this rule must be stated explicitly in the subagent's markdown. Add a "Write Restrictions" section to any subagent that has `write: true` and may be invoked on the main repo path.

**Why this matters:**
- Prevents confusion when agents recommend actions they cannot perform
- Makes agent capabilities explicit and predictable
- Enables safer parallel execution (read-only agents can't conflict)
- Prevents subagents from bypassing branch protection when invoked via Task tool
- Documents intent for both humans and AI systems

#### Agent Directory Architecture
Expand Down
Loading