Governed agents
Governed agents are AI coding agents run inside hard boundaries, not given free rein over a machine: a subprocess environment scrubbed to one provider credential, an isolated worktree, and a default-deny tool-call allowlist that validates every argument before anything spawns. Caisson's agent-runner and tool-exec packages ship both boundaries together.
In code
async run(
name: string,
args: unknown,
reason?: string,
): Promise<ExecResult> {
const spec = registry.get(name);
if (spec === undefined) {
throw new NotFoundError(`No command registered for "${name}"`, {
command: name,
});
}
const validatedArgs = parseStrict(spec.argsSchema, args);
const { stdout, stderr, exitCode } = await execFn(
spec.command,
validatedArgs,
{ cwd, timeoutMs },
);
const result: ExecResult = {
command: spec.command,
args: validatedArgs,
exitCode,
stdout,
stderr,
ok: exitCode === 0,
at: now(),
};
return reason === undefined ? result : { ...result, reason };
}How it holds
Env scrubbed to one credential
buildEngineEnv() builds the child process environment from scratch off a fixed non-secret passthrough allowlist (PATH, LANG, TERM, TZ and similar) plus only the target provider's routing variable and key; it never spreads process.env, so a subprocess that egresses to a model provider carries no credential beyond that one key.
Default-deny tool allowlist
tool-exec's registry maps a logical command name to a real executable plus a Zod .strict() argument schema. An unregistered name throws NotFoundError before anything spawns; a registered call is validated against its schema before an argv array is ever built.
Validated argv, never a shell
A tool call's validated arguments become the exact argv array passed to execFile; execSync, exec, and shell: true never appear in tool-exec, so no user-controlled string is ever concatenated into a shell command.
Caller owns every side effect
The sandboxed agent runs detached in an isolated worktree and returns a diff, a transcript, and a structured run report; git, PR, and deploy actions stay with the caller, matching agent-runner's stated trust boundary.