@soft-boy/agentschema 0.1.2 → 0.2.0

package/README.md

@@ -4,17 +4,22 @@ Define an AI-Agent as a folder of Markdown files.
 
 ```
 my-agent/
-├── agent.md   # the agent
-└── env.md     # the environment it runs in
+├── agent.md        # the agent
+├── env.md          # the environment it runs in
+└── tools/          # one file per tool, in any folders you like
+    ├── built-in/
+    │   ├── bash.md
+    │   └── read.md
+    └── read_file.md
 ```
 
-**Status:** v0.1 draft.
+**Status:** v0.2 draft. v0.2 breaks from the Claude Managed Agents schema: tools move out of `agent.md` and into `tools/`.
 
 ## Philosophy
 
 1. **One folder, one agent.** A folder defines one agent and the one environment it runs in. Sessions, credentials, mounted files and repositories, and schedules are supplied by whatever runs the agent.
 2. **Everything is a Markdown file.** An agent is plain files you can read, diff, review and version like any other code. Structured settings go in YAML frontmatter, and prose the model reads goes in the Markdown body.
-3. **Inspired by Claude Managed Agents, not tied to it.** The fields follow the Claude Managed Agents schema because it's a well-documented vocabulary for agents. The format itself assumes no particular infrastructure, so any runtime that can read the files can run the agent.
+3. **Inspired by Claude Managed Agents, not tied to it.** `agent.md` and `env.md` use the Claude Managed Agents fields because they're a well-documented vocabulary for agents. Tools are the exception: each one is its own file, and agentschema compiles them into the API's format. The format itself assumes no particular infrastructure, so any runtime that can read the files can run the agent.
 
 ## Install
 
@@ -26,20 +31,25 @@ npm install -g @soft-boy/agentschema
 
 ### Files
 
-An instance is a folder of Markdown files.
+An instance is a folder of Markdown files. `agent.md` and `env.md` are required; `tools/` is optional.
 
 ```
 my-agent/
-├── agent.md   # the agent
-└── env.md     # the environment it runs in
+├── agent.md        # the agent
+├── env.md          # the environment it runs in
+└── tools/          # one file per tool, in any folders you like
+    ├── built-in/
+    │   ├── bash.md
+    │   └── read.md
+    └── read_file.md
 ```
 
 ### `agent.md`
 Field reference: [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup).
 
-- **Frontmatter** uses the fields of a Claude Managed Agents agent (the `POST /v1/agents` request body), written as YAML. `name` and `model` are required. Every other field (`description`, `tools`, `mcp_servers`, `skills`, `multiagent`, `metadata`, …) is optional and uses the same names and shapes.
+- **Frontmatter** uses the fields of a Claude Managed Agents agent (the `POST /v1/agents` request body), written as YAML. `name` and `model` are required. Every other field (`description`, `mcp_servers`, `skills`, `multiagent`, `metadata`, …) is optional and uses the same names and shapes.
 - **Body** is the agent's system prompt, sent as `system` exactly as written (leading and trailing whitespace trimmed). An empty body means no system prompt.
-- Setting `system` in the frontmatter is an error, because the body is the system prompt.
+- Setting `system` in the frontmatter is an error, because the body is the system prompt. So is `tools`, because tools live in `tools/`.
 
 ### `env.md`
 Field reference: [Environments](https://platform.claude.com/docs/en/managed-agents/environments).
@@ -47,6 +57,59 @@ Field reference: [Environments](https://platform.claude.com/docs/en/managed-agen
 - **Frontmatter** uses the fields of a Claude Managed Agents environment (the `POST /v1/environments` request body), written as YAML: `name`, `config`, and any other field the schema defines. 
 - **Body** is a note for people reading the folder. It is not sent anywhere.
 
+### `tools/`
+
+Each `.md` file in `tools/` is one tool, and the file name is the tool's name. agentschema supports two kinds: pre-built and custom.
+
+Subfolders are only for organizing. Every `.md` file under `tools/`, at any depth, is a tool, and its folder is ignored when compiling: moving a file between folders changes nothing that's deployed. Because the folders are dropped, two tools can't share a name even in different folders. Folders and files whose names start with `.` are skipped. By convention, the pre-built tools go in `tools/built-in/`.
+
+**Pre-built tools** are the tools Claude Managed Agents runs in the container: `bash`, `edit`, `glob`, `grep`, `read`, `web_fetch`, `web_search` and `write`. Name the file after the tool (for example `tools/built-in/bash.md`), and give it only a `type`:
+
+```markdown
+---
+type: agent_toolset_20260401
+---
+```
+
+Only the pre-built tools that have a file are enabled; delete a file to disable that tool. The body is a note for people and isn't sent anywhere.
+
+**Custom tools** run on your side: when the agent calls one, `agentschema run` runs its code on your machine and sends back the result.
+
+````markdown
+---
+type: custom
+name: read_file
+description: Read a file and output its contents as a string.
+---
+
+## Input Schema
+
+| Name | Type | Description | Required |
+|---|---|---|---|
+| `filePath` | `string` | The path of the file to read | `true` |
+
+## Code
+
+```javascript
+const fs = require('fs').promises;
+
+module.exports = async ({ filePath }) => {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    return `Error reading file: ${error.message}`;
+  }
+};
+```
+````
+
+- **Frontmatter:** `type: custom`, a `name` that matches the file name, and a `description` the model reads to decide when to call the tool. The name can't reuse a pre-built tool's name (so `read_file`, not `read`), because the API rejects that.
+- **`## Input Schema`** is a table with the columns Name, Type, Description and Required. Type is `string`, `number`, `integer`, `boolean`, `object` or `array`, or one of those followed by `[]` for a list. Leave the section out for a tool that takes no input.
+- **`## Code`** is required, and must be one JavaScript code block. It's a CommonJS module, and `module.exports` is the function. It's called with the call's input as an object. A string it returns (or resolves to) is sent as the result; anything else is sent as JSON. If it throws, the error message is sent as an error result. `require()` resolves from the tool's file, so packages installed in the agent folder work.
+- Other sections are notes for people.
+
+**Compiling.** `deploy` turns `tools/` into the agent's `tools` list, sorted by tool name: one `agent_toolset_20260401` entry with `default_config: { enabled: false }` and a config enabling each pre-built tool with a file, then the custom tools. A custom tool sends only its name, description and input schema; the code never leaves your machine.
+
 ## Usage
 
 ```sh
@@ -65,22 +128,23 @@ agentschema sessions delete <id>      # delete a session
 **`init`** creates the folder `<name>` with an `agent.md` and an `env.md` that pass `check`. It asks for:
 - the agent's name and model
 - its system prompt
-- whether it gets the built-in tools, and how tool calls are approved (`auto`, `always_allow` or `always_ask`)
+- whether it gets the pre-built tools; if so, `init` writes a file for each one in `tools/built-in/`
 - the environment's name and networking
 
 Press Enter to keep the default shown, or pass `--yes` to skip the questions. `init` won't write into a folder that already has files in it.
 
-**`check`** reads both files and reports every problem it finds:
+**`check`** reads every file and reports every problem it finds:
 - a missing file, or a name that isn't lowercase
 - frontmatter that is missing, unclosed, or invalid YAML
-- a missing `name` or `model`, or a `system` key in `agent.md`'s frontmatter
+- a missing `name` or `model`, or a `system` or `tools` key in `agent.md`'s frontmatter
+- a tool file that isn't a known pre-built tool, or a custom tool with a missing description, a malformed input table, or code that isn't JavaScript or doesn't parse
 - values over the API's limits
 - anything that looks like an API key or token
 
 Unknown fields are only warnings, because they're sent to the API as written. `check` exits with status 1 when there are errors.
 
 **`deploy`** runs `check` first, then creates or updates the environment and the agent, and records their IDs in `claude-lock.json` in the folder. Commit that file.
-- **Later runs update the same resources.** A file that hasn't changed since the last deploy is skipped. Each change to `agent.md` adds a new version of the agent, and sessions already running keep the version they started on.
+- **Later runs update the same resources.** A file that hasn't changed since the last deploy is skipped. Each change to `agent.md` or `tools/` adds a new version of the agent, and sessions already running keep the version they started on.
 - **The files are the source of truth.** A field you delete from a file is cleared on the next deploy, rather than left at its old value.
 - **Changes made elsewhere aren't overwritten silently.** If the agent was changed outside the folder since the last deploy, `deploy` stops; `--force` overwrites it.
 
@@ -89,7 +153,7 @@ Unknown fields are only warnings, because they're sent to the API as written. `c
 **`run`** starts a session on the agent and environment in `claude-lock.json`, then opens a chat in the terminal. Deploy first; if you've edited the files since, `run` warns you and still uses the deployed version.
 - **Messages:** type a message and press Enter. The agent's replies stream in, with a one-line summary of each tool call.
 - **Approvals:** when a tool call needs approval (`always_ask`, or `auto` when the server can't decide), `run` asks you. Answer `y` to allow it, or type a reason to deny it; the agent sees the reason.
-- **Custom tools:** `run` shows the call's input and asks you to type the result.
+- **Custom tools:** `run` runs the tool's code from `tools/` and sends back the result. The code runs on your machine with your permissions, like any script in the folder. If the folder doesn't pass `check`, or the tool isn't in it (for example, when you resume a session from somewhere else), `run` shows the call's input and asks you to type the result.
 - **Interrupting:** Ctrl+C interrupts the agent mid-turn, and a second Ctrl+C quits. Ctrl+D quits at the prompt.
 - **Resuming:** quitting leaves the session in place, and `run` prints a command to resume it: `agentschema run --resume sesn_…`.
 

package/bin/agentschema.js

@@ -153,7 +153,7 @@ async function main(argv) {
         sessionId: values.resume,
       });
       for (const note of notes) console.warn(`warning: ${note}`);
-      await chat(client, session, { agentName: session.agent?.name ?? "agent" });
+      await chat(client, session, { agentName: session.agent?.name ?? "agent", tools: customTools(dir) });
       return 0;
     }
   } catch (err) {
@@ -180,6 +180,19 @@ async function confirm(question) {
   }
 }
 
+// The folder's custom tools, by name, for run to execute. A folder that doesn't pass check
+// runs none of them; run asks you for each result instead.
+function customTools(dir) {
+  const { instance, errors } = check(dir);
+  const customs = instance?.tools.filter((t) => t.data.type === "custom") ?? [];
+  if (customs.length === 0) return {};
+  if (errors.length > 0) {
+    console.warn(`warning: ${dir} doesn't pass check, so its custom tools won't run; you'll be asked for each result`);
+    return {};
+  }
+  return Object.fromEntries(customs.map((t) => [t.name, t]));
+}
+
 // A dry run makes no API calls, so it works without credentials.
 function makeClient(dryRun) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soft-boy/agentschema",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Markdown based AI agent schema",
   "type": "module",
   "bin": {

package/src/chat.js

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline";
 import { Conversation } from "./session.js";
+import { loadTool } from "./tools.js";
 
 const color = (code) => (text) => (process.stdout.isTTY ? `\x1b[${code}m${text}\x1b[0m` : text);
 const dim = color(2);
@@ -53,8 +54,20 @@ function firstLine(content = []) {
 
 const truncate = (s, n = 100) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
 
+// Runs a custom tool's code with the call's input. A thrown error is returned as an error
+// result, so the agent sees what went wrong.
+export async function runTool(tool, input) {
+  try {
+    const value = await loadTool(tool)(input);
+    return { text: typeof value === "string" ? value : (JSON.stringify(value) ?? "") };
+  } catch (err) {
+    return { text: `Error: ${err?.message ?? err}`, isError: true };
+  }
+}
+
 // Runs an interactive chat in the terminal until the user quits or the session ends.
-export async function chat(client, session, { agentName, input = process.stdin, output = process.stdout }) {
+// `tools` maps custom tool names to their tools/ files; their code runs here when called.
+export async function chat(client, session, { agentName, tools = {}, input = process.stdin, output = process.stdout }) {
   const rl = createInterface({ input, output, terminal: input.isTTY });
   const lines = rl[Symbol.asyncIterator]();
   let running = false;
@@ -80,6 +93,11 @@ export async function chat(client, session, { agentName, input = process.stdin,
       return { result: "deny", deny_message: reason && !/^(n|no)$/i.test(reason) ? reason : undefined };
     },
     async customToolResult(event) {
+      if (tools[event.name]) {
+        const result = await runTool(tools[event.name], event.input);
+        if (result.isError) output.write(`${red(`  ↳ ${truncate(result.text.split("\n")[0])}`)}\n`);
+        return result;
+      }
       output.write(dim(`${event.name} is a custom tool, so you supply its result.\n`));
       output.write(dim(`input: ${JSON.stringify(event.input)}\n`));
       return (await ask(bold("result> "))) ?? "The user didn't provide a result.";

package/src/check.js

@@ -1,7 +1,8 @@
 import { AGENT_FILE, ENV_FILE, readInstance } from "./instance.js";
+import { TOOLS_DIR, checkTools, readTools } from "./tools.js";
 
 const AGENT_FIELDS = new Set([
-  "name", "model", "description", "tools", "mcp_servers", "skills",
+  "name", "model", "description", "mcp_servers", "skills",
   "multiagent", "metadata", "execution_identity",
 ]);
 const ENV_FIELDS = new Set(["name", "config", "description", "metadata", "scope"]);
@@ -20,18 +21,21 @@ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v)
 // Returns { errors, warnings, instance }; instance is null when the files can't be read.
 export function check(dir) {
   const { agent, env, errors } = readInstance(dir);
+  const { tools, errors: toolErrors } = readTools(dir);
+  errors.push(...toolErrors);
   const warnings = [];
 
   if (agent) checkAgent(agent, errors, warnings);
   if (env) checkEnv(env, errors, warnings);
-  for (const [file, parsed] of [[AGENT_FILE, agent], [ENV_FILE, env]]) {
+  checkTools(tools, errors);
+  for (const [file, parsed] of [[AGENT_FILE, agent], [ENV_FILE, env], ...tools.map((t) => [t.file, t])]) {
     if (!parsed) continue;
     for (const [pattern, what] of SECRET_PATTERNS) {
       if (pattern.test(parsed.raw)) errors.push(`${file}: looks like it contains ${what}; keep secrets out of these files`);
     }
   }
 
-  return { errors, warnings, instance: agent && env ? { agent, env } : null };
+  return { errors, warnings, instance: agent && env ? { agent, env, tools } : null };
 }
 
 function checkAgent({ data, body }, errors, warnings) {
@@ -53,7 +57,9 @@ function checkAgent({ data, body }, errors, warnings) {
     else if (data.description.length > 2048) err("`description` must be at most 2048 characters");
   }
 
-  for (const [field, max] of [["tools", 256], ["mcp_servers", 20], ["skills", 500]]) {
+  if ("tools" in data) err(`\`tools\` is not allowed in frontmatter; define each tool as a file in ${TOOLS_DIR}/`);
+
+  for (const [field, max] of [["mcp_servers", 20], ["skills", 500]]) {
     if (data[field] === undefined) continue;
     if (!Array.isArray(data[field])) err(`\`${field}\` must be a list`);
     else if (data[field].length > max) err(`\`${field}\` has ${data[field].length} entries; the limit is ${max}`);
@@ -62,7 +68,7 @@ function checkAgent({ data, body }, errors, warnings) {
   checkMetadata(data.metadata, 16, err);
 
   for (const key of Object.keys(data)) {
-    if (!AGENT_FIELDS.has(key) && key !== "system") {
+    if (!AGENT_FIELDS.has(key) && key !== "system" && key !== "tools") {
       warnings.push(`${AGENT_FILE}: unknown field \`${key}\` will be sent to the API as written`);
     }
   }

package/src/deploy.js

@@ -21,8 +21,8 @@ export async function deploy(dir, { client, dryRun = false, force = false, log =
   }
 
   const steps = [
-    { file: ENV_FILE, kind: "environment", body: envBody(instance.env) },
-    { file: AGENT_FILE, kind: "agent", body: agentBody(instance.agent) },
+    { file: ENV_FILE, kind: "environment", body: envBody(instance) },
+    { file: AGENT_FILE, kind: "agent", body: agentBody(instance) },
   ];
   for (const step of steps) {
     step.key = `./${step.file}`;

package/src/init.js

@@ -1,13 +1,13 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { createInterface, emitKeypressEvents } from "node:readline";
 import { stringify } from "yaml";
 import { AGENT_FILE, ENV_FILE } from "./instance.js";
+import { BUILT_IN_DIR, PREBUILT_TOOLS, TOOLSET, TOOLS_DIR } from "./tools.js";
 
 export class InitError extends Error {}
 
 export const MODELS = ["claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"];
-export const APPROVALS = ["auto", "always_allow", "always_ask"];
 export const NETWORKING = ["limited", "unrestricted"];
 
 // The answers used when a question is skipped (--yes, or input ends early).
@@ -18,22 +18,16 @@ export function defaults(dir) {
     model: MODELS[0],
     system: "You are a helpful assistant.",
     tools: true,
-    approval: "auto",
     environment: slug,
     networking: "limited",
     packageManagers: true,
   };
 }
 
-// Returns { "agent.md": text, "env.md": text } for a set of answers.
+// Returns { path: text } for a set of answers: agent.md, env.md, and a tools/built-in/ file
+// for each pre-built tool when the agent gets them.
 export function scaffold(answers) {
   const agent = { name: answers.name, model: answers.model };
-  if (answers.tools) {
-    const toolset = { type: "agent_toolset_20260401" };
-    // always_allow is the toolset's default, so it needs no config.
-    if (answers.approval !== "always_allow") toolset.default_config = { permission_policy: { type: answers.approval } };
-    agent.tools = [toolset];
-  }
 
   const networking = { type: answers.networking };
   if (answers.networking === "limited") networking.allow_package_managers = answers.packageManagers;
@@ -42,10 +36,14 @@ export function scaffold(answers) {
   const access = answers.networking === "unrestricted"
     ? "unrestricted network access"
     : answers.packageManagers ? "limited networking and package manager access" : "limited networking";
-  return {
+  const files = {
     [AGENT_FILE]: `---\n${stringify(agent)}---\n\n${answers.system.trim()}\n`,
     [ENV_FILE]: `---\n${stringify(env)}---\nCloud container with ${access}.\n`,
   };
+  if (answers.tools) {
+    for (const name of PREBUILT_TOOLS) files[`${TOOLS_DIR}/${BUILT_IN_DIR}/${name}.md`] = `---\ntype: ${TOOLSET}\n---\n`;
+  }
+  return files;
 }
 
 // Asks the setup questions, then writes agent.md and env.md into a new folder `dir`.
@@ -57,11 +55,14 @@ export async function init(dir, { yes = false, input = process.stdin, output = p
   const answers = defaults(dir);
   if (!yes) await ask(answers, input, output);
 
-  mkdirSync(dir, { recursive: true });
   const files = scaffold(answers);
-  for (const [file, text] of Object.entries(files)) writeFileSync(resolve(dir, file), text);
+  for (const [file, text] of Object.entries(files)) {
+    mkdirSync(dirname(resolve(dir, file)), { recursive: true });
+    writeFileSync(resolve(dir, file), text);
+  }
 
-  output.write(`\nCreated ${dir}/${AGENT_FILE} and ${dir}/${ENV_FILE}.\n\nNext:\n`);
+  const tools = answers.tools ? `, and ${dir}/${TOOLS_DIR}/${BUILT_IN_DIR}/ with the pre-built tools (delete a file to disable that tool)` : "";
+  output.write(`\nCreated ${dir}/${AGENT_FILE} and ${dir}/${ENV_FILE}${tools}.\n\nNext:\n`);
   output.write(`  agentschema deploy ${dir}\n  agentschema run ${dir}\n`);
   return files;
 }
@@ -83,7 +84,6 @@ async function ask(answers, input, output) {
     answers.model = await io.select("Model?", MODELS, answers.model);
     answers.system = await io.text("System prompt?", answers.system);
     answers.tools = await confirm("Give it the built-in tools (bash, files, web)?", answers.tools);
-    if (answers.tools) answers.approval = await io.select("Tool approvals?", APPROVALS, answers.approval);
     answers.environment = await io.text("Environment name?", answers.environment);
     answers.networking = await io.select("Networking?", NETWORKING, answers.networking);
     if (answers.networking === "limited") {

package/src/instance.js

@@ -1,38 +1,12 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { parseDocument } from "yaml";
+import { FileError, parseMarkdown } from "./markdown.js";
+import { compileTools } from "./tools.js";
 
 export const AGENT_FILE = "agent.md";
 export const ENV_FILE = "env.md";
 
-export class FileError extends Error {}
-
-// Splits a Markdown file into YAML frontmatter (between `---` fences) and body.
-export function parseMarkdown(text, file) {
-  const normalized = text.replace(/^/, "").replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) {
-    throw new FileError(`${file}: must start with YAML frontmatter between --- lines`);
-  }
-  const closing = /^---[ \t]*$/m.exec(normalized.slice(4));
-  if (!closing) throw new FileError(`${file}: frontmatter is not closed with a --- line`);
-  const end = 4 + closing.index;
-  const afterFence = normalized.slice(end + closing[0].length);
-
-  const doc = parseDocument(normalized.slice(4, end));
-  if (doc.errors.length > 0) {
-    // The YAML library counts lines from the start of the frontmatter; +1 for the opening fence.
-    const err = doc.errors[0];
-    const line = err.linePos?.[0]?.line;
-    const where = line ? `:${line + 1}` : "";
-    throw new FileError(`${file}${where}: invalid YAML: ${err.message.split("\n")[0]}`);
-  }
-
-  const data = doc.toJS() ?? {};
-  if (typeof data !== "object" || Array.isArray(data)) {
-    throw new FileError(`${file}: frontmatter must be a YAML mapping (key: value pairs)`);
-  }
-  return { data, body: afterFence.trim(), raw: text };
-}
+export { FileError, parseMarkdown };
 
 // Reads agent.md and env.md from an instance folder.
 // Returns { agent, env, errors }; a file that can't be read is null and has an entry in errors.
@@ -67,12 +41,13 @@ export function readInstance(dir) {
 }
 
 // The bodies sent to POST /v1/agents and POST /v1/environments.
-export function agentBody(agent) {
-  const body = { ...agent.data };
+// The agent's tools come from tools/, compiled into the API's `tools` list.
+export function agentBody({ agent, tools }) {
+  const body = { ...agent.data, tools: compileTools(tools) };
   if (agent.body) body.system = agent.body;
   return body;
 }
 
-export function envBody(env) {
+export function envBody({ env }) {
   return { ...env.data };
 }

package/src/markdown.js

@@ -0,0 +1,30 @@
+import { parseDocument } from "yaml";
+
+export class FileError extends Error {}
+
+// Splits a Markdown file into YAML frontmatter (between `---` fences) and body.
+export function parseMarkdown(text, file) {
+  const normalized = text.replace(/^/, "").replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    throw new FileError(`${file}: must start with YAML frontmatter between --- lines`);
+  }
+  const closing = /^---[ \t]*$/m.exec(normalized.slice(4));
+  if (!closing) throw new FileError(`${file}: frontmatter is not closed with a --- line`);
+  const end = 4 + closing.index;
+  const afterFence = normalized.slice(end + closing[0].length);
+
+  const doc = parseDocument(normalized.slice(4, end));
+  if (doc.errors.length > 0) {
+    // The YAML library counts lines from the start of the frontmatter; +1 for the opening fence.
+    const err = doc.errors[0];
+    const line = err.linePos?.[0]?.line;
+    const where = line ? `:${line + 1}` : "";
+    throw new FileError(`${file}${where}: invalid YAML: ${err.message.split("\n")[0]}`);
+  }
+
+  const data = doc.toJS() ?? {};
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new FileError(`${file}: frontmatter must be a YAML mapping (key: value pairs)`);
+  }
+  return { data, body: afterFence.trim(), raw: text };
+}

package/src/session.js

@@ -1,6 +1,7 @@
 import { check } from "./check.js";
 import { AGENT_FILE, ENV_FILE, agentBody, envBody } from "./instance.js";
 import { LOCK_FILE, hashBody, readLock } from "./lock.js";
+import { TOOLS_DIR } from "./tools.js";
 
 export class SessionError extends Error {}
 
@@ -21,10 +22,10 @@ export async function openSession(dir, { client, sessionId }) {
   }
 
   const notes = [];
-  const { instance } = check(dir);
-  if (instance) {
-    if (hashBody(agentBody(instance.agent)) !== agent.hash) notes.push(`${AGENT_FILE} has changed since the last deploy`);
-    if (hashBody(envBody(instance.env)) !== env.hash) notes.push(`${ENV_FILE} has changed since the last deploy`);
+  const { instance, errors } = check(dir);
+  if (instance && errors.length === 0) {
+    if (hashBody(agentBody(instance)) !== agent.hash) notes.push(`${AGENT_FILE} or ${TOOLS_DIR}/ has changed since the last deploy`);
+    if (hashBody(envBody(instance)) !== env.hash) notes.push(`${ENV_FILE} has changed since the last deploy`);
     if (notes.length > 0) notes.push(`this session uses the deployed version; run agentschema deploy to pick up the changes`);
   }
 
@@ -41,7 +42,7 @@ export async function openSession(dir, { client, sessionId }) {
 // Drives a session one turn at a time. `ui` answers what only a person can:
 //   ui.event(event)          show an event
 //   ui.confirm(event)        -> { result: "allow" | "deny", deny_message? } for a paused tool call
-//   ui.customToolResult(event) -> string, the result of a custom tool call
+//   ui.customToolResult(event) -> string, or { text, isError }: the result of a custom tool call
 export class Conversation {
   constructor(client, sessionId, ui) {
     this.client = client;
@@ -108,8 +109,11 @@ export class Conversation {
         }
         return null;
       case "agent.custom_tool_use": {
-        const text = await this.ui.customToolResult(event);
-        await send({ type: "user.custom_tool_result", custom_tool_use_id: event.id, content: [{ type: "text", text }] });
+        const result = await this.ui.customToolResult(event);
+        const { text, isError } = typeof result === "string" ? { text: result } : result;
+        const reply = { type: "user.custom_tool_result", custom_tool_use_id: event.id, content: [{ type: "text", text }] };
+        if (isError) reply.is_error = true;
+        await send(reply);
         return null;
       }
       case "session.status_idle":

package/src/tools.js

@@ -0,0 +1,210 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, join, resolve } from "node:path";
+import { Script, runInThisContext } from "node:vm";
+import { FileError, parseMarkdown } from "./markdown.js";
+
+export const TOOLS_DIR = "tools";
+export const BUILT_IN_DIR = "built-in";
+export const TOOLSET = "agent_toolset_20260401";
+export const PREBUILT_TOOLS = ["bash", "edit", "glob", "grep", "read", "web_fetch", "web_search", "write"];
+const TYPES = ["string", "number", "integer", "boolean", "object", "array"];
+
+// Reads every .md file under tools/, in any subfolder, sorted by name. Folders are only for
+// organizing: a tool's name is its file name, and its path isn't compiled into anything.
+// A missing tools/ folder means no tools.
+// Returns { tools, errors }; a tool file that can't be parsed has an entry in errors.
+export function readTools(dir) {
+  const folder = join(dir, TOOLS_DIR);
+  try {
+    if (!statSync(folder).isDirectory()) return { tools: [], errors: [`${TOOLS_DIR}: not a directory`] };
+  } catch {
+    return { tools: [], errors: [] };
+  }
+
+  const tools = [];
+  const errors = [];
+  for (const file of markdownFiles(folder, TOOLS_DIR)) {
+    try {
+      const parsed = parseMarkdown(readFileSync(join(dir, file), "utf8"), file);
+      const name = basename(file, ".md");
+      tools.push({ file, path: resolve(dir, file), name, ...parsed, ...parseSections(parsed.body, file) });
+    } catch (err) {
+      if (!(err instanceof FileError)) throw err;
+      errors.push(err.message);
+    }
+  }
+
+  // Names must be unique across folders, since the folders are dropped.
+  for (const [name, same] of groupBy(tools, (t) => t.name)) {
+    if (same.length > 1) errors.push(`${TOOLS_DIR}: more than one tool is named \`${name}\` (${same.map((t) => t.file).join(", ")})`);
+  }
+  return { tools: tools.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)), errors };
+}
+
+// Paths, relative to the instance folder, of the .md files under `folder`; hidden entries are skipped.
+function markdownFiles(folder, relative) {
+  const files = [];
+  for (const entry of readdirSync(folder, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (entry.name.startsWith(".")) continue;
+    const rel = `${relative}/${entry.name}`;
+    if (entry.isDirectory()) files.push(...markdownFiles(join(folder, entry.name), rel));
+    else if (entry.name.endsWith(".md")) files.push(rel);
+  }
+  return files;
+}
+
+function groupBy(items, key) {
+  const groups = new Map();
+  for (const item of items) groups.set(key(item), [...(groups.get(key(item)) ?? []), item]);
+  return groups;
+}
+
+// Pulls the `## Input Schema` table and the `## Code` block out of a tool file's body.
+function parseSections(body, file) {
+  const sections = {};
+  let current = null;
+  let fence = null;
+  for (const line of body.split("\n")) {
+    const marker = /^(```|~~~)/.exec(line)?.[1];
+    if (marker && (!fence || fence === marker)) fence = fence ? null : marker;
+    const heading = !fence && /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1].toLowerCase();
+      sections[current] = [];
+    } else if (current) {
+      sections[current].push(line);
+    }
+  }
+
+  const result = { params: null, code: null };
+  if (sections["input schema"]) result.params = parseTable(sections["input schema"], file);
+  if (sections.code) result.code = parseCode(sections.code, file);
+  return result;
+}
+
+// Rows of the Name | Type | Description | Required table.
+function parseTable(lines, file) {
+  const rows = lines.filter((l) => l.trim().startsWith("|")).map(splitRow);
+  if (rows.length === 0) return [];
+  const header = rows[0].map((c) => c.toLowerCase());
+  const want = ["name", "type", "description", "required"];
+  if (want.some((c, i) => header[i] !== c)) {
+    throw new FileError(`${file}: the Input Schema table's columns must be Name | Type | Description | Required`);
+  }
+  return rows.slice(2).map(([name, type, description, required]) => ({ name, type, description, required }));
+}
+
+function splitRow(line) {
+  const cells = line.trim().replace(/^\|/, "").replace(/\|$/, "").split(/(?<!\\)\|/);
+  return cells.map((c) => c.trim().replace(/\\\|/g, "|").replace(/^`(.*)`$/, "$1"));
+}
+
+function parseCode(lines, file) {
+  const text = lines.join("\n");
+  const blocks = [...text.matchAll(/^(```|~~~)[ \t]*([\w-]*)[^\n]*\n([\s\S]*?)^\1[ \t]*$/gm)];
+  if (blocks.length !== 1) throw new FileError(`${file}: the Code section must hold exactly one fenced code block`);
+  const [, , lang, source] = blocks[0];
+  return { lang: lang.toLowerCase(), source };
+}
+
+// Errors and warnings for the tool files, in check's format.
+export function checkTools(tools, errors) {
+  const customs = tools.filter((t) => t.data.type === "custom");
+  if (customs.length + (customs.length < tools.length ? 1 : 0) > 256) errors.push(`${TOOLS_DIR}: more than 256 tools`);
+
+  for (const tool of tools) {
+    const err = (msg) => errors.push(`${tool.file}: ${msg}`);
+    const { type } = tool.data;
+    const extra = (allowed) => {
+      for (const key of Object.keys(tool.data)) if (!allowed.includes(key)) err(`unknown field \`${key}\``);
+    };
+
+    if (type === TOOLSET) {
+      if (!PREBUILT_TOOLS.includes(tool.name)) {
+        err(`not a pre-built tool; name the file after one of: ${PREBUILT_TOOLS.join(", ")}`);
+      }
+      extra(["type"]);
+    } else if (type === "custom") {
+      checkCustom(tool, err);
+      extra(["type", "name", "description"]);
+    } else {
+      err(`\`type\` must be \`${TOOLSET}\` (a pre-built tool) or \`custom\``);
+    }
+  }
+}
+
+function checkCustom(tool, err) {
+  const { name, description } = tool.data;
+  if (name !== tool.name) err(`\`name\` must match the file name (${tool.name})`);
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(tool.name)) err("the name may only use letters, digits, _ and -, up to 64 characters");
+  if (PREBUILT_TOOLS.includes(tool.name)) err(`\`${tool.name}\` is a pre-built tool's name; the API rejects custom tools that reuse one`);
+  if (/^(mcp__|ant__)/.test(tool.name)) err("custom tool names can't start with mcp__ or ant__");
+  if (typeof description !== "string" || description.trim() === "") err("`description` is required");
+
+  const seen = new Set();
+  for (const p of tool.params ?? []) {
+    if (!p.name) err("an Input Schema row has no name");
+    else if (seen.has(p.name)) err(`input \`${p.name}\` is listed twice`);
+    seen.add(p.name);
+    if (!TYPES.includes(p.type?.replace(/\[\]$/, ""))) {
+      err(`input \`${p.name}\` has type \`${p.type}\`; use ${TYPES.join(", ")}, or one of them followed by []`);
+    }
+    if (!["true", "false"].includes(p.required?.toLowerCase())) err(`input \`${p.name}\`: Required must be true or false`);
+  }
+
+  if (!tool.code) return err("a `## Code` section with a JavaScript code block is required");
+  if (!["javascript", "js"].includes(tool.code.lang)) err("the code must be JavaScript (```javascript)");
+  else {
+    try {
+      new Script(wrap(tool.code.source), { filename: tool.file });
+    } catch (e) {
+      err(`the code doesn't parse: ${e.message}`);
+    }
+  }
+}
+
+// The tools list sent to the API: one toolset entry that enables only the pre-built tools
+// with a file (so deleting a file disables the tool), then the custom tools, sorted by name.
+export function compileTools(tools) {
+  const compiled = [];
+  const prebuilt = tools.filter((t) => t.data.type === TOOLSET).map((t) => t.name).sort();
+  if (prebuilt.length > 0) {
+    compiled.push({
+      type: TOOLSET,
+      default_config: { enabled: false },
+      configs: prebuilt.map((name) => ({ name, enabled: true })),
+    });
+  }
+  for (const tool of tools.filter((t) => t.data.type === "custom").sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    compiled.push({ type: "custom", name: tool.name, description: tool.data.description, input_schema: inputSchema(tool.params ?? []) });
+  }
+  return compiled;
+}
+
+function inputSchema(params) {
+  const properties = {};
+  for (const p of params) {
+    const list = p.type.endsWith("[]");
+    const type = p.type.replace(/\[\]$/, "");
+    const prop = list ? { type: "array", items: { type } } : { type };
+    if (p.description) prop.description = p.description;
+    properties[p.name] = prop;
+  }
+  const required = params.filter((p) => p.required.toLowerCase() === "true").map((p) => p.name);
+  return required.length > 0 ? { type: "object", properties, required } : { type: "object", properties };
+}
+
+// Loads a custom tool's code as a CommonJS module whose module.exports is the function.
+// require() resolves relative to the tool's file, so the agent folder's node_modules work.
+export function loadTool(tool) {
+  const module = { exports: {} };
+  const fn = runInThisContext(wrap(tool.code.source), { filename: tool.path });
+  fn(module.exports, createRequire(tool.path), module, tool.path, resolve(tool.path, ".."));
+  if (typeof module.exports !== "function") {
+    throw new Error(`${tool.file}: module.exports must be a function`);
+  }
+  return module.exports;
+}
+
+const wrap = (source) => `(function (exports, require, module, __filename, __dirname) {${source}\n})`;