A local-first multi-agent app development platform, built on PenguinHarness
/**
* Command policy — the project-level sandbox guardrail for shell commands.
*
* A deny-rule list the Session applies to the **injected approval callback**: `Session.run`
* wraps `RunOptions.approve` with `withCommandPolicy`, so a matching command answers "deny"
* without the human being consulted, and the policy therefore outranks every approval mode,
* allow-all included. Nothing about it reaches `context_engine`, which keeps doing what it
* always did — ask the approval boundary, record the decision, feed a denied call its
* terminal output.
*
* Both tools that reach a shell are checked: `exec_command`'s `cmd` (the launch, read through
* the tool's own argument list so its `command` alias is screened the same) and
* `input_command`'s `chars` (what gets typed into an already-running one). Guarding only the
* first would have made the guardrail exactly one interpreter launch deep — start `bash`,
* which matches nothing, then type. The one exemption is a lone `\u0003`, which the tool
* turns into SIGINT rather than writing it to stdin.
*
* The config lives in `.project_config.toml` (`[command_policy]`) — Project-owned on purpose:
* security policy belongs to the Project, not to Agent State the Agent itself can rewrite.
* The Session receives a policy SOURCE — a getter answering with the policy of the model
* context it is running, read from disk once when each context opens: command policy is
* strict-tier, so an edit applies when the next context opens (rotation), never mid-file.
* The getter is still consulted per decision, which is what hands the tool calls after a
* mid-run rotation the new context's policy without any reload machinery.
*
* The rules are **data, not code**: every rule (name / pattern / description / enabled) is
* project-editable, and the factory set (state/command-policy-defaults.ts) is *seeded* into
* new projects' config the same way model presets are — copied in at creation, never
* rewritten afterward. A config without a `rules` list behaves as the factory set
* (pre-seeding projects); the first saved edit materializes the list into the file.
*
* This is an **accident guardrail, not a security boundary**, and the distinction is not
* modesty: shell is a programming language, and deciding what a program will do by matching
* its text before it runs is not a thing more rules get closer to. What the rules do cover is
* ordinary typing — a path (`/bin/rm`), a wrapper (`sudo`, `env`, `xargs`), quoting or a
* backslash escape of the command word, and a literal `sh -c '<payload>'` — because those are
* spellings a model reaches for by habit, not evasion. What they deliberately do not cover is
* anything that computes the command at run time: `$IFS` splicing, `X=rm; $X`, `eval`,
* base64 into a shell, `python -c`, an interpreter reached through a pipe. Each of those
* would take a pattern that costs maintenance and buys only the appearance of coverage.
*
* MCP tools are out of scope by design. The per-server `permission` level is what exists for
* that surface, and it only fixes the level a Server's tools report to the approval mode — it
* confines nothing. For an actual boundary rather than a speed bump, the
* confinement interface (bubblewrap / dsh) is the mechanism; this policy is complementary to
* it and no substitute.
* Docs: /docs/configuration § "Command policy".
*/
import type { ApproveFn, CommandPolicyConfig, CommandPolicyRule } from "../interfaces/index.js";
import { effectiveCommandPolicyRules } from "../state/command-policy-defaults.js";
import {
EXEC_COMMAND_NAME,
EXEC_COMMAND_TEXT_ARGUMENTS,
} from "../environment/tools/exec-command.js";
import { INPUT_COMMAND_NAME, INTERRUPT } from "../environment/tools/input-command.js";
import { stringArgument } from "../environment/tools/tool-arguments.js";
/** A command-policy hit: the matched rule's name. */
export interface CommandPolicyVeto {
rule: string;
}
/** Collapses whitespace runs to single spaces (the only normalization rule patterns may assume). */
function normalizeCommand(cmd: string): string {
return cmd.replace(/\s+/g, " ").trim();
}
/**
* The spellings a rule is tested against: the command as written, plus — when it differs —
* the same text with shell quoting removed (`'` / `"` dropped, `\x` reduced to `x`). Quoting
* is where the plain spellings hide: `"rm" -rf /`, `r''m -rf /`, `\rm -rf /`, and the literal
* `sh -c 'rm -rf /'` are all the unquoted text once the marks come off. Both are tested, so
* unquoting can only add matches, never drop one a rule would otherwise make.
*
* This is a normalization, not an evaluation: it does not expand a variable, run a
* substitution, or decode anything, so a command assembled at run time still walks past.
*/
function commandVariants(cmd: string): string[] {
const literal = normalizeCommand(cmd);
const unquoted = normalizeCommand(cmd.replace(/\\(.)/g, "$1").replace(/['"]/g, ""));
return unquoted === literal ? [literal] : [literal, unquoted];
}
/**
* Compiles a rule's pattern, returning null for an invalid regex instead of throwing: a
* broken rule must not take the whole policy (or the Session) down with it. Write paths
* validate patterns up front (the server rejects an uncompilable rule), so this only fires
* for hand-placed data.
*/
function compileRule(rule: CommandPolicyRule): RegExp | null {
try {
return new RegExp(rule.pattern);
} catch {
return null;
}
}
/**
* Evaluates one command against the policy: the first matching enabled rule wins, in list
* order. Returns null when the policy is disabled or nothing matches. An absent config or
* an absent `rules` list means the factory set (a project from before the block was
* seeded, or an SDK embedder passing no policy).
*/
export function evaluateCommandPolicy(
cmd: string,
policy?: CommandPolicyConfig,
): CommandPolicyVeto | null {
if (policy?.enabled === false) return null;
const variants = commandVariants(cmd);
if (variants[0] === "") return null;
for (const rule of effectiveCommandPolicyRules(policy)) {
if (rule.enabled === false) continue;
const re = compileRule(rule);
if (re && variants.some((v) => re.test(v))) {
return { rule: rule.name };
}
}
return null;
}
/**
* The arguments that carry shell text, per tool, in the order the tool itself reads them:
* `exec_command` launches one (`cmd`, or its alias `command`) and `input_command` types into
* one already running (`chars`). Sharing the tool's own list is what keeps the screened text
* and the executed text one value. Every other tool — MCP included — is not the policy's
* business.
*/
const SHELL_TEXT_ARGUMENTS: Readonly<Record<string, readonly string[]>> = {
[EXEC_COMMAND_NAME]: EXEC_COMMAND_TEXT_ARGUMENTS,
[INPUT_COMMAND_NAME]: ["chars"],
};
/**
* Policy gate for one tool call, keyed by tool name: the tool's shell-text argument is
* evaluated, and anything else passes. A lone `\u0003` is exempt — `input_command`
* special-cases it into SIGINT rather than writing it to stdin, so it is a Ctrl-C, not a
* command. `argsJson` is the tool_call's raw argument JSON; malformed JSON or a
* malformed argument is the tool's own validation error, not a policy hit.
*/
export function vetoForToolCall(
toolName: string,
argsJson: string,
policy?: CommandPolicyConfig,
): CommandPolicyVeto | null {
const names = SHELL_TEXT_ARGUMENTS[toolName];
if (names === undefined) return null;
let args: unknown;
try {
args = JSON.parse(argsJson) as unknown;
} catch {
return null;
}
if (args === null || typeof args !== "object" || Array.isArray(args)) return null;
const text = stringArgument(args as Record<string, unknown>, names)?.value;
if (text === undefined) return null;
if (text === INTERRUPT) return null;
return evaluateCommandPolicy(text, policy);
}
/** Where the policy comes from at decision time: a getter answering with the running context's policy (see SessionConfig.commandPolicy) — consulted per approval, so a mid-run rotation swaps what later calls see. */
export type CommandPolicySource = () => CommandPolicyConfig | undefined;
/**
* Wraps an approval callback with the policy: a vetoed call answers `"forbidden"` here and
* `approve` is never reached, so no approval mode — and no Human implementation — can let
* it through. `"forbidden"` is the decision's own third value: the engine renders it as
* the fixed aborted line "Tool call denied by policy." (a person's denial reads "by
* user."), and the `approval_decision` event carries it — the model's text and the Trace
* both name the decider. The `source` getter is consulted at every decision (no source, or
* a source yielding nothing, applies the factory rule set); a source that cannot be read
* fails toward the factory rules rather than waving the call through.
*/
export function withCommandPolicy(approve: ApproveFn, source?: CommandPolicySource): ApproveFn {
return async (toolCall) => {
let policy: CommandPolicyConfig | undefined;
try {
policy = source?.();
} catch {
policy = undefined;
}
const veto = vetoForToolCall(toolCall.payload.name, toolCall.payload.arguments, policy);
if (veto) return "forbidden";
return approve(toolCall);
};
}