Subagent Tool Scoping: Limiting What a Delegated Task Can Touch

Tool scoping is cheaper than it looks only if the child needs to exist. Microsoft's guidance is to use the lowest level of complexity that reliably meets the requirement, and to justify multiagent orchestration through prompt complexity, tool overload or genuine security boundaries per the Azure Architecture Center. If your reason for spawning a child is "the prompt got long," scoping is paperwork on top of an unnecessary problem.

The decision rule I use:

Multi-agent setups carry coordination overhead, latency and their own failure modes, and fan-out patterns multiply concurrent requests against the same rate limits per Beam's production write-up of orchestration patterns. If the only thing you gain from a subagent is a permission boundary, that is often still worth it. If you gain no boundary, reconsider.

A permission policy is a data file, not a function buried inside agent setup. Putting rules in a separate, reviewable artifact is the pattern the AI SDK documents for its OPA-based tool approvals: rules live in .rego files, are testable in CI with opa test, and can be edited without a code deploy per the AI SDK policy documentation.

The policy should answer three questions per tool call: which tool, which argument shape, and what decision. Keep decisions to three states, which map directly onto the approval statuses that SDK uses: allow runs the tool, deny returns a denied result the model can reason about, and requires approval pauses for a human response.

# tools.policy.yaml
version: 3
defaults:
  decision: deny          # fail closed for anything unmatched
tools:
  search_tickets:
    - decision: allow
      args: {query: {type: string, max_length: 200}}
  read_customer_record:
    - decision: allow
      args: {customer_id: {pattern: "^cust_[0-9]{6}$"}}
      data_class: [internal, pii]
  send_email:
    - decision: require_approval
      args: {to: {required: true}}
      reason: "outbound mail always needs a human"
  refund:
    - decision: allow
      args: {amount: {max: 0}}
    - decision: require_approval
      args: {amount: {min: 0.01, max: 50}}
    - decision: deny
      args: {amount: {min: 50.01}}
      reason: "refunds above 50 need finance, not an agent"

Three details make this file useful rather than decorative. First, defaults.decision: deny inverts the usual posture. The AI SDK notes that an unmatched rule normalizes to not-applicable, which the SDK treats as allow, so you must add an explicit default deny to your policy to get fail-closed behavior per the same documentation. Second, argument patterns carry as much weight as tool names: allowing refund without a ceiling is not scoping. Third, the decision should be able to consult history, not just the current call. A rule like "deny a second irreversible action in the same run" requires the policy input to include prior calls, which the AI SDK exposes through the full message and tool-call history.

Policy enforcement is strongest on deterministic checks: scopes, thresholds, allowlists, counts and running totals. Content judgments such as "block hostile language" are best-effort and easy to bypass, so keep those in a classifier and let policy handle the deterministic gate around it per the AI SDK guidance.

The policy says what could be allowed. The risk profile says what this child gets. Three inputs do most of the work.

Data sensitivity. What class of data does the child's task touch? A child summarizing public documentation should not hold a credential that reads customer records, even if the parent session can. Classify the input data and map classes to permitted tools.

Action reversibility. Reads are free, writes are not. Deleting a row, sending an email, pushing to a main branch and issuing a refund are all irreversible in the sense that a human will notice and a rollback is expensive. Irreversible actions should default to approval regardless of how privileged the parent is.

Blast radius. How many resources can the child touch if it goes wrong? A query scoped to one tenant is small. A credential that lists every bucket in an account is large. Blast radius is often better controlled by the credential than by the tool name.

Put these together as a derivation function that runs before spawn:

def derive_scope(parent_ctx, task):
    level = 0
    if task.touches_pii or task.touches_secrets:
        level = max(level, 2)
    if not task.reversible:
        level = max(level, 2)
    if task.resource_count > 10:
        level = max(level, 1)
    # level 0: read-only tools; 1: scoped writes; 2: writes gated on approval
    return {
        "tools": TOOLSET_BY_LEVEL[level],
        "credential_ttl_seconds": [900, 600, 300][level],
        "approval_required": level == 2,
        "tenant": parent_ctx.tenant,
        "trace_id": parent_ctx.trace_id,
    }

The result of this function is the child's task envelope. It travels with the spawn call and is the only source of truth for what the child may do. The parent's own permissions are never consulted by the child at runtime.

A worked example with numbers clarifies the tradeoff. Suppose the parent orchestrator can call 14 tools. A spawned "summarize support tickets" child needs two of them. If you inherit wholesale, the child's effective surface is 14 tools and one write-capable token; if one in twenty delegated calls is misrouted, four of every five hundred children get a surface far beyond their task. If you derive scope, the child gets two tools and a 900-second read-only token. The failure is still possible, but it is bounded to reading tickets for fifteen minutes.

Telling the child in its instructions to avoid certain tools is a suggestion. Enforcement means the child literally cannot reach them. Three mechanisms do that work.

Scoped credentials. Mint a child-bound token rather than passing the parent's token downward. The distinction between token inheritance and a token broker is central: inheritance passes existing OAuth material down, while a broker mints child-bound, scope-minimized, time-bounded credentials tied to a delegated approval event per Permit. Treat scope minimization as a property of the credential, not of the tool.

Argument validation wrapper. Every tool call passes through a wrapper that loads the policy, evaluates the call, and either runs it, returns a denied result, or raises an approval request. The wrapper must never fall through to allow. Where the framework supports a policy decision point outside the model, put the check there rather than in application code, because every control that depends on best-effort prompt instructions will eventually be bypassed per Permit's audit trail guidance.

Fail-closed timeouts. An approval request that nobody answers must resolve to denial, not to a stalled child. Name the denial reason so the parent can recover deterministically. Silent stalls are a distinct failure mode from denials, and operators need to tell them apart per Permit.

For teams running agents against production systems, this is where Quanta Inference fits as the credential-free layer: text, image and embedding models behind one OpenAI-compatible endpoint, so the model call itself holds no tool authority and the scoping work stays in your wrapper. Details are at Quanta Inference.

An audit trail for an agent action is not the same thing as a tool trace. A tool trace tells you a function was called. An authorization record tells you whether that call was permitted, for which agent, on whose behalf, against which resource, under which policy version, with what outcome per Permit. Auditors sample for the second.

Carry the trace context across the delegation boundary. Context propagation exists precisely so signals can be correlated across process and network boundaries, and the default propagator uses W3C TraceContext headers per OpenTelemetry's context propagation documentation. Those headers follow a defined format, version-trace-id-parent-id-trace-flags per the W3C Trace Context specification.

Agent boundaries break this in known ways. When an orchestrator enqueues work for a worker, there is no HTTP request to carry traceparent, so the worker starts its own root span and the causal link is severed; the standard fix is to extract the context, serialize it into the message payload, and reattach it on the consumer side per TianPan's write-up on tracing across agent service boundaries. The same problem applies to model context protocol calls, where the calling agent must inject the header at the invocation site.

An in-flight proposal for agent-to-agent tracing makes the gap concrete: the SDK creates spans locally, but there is no standard mechanism to inject traceparent into a delegated message and extract it on the other end, so each delegation produces a disconnected trace per this A2A issue. That proposal also declines to propagate baggage in its first version, on the grounds that baggage travels in plaintext to all downstream services and creates a leakage vector in multi-tenant deployments per the same issue. The lesson for scoping is direct: do not put scope in anything that fans out indiscriminately.

Record at minimum, per decision: agent identity, parent task or delegation chain, tool and arguments, resource, policy ID and version, decision and reason, approval record if any, timestamp, trace ID, and outcome. That is the evidence package that lets an auditor reconstruct the decision later per Permit. Deny records matter as much as allow records, because they prove the gate is active.

Two rows deserve emphasis. The credential row is the one teams skip, and it is the one that survives a buggy policy evaluation: if the child's token cannot write, a policy error cannot cause a write. The history row is the one teams forget: a policy that evaluates only the current call will happily approve the same destructive action ten times in a row, which is why the input should carry prior tool calls per the AI SDK documentation.

If your team is standing up this pattern across many workflows, the fastest route is often to have someone build the policy layer, wrapper and trace plumbing alongside you rather than after an incident. Quanta specialists can take a described requirement and hand back working deliverables, starting from Quanta.