Plugins
Write and run orchestration plugins — hooks, the context object, isolation under the Node.js permission model, limits and the conditions for running.
A plugin is one self-contained ES module (bundle its dependencies) in the manifest's plugin.source, exporting a
function per hook it lists in plugin.hooks.
| Hook | Export | When | May return |
|---|---|---|---|
task.prepare | prepare(ctx) | Before the agent starts | { instructions }, added to the agent's prompt |
task.verify | verify(ctx) | With the other verification checks | { checks: [{ name, passed, summary }] } — a failed check is a required step |
task.completed | completed(ctx) | After the task completed | Nothing |
ctx holds task (id, title, prompt, projectId, environment), projectDir, config (the installation's
configuration), hook data — verification and changedFiles for verify, report for completed — and log(…),
whose lines appear in the task timeline.
export function verify(ctx) {
const touched = (ctx.changedFiles ?? []).filter((f) => f.startsWith('legacy/'));
return { checks: [{ name: 'legacy/ untouched', passed: touched.length === 0, summary: touched.join(', ') }] };
}When plugins run
Only when all of these hold:
- a platform administrator turned on the
plugins.executionfeature flag for the organization (off by default); - an administrator approved the installation (plugins always need approval);
- the worker's owner has not unticked Run approved plugin code on this machine.
Otherwise the timeline records why the plugin was skipped. Workers need Node.js 22.13 or later.
Isolation
Each hook runs in a new Node.js process under the permission model:
| Permission | Grants |
|---|---|
| (none) | Read its own code; read and write its own data folder |
filesystem.project.read / .write | Read / read and write the project folder |
filesystem.read / filesystem.write | Read / write anywhere the worker's user can |
network.outbound | Network access; otherwise sockets, HTTP, fetch, WebSocket, DNS, UDP and listening are blocked |
process.execute, shell | Child processes — unrestricted, effectively full access |
secrets.read | secret:NAME configuration values resolved (each delivery audited) |
Plugins never get the worker's environment variables or credentials; native addons, WASI and process.binding are
unavailable. Each hook has a time limit (timeoutMs, default 30 s) and a memory limit (memoryMb, default 256 MB).
A plugin that crashes, times out or returns an invalid result is recorded and never fails the task by itself. The
control plane stores the code's SHA-256 at registration, and workers refuse code that does not match.
Not an OS sandbox
Network blocking is in-process (Node.js 22 has no network permission), and a plugin granted process.execute or
shell can start unrestricted processes. Plugin isolation has been tested on Windows only.