Scope subagents with a delegation envelope

Learning objective

Scope a coding subagent so that it receives enough authority and information to complete one bounded task, but no unrelated access. This lesson focuses on the delegation boundary, not on choosing a multiagent workflow topology.

Core idea

Treat every subagent assignment as a delegation envelope with four aligned parts:

1. Task: the outcome the subagent owns.
2. Context: the information it can use to make decisions.
3. Tools: the kinds of actions it can propose.
4. Privileges: the resources and effects those actions may reach.

Start with the task, then derive the other three parts. A repository researcher needs relevant source files and search tools, but it does not need file-write access or production credentials. A migration worker might need write and test tools, but only for its assigned package and an isolated test environment.

This model balances two failure modes. An envelope that is too narrow makes the subagent fail, guess, or repeatedly request more access. An envelope that is too broad increases distraction, conflicting edits, data exposure, and the impact of a mistaken action.

How it works

Bound the task

State one deliverable, its scope, constraints, completion evidence, and return format. For example: “Inspect services/billing/ for calls to the deprecated client. Do not edit files. Return file-and-line findings plus replacement guidance.” This is stronger than “review billing” because the subagent can tell what belongs to the task and when it is done.

Partition concurrent editing tasks by file or module ownership. If two subagents can edit the same file, the parent must serialize their work or define an explicit merge owner. A separate Git worktree prevents concurrent changes from colliding in one checkout, but it does not resolve incompatible designs. Antigravity supports an inherited workspace, an isolated Git worktree through the branch option, or shared directory storage through the share option (Subagents).

Select context deliberately

Context is the task prompt, role instructions, relevant repository material, standards, and prior decisions that the worker can inspect. It is not the same as filesystem permission. Antigravity starts a subagent with a separate context window rather than copying the parent’s conversation history, so the parent must pass the assumptions and acceptance criteria that matter (Subagents).

Prefer the smallest coherent context, not isolated fragments. Include the interface and tests that define the assigned component’s behavior, but omit unrelated transcripts, secrets, and large logs. Too much context consumes model capacity and introduces irrelevant instructions; too little hides dependencies and encourages incorrect local conclusions.

Allow only necessary tools

A tool defines an action category, such as searching files, editing code, running commands, browsing, or calling a Model Context Protocol (MCP) server. Give a subagent the smallest tool set that can produce its deliverable. Antigravity custom subagents support an explicit tools list and optional MCP servers; the SDK also supports custom subagents with dedicated tool sets (custom subagents, SDK delegation).

Tool reduction limits both the model’s action space and the number of risky paths to govern. It also reduces flexibility. A read-only reviewer cannot make an accidental edit, but it also cannot apply an approved fix. The parent can delegate implementation later to a different, write-enabled subagent.

Restrict privileges separately

Tool availability answers what kind of action is possible. Privilege answers whether a specific action may execute against a specific target. A shell tool might be available while only npm test is allowed automatically. An MCP tool might be visible while access to a production project is denied or requires approval.

Antigravity expresses sensitive access as actions on targets, including file paths, command prefixes, URLs, and MCP server tools. Its decisions are deny, ask, or allow, with deny taking precedence (Agent permissions). Subagents inherit the parent’s terminal-command scopes, file scopes, and sandbox settings; an authorization request can bubble up for approval (permission inheritance). Therefore, a fresh context or isolated worktree does not automatically create least privilege. Configure restrictive parent or project grants when inherited access would be too broad, and keep service-side identity and authorization controls around remote resources.

Key distinctions and trade-offs

The four controls answer different questions:

A system prompt such as “do not deploy” is a task constraint, not an authorization boundary. Removing the deployment tool reduces capability. Denying the deployment target enforces privilege at execution. For important resources, combine all three instead of relying on wording alone.

Architecture / decision scenario

A team wants a subagent to assess whether a payment service can upgrade a third-party library. The parent assigns this envelope:

• Task: identify affected calls and failing tests; return a cited risk report; make no changes.
• Context: the payment package, its lockfile, interface contracts, tests, and the target library’s official migration guide.
• Tools: file search, file read, and a test runner. No edit, deployment, or general-purpose MCP tools.
• Privileges: read access only to the payment package and required shared interfaces; permission to run the specific test command in a sandbox; no production credentials or unrestricted network access.

This envelope is sufficient for evidence-based analysis and has a small blast radius. If the report supports the upgrade, the parent creates a separate implementation assignment with file ownership, write access to that package, and required verification. It does not silently widen the researcher’s authority mid-task.

Common exam traps

• Giving a subagent a role name but no concrete deliverable, evidence, or stop condition.
• Assuming the subagent automatically knows important facts from the parent’s conversation even though it has a separate context window.
• Treating a visible tool as permission to use it against every resource.
• Treating a read-only prompt as equivalent to removing write tools or denying write privileges.
• Assuming a separate context window or Git worktree creates a separate security identity and least-privilege boundary.
• Giving every subagent the parent’s full context and access “in case” it needs them, which removes much of the safety and focus gained from delegation.

What to remember

• Define a subagent with one delegation envelope: task, context, tools, and privileges.
• Derive context, tools, and privileges from a concrete deliverable and its completion evidence.
• Keep tools and privileges separate: capability does not equal authorization.
• Context isolation and workspace isolation do not guarantee least privilege.
• Widen a scope only for a demonstrated need, and verify the returned result before the parent integrates it.

Knowledge check

References

• Google Antigravity, Subagents
• Google Antigravity SDK, Multi-agent subagent delegation
• Google Antigravity, Agent permissions
• Google Antigravity, Projects
• Google Cloud, How Google secures AI agents