The agent runtime and tool surface

When an agent runs in Disco Parrot, the useful question is not how clever the model is. It is what the agent can actually do: which tools it has, where each one runs, and what happens the moment it tries to change something you care about. The answer is a fixed, well-defined tool surface and a single gate that every write to your work model passes through. This page is how that surface is built.

It is the architecture view, not the governance view. What an agent is allowed to do, the permissions and the scope model, is covered on approved actions and least privilege and the approved actions concept; what working with an agent feels like is on chat. Here the question is the mechanism: the shape of the tool surface and the checks behind it.

The four kinds of tools

Everything an agent can call falls into one of four kinds, and the kind tells you where the tool runs and what it can touch.

• The agent's own tools, inside the sandbox. Reading and writing files, running a shell command, fetching a URL, keeping a task list. These come from the agent SDK and run in the container, with no trip back to the platform. The shell is one of them: an agent can run commands, and the container, not a missing tool, is what bounds what those commands can reach. A flow step set to strict command enforcement can drop the shell from the set, but the everyday agent has it.
• Tools that pause for a person. A small number of tools exist so the agent can stop and ask. One asks you a question, another presents a plan for your approval, and calling either suspends the turn until you answer. These are rendered by the platform, in your app, not run in the container.
• Tools that change your work model. When an agent creates or edits an initiative, a plan, a skill, an agent instruction, or a sandbox profile, it calls a tool that the platform executes on the host, not the container. Every one of these passes the gate described below before anything is written.
• Your connected tools. The MCP servers you connect, a tracker, a database, an internal service, attach to a sandbox profile, and the agent reaches them through the MCP tool surface. Which of their tools are on is a per-profile allowlist, so a workspace's connected reach is configuration, not code.

How a tool call travels

Where a tool runs decides who can govern it, so the four kinds split into two paths. The agent's own SDK tools run where the agent runs, inside the container, and their results never leave it until the agent decides to write something. A file read is a file read; the platform is not in the loop.

The other three kinds are host-executed. When the agent calls one, the call travels out of the container, back over the platform's transport to the host, where the platform runs it, checks it, records it, and returns the result to the agent to continue its turn. Asking you a question, changing a plan, reaching a connected tool: each is a round trip the platform sees and governs, which is exactly why those are the calls that can pause for you, pass the write checks, or be held to a budget. The payoff is direct: every call that can touch your data or pause for your input is one the platform governs, while the cheap local work is not slowed by a round trip it does not need.

How an agent reads and writes your work

An agent does most of its work the way a person on your team would: in files. At the start of a run, the records the work is about, the focal initiative, its plans, the bugs and attachments in scope, are materialized into the container as files the agent can read. If it needs a related record mid-turn, a read-only tool fetches that record into the workspace as well, so the agent reads your work model much the way you query it, except as files in front of it rather than rows behind a screen. What it can read is bounded to your workspace and to the work the run is about; there is no general query-the-whole-database tool.

Changing your actual records is a different act from editing those files. The files are a working copy; your initiatives, plans, and bugs are records in the store. When the agent's edits should land on a record, that happens through a host-executed authoring call that crosses back to the platform and passes the gate below, and when the turn ends a sweep reads the changed files back and writes them through that same gate, marked as the agent's hand. This is why an agent's two kinds of output land in two different places: its code work becomes a branch and a pull request you review and merge, and its work-model edits become versioned, audited records you can read and restore. The agent works in files; the platform decides what becomes a record, and on what terms.

Every write to your work passes one gate

This is the load-bearing part. An agent does not write to your work model directly. Every authoring call, every create or edit of an initiative, plan, skill, instruction, or profile, runs the same checks around the write, and five things happen across them:

1. Permission, before the write. The change is checked against the acting person's scopes. If the person the run belongs to could not make this change by hand, the agent cannot make it for them. There is no agent override.
2. Rate, before the write. The change is counted against a budget, so a runaway loop cannot author a thousand records. The budgets are per workspace and per person, by kind of write, and a call over the line is refused with a retry-after rather than served.
3. Concurrency, at the write. The write commits against the exact version the agent read. If the record changed underneath the agent while it was working, the write is refused with a precondition-failed result rather than landing, and the agent has to re-read the current state and try again. A concurrent human edit cannot be silently overwritten, because the write that did not see it does not commit.
4. Version, after the write. Once the change lands, it is captured as a new version snapshot, tagged as the agent's hand, so the prior state is recoverable and the history shows the agent authored this one.
5. Audit, after the write. The change is written to the trail, and so are the attempts the checks refuse, so the record of what an agent tried is as complete as the record of what it did.

The same checks run no matter which tool did the authoring and no matter which model backs the run. That is what lets the rest of the system treat an agent's edit and a person's edit as the same kind of event, marked apart only by whose hand it was.

The tool set is fixed when the turn starts

An agent's tool surface is assembled before the turn begins and cannot be widened from inside it. The platform decides the exact set of tools for this run, on this surface, for this person, and hands it to the agent as a fixed list. There is no tool the agent can call to grant itself another tool, and no prompt, including a malicious one injected through a document or a web page, can add to the set mid-turn. The agent works with the hand it was dealt.

Injection can still try the other move: making the agent misuse a tool it does have, asking it to edit a record it can legitimately reach. That is the other half of why the write checks exist. A tool the agent holds still cannot change a record the acting person could not change by hand, so a misused tool runs into the same permission wall a misused account would. The surface bounds what the agent can reach; the checks bound what it can do with what it reached.

That is why the container can be the security boundary rather than a per-call permission prompt. The platform is not asking the agent's permission system to behave; it is deciding the surface up front and running the agent inside a container that bounds the rest. An agent that is talked into trying something outside its surface finds the tool is not there. Approved actions and least privilege is the governance account of why that holds.

When one agent hands off to another

A run can fan out. An agent can spawn a set of sub-agents to work in parallel, up to twenty at once, each taking part of the job. That is useful for work that splits cleanly, reviewing twenty files, drafting against twenty records, and it is the question a prospect comparing agent platforms asks, because delegation is where reach tends to leak.

It does not leak here. A sub-agent is not a way around the boundary; it inherits it. Each one runs in its own container, on the same fixed tool surface, and every change it makes to your work model passes the same gate as the agent that spawned it. Fan-out multiplies the hands, not the reach: twenty sub-agents have exactly the authority one agent has, scoped to the same person and checked the same way. The cap on how many run at once is a guardrail in its own right, so a run cannot spawn an unbounded swarm.

The same surface across models

A skill or an instruction you write should not have to care which model runs it, and it does not. Disco Parrot runs more than one model runtime, Claude, Codex, and Copilot among them, and an agent sees the same tool surface whichever one backs the turn. The tool an agent calls to ask you a question carries the same name and the same shape to all three; only the registration that wires it into each runtime differs. So a skill author writes against "ask the user" once, and a workspace can switch the model behind a run, from Claude to Codex, say, without rewriting a skill, re-checking a permission, or changing what the agent is able to do. The one part that varies is the connected MCP tools, and they vary by profile, not by model: the profile decides which connected tools are on, and whichever model runs inherits that set.

Pausing for a person, mid-turn

The two tools that pause a turn are worth separating from a flow's checkpoints. A flow checkpoint sits between steps; these tools pause inside a single agent turn. When the agent calls one, the turn suspends, the question or the plan surfaces in your app, and the run waits. Your answer comes back on the next exchange and the turn resumes from where it paused, with the answer in hand.

When a run is sent to the background, those same pauses are auto-resolved so the run can keep moving without a person watching, and each auto-resolution is logged rather than silent, so the trail shows the agent proceeded on its own judgment at that point. Human oversight and approvals is the governance view of how that stays reviewable.

Reaching out

One of the agent's native tools fetches a URL, and the honest account of what governs that is worth giving plainly. There is no egress allowlist around the agent today; an agent can make an outbound request. What keeps that from being a way out of your data is not a network fence around the container but the same two facts that bound everything else: the agent holds no standing credentials, so an outbound request reaches nothing protected without a credential the platform leased it for that exact use, and the container is the boundary for everything that happens inside it. Outbound is governed by the credential model, not by a list of allowed destinations. And what an agent can put into an outbound request is itself bounded by what it was able to read in the first place. Data access covers what that means for what an agent can and cannot send out.

When a run genuinely needs a credential, a token to clone a repository, a key a connected tool authenticates with, it does not receive the secret. It calls a tool that requests a lease and gets back an opaque grant, a lease identifier and an expiry, never the credential value. The platform resolves the real secret on its own side, at the moment of use, scoped to that one operation, and delivers it to the operation rather than to the agent; the lease itself is recorded on the audit trail. The agent gets the use of a credential for the moment it needs one, not the credential to keep. Credential leases is the full account.

The budgets the surface enforces

The host-executed tools are held to per-turn budgets, so a single turn cannot lean on any one of them without limit. A turn gets on the order of twenty authoring writes, a handful of reaches for related records, a few flow starts, a few credential leases; past the budget, that tool is refused for the rest of the turn. Authoring also carries a per-day budget the permission step applies, on the order of fifty writes per workspace and twenty per person, and it is counted by kind: a skill, an agent instruction, an MCP connection, a sandbox profile, a flow, a portfolio, and a project each carry their own daily count, so heavy work on one does not exhaust the budget for another. Sustained authoring is bounded across turns as well as within one. These are not the model's own rate limits; they are the platform's, applied to the tool surface regardless of which model is driving.

An agent editing a plan, step by step

When an agent on Priya's team adds an acceptance criterion to a plan, the write does not go straight to the store. The checks run first: the platform confirms the run's owner holds the permission to edit plans and counts the write against the budget. The write then commits against the version the agent read. The plan had not changed, so it lands, and the change is recorded as a new version marked as the agent's hand and written to the audit trail. A moment later the agent tries a second edit, but Priya has just edited the same plan in her own tab; the commit is refused with precondition-failed, the agent re-reads the current plan, folds in her change, and writes again. Nothing was clobbered, both edits are in the history, and the trail shows exactly which hand made each one. None of that depended on the model behaving well; the checks made the outcome the same either way.

Why the runtime works this way

An agent is capable, fast, and occasionally wrong, and it runs on input you do not fully control, a web page, a document, a tool's response. A design that trusts the agent to police itself fails the first time something in that input talks it into misbehaving. So Disco Parrot does not trust the agent; it bounds it. The tool surface is decided before the turn and cannot grow from inside it. The cheap local work stays in a container that is the boundary. And the one thing that matters most, a change to your work, passes a single gate that checks permission, rate, concurrency, version, and audit every time, for every tool and every model. The result is that you can hand an agent real authority over real records, because the authority is shaped by the platform rather than promised by the agent.

For a developer, the model is a fixed tool surface in four kinds: SDK-native tools that run in the container, host tools that pause for a person, host tools that author your work model through the write checks, and per-profile MCP tools. Authoring runs the same checks every time, permission and rate before the write, a precondition at the commit, a version snapshot and an audit entry after, and the surface is assembled at dispatch, identical in name and shape across model runtimes.

For a platform engineer, the operational facts are that the tool set is immutable for the life of a turn, host-executed tools carry per-turn budgets and authoring carries per-day budgets by kind, and a concurrent edit is caught by a precondition check rather than a lock. The shell is a base tool, removed only by a strict-command step, and outbound has no egress allowlist, so the credential model is what bounds reach.

For an enterprise reviewer, the surface is the thing to check: an agent's reach is an enumerated set decided before it runs and not extensible from inside the run, there is no agent override on permission, and every write is recorded as a version and an audit entry against the acting person. A prompt-injected agent finds the tools it was not given are absent.

For a prospect, the assurance is that letting an agent act is not a leap of faith and not a bet on the model's good behavior. It works with a set of tools you can see, it pauses for you where it should, every change it makes to your records is checked and recorded the same way a person's is, and nothing it reads can talk it into reaching further than it was given.