A local-first multi-agent app development platform, built on PenguinHarness
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { rmEventually } from "./rm-eventually.js";
import {
Session,
assistantText,
isEventMessage,
parsePreToolUseResult,
parseStopHookResult,
runHookScript,
runPreToolUseHooks,
runStopHooks,
scriptPreToolUseHook,
scriptStopHook,
scriptUserPromptHook,
tokenUsage,
toolCall,
toolCallOutput,
userText,
} from "../src/index.js";
import type {
CommandPolicyConfig,
EnvironmentInterface,
HookPayload,
HookSubagentRequest,
HookSubagentSpawned,
LLMInterface,
LLMOutcome,
OmniMessage,
PreToolUseHook,
SessionMetaPayload,
StopHook,
StopHookInput,
TokenCounts,
TraceSink,
} from "../src/index.js";
function usage(total: number, cacheRead = 0): TokenCounts {
return { cache_read: cacheRead, cache_write: 0, output: 0, total };
}
function stopInput(over: Partial<StopHookInput> = {}): StopHookInput {
return { sessionId: "s1", ...over };
}
/** A script that reads the hook input from stdin and answers with `body` (a JS expression over `input`). */
const answering = (body: string): string =>
'const raw = await new Promise((r) => { let s = ""; process.stdin.setEncoding("utf8").on("data", (c) => (s += c)).on("end", () => r(s)); });\n' +
"const input = JSON.parse(raw);\n" +
`process.stdout.write(JSON.stringify(${body}));\n`;
describe("runStopHooks", () => {
it("records every answer, honors the first continue, and keeps a throwing hook from taking the run down", async () => {
const hooks: StopHook[] = [
{ name: "quiet", run: async () => undefined },
{ name: "broken", run: async () => Promise.reject(new Error("boom")) },
{
name: "first",
run: async () => ({ decision: "continue", input: "again", reason: "one" }),
},
{
name: "second",
run: async () => ({ decision: "continue", input: "later", output: { n: 2 } }),
},
{ name: "note", run: async () => ({ reason: "just a record" }) },
];
const { events, next } = await runStopHooks(hooks, stopInput());
expect(next).toBe("again");
// No event for a void answer; the injected input never rides an event.
expect(events.map((e) => (e.payload as HookPayload).name)).toEqual([
"broken",
"first",
"second",
"note",
]);
expect(events[0]!.payload).toMatchObject({ hook: "stop", reason: "hook failed: boom" });
expect((events[0]!.payload as HookPayload).decision).toBeUndefined();
expect(events[1]!.payload).toEqual({
type: "hook",
hook: "stop",
name: "first",
decision: "continue",
reason: "one",
});
expect((events[2]!.payload as HookPayload).output).toEqual({ n: 2 });
expect(JSON.stringify(events)).not.toContain("again");
});
it("hands a subagent request to the spawner and records the child's session id; a missing or failing spawner is recorded", async () => {
const asks: HookSubagentRequest[] = [];
const hook: StopHook = {
name: "review",
run: async () => ({
reason: "delegated",
output: { turns: 20 },
subagent: { prompt: "review this", agentId: "b" },
}),
};
const childMeta = {
type: "session_meta",
origin: ["child-1"],
payload: { session_id: "child-1" },
} as unknown as OmniMessage;
const spawned = await runStopHooks([hook], stopInput(), async (req) => {
asks.push(req);
return { sessionId: "child-1", meta: childMeta };
});
expect(asks).toEqual([{ prompt: "review this", agentId: "b" }]);
expect(spawned.events[0]!.payload).toMatchObject({
reason: "delegated",
output: { turns: 20, session_id: "child-1" },
});
// Behind the event: the child's own meta, for the host to register it from.
expect(spawned.events[1]).toBe(childMeta);
expect(spawned.events).toHaveLength(2);
const unspawned = await runStopHooks([hook], stopInput());
expect((unspawned.events[0]!.payload as HookPayload).reason).toBe(
"delegated · subagent not spawned: no spawner",
);
const failed = await runStopHooks([hook], stopInput(), async () => {
throw new Error("depth limit");
});
expect((failed.events[0]!.payload as HookPayload).reason).toBe(
"delegated · subagent not spawned: depth limit",
);
expect((failed.events[0]!.payload as HookPayload).output).toEqual({ turns: 20 });
expect(failed.events).toHaveLength(1);
});
});
describe("script hooks", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-script-hook-"));
});
afterEach(async () => {
await rmEventually(dir);
});
const write = async (name: string, body: string): Promise<string> => {
const file = path.join(dir, name);
await fs.writeFile(file, body, "utf8");
return file;
};
it("runHookScript feeds the input on stdin and returns the parsed stdout; empty stdout is no opinion", async () => {
const echo = await write(
"echo.mjs",
answering("{ got: input, cwd: process.cwd(), asNode: process.env.ELECTRON_RUN_AS_NODE }"),
);
const out = (await runHookScript(echo, { hook: "stop", session_id: "s1" })) as Record<
string,
unknown
>;
expect(out.got).toEqual({ hook: "stop", session_id: "s1" });
// Real paths on both sides: macOS reports the temp dir through its /private symlink.
expect(await fs.realpath(out.cwd as string)).toBe(await fs.realpath(dir));
// The Electron-safety flag reaches the child (see runHookScript's spawn env).
expect(out.asNode).toBe("1");
const quiet = await write("quiet.mjs", "process.exit(0);\n");
expect(await runHookScript(quiet, {})).toBeUndefined();
});
it("pathPrepend puts the host's directories at the front of the script's PATH", async () => {
// A hook is spawned as `node <script>` — no shell, so nothing re-orders PATH after
// this. It is the same directory commands get (the harness's own CLI shim), so a hook
// that shells out to `penguin` reaches the harness running it.
const readPath = await write("path.mjs", answering("{ path: process.env.PATH }"));
const out = (await runHookScript(readPath, {}, { pathPrepend: ["/opt/penguin/bin"] })) as {
path: string;
};
expect(out.path.startsWith(`/opt/penguin/bin${path.delimiter}`)).toBe(true);
expect(out.path).toContain(process.env.PATH ?? "");
});
it("a non-zero exit, non-JSON stdout, and a timeout each fail with a reason", async () => {
const crash = await write("crash.mjs", 'process.stderr.write("kaboom\\n"); process.exit(3);\n');
await expect(runHookScript(crash, {})).rejects.toThrow(/exit 3: kaboom/);
const garbage = await write("garbage.mjs", 'process.stdout.write("not json");\n');
await expect(runHookScript(garbage, {})).rejects.toThrow(/stdout is not JSON/);
const hang = await write("hang.mjs", "setInterval(() => {}, 1000);\n");
await expect(runHookScript(hang, {}, { timeoutS: 0.2 })).rejects.toThrow(/timed out/);
});
it("parseStopHookResult keeps the contract's fields only, and scalars only in output", () => {
expect(
parseStopHookResult({
decision: "continue",
input: "next",
reason: "r",
output: { a: 1, b: "x", c: true, d: { nested: 1 }, e: null },
subagent: { prompt: "p", agent_id: "b", extra: 1 },
unknown: "dropped",
}),
).toEqual({
decision: "continue",
input: "next",
reason: "r",
output: { a: 1, b: "x", c: true },
subagent: { prompt: "p", agentId: "b" },
});
expect(parseStopHookResult({ decision: "maybe", input: 5, subagent: { prompt: " " } })).toEqual(
{},
);
expect(parseStopHookResult("nope")).toBeUndefined();
expect(parseStopHookResult(null)).toBeUndefined();
});
it("scriptStopHook adapts one installed command: the hook input on stdin, the answer parsed", async () => {
await write(
"stop.mjs",
answering(
'{ decision: "stop", reason: `${input.hook} ${input.session_id} ${input.trace_path}` }',
),
);
const hook = scriptStopHook("demo", dir, "stop.mjs", { timeoutS: 5 });
expect(hook.name).toBe("demo");
expect(await hook.run({ sessionId: "s1", tracePath: "/t/s1_001.jsonl" })).toEqual({
decision: "stop",
reason: "stop s1 /t/s1_001.jsonl",
});
});
});
describe("script hooks under the sandbox", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-hooks-sandbox-"));
});
afterEach(async () => {
await rmEventually(dir);
});
it("spawns the confiner's argv with the runner's environment laid over the script's", async () => {
// A stand-in runner: runs the script it is handed, and shows that it ran through it.
const runner = path.join(dir, "runner.mjs");
await fs.writeFile(
runner,
[
'import { pathToFileURL } from "node:url";',
'process.env.HOOK_RAN_THROUGH = "runner";',
"await import(pathToFileURL(process.argv[2]).href);",
].join("\n"),
);
const script = path.join(dir, "report.mjs");
await fs.writeFile(
script,
"process.stdout.write(JSON.stringify({ through: process.env.HOOK_RAN_THROUGH, marker: process.env.HOOK_RUNNER_MARK }));\n",
);
const seen: string[][] = [];
const out = (await runHookScript(
script,
{},
{
confine: (argv) => {
seen.push([...argv]);
return { argv: [argv[0]!, runner, ...argv.slice(1)], env: { HOOK_RUNNER_MARK: "set" } };
},
},
)) as { through: string; marker: string };
expect(seen).toEqual([[process.execPath, script]]);
expect(out).toEqual({ through: "runner", marker: "set" });
});
it("fails the hook when the confiner cannot enforce its policy, and never runs the script", async () => {
const script = path.join(dir, "touch.mjs");
const witness = path.join(dir, "ran");
await fs.writeFile(
script,
`import fs from "node:fs"; fs.writeFileSync(${JSON.stringify(witness)}, "");\n`,
);
await expect(
runHookScript(
script,
{},
{
confine: () => {
throw new Error("no sandbox backend is mounted");
},
},
),
).rejects.toThrow(/sandbox: no sandbox backend is mounted/);
await expect(fs.access(witness)).rejects.toThrow();
});
it("an installed command reads the Session's confiner at every run, with the package directory as cwd and the Session's scope", async () => {
const script = path.join(dir, "stop.mjs");
await fs.writeFile(script, 'process.stdout.write(JSON.stringify({ decision: "stop" }));\n');
const scopes: unknown[] = [];
let confiner: ((argv: readonly string[], opts: unknown) => { argv: readonly string[] }) | null =
null;
const hook = scriptStopHook("demo", dir, "stop.mjs", {
confineSpawn: () => confiner,
scope: { workspaceDir: "/ws", scratchpadDir: "/scratch/s1" },
});
// Unconfined while the getter answers null…
expect(await hook.run(stopInput())).toEqual({ decision: "stop" });
// …confined under whatever it answers next, with the scope a command would get.
confiner = (argv, opts) => {
scopes.push(opts);
return { argv };
};
expect(await hook.run(stopInput())).toEqual({ decision: "stop" });
expect(scopes).toEqual([{ cwd: dir, workspaceDir: "/ws", scratchpadDir: "/scratch/s1" }]);
confiner = () => {
throw new Error("refused");
};
await expect(hook.run(stopInput())).rejects.toThrow(/sandbox: refused/);
});
});
describe("script pre-tool-use hooks", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-tool-script-"));
});
afterEach(async () => {
await rmEventually(dir);
});
it("scriptPreToolUseHook feeds the call on stdin and narrows the parsed answer", async () => {
const script = path.join(dir, "guard.mjs");
await fs.writeFile(
script,
[
'import fs from "node:fs";',
'const input = JSON.parse(fs.readFileSync(0, "utf8"));',
"const args = JSON.parse(input.arguments);",
"process.stdout.write(JSON.stringify({",
' decision: "deny",',
" reason: `${input.hook}/${input.tool_name}/${input.tool_call_id}: ${args.cmd}`,",
" output: { checked: true, nested: { dropped: true } },",
"}));",
].join("\n"),
);
const hook = scriptPreToolUseHook("guard", dir, "guard.mjs");
const result = await hook.run({
sessionId: "s1",
toolName: "exec_command",
toolCallId: "c9",
argumentsJson: '{"cmd":"make it"}',
});
expect(result).toEqual({
decision: "deny",
reason: "pre_tool_use/exec_command/c9: make it",
output: { checked: true },
});
});
it("parsePreToolUseResult drops unknown decisions", () => {
expect(parsePreToolUseResult({ decision: "continue", reason: "r" })).toEqual({ reason: "r" });
expect(parsePreToolUseResult("nope")).toBeUndefined();
});
});
describe("Session user-prompt hook", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-prompt-hook-"));
});
afterEach(async () => {
await rmEventually(dir);
});
it("runs the named package's host-triggered hook with the Session's own id and scratchpad, null when absent", async () => {
const script = path.join(dir, "expand.mjs");
await fs.writeFile(
script,
[
'import fs from "node:fs";',
'const input = JSON.parse(fs.readFileSync(0, "utf8"));',
"process.stdout.write(JSON.stringify({",
" context: `${input.hook}/${input.session_id}/${input.prompt}/${input.budget} @ ${input.scratchpad_dir}`,",
"}));",
].join("\n"),
);
const meta: SessionMetaPayload = {
session_id: "session-1",
provider: "custom",
model_id: "m1",
model_context_window: 1000,
system_prompt: "sp",
agent_state: dir,
workspace: dir,
source: "user",
};
const scratchpad = path.join(dir, "scratchpad", "session-1");
const session = new Session({
meta,
bootstrap: async () => {
throw new Error("not used");
},
environment: {
listTools: async () => [],
// eslint-disable-next-line require-yield
executeTool: async function* () {
throw new Error("not used");
},
toolPermission: () => undefined,
},
imagesDir: scratchpad,
modelHasVision: true,
hooks: {
userPrompt: [scriptUserPromptHook("goal", dir, "expand.mjs", { trigger: "host" })],
},
});
const result = await session.runUserPromptHook("goal", "ship it", { budget: 500 });
expect(result?.context).toBe(`user_prompt/session-1/ship it/500 @ ${scratchpad}`);
expect(await session.runUserPromptHook("not-installed", "x")).toBeNull();
});
});
describe("Session stop hooks", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-hooks-"));
});
afterEach(async () => {
await rmEventually(dir);
});
const fakeEnvironment: EnvironmentInterface = {
listTools: async () => [],
// eslint-disable-next-line require-yield
executeTool: async function* () {
throw new Error("not used");
},
toolPermission: () => undefined,
};
/** Echoes each Task's input as one final text, with usage. */
function echoLLM(): LLMInterface & { inputs: string[] } {
const inputs: string[] = [];
return {
inputs,
async *streamGenerate({ newMessages }) {
const last = newMessages[newMessages.length - 1]?.payload as { text?: string } | undefined;
inputs.push(last?.text ?? "");
yield assistantText(`echo: ${last?.text ?? ""}`);
yield tokenUsage(usage(100), usage(100, 30));
return { status: "completed" } satisfies LLMOutcome;
},
};
}
function makeSession(
hooks: StopHook[],
llm: LLMInterface,
extra: {
trace?: TraceSink;
spawnSubagent?: (
request: HookSubagentRequest,
approve?: unknown,
) => Promise<HookSubagentSpawned>;
preToolUse?: PreToolUseHook[];
commandPolicy?: CommandPolicyConfig;
environment?: EnvironmentInterface;
} = {},
): Session {
const meta: SessionMetaPayload = {
session_id: "session-1",
provider: "custom",
model_id: "m1",
model_context_window: 1000,
system_prompt: "sp",
agent_state: dir,
workspace: dir,
source: "user",
};
return new Session({
meta,
bootstrap: async () => ({ llm }),
environment: extra.environment ?? fakeEnvironment,
imagesDir: path.join(dir, "scratchpad", "session-1"),
modelHasVision: true,
hooks: {
stop: hooks,
...(extra.preToolUse ? { preToolUse: extra.preToolUse } : {}),
...(extra.spawnSubagent ? { spawnSubagent: extra.spawnSubagent } : {}),
},
...(extra.commandPolicy ? { commandPolicy: () => extra.commandPolicy } : {}),
...(extra.trace ? { trace: extra.trace } : {}),
});
}
it("a continue drives a second Task in the same run, with its input yielded and the events recorded in the Trace", async () => {
const seen: StopHookInput[] = [];
const hook: StopHook = {
name: "once",
run: async (input) => {
seen.push(input);
return seen.length === 1
? { decision: "continue", input: "again", output: { k: true } }
: { decision: "stop" };
},
};
const writes: OmniMessage[] = [];
const trace: TraceSink = {
write: async (m) => {
writes.push(m);
},
currentPath: () => "/traces/session-1_001.jsonl",
};
const llm = echoLLM();
const session = makeSession([hook], llm, { trace });
const stream: OmniMessage[] = [];
for await (const msg of session.run([userText("hello")])) stream.push(msg);
// Two Tasks ran: the second on the hook's input.
expect(llm.inputs).toEqual(["hello", "again"]);
// The hook is told where to look, nothing more.
expect(seen).toEqual([
{ sessionId: "session-1", tracePath: "/traces/session-1_001.jsonl" },
{ sessionId: "session-1", tracePath: "/traces/session-1_001.jsonl" },
]);
// The stream: the hook event, then the injected user input, then the second Task.
const kinds = stream.map((m) =>
isEventMessage(m) && m.payload.type === "hook"
? `hook:${(m.payload as HookPayload).decision}`
: m.type === "model_msg" && (m.payload as { role?: string }).role === "user"
? `user:${(m.payload as { text: string }).text}`
: null,
);
expect(kinds.filter(Boolean)).toEqual(["hook:continue", "user:again", "hook:stop"]);
// The injected input carries the harness stamp — hosts key round/origin display on it.
const injected = stream.find(
(m) => m.type === "model_msg" && (m.payload as { text?: string }).text === "again",
);
expect((injected!.payload as { sender?: string }).sender).toBe("harness");
// Both hook events reached the Trace.
const hookWrites = writes.filter((m) => isEventMessage(m) && m.payload.type === "hook");
expect(hookWrites.map((m) => (m.payload as HookPayload).decision)).toEqual([
"continue",
"stop",
]);
});
it("never continues after the signal is aborted, even when a hook asks to", async () => {
const controller = new AbortController();
const hook: StopHook = {
name: "eager",
run: async () => {
controller.abort();
return { decision: "continue", input: "again" };
},
};
const llm = echoLLM();
const session = makeSession([hook], llm);
const stream: OmniMessage[] = [];
for await (const msg of session.run([userText("hello")], { signal: controller.signal })) {
stream.push(msg);
}
expect(llm.inputs).toEqual(["hello"]);
// The answer is still on record.
expect(stream.some((m) => isEventMessage(m) && m.payload.type === "hook")).toBe(true);
});
it("honors a subagent answer through the Session's spawner, passing the run's approval callback", async () => {
const asks: Array<{ prompt: string; approved: boolean }> = [];
const childMeta = {
type: "session_meta",
origin: ["child-9"],
payload: { session_id: "child-9" },
} as unknown as OmniMessage;
const hook: StopHook = {
name: "review",
run: async () => ({ reason: "delegated", subagent: { prompt: "look" } }),
};
const llm = echoLLM();
const session = makeSession([hook], llm, {
spawnSubagent: async (request, approve) => {
asks.push({ prompt: request.prompt, approved: approve !== undefined });
return { sessionId: "child-9", meta: childMeta };
},
});
const stream: OmniMessage[] = [];
for await (const msg of session.run([userText("hello")], { approve: async () => "allow" })) {
stream.push(msg);
}
expect(asks).toEqual([{ prompt: "look", approved: true }]);
const at = stream.findIndex((m) => isEventMessage(m) && m.payload.type === "hook");
expect((stream[at]!.payload as HookPayload).output).toEqual({ session_id: "child-9" });
// The child's origin-stamped meta follows the event on the stream — what a host registers
// the child session from.
expect(stream[at + 1]).toBe(childMeta);
expect(llm.inputs).toEqual(["hello"]);
});
});
describe("runPreToolUseHooks", () => {
const input = {
sessionId: "session-1",
toolName: "exec_command",
toolCallId: "c1",
argumentsJson: '{"cmd":"ls"}',
};
it("records every answer, first decision wins, a throwing hook has no opinion", async () => {
const hooks: PreToolUseHook[] = [
{ name: "watcher", run: async () => ({ output: { seen: true } }) },
{
name: "broken",
run: async () => {
throw new Error("boom");
},
},
{ name: "guard", run: async () => ({ decision: "deny", reason: "not here" }) },
{ name: "late", run: async () => ({ decision: "allow", reason: "too late" }) },
{ name: "quiet", run: async () => undefined },
];
const outcome = await runPreToolUseHooks(hooks, input);
expect(outcome.decision).toBe("deny");
expect(outcome.name).toBe("guard");
expect(outcome.reason).toBe("not here");
const events = outcome.events.map((e) => e.payload as HookPayload);
expect(events.map((e) => e.name)).toEqual(["watcher", "broken", "guard", "late"]);
expect(events.every((e) => e.hook === "pre_tool_use")).toBe(true);
expect(events[1]!.reason).toContain("hook failed: boom");
expect(events[1]!.decision).toBeUndefined();
});
it("no hook answering means a null decision and no events", async () => {
const outcome = await runPreToolUseHooks(
[{ name: "quiet", run: async () => undefined }],
input,
);
expect(outcome).toEqual({ events: [], decision: null });
});
});
describe("Session pre-tool-use hooks", () => {
let dir: string;
beforeEach(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-tool-hooks-"));
});
afterEach(async () => {
await rmEventually(dir);
});
/** Turn 1 calls exec_command; turn 2 answers with the tool output it saw. */
function toolLLM(cmd: string): LLMInterface & { toolOutputs: string[] } {
let calls = 0;
const toolOutputs: string[] = [];
return {
toolOutputs,
async *streamGenerate({ newMessages }): AsyncGenerator<OmniMessage, LLMOutcome> {
calls += 1;
if (calls === 1) {
yield toolCall({
name: "exec_command",
arguments: JSON.stringify({ cmd }),
toolCallId: "c1",
stopReason: "completed",
});
yield tokenUsage(usage(1), usage(1));
return { status: "completed" };
}
for (const m of newMessages) {
const p = m.payload as { type?: string; output?: string };
if (p.type === "tool_call_output" && typeof p.output === "string") {
toolOutputs.push(p.output);
}
}
yield assistantText("done");
yield tokenUsage(usage(1), usage(1));
return { status: "completed" };
},
};
}
const runningEnv: EnvironmentInterface = {
listTools: async () => [],
executeTool: async function* ({ toolCall: tc }) {
yield toolCallOutput({
output: "ran",
toolCallId: tc.payload.tool_call_id,
stopReason: "completed",
});
},
toolPermission: () => undefined,
};
function session(
llm: LLMInterface,
preToolUse: PreToolUseHook[],
commandPolicy?: CommandPolicyConfig,
): Session {
const meta: SessionMetaPayload = {
session_id: "session-1",
provider: "custom",
model_id: "m1",
model_context_window: 1000,
system_prompt: "sp",
agent_state: dir,
workspace: dir,
source: "user",
};
return new Session({
meta,
bootstrap: async () => ({ llm }),
environment: runningEnv,
imagesDir: path.join(dir, "scratchpad", "session-1"),
modelHasVision: true,
hooks: { preToolUse },
...(commandPolicy ? { commandPolicy: () => commandPolicy } : {}),
});
}
async function collect(
s: Session,
approve: (tc: OmniMessage) => Promise<"allow" | "deny">,
): Promise<OmniMessage[]> {
const stream: OmniMessage[] = [];
for await (const msg of s.run([userText("go")], { approve: approve as never })) {
stream.push(msg);
}
return stream;
}
it("a deny refuses the call without consulting approval, with the hook's reason in the output", async () => {
const llm = toolLLM("ls");
let approvals = 0;
const guard: PreToolUseHook = {
name: "guard",
run: async (input) => {
expect(input.toolName).toBe("exec_command");
expect(input.toolCallId).toBe("c1");
expect(JSON.parse(input.argumentsJson)).toEqual({ cmd: "ls" });
return { decision: "deny", reason: "not in this sandbox" };
},
};
const stream = await collect(session(llm, [guard]), async () => {
approvals += 1;
return "allow";
});
expect(approvals).toBe(0);
const hookEvents = stream.filter((m) => isEventMessage(m) && m.payload.type === "hook");
expect(hookEvents).toHaveLength(1);
expect(hookEvents[0]!.payload).toMatchObject({
hook: "pre_tool_use",
name: "guard",
decision: "deny",
});
const decision = stream.find(
(m) => isEventMessage(m) && m.payload.type === "approval_decision",
);
expect((decision!.payload as { decision: string }).decision).toBe("deny");
expect(llm.toolOutputs).toEqual(["Tool call denied by the guard hook: not in this sandbox."]);
});
it("an allow approves without consulting the host", async () => {
const llm = toolLLM("ls");
let approvals = 0;
const stream = await collect(
session(llm, [{ name: "opener", run: async () => ({ decision: "allow" }) }]),
async () => {
approvals += 1;
return "deny";
},
);
expect(approvals).toBe(0);
const decision = stream.find(
(m) => isEventMessage(m) && m.payload.type === "approval_decision",
);
expect((decision!.payload as { decision: string }).decision).toBe("allow");
expect(llm.toolOutputs).toEqual(["ran"]);
});
it("no answer falls through to the approval callback", async () => {
const llm = toolLLM("ls");
let approvals = 0;
await collect(session(llm, [{ name: "quiet", run: async () => undefined }]), async () => {
approvals += 1;
return "allow";
});
expect(approvals).toBe(1);
expect(llm.toolOutputs).toEqual(["ran"]);
});
it("the command policy outranks a hook allow: the vetoed call stays forbidden", async () => {
const llm = toolLLM("rm -rf /");
let approvals = 0;
const stream = await collect(
session(llm, [{ name: "opener", run: async () => ({ decision: "allow" }) }], {
rules: [{ name: "no-rm", pattern: "^rm " }],
}),
async () => {
approvals += 1;
return "allow";
},
);
expect(approvals).toBe(0);
const decision = stream.find(
(m) => isEventMessage(m) && m.payload.type === "approval_decision",
);
expect((decision!.payload as { decision: string }).decision).toBe("forbidden");
expect(llm.toolOutputs).toEqual(["Tool call denied by policy."]);
});
});