@soft-boy/agentschema 0.1.1 → 0.2.0

package/README.md

@@ -1,20 +1,25 @@
 # agentschema
 
-Define a Claude Managed Agent as a folder of Markdown files.
+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. `check`, `deploy` and `run` work.
+**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
 
@@ -22,53 +27,29 @@ my-agent/
 npm install -g @soft-boy/agentschema
 ```
 
-## Example
-
-[`examples/coding-agent/agent.md`](examples/coding-agent/agent.md):
-
-```markdown
----
-name: Coding Assistant
-model: claude-opus-5-5
-tools:
-  - type: agent_toolset_20260401
----
-
-You are a helpful coding assistant. Write clean, well-documented code.
-```
-
-[`examples/coding-agent/env.md`](examples/coding-agent/env.md):
-
-```markdown
----
-name: quickstart
-config:
-  type: cloud
-  networking:
-    type: limited
-    allow_package_managers: true
----
-Cloud container with limited networking and package manager access.
-```
-
 ## Specification
 
 ### 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).
@@ -76,49 +57,137 @@ 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
+agentschema init <name>               # scaffold a new agent folder
 agentschema check [dir]               # validate the folder, no network
 agentschema deploy [dir]              # create or update the agent and environment
 agentschema run [dir]                 # chat with the deployed agent in the terminal
+agentschema list                      # list the agents in your workspace
+agentschema delete <agent_id>         # archive an agent
+agentschema sessions list             # list the sessions in your workspace
+agentschema sessions delete <id>      # delete a session
 ```
 
 `dir` defaults to the current directory.
 
-**`check`** reads both files and reports every problem it finds:
+**`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 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 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.
 
-`deploy` authenticates with `ANTHROPIC_API_KEY`, or with a profile from `ant auth login`.
-
 `claude-lock.json` uses the same layout as `ant apply`'s, so `deploy` updates resources that `ant apply` created. The two tools hash files differently, though, so the first `deploy` after an `ant apply` updates both resources even if nothing changed.
 
 **`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 --session sesn_…`.
+- **Resuming:** quitting leaves the session in place, and `run` prints a command to resume it: `agentschema run --resume sesn_…`.
 
 ```sh
-agentschema run [dir] --vault vlt_…        # attach a vault for MCP or other credentials (repeatable)
-agentschema run [dir] --title "Bug triage" # name the session
-agentschema run --session sesn_…           # resume an existing session
+agentschema run --resume sesn_…   # resume an existing session
 ```
 
 To run the agent from your own code, create a session with the agent and environment IDs from the lock file.
 
+**`list`** prints every agent in your workspace, with its ID, latest version, model and when it was last updated. It includes agents that weren't deployed with agentschema, and leaves out archived ones.
+
+**`sessions list`** prints every session in your workspace, newest first, with its status, the agent and version it runs, and its title. Pass an ID to `run --resume` to pick a session back up.
+
+**`delete`** archives an agent. The API can't delete agents outright, so this is as close as it gets. An archived agent drops out of `list`, and the API has no way to unarchive it. If the agent is in a folder's `claude-lock.json`, remove its entry so the next `deploy` creates a new one.
+
+**`sessions delete`** permanently deletes a session and its event history. A running session can't be deleted; wait for it to go idle, or interrupt it, first.
+
+Both ask for confirmation first, showing the agent's name or the session's title. Pass `--yes` to skip that, for example in scripts; without a terminal to ask in, they refuse unless you pass `--yes`.
+
+### Authentication
+
+agentschema has no account setting of its own. Every command except `init` and `check` uses whichever Anthropic credentials are in your shell:
+
+1. `ANTHROPIC_API_KEY`, if it's set
+2. otherwise, the profile you signed in to with `ant auth login` (the active one, or the one `ANTHROPIC_PROFILE` names)
+
+An API key belongs to one workspace, and the agent and environment are created in that workspace. Each person deploys with their own key, and to deploy somewhere else you switch the key:
+
+```sh
+ANTHROPIC_API_KEY=sk-ant-… agentschema deploy my-agent
+```
+
+`claude-lock.json` holds the IDs from one workspace. A committed lock works for everyone whose key is in that workspace, and they all update the same agent. If you deploy the folder from a key in a different workspace, `deploy` can't find those IDs and stops. In that case, deploy from a copy of the folder, or don't commit that lock file.
+
 ## Development
 
 ```sh

package/bin/agentschema.js

@@ -1,44 +1,58 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import Anthropic from "@anthropic-ai/sdk";
 import { chat } from "../src/chat.js";
 import { check } from "../src/check.js";
+import { DeleteError, deleteAgent, deleteSession } from "../src/delete.js";
 import { DeployError, deploy } from "../src/deploy.js";
+import { InitError, init } from "../src/init.js";
+import { listAgents, listSessions } from "../src/list.js";
 import { SessionError, openSession } from "../src/session.js";
 
 const USAGE = `Usage: agentschema <command> [dir] [options]
 
 Commands:
-  check [dir]     Validate agent.md and env.md, without calling the API
-  deploy [dir]    Create or update the agent and environment, and write claude-lock.json
-  run [dir]       Chat with the deployed agent in a new session
+  init <name>           Scaffold a new agent folder, asking a few questions
+  check [dir]           Validate agent.md and env.md, without calling the API
+  deploy [dir]          Create or update the agent and environment, and write claude-lock.json
+  run [dir]             Chat with the deployed agent in a new session
+  list                  List the agents in your workspace
+  delete <agent_id>     Archive an agent (agents can't be deleted outright)
+  sessions list         List the sessions in your workspace, newest first
+  sessions delete <id>  Delete a session and its history
 
 Options:
+  -y, --yes         (init) Skip the questions and use the defaults
+                    (delete) Don't ask for confirmation
   --dry-run         (deploy) Show what would be created or updated, change nothing
   --force           (deploy) Update the agent even if it was changed outside this folder
-  --vault <id>      (run) Attach a vault (vlt_...) for MCP and other credentials; repeatable
-  --title <title>   (run) Title for the new session
-  --session <id>    (run) Resume an existing session (sesn_...) instead of starting one
+  --resume <id>     (run) Resume an existing session (sesn_...) instead of starting one
   -h, --help        Show this help
   -v, --version     Show the version
 
-dir defaults to the current directory. deploy and run authenticate with
+dir defaults to the current directory. Every command but init and check authenticates with
 ANTHROPIC_API_KEY, or with a profile from \`ant auth login\`.`;
 
 const OPTIONS = {
+  yes: { type: "boolean", short: "y" },
   "dry-run": { type: "boolean" },
   force: { type: "boolean" },
-  vault: { type: "string", multiple: true },
-  title: { type: "string" },
-  session: { type: "string" },
+  resume: { type: "string" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" },
 };
-const COMMAND_OPTIONS = {
-  check: [],
-  deploy: ["dry-run", "force"],
-  run: ["vault", "title", "session"],
+// For each command: how many positional arguments it takes, and which options.
+const COMMANDS = {
+  init: { args: [1, 1], options: ["yes"] },
+  check: { args: [0, 1], options: [] },
+  deploy: { args: [0, 1], options: ["dry-run", "force"] },
+  run: { args: [0, 1], options: ["resume"] },
+  list: { args: [0, 0], options: [] },
+  delete: { args: [1, 1], options: ["yes"] },
+  "sessions list": { args: [0, 0], options: [] },
+  "sessions delete": { args: [1, 1], options: ["yes"] },
 };
 
 async function main(argv) {
@@ -50,7 +64,8 @@ async function main(argv) {
     return 1;
   }
   const { values, positionals } = parsed;
-  const [command, dir = ".", ...extra] = positionals;
+  let [command, ...args] = positionals;
+  if (command === "sessions") command = `sessions ${args.shift() ?? ""}`.trim();
 
   if (values.version) {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -61,16 +76,38 @@ async function main(argv) {
     console.log(USAGE);
     return command || values.help ? 0 : 1;
   }
-  if (!(command in COMMAND_OPTIONS)) {
+  if (command.startsWith("sessions") && !(command in COMMANDS)) {
+    console.error(`agentschema: usage: agentschema sessions list | sessions delete <id>`);
+    return 1;
+  }
+  if (!(command in COMMANDS)) {
     console.error(`agentschema: unknown command "${command}"\n\n${USAGE}`);
     return 1;
   }
-  const misplaced = Object.keys(values).filter((k) => !COMMAND_OPTIONS[command].includes(k));
-  if (extra.length > 0 || misplaced.length > 0) {
-    const arg = extra[0] ?? `--${misplaced[0]}`;
+  const spec = COMMANDS[command];
+  const misplaced = Object.keys(values).filter((k) => !spec.options.includes(k));
+  if (args.length > spec.args[1] || misplaced.length > 0) {
+    const arg = args[spec.args[1]] ?? `--${misplaced[0]}`;
     console.error(`agentschema: unexpected argument ${arg} for ${command}\n\n${USAGE}`);
     return 1;
   }
+  if (args.length < spec.args[0]) {
+    const example = { init: "init my-agent", delete: "delete agent_…", "sessions delete": "sessions delete sesn_…" }[command];
+    console.error(`agentschema: ${command} needs an argument, e.g. agentschema ${example}`);
+    return 1;
+  }
+  const dir = args[0] ?? ".";
+
+  if (command === "init") {
+    try {
+      await init(dir, { yes: values.yes ?? false });
+      return 0;
+    } catch (err) {
+      if (!(err instanceof InitError)) throw err;
+      console.error(`error: ${err.message}`);
+      return 1;
+    }
+  }
 
   if (command === "check") {
     const { errors, warnings } = check(dir);
@@ -94,16 +131,29 @@ async function main(argv) {
       return 0;
     }
 
+    if (command === "list" || command === "sessions list") {
+      const lines = command === "list" ? await listAgents(makeClient(false)) : await listSessions(makeClient(false));
+      for (const line of lines) console.log(line);
+      return 0;
+    }
+
+    if (command === "delete" || command === "sessions delete") {
+      const remove = command === "delete" ? deleteAgent : deleteSession;
+      await remove(makeClient(false), args[0], {
+        confirm: values.yes ? async () => true : confirm,
+        log: (line) => console.log(line),
+      });
+      return 0;
+    }
+
     if (command === "run") {
       const client = makeClient(false);
       const { session, notes } = await openSession(dir, {
         client,
-        sessionId: values.session,
-        vaultIds: values.vault ?? [],
-        title: values.title,
+        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) {
@@ -111,7 +161,7 @@ async function main(argv) {
       console.error(`error: ${err.status ?? "network error"}: ${err.error?.error?.message ?? err.message}`);
       return 1;
     }
-    if (err instanceof DeployError || err instanceof SessionError || err instanceof Anthropic.AnthropicError) {
+    if (err instanceof DeployError || err instanceof DeleteError || err instanceof SessionError || err instanceof Anthropic.AnthropicError) {
       console.error(`error: ${err.message}`);
       return 1;
     }
@@ -119,6 +169,30 @@ async function main(argv) {
   }
 }
 
+// Asks a yes/no question in the terminal; without one, there's no one to ask.
+async function confirm(question) {
+  if (!process.stdin.isTTY) throw new DeleteError("not a terminal, so can't ask for confirmation; pass --yes");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^(y|yes)$/i.test((await rl.question(`${question} [y/N] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// 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.1",
+  "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.";
@@ -131,5 +149,5 @@ export async function chat(client, session, { agentName, input = process.stdin,
     conversation.close();
     rl.close();
   }
-  if (!ended) output.write(dim(`Resume this conversation with: agentschema run --session ${session.id}\n`));
+  if (!ended) output.write(dim(`Resume this conversation with: agentschema run --resume ${session.id}\n`));
 }

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 in a vault`);
+      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/delete.js

@@ -0,0 +1,25 @@
+export class DeleteError extends Error {}
+
+// Agents can't be deleted, only archived: an archived agent drops out of `list`, and
+// there's no unarchive. `confirm(question)` resolves to true to go ahead.
+export async function deleteAgent(client, agentId, { confirm, log }) {
+  const agent = await client.beta.agents.retrieve(agentId);
+  if (agent.archived_at) throw new DeleteError(`${agentId} is already archived`);
+  const ok = await confirm(`Archive agent "${agent.name}" (${agentId})? It can't be undone.`);
+  if (!ok) return log("Nothing changed.");
+  await client.beta.agents.archive(agentId);
+  log(`Archived ${agentId}.`);
+}
+
+// Deletes a session and its event history for good.
+export async function deleteSession(client, sessionId, { confirm, log }) {
+  const session = await client.beta.sessions.retrieve(sessionId);
+  if (session.status === "running") {
+    throw new DeleteError(`${sessionId} is running; wait for it to go idle, or interrupt it, then try again`);
+  }
+  const label = session.title ? `"${session.title}" (${sessionId})` : sessionId;
+  const ok = await confirm(`Delete session ${label} and its history? It can't be undone.`);
+  if (!ok) return log("Nothing changed.");
+  await client.beta.sessions.delete(sessionId);
+  log(`Deleted ${sessionId}.`);
+}

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

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+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 NETWORKING = ["limited", "unrestricted"];
+
+// The answers used when a question is skipped (--yes, or input ends early).
+export function defaults(dir) {
+  const slug = basename(resolve(dir)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "agent";
+  return {
+    name: slug.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" "),
+    model: MODELS[0],
+    system: "You are a helpful assistant.",
+    tools: true,
+    environment: slug,
+    networking: "limited",
+    packageManagers: true,
+  };
+}
+
+// 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 };
+
+  const networking = { type: answers.networking };
+  if (answers.networking === "limited") networking.allow_package_managers = answers.packageManagers;
+  const env = { name: answers.environment, config: { type: "cloud", networking } };
+
+  const access = answers.networking === "unrestricted"
+    ? "unrestricted network access"
+    : answers.packageManagers ? "limited networking and package manager access" : "limited networking";
+  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`.
+export async function init(dir, { yes = false, input = process.stdin, output = process.stdout } = {}) {
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    throw new InitError(`${dir} already exists and isn't empty`);
+  }
+
+  const answers = defaults(dir);
+  if (!yes) await ask(answers, input, output);
+
+  const files = scaffold(answers);
+  for (const [file, text] of Object.entries(files)) {
+    mkdirSync(dirname(resolve(dir, file)), { recursive: true });
+    writeFileSync(resolve(dir, file), text);
+  }
+
+  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;
+}
+
+// Fills in `answers` from the user's replies; an empty reply keeps the default shown.
+async function ask(answers, input, output) {
+  const io = input.isTTY ? terminalPrompts(input, output) : linePrompts(input, output);
+  const confirm = async (question, fallback) => {
+    while (true) {
+      const reply = (await io.text(`${question} [y/n]`, fallback ? "y" : "n")).toLowerCase();
+      if (/^(y|yes)$/.test(reply)) return true;
+      if (/^(n|no)$/.test(reply)) return false;
+      output.write("Answer y or n\n");
+    }
+  };
+
+  try {
+    answers.name = await io.text("Agent name?", answers.name);
+    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);
+    answers.environment = await io.text("Environment name?", answers.environment);
+    answers.networking = await io.select("Networking?", NETWORKING, answers.networking);
+    if (answers.networking === "limited") {
+      answers.packageManagers = await confirm("Allow package managers (npm, pip, …)?", answers.packageManagers);
+    }
+  } finally {
+    io.close();
+  }
+}
+
+// Prompts for piped input: one answer per line, and choices picked by name or number.
+function linePrompts(input, output) {
+  const rl = createInterface({ input, output, terminal: false });
+  const lines = rl[Symbol.asyncIterator]();
+  let ended = false;
+
+  const text = async (question, fallback) => {
+    if (ended) return fallback;
+    output.write(`${question} (${fallback}) `);
+    const { value, done } = await lines.next();
+    if (done) {
+      ended = true;
+      output.write("\n");
+      return fallback;
+    }
+    return value.trim() || fallback;
+  };
+  const select = async (question, choices, fallback) => {
+    const listed = choices.map((c, i) => `${i + 1}) ${c}`).join("  ");
+    while (true) {
+      const reply = await text(`${question} ${listed}`, String(choices.indexOf(fallback) + 1));
+      const picked = choices[Number(reply) - 1] ?? choices.find((c) => c === reply);
+      if (picked) return picked;
+      output.write(`Pick one of: ${choices.join(", ")}\n`);
+    }
+  };
+  return { text, select, close: () => rl.close() };
+}
+
+const ESC = "\x1b[";
+const cyan = (s) => `${ESC}36m${s}${ESC}0m`;
+const dim = (s) => `${ESC}2m${s}${ESC}0m`;
+
+// Prompts for a terminal: choices are picked with the arrow keys and Enter.
+function terminalPrompts(input, output) {
+  const cancelled = () => new InitError("cancelled");
+
+  // A fresh readline per question, so it doesn't fight the raw-mode select for the arrow keys.
+  const text = (question, fallback) =>
+    new Promise((resolve, reject) => {
+      const rl = createInterface({ input, output, terminal: true });
+      rl.on("SIGINT", () => {
+        rl.close();
+        output.write("\n");
+        reject(cancelled());
+      });
+      rl.question(`${question} ${dim(`(${fallback})`)} `, (reply) => {
+        rl.close();
+        resolve(reply.trim() || fallback);
+      });
+    });
+
+  const select = (question, choices, fallback) =>
+    new Promise((resolve, reject) => {
+      let index = Math.max(0, choices.indexOf(fallback));
+      const render = (first) => {
+        if (!first) output.write(`${ESC}${choices.length}A`);
+        for (const [i, choice] of choices.entries()) {
+          output.write(`${ESC}2K${i === index ? cyan(`❯ ${choice}`) : `  ${choice}`}\n`);
+        }
+      };
+      const finish = (err) => {
+        input.off("keypress", onKey);
+        input.setRawMode(false);
+        input.pause();
+        // Collapse the list to one line with the answer.
+        output.write(`${ESC}${choices.length + 1}A${ESC}J${ESC}?25h`);
+        output.write(`${question} ${err ? dim("cancelled") : cyan(choices[index])}\n`);
+        err ? reject(err) : resolve(choices[index]);
+      };
+      const onKey = (str, key = {}) => {
+        if (key.ctrl && key.name === "c") return finish(cancelled());
+        if (key.name === "return" || key.name === "enter") return finish();
+        if (key.name === "up" || key.name === "k") index = (index - 1 + choices.length) % choices.length;
+        else if (key.name === "down" || key.name === "j" || key.name === "tab") index = (index + 1) % choices.length;
+        else if (/^[1-9]$/.test(str ?? "") && Number(str) <= choices.length) index = Number(str) - 1;
+        else return;
+        render(false);
+      };
+
+      emitKeypressEvents(input);
+      input.setRawMode(true);
+      input.resume();
+      output.write(`${question} ${dim("(↑/↓, Enter)")}\n${ESC}?25l`);
+      render(true);
+      input.on("keypress", onKey);
+    });
+
+  return { text, select, close() {} };
+}

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/list.js

@@ -0,0 +1,49 @@
+// Lists the agents and sessions in the workspace the credentials belong to.
+
+export async function listAgents(client) {
+  const rows = [];
+  for await (const agent of client.beta.agents.list()) {
+    rows.push({
+      name: agent.name,
+      id: agent.id,
+      version: String(agent.version),
+      model: agent.model?.id ?? "",
+      updated: formatDate(agent.updated_at),
+    });
+  }
+  return table(rows, { name: "NAME", id: "ID", version: "VERSION", model: "MODEL", updated: "UPDATED" }, "No agents.");
+}
+
+export async function listSessions(client) {
+  const rows = [];
+  // Newest first, the API's default order.
+  for await (const session of client.beta.sessions.list()) {
+    rows.push({
+      id: session.id,
+      status: session.status,
+      agent: session.agent ? `${session.agent.name} v${session.agent.version}` : "",
+      title: truncate(session.title ?? "", 40),
+      created: formatDate(session.created_at),
+    });
+  }
+  return table(rows, { id: "ID", status: "STATUS", agent: "AGENT", title: "TITLE", created: "CREATED" }, "No sessions.");
+}
+
+// Lines of a plain-text table, with columns padded to their widest value.
+function table(rows, headers, empty) {
+  if (rows.length === 0) return [empty];
+  const keys = Object.keys(headers);
+  const widths = keys.map((k) => Math.max(headers[k].length, ...rows.map((r) => r[k].length)));
+  const line = (r) => keys.map((k, i) => (i === keys.length - 1 ? r[k] : r[k].padEnd(widths[i]))).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)];
+}
+
+// "2026-11-03 14:02" in local time.
+function formatDate(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);

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,12 +1,13 @@
 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 {}
 
 // Starts a session on the agent and environment recorded in claude-lock.json, or resumes `sessionId`.
 // Returns { session, notes }: notes are warnings worth showing, such as files changed since the last deploy.
-export async function openSession(dir, { client, sessionId, vaultIds = [], title }) {
+export async function openSession(dir, { client, sessionId }) {
   if (sessionId) {
     const session = await client.beta.sessions.retrieve(sessionId);
     if (session.status === "terminated") throw new SessionError(`session ${sessionId} has terminated`);
@@ -21,10 +22,10 @@ export async function openSession(dir, { client, sessionId, vaultIds = [], title
   }
 
   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`);
   }
 
@@ -33,16 +34,15 @@ export async function openSession(dir, { client, sessionId, vaultIds = [], title
     agent: { type: "agent", id: agent.id, version: Number(agent.version) },
     environment_id: env.id,
   };
-  if (vaultIds.length > 0) params.vault_ids = vaultIds;
   const name = instance?.agent.data.name;
-  params.title = title ?? (name ? `${name} (agentschema run)` : "agentschema run");
+  params.title = name ? `${name} (agentschema run)` : "agentschema run";
   return { session: await client.beta.sessions.create(params), notes };
 }
 
 // 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;
@@ -109,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})`;