fix(shell): advertise foreground-only timeout default

Summary
run_shell schema timeout copy now says the default is foreground-only
and to omit timeout on background:true. Advertise uses the same
default as resolveShellTimeoutMs when only maxTimeoutMs is set.

Verification
bun test ./src/plugins/shell-guard-plugin.test.ts
bun run typecheck
bun run check

Author: TheGreatAxios

src/agent/tools.ts

@@ -592,7 +592,11 @@ export async function createAgentToolset(
   const baseTools: AgentTool[] = [
     ...fromToolRunner(posixTools).map((tool) => {
       let definition = advertiseEditFileLineRange(
-        advertiseShellGuardTimeout(tool.definition, shellTimeout?.defaultMs),
+        advertiseShellGuardTimeout(
+          tool.definition,
+          shellTimeout?.defaultMs,
+          shellTimeout?.maxMs,
+        ),
       );
       if (getEvidenceArchive !== undefined)
         definition = advertiseArchiveSurface(definition);

src/plugins/shell-guard-plugin.test.ts

@@ -497,40 +497,25 @@ describe("background run_shell (shellGuardPlugin)", () => {
 });
 
 describe("advertiseShellGuardTimeout", () => {
-  test("rewrites run_shell timeout description when a settings default is set", () => {
-    const rewritten = advertiseShellGuardTimeout(
-      {
-        name: "run_shell",
-        description: "Execute a shell command",
-        inputSchema: {
-          type: "object",
-          properties: {
-            command: { type: "string" },
-            timeout: {
-              type: "number",
-              description: "Timeout in milliseconds (default: 30000)",
-            },
-          },
-          required: ["command"],
-        },
-      },
-      120_000,
-    );
-    const timeout = (
-      rewritten.inputSchema["properties"] as Record<
-        string,
-        { description: string }
-      >
-    )["timeout"];
-    expect(timeout?.description).toContain("120000");
-    expect(timeout?.description).not.toContain("30000");
-    expect((timeout as { default?: number } | undefined)?.default).toBe(
-      120_000,
-    );
-  });
+  function timeoutSchema(def: {
+    inputSchema: { properties?: unknown };
+  }): { description?: string; default?: number } | undefined {
+    const properties = def.inputSchema["properties"] as
+      | Record<string, { description?: string; default?: number }>
+      | undefined;
+    return properties?.["timeout"];
+  }
 
-  test("advertises default 120000 when settings default is unset", () => {
-    const rewritten = advertiseShellGuardTimeout({
+  function runShellDef(): {
+    name: string;
+    description: string;
+    inputSchema: {
+      type: "object";
+      properties: Record<string, { type: string; description?: string }>;
+      required: string[];
+    };
+  } {
+    return {
       name: "run_shell",
       description: "Execute a shell command",
       inputSchema: {
@@ -544,18 +529,48 @@ describe("advertiseShellGuardTimeout", () => {
         },
         required: ["command"],
       },
-    });
-    const timeout = (
-      rewritten.inputSchema["properties"] as Record<
-        string,
-        { description: string; default?: number }
-      >
-    )["timeout"];
-    expect(timeout?.description).toContain("120000");
+    };
+  }
+
+  test("rewrites run_shell timeout description when a settings default is set", () => {
+    const rewritten = advertiseShellGuardTimeout(runShellDef(), 120_000);
+    const timeout = timeoutSchema(rewritten);
+    expect(timeout?.description).toContain("foreground default: 120000");
+    expect(timeout?.description).toMatch(
+      /omit on background:true for no timeout/,
+    );
+    expect(timeout?.description).not.toContain("30000");
+    expect(timeout?.default).toBe(120_000);
+  });
+
+  test("advertises default 120000 when settings default is unset", () => {
+    const rewritten = advertiseShellGuardTimeout(runShellDef());
+    const timeout = timeoutSchema(rewritten);
+    expect(timeout?.description).toContain("foreground default: 120000");
     expect(timeout?.default).toBe(120_000);
     expect(timeout?.description).not.toContain("30000");
     expect(timeout?.description).not.toContain("15000");
-    expect(timeout?.description).not.toMatch(/no default|omit/i);
+    expect(timeout?.description).toMatch(
+      /omit on background:true for no timeout/,
+    );
+  });
+
+  test("advertised default matches resolver when only maxTimeoutMs is set", () => {
+    const maxMs = 60_000;
+    const resolved = resolveShellTimeoutMs({
+      requested: undefined,
+      background: false,
+      maxMs,
+    });
+    const rewritten = advertiseShellGuardTimeout(
+      runShellDef(),
+      undefined,
+      maxMs,
+    );
+    const timeout = timeoutSchema(rewritten);
+    expect(resolved).toBe(60_000);
+    expect(timeout?.default).toBe(resolved);
+    expect(timeout?.description).toContain(`foreground default: ${resolved}`);
   });
 
   test("leaves other tools unchanged", () => {
@@ -585,6 +600,7 @@ describe("advertiseShellGuardTimeout", () => {
     )["background"];
     expect(background).toBeDefined();
     expect(background?.description).toContain("shell_collect");
+    expect(background?.description).toMatch(/omit timeout/i);
     expect(background?.description).toMatch(
       /does not change the retained shell cwd/i,
     );

src/plugins/shell-guard-plugin.ts

@@ -82,13 +82,19 @@ export function formatShellTimeoutNotice(timeoutMs: number): string {
 
 /**
  * Stock tools-posix still advertises timeout default 30000. Shell-guard's
- * foreground default is 120s (settings.shell.timeoutMs overrides); rewrite the
- * definition the model sees so schema and behavior agree. Corbits Code-only —
- * does not patch interchange.
+ * foreground default is 120s (settings.shell.timeoutMs overrides; maxTimeoutMs
+ * clamps that default path); rewrite the definition the model sees so schema
+ * and behavior agree. Corbits Code-only — does not patch interchange.
+ *
+ * Schema `default` is the foreground omit path. Description says omit
+ * timeout on background:true so the model does not copy 120000 onto
+ * background calls (a copied value becomes a requested timeout and kills
+ * the job).
  */
 export function advertiseShellGuardTimeout(
   definition: ToolDefinition,
   defaultMs?: number,
+  maxMs?: number,
 ): ToolDefinition {
   if (definition.name !== "run_shell") return definition;
   const schema = definition.inputSchema;
@@ -101,17 +107,20 @@ export function advertiseShellGuardTimeout(
   const cwdProp = properties["cwd"];
   const nextProperties = { ...properties };
   const advertisedDefault =
-    defaultMs !== undefined && defaultMs > 0
-      ? defaultMs
-      : DEFAULT_FOREGROUND_SHELL_TIMEOUT_MS;
+    resolveShellTimeoutMs({
+      requested: undefined,
+      background: false,
+      ...(defaultMs !== undefined ? { defaultMs } : {}),
+      ...(maxMs !== undefined ? { maxMs } : {}),
+    }) ?? DEFAULT_FOREGROUND_SHELL_TIMEOUT_MS;
   if (
     timeout !== undefined &&
     typeof timeout === "object" &&
     timeout !== null
   ) {
     nextProperties["timeout"] = {
       ...(timeout as Record<string, unknown>),
-      description: `Timeout in milliseconds (default: ${advertisedDefault})`,
+      description: `Timeout in milliseconds (foreground default: ${advertisedDefault}; omit on background:true for no timeout)`,
       default: advertisedDefault,
     };
   }
@@ -127,7 +136,8 @@ export function advertiseShellGuardTimeout(
     description:
       "Set true to run without holding the turn open (prefer this for builds, test suites, and dev servers). " +
       "Returns a shell_id immediately; the exit status and output are delivered when the process finishes. " +
-      "Use shell_collect to collect or cancel. Does not change the retained shell cwd.",
+      "Use shell_collect to collect or cancel. Omit timeout for no timeout. " +
+      "Does not change the retained shell cwd.",
   };
   return {
     ...definition,

src/subagent/run.ts

@@ -709,11 +709,15 @@ async function runSubAgentInner(
       : runController.signal;
 
   try {
-    const shellDefaultMs = params.shellTimeout?.defaultMs;
+    const shellTimeout = params.shellTimeout;
     let tools = fromToolRunner(posixTools).map((tool) => ({
       ...tool,
       definition: advertiseEditFileLineRange(
-        advertiseShellGuardTimeout(tool.definition, shellDefaultMs),
+        advertiseShellGuardTimeout(
+          tool.definition,
+          shellTimeout?.defaultMs,
+          shellTimeout?.maxMs,
+        ),
       ),
     }));