feat(core,vendo): a tool you write by hand is a zod schema and a function

[yousefh409]

Summary

Adds defineTool — a typed helper for authoring host tools by hand. Today the tools: slot already accepts a ToolDefinition, but writing one meant hand-authoring JSON Schema beside the TypeScript execute function and keeping the two honest about each other forever, with nothing checking they agreed.

defineTool takes the input schema once, as zod, and derives both halves: the JSON Schema the model is shown, and the runtime parse that validates arguments before execute runs. Arguments the schema rejects are refused by naming the field, and the body never executes.

Public surface

packages/core/src/define-tool.ts, value-exported from the @vendoai/vendo / vendoai umbrella:

export function defineTool<Input extends z.ZodType>(tool: {
  name: string; description: string; input: Input;
  risk: GradedRiskLabel;
  execute(input: z.infer<Input>, context: RunContext): Promise<Json>;
}): ToolDefinition;

risk is required and graded — ungraded stays extraction's own answer. The return is a plain ToolDefinition (generic erased), so any field the helper doesn't ask for is still a spread away (e.g. { ...defineTool({...}), confirmEach: true }).

Testing

4 unit tests on defineTool itself (schema-to-JSON-Schema derivation, argument validation, risk requirement) plus 3 seam tests that exercise a defineTool-built tool through the real guard — no stub on either side.

Stack

Part of a 4-PR stack (data ingestion + custom tools + connectors + tenant connectors). This PR is the bottom of the stack; the next PR (openApiConnector) is based on this branch. The merge unit is the stack tip — this PR is a review window, not an independent merge.

🤖 Generated with Claude Code

---

Summary by cubic

Defines defineTool to build host tools from a Zod v4 schema and an execute function. Previously you hand‑authored JSON Schema beside the function; now we derive the model-facing schema and validate inputs (including async refinements) before execution, rejecting invalid calls by field.

• Public API and exports: defineTool({ name, description, input, risk, execute }) returns a plain ToolDefinition you can spread; the derived inputSchema omits $schema. Exported from @vendoai/core and @vendoai/vendo. Adds a “Custom tools” docs page.
• Validation behavior: uses async parsing so Zod refinements that await do not throw; invalid inputs never reach execute.
• Risk and migration: risk is required and graded; ungraded remains extraction-only. Zod 4 shapes only — on Zod 3.25+ import z from zod/v4; otherwise upgrade to Zod 4.

^{Written for commit 7d48075. Summary will update on new commits.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Vendo	🟢 Ready	View Preview	Aug 18, 2026, 12:26 PM

[greptile-apps]

Greptile Summary

Adds a public Zod-backed helper for custom tool definitions, including schema projection, argument validation, exports, documentation, and coverage. One existing integration defect remains: custom tool handlers do not receive the call metadata supplied by the execution contract. The earlier asynchronous-schema concern was disproved by executing valid and invalid asynchronous Zod refinements through defineTool; asynchronous parsing now completes and reports validation failures normally.

Confidence Score: 4/5

One non-security P1 failure remains: call-aware custom tools created through defineTool cannot receive their ToolCall metadata.

The actionable findings contain exactly one non-security P1, which maps to confidence 4.

Files Needing Attention: packages/core/src/define-tool.ts

T-Rex Logs

What T-Rex did

• T-Rex produced a proof for a posted P1 finding, validating the finding with a formal proof.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "fix(core): defineTool parses async schem..." | Re-trigger Greptile}