killeros 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.3] - 2026-08-01
+
+### Fixed
+
+- Added child-runtime tool budgets for read-only roles, with a soft finalization nudge and hard blocking for read and web tools after 32 calls.
+- Added bounded child report instructions and kept read-tool budgets cumulative across steering restarts.
+- Lowered the default child quota to 250,000 tokens and $5, and exposed child tool-call counts in results.
+
 ## [1.4.2] - 2026-08-01
 
 ### Added

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.1
+  pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.3
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -103,7 +103,7 @@ The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` before work and to use web research when external evidence is needed. KillerOS allows at most eight tasks, four parallel readers, ten minutes, a 32 MiB JSONL line, 2 MiB retained trace, 64 KiB stderr, 50 KiB returned output, one million tokens, and $10 per child. Esc cancellation terminates active children and escalates after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access` and the KillerOS child-budget hook, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md`, work in bounded passes, and report after its first useful evidence. KillerOS allows at most eight tasks, four parallel readers, ten minutes, a 32 MiB JSONL line, 2 MiB retained trace, 64 KiB stderr, 50 KiB returned output, 250,000 tokens, and $5 per child. Read-only children receive a 24-call soft and 32-call hard tool budget that blocks read and web tools after the hard limit; final reports remain allowed. Esc cancellation terminates active children and escalates after five seconds.
 
 ### Thread lifecycle
 
@@ -113,7 +113,7 @@ Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `close
 
 The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful.
 
-A child completes naturally when it returns a final answer. Routine turn caps do not end useful work. Named resource guards still stop unsafe growth: wall time, output bytes, retained trace, stderr, quota, task count, and concurrency. A guard reports its cause and returns any partial work clearly. Esc cancellation terminates active children and escalates after five seconds.
+A child completes naturally when it returns a final answer. Routine turn caps do not end useful work. Named resource guards still stop unsafe growth: wall time, output bytes, retained trace, stderr, quota, read-tool calls, task count, and concurrency. Read-tool budgets are enforced inside the child process, so the model receives a finalization nudge and a blocked-tool result instead of being killed while it is still researching. A guard reports its cause and returns any partial work clearly. Esc cancellation terminates active children and escalates after five seconds.
 
 The replacement lifecycle has nine phases:
 
@@ -163,7 +163,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For the current unreleased `1.4.2`, publish after the validation checks pass:
+For the current unreleased `1.4.3`, publish after the validation checks pass:
 
 ```bash
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [
@@ -24,6 +24,7 @@
     "subagents.ts",
     "subagent-lifecycle.ts",
     "subagent-process.ts",
+    "subagent-budget.ts",
     "subagent-ui.ts",
     "agents/*.md",
     "themes/killeros.json",

package/subagent-budget.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_BUDGET_ENV = "PI_KILLEROS_TOOL_BUDGET";
+
+export interface ChildToolBudget {
+	soft?: number;
+	hard: number;
+	block: "*" | string[];
+}
+
+export function parseChildToolBudget(value: string | undefined): ChildToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	try {
+		const parsed = JSON.parse(value) as Record<string, unknown>;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		const hard = parsed.hard;
+		const soft = parsed.soft;
+		const block = parsed.block;
+		if (typeof hard !== "number" || !Number.isSafeInteger(hard) || hard < 1) return undefined;
+		if (soft !== undefined && (typeof soft !== "number" || !Number.isSafeInteger(soft) || soft < 1 || soft > hard)) return undefined;
+		if (block !== "*" && (!Array.isArray(block) || block.length === 0 || block.some((tool) => typeof tool !== "string" || !tool.trim()))) return undefined;
+		return {
+			hard,
+			...(soft === undefined ? {} : { soft }),
+			block: block === "*" ? "*" : [...new Set((block as string[]).map((tool) => tool.trim()))],
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function softNudge(budget: ChildToolBudget, calls: number): string {
+	return `Tool budget soft limit reached after ${calls} tool call${calls === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+function shouldBlock(budget: ChildToolBudget, toolName: string, calls: number): boolean {
+	return calls > budget.hard && (budget.block === "*" || budget.block.includes(toolName));
+}
+
+export default function registerSubagentBudget(pi: ExtensionAPI): void {
+	const budget = parseChildToolBudget(process.env[CHILD_TOOL_BUDGET_ENV]);
+	if (!budget) return;
+	let calls = 0;
+	let nudged = false;
+	const sendUserMessage = (pi as unknown as {
+		sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown;
+	}).sendUserMessage;
+
+	pi.on("tool_call", (event): ToolCallEventResult | void => {
+		calls += 1;
+		if (!nudged && budget.soft !== undefined && calls >= budget.soft) {
+			nudged = true;
+			try {
+				sendUserMessage?.(softNudge(budget, calls), { deliverAs: "steer" });
+			} catch {
+				// The hard block below remains authoritative if steering is unavailable.
+			}
+		}
+		if (!shouldBlock(budget, event.toolName, calls)) return undefined;
+		return {
+			block: true,
+			reason: `Tool budget hard limit reached after ${calls} tool calls (hard ${budget.hard}). Finalize from the context you already have.`,
+		};
+	});
+}

package/subagent-process.ts

@@ -8,8 +8,8 @@ export const SUBAGENT_PROCESS_LIMITS = {
   traceBytes: 2 * 1024 * 1024,
   stderrBytes: 64 * 1024,
   outputBytes: 50 * 1024,
-  quotaTokens: 1_000_000,
-  quotaUsd: 10,
+  quotaTokens: 250_000,
+  quotaUsd: 5,
   killGraceMs: 5_000,
 } as const;
 
@@ -43,6 +43,7 @@ export interface SubagentProcessResult {
   output: string;
   outputBytes: number;
   outputTruncatedBytes: number;
+  toolCallCount: number;
   usage: SubagentProcessUsage;
   model?: string;
   stopReason?: string;
@@ -67,9 +68,10 @@ export interface SubagentProcessOptions {
   cwd: string;
   signal?: AbortSignal;
   limits?: Partial<SubagentProcessLimits>;
+  environment?: NodeJS.ProcessEnv;
   onUpdate?: (result: Readonly<SubagentProcessResult>) => void;
   /** Test or embed hook. It receives the exact Pi arguments supplied above. */
-  spawnProcess?: (args: string[], cwd: string) => SubagentProcessChild;
+  spawnProcess?: (args: string[], cwd: string, environment?: NodeJS.ProcessEnv) => SubagentProcessChild;
 }
 
 export interface SubagentProcessLimits {
@@ -161,6 +163,11 @@ function textContent(message: any): string {
     .join("\n");
 }
 
+function toolCallCount(message: any): number {
+  if (!Array.isArray(message?.content)) return 0;
+  return message.content.filter((part: any) => part?.type === "toolCall").length;
+}
+
 function traceMessage(message: any): string[] {
   if (!Array.isArray(message?.content)) return [];
   const entries: string[] = [];
@@ -224,12 +231,12 @@ export function subagentProcessEnvironment(environment: NodeJS.ProcessEnv = proc
   return childEnvironment;
 }
 
-function defaultSpawnProcess(args: string[], cwd: string): SubagentProcessChild {
+function defaultSpawnProcess(args: string[], cwd: string, environment?: NodeJS.ProcessEnv): SubagentProcessChild {
   const invocation = getPiInvocation(args);
   return spawn(invocation.command, invocation.args, {
     cwd,
     detached: process.platform !== "win32",
-    env: subagentProcessEnvironment(),
+    env: subagentProcessEnvironment({ ...process.env, ...environment }),
     shell: false,
     stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true,
@@ -283,6 +290,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
     output: "",
     outputBytes: 0,
     outputTruncatedBytes: 0,
+    toolCallCount: 0,
     usage: emptyUsage(),
     exitCode: null,
     durationMs: 0,
@@ -373,6 +381,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       }
       state.usage.turns += 1;
       addUsage(state.usage, { ...message.usage, turns: 0 });
+      state.toolCallCount += toolCallCount(message);
       if (state.usage.totalTokens > limits.quotaTokens) {
         requestTermination("limited", "quota_tokens", `Child token usage exceeds ${limits.quotaTokens}`);
       } else if (state.usage.cost.total > limits.quotaUsd) {
@@ -431,7 +440,9 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
     abortHandler();
   } else {
     try {
-      child = (options.spawnProcess ?? defaultSpawnProcess)(args, options.cwd);
+      child = options.spawnProcess
+        ? options.spawnProcess(args, options.cwd, options.environment)
+        : defaultSpawnProcess(args, options.cwd, options.environment);
       child.stdout.on("data", (chunk: Buffer | string) => {
         if (requestedStatus) return;
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);

package/subagents.ts

@@ -15,6 +15,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { CHILD_TOOL_BUDGET_ENV, type ChildToolBudget } from "./subagent-budget.ts";
 import { SubagentThreadRegistry, type SubagentThread, type SubagentThreadId, type SubagentThreadState } from "./subagent-lifecycle.ts";
 import { runSubagentProcess, type SubagentProcessHandle, type SubagentProcessResult } from "./subagent-process.ts";
 import { formatThreadBoard, formatThreadInspection, type ThreadRecord as ThreadBoardRecord } from "./subagent-ui.ts";
@@ -29,8 +30,10 @@ export const SUBAGENT_LIMITS = {
   stderrBytes: 64 * 1024,
   taskOutputBytes: 50 * 1024,
   toolOutputBytes: 50 * 1024,
-  quotaTokens: 1_000_000,
-  quotaUsd: 10,
+  quotaTokens: 250_000,
+  quotaUsd: 5,
+  readToolBudgetSoft: 24,
+  readToolBudgetHard: 32,
   roleFileBytes: 64 * 1024,
   taskCharacters: 20_000,
   killGraceMs: 5_000,
@@ -41,9 +44,16 @@ const READ_TOOLS = new Set(["read", "grep", "find", "ls", ...WEB_TOOLS]);
 const WRITE_TOOLS = new Set(["bash", "edit", "write"]);
 const KNOWN_TOOLS = new Set([...READ_TOOLS, ...WRITE_TOOLS]);
 const SUBAGENT_WEB_EXTENSION = "npm:pi-web-access";
+const SUBAGENT_BUDGET_EXTENSION = fileURLToPath(new URL("./subagent-budget.ts", import.meta.url));
 const INHERIT_SETTING = "inherit";
 const MAX_RUNTIME_STEERING_MESSAGES = 20;
 const ROLE_FIELDS = new Set(["name", "description", "access", "tools", "model", "thinking", "timeoutMs"]);
+const CHILD_REPORT_PROTOCOL = [
+  "## Child report protocol",
+  "Work in bounded passes. After the first useful evidence, write a concise report with findings, exact files, checks run, and remaining work.",
+  "Do not keep opening files or searching after you have enough evidence to answer the task.",
+  "If a tool budget notice or blocked-tool message appears, stop research and report from the context you have. A partial report is better than no report.",
+].join("\n");
 
 type ThinkingLevel = ModelThinkingLevel;
 export type AgentAccess = "read" | "write";
@@ -105,6 +115,7 @@ export interface SubagentTaskResult {
   output: string;
   outputBytes: number;
   outputTruncatedBytes: number;
+  toolCallCount: number;
   usage: SubagentUsage;
   durationMs: number;
   exitCode: number | null;
@@ -155,7 +166,7 @@ export interface SubagentRuntimeOptions {
   bundledAgentsDir?: string;
   userAgentsDir?: string;
   webExtension?: string;
-  spawnProcess?: (args: string[], cwd: string) => SpawnedProcess;
+  spawnProcess?: (args: string[], cwd: string, environment?: NodeJS.ProcessEnv) => SpawnedProcess;
   limits?: Partial<SubagentLimits>;
 }
 
@@ -492,6 +503,7 @@ function makeQueuedResult(id: string, agent: string, task: string, step?: number
     output: "",
     outputBytes: 0,
     outputTruncatedBytes: 0,
+    toolCallCount: 0,
     usage: emptyUsage(),
     durationMs: 0,
     exitCode: null,
@@ -530,6 +542,7 @@ function mergeTaskResults(previous: SubagentTaskResult | undefined, next: Subage
   merged.output = next.output || previous.output;
   merged.outputBytes = previous.outputBytes + next.outputBytes;
   merged.outputTruncatedBytes = previous.outputTruncatedBytes + next.outputTruncatedBytes;
+  merged.toolCallCount = previous.toolCallCount + next.toolCallCount;
   merged.usage = emptyUsage();
   addUsage(merged.usage, previous.usage);
   addUsage(merged.usage, next.usage);
@@ -545,7 +558,7 @@ function cloneDetails(mode: SubagentDetails["mode"], scope: AgentScope, projectA
 async function writeRolePrompt(agent: AgentRole): Promise<{ directory: string; filePath: string }> {
   const directory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-"));
   const filePath = path.join(directory, `${agent.name.replace(/[^A-Za-z0-9_.-]/gu, "_")}.md`);
-  await writeFile(filePath, agent.prompt, { encoding: "utf8", mode: 0o600 });
+  await writeFile(filePath, `${agent.prompt}\n\n${CHILD_REPORT_PROTOCOL}`, { encoding: "utf8", mode: 0o600 });
   return { directory, filePath };
 }
 
@@ -557,13 +570,14 @@ interface RunTaskOptions {
   step?: number;
   model: ResolvedModel;
   signal?: AbortSignal;
-  spawnProcess: (args: string[], cwd: string) => SpawnedProcess;
+  spawnProcess: (args: string[], cwd: string, environment?: NodeJS.ProcessEnv) => SpawnedProcess;
   webExtension?: string;
   projectTrusted: boolean;
   limits: SubagentLimits;
   timeoutMs?: number;
   onChange: (result: SubagentTaskResult) => void;
   onHandle?: (handle: SubagentProcessHandle) => void;
+  toolBudget?: ChildToolBudget;
 }
 
 function applyProcessResult(
@@ -582,6 +596,7 @@ function applyProcessResult(
   target.output = source.output;
   target.outputBytes = source.outputBytes;
   target.outputTruncatedBytes = source.outputTruncatedBytes;
+  target.toolCallCount = source.toolCallCount;
   target.usage = { ...source.usage, cost: { ...source.usage.cost } };
   target.model = source.model ?? target.model;
   target.terminationReason = source.terminationReason;
@@ -629,6 +644,7 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
       "--no-session",
       "--no-extensions",
       "--extension", options.webExtension ?? SUBAGENT_WEB_EXTENSION,
+      "--extension", SUBAGENT_BUDGET_EXTENSION,
       "--no-prompt-templates",
       options.projectTrusted ? "--approve" : "--no-approve",
       "--model", options.model.model,
@@ -652,6 +668,9 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
         quotaUsd: limits.quotaUsd,
         killGraceMs: limits.killGraceMs,
       },
+      environment: options.toolBudget ? {
+        [CHILD_TOOL_BUDGET_ENV]: JSON.stringify(options.toolBudget),
+      } : undefined,
       onUpdate: (next) => applyProcessResult(result, next, startedAt, options.onChange),
     });
     options.onHandle?.(handle);
@@ -861,6 +880,7 @@ function threadResult(thread: SubagentThread, source?: SubagentTaskResult): Suba
       turns: thread.usage.turns,
     },
     output: thread.result ?? "",
+    toolCallCount: 0,
     terminationReason: thread.stopReason,
   };
 }
@@ -1215,6 +1235,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         const runtime: ActiveThreadRuntime = { controller, steering: [], restarting: false, traceCount: 0, startedAt: Date.now() };
         activeRuntimes.set(threadId, runtime);
         const agent = roles.get(input.agent)!;
+        const baseToolBudget: ChildToolBudget | undefined = agent.access === "read"
+          ? { soft: limits.readToolBudgetSoft, hard: limits.readToolBudgetHard, block: [...READ_TOOLS] }
+          : undefined;
         const queuedSteering = initialThread.steering.map((entry) => entry.message);
         let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, undefined, limits.taskCharacters) : task;
         const stopForBudget = (reason: string, message: string): void => {
@@ -1242,6 +1265,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             const usedTraceBytes = aggregate?.traceBytes ?? 0;
             const usedStderrBytes = aggregate?.stderrBytes ?? 0;
             const usedOutputBytes = aggregate?.outputBytes ?? 0;
+            const usedToolCalls = aggregate?.toolCallCount ?? 0;
             const usedTokens = aggregate?.usage.totalTokens ?? 0;
             const usedCost = aggregate?.usage.cost.total ?? 0;
             if (remainingWallTimeMs <= 0) {
@@ -1260,6 +1284,10 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               stopForBudget("output_limit", `Child thread emits more than ${limits.taskOutputBytes} output bytes`);
               break;
             }
+            if (baseToolBudget && usedToolCalls >= baseToolBudget.hard) {
+              stopForBudget("tool_call_limit", `Child thread exceeds ${baseToolBudget.hard} tool calls`);
+              break;
+            }
             if (usedTokens >= limits.quotaTokens) {
               stopForBudget("quota_tokens", `Child thread exceeds ${limits.quotaTokens} tokens`);
               break;
@@ -1269,6 +1297,13 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               break;
             }
             runtime.traceCount = 0;
+            const toolBudget = baseToolBudget
+              ? {
+                ...baseToolBudget,
+                soft: Math.max(1, (baseToolBudget.soft ?? baseToolBudget.hard) - usedToolCalls),
+                hard: baseToolBudget.hard - usedToolCalls,
+              }
+              : undefined;
             const next = await runTask({
               cwd: ctx.cwd,
               agent: roles.get(input.agent)!,
@@ -1290,6 +1325,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               },
               timeoutMs: remainingWallTimeMs,
               onHandle: (handle) => { runtime.handle = handle; },
+              toolBudget,
               onChange: (changed) => {
                 results[index] = syncThread(threadId, changed, runtime);
                 emit();