@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/tools/__tests__/schedule-tool-input-schemas.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, test } from "bun:test";
+
+import type { z } from "zod";
+
+import { scheduleCreateInputSchema } from "../schedule/create.js";
+import { scheduleDeleteInputSchema } from "../schedule/delete.js";
+import { scheduleListInputSchema } from "../schedule/list.js";
+import { scheduleUpdateInputSchema } from "../schedule/update.js";
+import { toToolInputSchema } from "../shared/zod-tool-schema.js";
+import { expectNoSchemaDrift } from "./tool-schema-drift-harness.js";
+
+/**
+ * Drift guard between the schedule skill's hand-written `TOOLS.json`
+ * `input_schema`s (the advertised contract) and the executors' runtime Zod
+ * schemas. See `tool-schema-drift-harness.ts` for what is (and deliberately
+ * is not) compared.
+ */
+
+const TOOLS_JSON = JSON.parse(
+  readFileSync(
+    join(import.meta.dir, "../../config/bundled-skills/schedule/TOOLS.json"),
+    "utf8",
+  ),
+) as Parameters<typeof expectNoSchemaDrift>[1];
+
+const CASES: {
+  name: string;
+  schema: z.ZodType;
+  advertiseRequired?: string[];
+  passthrough?: Record<string, string>;
+  nullableAtRuntime?: string[];
+}[] = [
+  {
+    name: "schedule_create",
+    schema: scheduleCreateInputSchema,
+    advertiseRequired: ["name", "description"],
+    passthrough: {
+      mode: "bespoke VALID_MODES check owns the error semantics",
+      routing_intent: "bespoke VALID_ROUTING_INTENTS check owns the error",
+      capabilities:
+        "CapabilityManifestSchema is the single validation authority; must reach the executor (and the requireFreshApproval promotion) unaltered",
+      workflow_args: "workflow runtime accepts any JSON value as args",
+    },
+  },
+  {
+    name: "schedule_update",
+    schema: scheduleUpdateInputSchema,
+    advertiseRequired: ["job_id"],
+    passthrough: {
+      mode: "bespoke VALID_MODES check owns the error semantics",
+      routing_intent: "bespoke VALID_ROUTING_INTENTS check owns the error",
+      workflow_name: "typeof-guarded null fallback (non-string clears)",
+      workflow_args: "workflow runtime accepts any JSON value as args",
+    },
+    nullableAtRuntime: ["timezone", "script", "routing_hints"],
+  },
+  { name: "schedule_list", schema: scheduleListInputSchema },
+  {
+    name: "schedule_delete",
+    schema: scheduleDeleteInputSchema,
+    advertiseRequired: ["job_id"],
+  },
+];
+
+describe("schedule TOOLS.json ↔ runtime Zod schema drift guard", () => {
+  for (const c of CASES) {
+    test(c.name, () => {
+      expectNoSchemaDrift(
+        {
+          name: c.name,
+          derived: toToolInputSchema(c.schema, {
+            advertiseRequired: c.advertiseRequired,
+          }),
+          passthrough: c.passthrough,
+          nullableAtRuntime: c.nullableAtRuntime,
+        },
+        TOOLS_JSON,
+      );
+    });
+  }
+});

package/src/tools/__tests__/subagent-workflow-tool-input-schemas.test.ts

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, test } from "bun:test";
+
+import type { z } from "zod";
+
+import { toToolInputSchema } from "../shared/zod-tool-schema.js";
+import { subagentAbortInputSchema } from "../subagent/abort.js";
+import { subagentMessageInputSchema } from "../subagent/message.js";
+import { subagentReadInputSchema } from "../subagent/read.js";
+import { subagentSpawnInputSchema } from "../subagent/spawn.js";
+import { subagentStatusInputSchema } from "../subagent/status.js";
+import { manageWorkflowsInputSchema } from "../workflows/manage-workflows.js";
+import { runWorkflowInputSchema } from "../workflows/run-workflow.js";
+import { expectNoSchemaDrift } from "./tool-schema-drift-harness.js";
+
+/**
+ * Drift guard between the subagent and workflows skills' hand-written
+ * `TOOLS.json` `input_schema`s (the advertised contract) and the executors'
+ * runtime Zod schemas. See `tool-schema-drift-harness.ts` for what is (and
+ * deliberately is not) compared.
+ */
+
+function loadToolsJson(
+  skill: string,
+): Parameters<typeof expectNoSchemaDrift>[1] {
+  return JSON.parse(
+    readFileSync(
+      join(import.meta.dir, `../../config/bundled-skills/${skill}/TOOLS.json`),
+      "utf8",
+    ),
+  ) as Parameters<typeof expectNoSchemaDrift>[1];
+}
+
+const CASES: {
+  skill: string;
+  name: string;
+  schema: z.ZodType;
+  advertiseRequired?: string[];
+  passthrough?: Record<string, string>;
+}[] = [
+  {
+    skill: "subagent",
+    name: "subagent_spawn",
+    schema: subagentSpawnInputSchema,
+    advertiseRequired: ["label", "objective"],
+    passthrough: {
+      fork: "deliberate `=== true` coercion owns malformed values",
+      send_result_to_user:
+        "deliberate `=== true` / `!== false` coercions own malformed values",
+      role: "SubagentManager.spawn's 'Invalid subagent role' error (test-asserted) owns non-enum values",
+    },
+  },
+  {
+    skill: "subagent",
+    name: "subagent_status",
+    schema: subagentStatusInputSchema,
+  },
+  {
+    skill: "subagent",
+    name: "subagent_abort",
+    schema: subagentAbortInputSchema,
+  },
+  {
+    skill: "subagent",
+    name: "subagent_message",
+    schema: subagentMessageInputSchema,
+    advertiseRequired: ["content"],
+  },
+  {
+    skill: "subagent",
+    name: "subagent_read",
+    schema: subagentReadInputSchema,
+    passthrough: {
+      last_n:
+        "typeof-guarded read ignores malformed values (including non-integer numbers the advertised type wouldn't admit)",
+    },
+  },
+  {
+    skill: "workflows",
+    name: "run_workflow",
+    schema: runWorkflowInputSchema,
+    passthrough: {
+      args: "workflow runtime accepts any JSON value as args",
+      capabilities:
+        "CapabilityManifestSchema is the single validation authority; executor.ts reads it pre-execution for the requireFreshApproval promotion",
+    },
+  },
+  {
+    skill: "workflows",
+    name: "manage_workflows",
+    schema: manageWorkflowsInputSchema,
+    advertiseRequired: ["action"],
+    passthrough: {
+      action:
+        "switch default owns the unknown-action error; executor.ts reads it pre-execution for the requireFreshApproval promotion",
+    },
+  },
+];
+
+describe("subagent + workflows TOOLS.json ↔ runtime Zod schema drift guard", () => {
+  for (const c of CASES) {
+    test(`${c.skill}:${c.name}`, () => {
+      expectNoSchemaDrift(
+        {
+          name: c.name,
+          derived: toToolInputSchema(c.schema, {
+            advertiseRequired: c.advertiseRequired,
+          }),
+          passthrough: c.passthrough,
+        },
+        loadToolsJson(c.skill),
+      );
+    });
+  }
+});

package/src/tools/__tests__/tool-input-schemas.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+
+import { askQuestionTool } from "../ask-question/ask-question-tool.js";
+import { fileEditTool } from "../filesystem/edit.js";
+import { fileListTool } from "../filesystem/list.js";
+import { fileReadTool } from "../filesystem/read.js";
+import { fileWriteTool } from "../filesystem/write.js";
+import { hostFileEditTool } from "../host-filesystem/edit.js";
+import { hostFileReadTool } from "../host-filesystem/read.js";
+import { hostFileWriteTool } from "../host-filesystem/write.js";
+import { hostShellTool } from "../host-terminal/host-shell.js";
+import { notifyParentTool } from "../subagent/notify-parent.js";
+import { requestSystemPermissionTool } from "../system/request-permission.js";
+import { shellTool } from "../terminal/shell.js";
+import { parseToolInput, TOOL_INPUT_SCHEMAS } from "../tool-input-schemas.js";
+
+describe("parseToolInput", () => {
+  test("passes input through unchanged for a tool with no registered schema", () => {
+    const input = { anything: 42, nested: { deep: true } };
+    const result = parseToolInput("some_unregistered_tool", input);
+    expect(result).toEqual({ ok: true, data: input });
+  });
+
+  test("rejects malformed input with a message naming the tool and field", () => {
+    const result = parseToolInput("file_write", { path: 42, content: "hi" });
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error("expected failure");
+    }
+    expect(result.message).toContain('Invalid input for tool "file_write"');
+    expect(result.message).toContain("path:");
+    expect(result.message).toContain("retry");
+  });
+
+  test("rejects a missing required field", () => {
+    const result = parseToolInput("file_write", { path: "a.txt" });
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error("expected failure");
+    }
+    expect(result.message).toContain("content");
+  });
+
+  test("accepts valid input and preserves unknown keys (injected fields)", () => {
+    const result = parseToolInput("file_write", {
+      path: "notes.md",
+      content: "hello",
+      activity: "Saving your notes",
+      injected_by_harness: true,
+    });
+    expect(result).toEqual({
+      ok: true,
+      data: {
+        path: "notes.md",
+        content: "hello",
+        activity: "Saving your notes",
+        injected_by_harness: true,
+      },
+    });
+  });
+
+  test("a malformed status-only activity field degrades instead of failing the call", () => {
+    const result = parseToolInput("file_write", {
+      path: "notes.md",
+      content: "hello",
+      activity: null,
+    });
+    expect(result).toEqual({
+      ok: true,
+      data: { path: "notes.md", content: "hello" },
+    });
+  });
+
+  test("file_read drops malformed optional fields the tool always ignored", () => {
+    const result = parseToolInput("file_read", {
+      path: "notes.md",
+      offset: "not-a-number",
+      limit: 10,
+    });
+    expect(result).toEqual({
+      ok: true,
+      data: { path: "notes.md", limit: 10 },
+    });
+  });
+
+  test("file_edit drops a malformed replace_all instead of failing", () => {
+    const result = parseToolInput("file_edit", {
+      path: "notes.md",
+      old_string: "a",
+      new_string: "b",
+      replace_all: "yes",
+    });
+    expect(result).toEqual({
+      ok: true,
+      data: { path: "notes.md", old_string: "a", new_string: "b" },
+    });
+  });
+
+  test("file_edit rejects an empty old_string with the explanatory message", () => {
+    const result = parseToolInput("file_edit", {
+      path: "notes.md",
+      old_string: "",
+      new_string: "b",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error("expected failure");
+    }
+    expect(result.message).toContain("old_string must not be empty");
+  });
+
+  test("ask_question rejects an option count outside 2-4 with the field path", () => {
+    const result = parseToolInput("ask_question", {
+      questions: [
+        {
+          question: "Which one?",
+          options: [{ id: "only", label: "Only" }],
+        },
+      ],
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error("expected failure");
+    }
+    expect(result.message).toContain("questions.0.options");
+  });
+});
+
+describe("derived input_schema", () => {
+  const derivedTools = [
+    fileReadTool,
+    fileWriteTool,
+    fileEditTool,
+    fileListTool,
+    askQuestionTool,
+    hostFileReadTool,
+    hostFileWriteTool,
+    hostFileEditTool,
+    shellTool,
+    hostShellTool,
+    requestSystemPermissionTool,
+    notifyParentTool,
+  ];
+
+  test("every registered schema belongs to a tool whose input_schema is derived from it", () => {
+    expect([...Object.keys(TOOL_INPUT_SCHEMAS)].sort()).toEqual(
+      derivedTools.map((t) => t.name).sort(),
+    );
+  });
+
+  test("derived schemas are plain tool-definition JSON schemas", () => {
+    for (const tool of derivedTools) {
+      const schema = tool.input_schema as Record<string, unknown>;
+      expect(schema.type).toBe("object");
+      // Tool definitions carry no draft marker, and permissive
+      // `additionalProperties` authoring artifacts are stripped.
+      expect(schema).not.toContainKey("$schema");
+      expect(JSON.stringify(schema)).not.toContain("additionalProperties");
+    }
+  });
+
+  test("filesystem tools still advertise activity as required with its description", () => {
+    for (const tool of [
+      fileReadTool,
+      fileWriteTool,
+      fileEditTool,
+      fileListTool,
+    ]) {
+      const schema = tool.input_schema as {
+        properties: Record<string, { type?: string; description?: string }>;
+        required: string[];
+      };
+      expect(schema.required).toContain("activity");
+      expect(schema.required).toContain("path");
+      expect(schema.properties.activity?.type).toBe("string");
+      expect(schema.properties.activity?.description).toContain(
+        "status update",
+      );
+    }
+  });
+
+  test("optional runtime-tolerant fields keep their descriptions and stay non-required", () => {
+    const schema = fileReadTool.input_schema as {
+      properties: Record<string, { type?: string; description?: string }>;
+      required: string[];
+    };
+    expect(schema.properties.offset?.type).toBe("number");
+    expect(schema.properties.offset?.description).toContain("1-indexed");
+    expect(schema.required).not.toContain("offset");
+    expect(schema.required).not.toContain("limit");
+  });
+});

package/src/tools/__tests__/tool-schema-drift-harness.ts

@@ -0,0 +1,142 @@
+import { expect } from "bun:test";
+
+/**
+ * Shared assertion harness for the per-skill TOOLS.json ↔ runtime Zod schema
+ * drift guards (`schedule-tool-input-schemas.test.ts`,
+ * `document-tool-input-schemas.test.ts`, …). Skill-owned tools are skipped by
+ * the central `TOOL_INPUT_SCHEMAS` gate, so the advertised contract
+ * (hand-written TOOLS.json) and the runtime validation (Zod schema in the
+ * executor module) live in different files; these helpers pin their STRUCTURE
+ * (property names, types, enums, required lists) together so a field added or
+ * retyped on one side cannot silently diverge on the other.
+ *
+ * What is deliberately NOT compared:
+ *
+ * - `description` strings — advertised prose is TOOLS.json-owned; the runtime
+ *   schema never reads it.
+ * - `passthrough` fields — advertised in TOOLS.json but undeclared in the Zod
+ *   schema (loose passthrough), because the executor's bespoke handling is the
+ *   validation contract. Each entry documents why. The harness still asserts
+ *   they exist in TOOLS.json (and are absent from the derived schema), so a
+ *   rename breaks the test.
+ * - `nullableAtRuntime` fields — declared `.nullable()` in the Zod schema
+ *   though advertised non-null (runtime-only tolerance); compared with the
+ *   null branch stripped so the slack is not advertised.
+ *
+ * This file is imported by test files at test time (after the preload's
+ * workspace override), and deliberately imports nothing from `src/` — callers
+ * pass in the already-derived JSON schema.
+ */
+
+export type JsonSchema = Record<string, unknown>;
+
+export interface DriftCase {
+  /** Tool name, matched against the TOOLS.json `tools[].name`. */
+  name: string;
+  /** `toToolInputSchema(...)` output for the tool's runtime Zod schema. */
+  derived: JsonSchema;
+  /** Advertised fields the runtime schema passes through unvalidated. */
+  passthrough?: Record<string, string>;
+  /** Declared fields that additionally accept null at runtime. */
+  nullableAtRuntime?: string[];
+}
+
+/** Strip `description` keys recursively — prose is TOOLS.json-owned. */
+function structural(node: unknown): unknown {
+  if (Array.isArray(node)) {
+    return node.map(structural);
+  }
+  if (node === null || typeof node !== "object") {
+    return node;
+  }
+  const out: JsonSchema = {};
+  for (const [key, value] of Object.entries(node as JsonSchema)) {
+    if (key === "description") {
+      continue;
+    }
+    out[key] = structural(value);
+  }
+  return out;
+}
+
+/**
+ * Canonicalize a derived property schema for comparison with TOOLS.json's
+ * hand-written form:
+ *
+ * - drop the safe-integer `minimum`/`maximum` bounds `z.int()` emits;
+ * - drop the empty `properties` block `z.looseObject({})` (an "any object"
+ *   passthrough) emits that TOOLS.json's bare `{type: "object"}` doesn't;
+ * - collapse `anyOf: [X, {type: "null"}]` (Zod's nullable encoding) into
+ *   TOOLS.json's `type: [t, "null"]` array form;
+ * - when `stripNull` is set (`nullableAtRuntime` fields), drop the null
+ *   branch entirely so the runtime-only null tolerance is not advertised.
+ */
+function canonicalize(prop: JsonSchema, stripNull: boolean): JsonSchema {
+  const out = { ...prop };
+  if (out.minimum === -(2 ** 53 - 1)) {
+    delete out.minimum;
+  }
+  if (out.maximum === 2 ** 53 - 1) {
+    delete out.maximum;
+  }
+  if (
+    typeof out.properties === "object" &&
+    out.properties !== null &&
+    Object.keys(out.properties).length === 0
+  ) {
+    delete out.properties;
+  }
+  const anyOf = out.anyOf;
+  if (Array.isArray(anyOf) && anyOf.length === 2) {
+    const nullIdx = anyOf.findIndex(
+      (entry) => (entry as JsonSchema).type === "null",
+    );
+    if (nullIdx !== -1) {
+      const base = canonicalize(anyOf[1 - nullIdx] as JsonSchema, false);
+      delete out.anyOf;
+      Object.assign(out, base);
+      if (!stripNull && typeof base.type === "string") {
+        out.type = [base.type, "null"];
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Assert one tool's derived runtime schema structurally matches its advertised
+ * TOOLS.json `input_schema`, modulo the documented exceptions above.
+ */
+export function expectNoSchemaDrift(
+  c: DriftCase,
+  toolsJson: { tools: { name: string; input_schema: JsonSchema }[] },
+): void {
+  const entry = toolsJson.tools.find((t) => t.name === c.name);
+  expect(entry).toBeDefined();
+  const advertised = structural(entry!.input_schema) as JsonSchema;
+  const derived = structural(c.derived) as JsonSchema;
+
+  const advertisedProps = { ...(advertised.properties as JsonSchema) };
+  const derivedProps = { ...(derived.properties as JsonSchema) };
+
+  for (const field of Object.keys(c.passthrough ?? {})) {
+    expect(advertisedProps[field]).toBeDefined();
+    expect(derivedProps[field]).toBeUndefined();
+    delete advertisedProps[field];
+  }
+
+  for (const [field, prop] of Object.entries(derivedProps)) {
+    derivedProps[field] = canonicalize(
+      prop as JsonSchema,
+      c.nullableAtRuntime?.includes(field) ?? false,
+    );
+  }
+
+  expect(Object.keys(derivedProps).sort()).toEqual(
+    Object.keys(advertisedProps).sort(),
+  );
+  expect(derivedProps).toEqual(advertisedProps);
+  expect(
+    [...((derived.required as string[] | undefined) ?? [])].sort(),
+  ).toEqual([...((advertised.required as string[] | undefined) ?? [])].sort());
+}

package/src/tools/acp/abort.ts

@@ -1,11 +1,31 @@
+import { z } from "zod";
+
 import { getAcpSessionManager } from "../../acp/index.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeAcpAbort}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools. The bespoke required check keeps its message for the
+ * missing/null/empty cases.
+ */
+export const acpAbortInputSchema = z.looseObject({
+  acp_session_id: nullAsOmitted(z.string()),
+});
+
 export async function executeAcpAbort(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acpSessionId = input.acp_session_id as string;
+  const parsedInput = acpAbortInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("acp_abort", parsedInput.error);
+  }
+  const acpSessionId = parsedInput.data.acp_session_id;
   if (!acpSessionId) {
     return { content: '"acp_session_id" is required.', isError: true };
   }

package/src/tools/acp/context.ts

@@ -2,19 +2,19 @@
  * Shared ToolContext accessors for the ACP tools.
  */
 
-import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { AssistantEvent } from "../../api/index.js";
 import type { ToolContext } from "../types.js";
 
 /**
- * Narrows `ToolContext.sendToClient` to the `ServerMessage` sender the ACP
+ * Narrows `ToolContext.sendToClient` to the `AssistantEvent` sender the ACP
  * session manager expects. ToolContext types the callback against an
  * index-signature message shape (`{ type: string; [key: string]: unknown }`)
- * that ServerMessage's union members don't structurally satisfy, so the
+ * that AssistantEvent's union members don't structurally satisfy, so the
  * cast lives here once instead of being duplicated at every ACP tool call
  * site.
  */
 export function getSendToClient(
   context: ToolContext,
-): ((msg: ServerMessage) => void) | undefined {
-  return context.sendToClient as ((msg: ServerMessage) => void) | undefined;
+): ((msg: AssistantEvent) => void) | undefined {
+  return context.sendToClient as ((msg: AssistantEvent) => void) | undefined;
 }

package/src/tools/acp/spawn.test.ts

@@ -49,7 +49,9 @@ mock.module("../credentials/metadata-store.js", () => ({
   getCredentialMetadata: (service: string, field: string) => {
     const key = `${service}/${field}`;
     const entry = metadataStore.get(key);
-    if (!entry) return undefined;
+    if (!entry) {
+      return undefined;
+    }
     return {
       credentialId: `cred-${key}`,
       service,
@@ -278,8 +280,12 @@ describe("executeAcpSpawn: sandboxed bun auto-install on missing binary", () =>
     // successful global install that links the adapter bin onto PATH.
     let binaryOnPath = false;
     which.setWhich((cmd) => {
-      if (cmd === "bun") return BUN_BIN;
-      if (binaryOnPath) return `/usr/local/bin/${cmd}`;
+      if (cmd === "bun") {
+        return BUN_BIN;
+      }
+      if (binaryOnPath) {
+        return `/usr/local/bin/${cmd}`;
+      }
       return null;
     });
     execScripts.set(BUN_ADD_KEY, {
@@ -326,8 +332,12 @@ describe("executeAcpSpawn: sandboxed bun auto-install on missing binary", () =>
   test("the installer cwd is a temp dir (not the project cwd) with secrets stripped", async () => {
     let binaryOnPath = false;
     which.setWhich((cmd) => {
-      if (cmd === "bun") return BUN_BIN;
-      if (binaryOnPath) return `/usr/local/bin/${cmd}`;
+      if (cmd === "bun") {
+        return BUN_BIN;
+      }
+      if (binaryOnPath) {
+        return `/usr/local/bin/${cmd}`;
+      }
       return null;
     });
     execScripts.set(BUN_ADD_KEY, {

package/src/tools/acp/spawn.ts

@@ -1,5 +1,7 @@
 import { basename } from "node:path";
 
+import { z } from "zod";
+
 import { markAcpConnectCardRaised } from "../../acp/acp-connect-card-state.js";
 import { resolveAgentWithAutoInstall } from "../../acp/auto-install.js";
 import { getAcpSessionManager } from "../../acp/index.js";
@@ -10,9 +12,26 @@ import {
 import { formatResolveFailure } from "../../acp/resolve-agent.js";
 import { claudeResumeHint } from "../../acp/resume-hint.js";
 import { FailedDependencyError } from "../../runtime/routes/errors.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 import { getSendToClient } from "./context.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeAcpSpawn}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools — see the schema block in `tools/document/document-tool.ts` for the
+ * framework. The bespoke '"task" is required.' check keeps its message for
+ * the missing/null/empty cases.
+ */
+export const acpSpawnInputSchema = z.looseObject({
+  agent: nullAsOmitted(z.string()),
+  task: nullAsOmitted(z.string()),
+  cwd: nullAsOmitted(z.string()),
+});
+
 /**
  * Recover the stable `acp_claude_oauth_missing` marker off a `prepareAgentEnv`
  * failure so the tool result can carry it as a structured `errorCode` instead
@@ -34,8 +53,12 @@ export async function executeAcpSpawn(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const agent = (input.agent as string) || "claude";
-  const task = input.task as string;
+  const parsedInput = acpSpawnInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("acp_spawn", parsedInput.error);
+  }
+  const agent = parsedInput.data.agent || "claude";
+  const task = parsedInput.data.task;
 
   if (!task) {
     return { content: '"task" is required.', isError: true };
@@ -87,7 +110,7 @@ export async function executeAcpSpawn(
 
   try {
     const manager = getAcpSessionManager();
-    const cwd = (input.cwd as string) || context.workingDir;
+    const cwd = parsedInput.data.cwd || context.workingDir;
     const { acpSessionId, protocolSessionId } = await manager.spawn(
       agent,
       agentConfig,