@evref-bl/pharo-agent 0.16.0 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/README.md

@@ -3,8 +3,8 @@
 `pharo-agent` gives a coding agent a Pharo Launcher of its own. It can see the
 templates the launcher offers, create images from them, start and stop them,
 and work inside the ones it started: classes, methods, senders, tests,
-refactorings, critiques, and the rest of what a Pharo IDE does. On macOS it
-can also read and edit an image's source as files.
+refactorings, critiques, and the rest of what a Pharo IDE does. On macOS and
+Linux it can also read and edit an image's source as files.
 
 It works with Claude Code, Codex and OpenCode.
 
@@ -32,10 +32,10 @@ tested together, and gives the agent one command surface over the lot.
 - Node 22.12 or later.
 - [Pharo Launcher](https://pharo-project.github.io/pharo-launcher/), which is
   where images and templates come from.
-- For editing source as files: macOS with [fuse-t](https://www.fuse-t.org/),
-  installed with `brew install --cask fuse-t`. Its daemon is downloaded for
-  you. Everywhere else images start with their Pharo tools and no projection,
-  rather than failing.
+- For editing source as files: macOS, which needs nothing more, or Linux with
+  FUSE 3 (the `fuse3` package, installed by default on most distributions).
+  Its daemon is downloaded for you. Where a projection cannot mount, the image
+  starts with its Pharo tools and a warning saying why, rather than failing.
 
 The image tools cover Pharo 12 to 15. An image outside that range still
 starts, and says what it will not have.
@@ -76,10 +76,11 @@ its schemas stay out of the agent's context. The tools belong to the image, so
 what exists depends on what that image has loaded. [Tools](docs/tools.md)
 covers both, and serving a different MCP from an image.
 
-**Source as files, on macOS.** Starting an image mounts its source below
+**Source as files, on macOS and Linux.** Starting an image mounts its source below
 `.pharo-agent/mounts`. A file edited there is compiled into the live image:
 the files and the tools are two views of one image, not of an export and an
-image.
+image. Setting `PHARO_AGENT_PROJECTION=off` in the environment starts images
+without mounting anything.
 
 **Guidance for the agent.** Setting a project up writes a Pharo guide into it,
 and a conditional line in the host's own guide pointing at that guide for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -32,8 +32,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "3.5.0",
-    "@evref-bl/plexus": "0.15.0",
+    "@evref-bl/pharo-mcp": "3.6.0",
+    "@evref-bl/plexus": "0.15.1",
     "@modelcontextprotocol/sdk": "1.32.2"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-feedback/SKILL.md

@@ -63,7 +63,7 @@ instead of a new issue.
 One issue per problem; findings that share a cause make one issue. Title it
 with what goes wrong, in the tool's own terms. Keep the body short:
 
-- **Tool:** its name; `pharo-agent 0.16.0`; the image's Pharo version, which
+- **Tool:** its name; `pharo-agent 0.17.0`; the image's Pharo version, which
   `image_list` gives; the host you run in.
 - **What happened:** what you asked for and what came back, the error quoted
   and trimmed.

package/skills/pharo-setup/SKILL.md

@@ -10,7 +10,7 @@ the host this chat runs in: `--host claude` in Claude Code, `--host codex` in
 Codex, `--host opencode` in OpenCode.
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.16.0 init --host claude
+npx --yes @evref-bl/pharo-agent@0.17.0 init --host claude
 ```
 
 It writes the project's Pharo guide, skills and references, and a block in the

package/src/cli.js

@@ -2,11 +2,18 @@ import { hostChoices, hostList } from "./hosts.js";
 import { usage } from "./help.js";
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
-import { callImageTool, listImageTools } from "./gateway.js";
+import { callImageTool, listAdvertisedTools, toolContract } from "./gateway.js";
 import { serveImagesMcp } from "./mcpServer.js";
 import { listImageTemplates, startAgentImage, stopAgentImage } from "./live.js";
 import { findProjectRoot } from "./project.js";
 import { readRunningImage } from "./runtime.js";
+import {
+  isToolName,
+  resultText,
+  toolArguments,
+  toolListing,
+  toolUsage,
+} from "./toolCommand.js";
 
 function parseInit(args) {
   let host;
@@ -97,20 +104,6 @@ function requireNoArguments(command, args) {
   }
 }
 
-function parseToolArguments(value) {
-  if (value === undefined) return {};
-  let parsed;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw new Error("Tool arguments must be a JSON object.");
-  }
-  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
-    throw new Error("Tool arguments must be a JSON object.");
-  }
-  return parsed;
-}
-
 // A tool the image answered with an error is still an answer: the MCP result
 // carries the Pharo exception, and a caller wants to read it. Print it as
 // always, and report the failure in the exit status too, so `set -e` and
@@ -119,8 +112,61 @@ export function exitCodeForToolResult(result) {
   return result?.isError === true ? 1 : 0;
 }
 
+function takeFlag(args, flag) {
+  return { present: args.includes(flag), rest: args.filter((value) => value !== flag) };
+}
+
+// `pharo-agent <tool> ...`: the answer's text for a reader, or the MCP result
+// with --json. Its schema is fetched only when the words need reading.
+// The MCP server's own tools manage images; from the shell they are the
+// image commands, which an agent that knows the server may not have read.
+const lifecycleTools = new Set(["image_templates", "image_add", "image_start", "image_list", "image_stop"]);
+
+async function runTool([toolName, ...words]) {
+  if (lifecycleTools.has(toolName)) {
+    throw new Error(`${toolName} is pharo-agent image ${toolName.slice("image_".length)} here.`);
+  }
+  const { image, rest: withoutImage } = takeImageOption(words);
+  const json = takeFlag(withoutImage, "--json");
+  const help = takeFlag(json.rest, "--help");
+  if (help.present) {
+    // Help answers before a project or image exists; only the tool's own
+    // arguments need its image.
+    try {
+      const projectRoot = findProjectRoot();
+      console.log(toolUsage(await toolContract(projectRoot, readRunningImage(projectRoot, image), toolName)));
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.log(`${usage(["<tool>"])}\n\n${toolName}'s own arguments come from a running image: ${reason}`);
+    }
+    return 0;
+  }
+  const projectRoot = findProjectRoot();
+  const running = readRunningImage(projectRoot, image);
+  const argumentsValue = help.rest.length === 0 ? {}
+    : toolArguments(toolName, help.rest, (await toolContract(projectRoot, running, toolName)).inputSchema);
+  const result = await callImageTool(projectRoot, running, toolName, argumentsValue);
+  console.log(json.present ? JSON.stringify(result, null, 2) : resultText(result));
+  return exitCodeForToolResult(result);
+}
+
+async function listTools(words) {
+  const { image, rest: withoutImage } = takeImageOption(words);
+  const json = takeFlag(withoutImage, "--json");
+  requireNoArguments("list", json.rest);
+  const projectRoot = findProjectRoot();
+  const tools = await listAdvertisedTools(projectRoot, readRunningImage(projectRoot, image));
+  console.log(json.present ? JSON.stringify(tools, null, 2) : toolListing(tools));
+}
+
 export async function main(args) {
   const [command, ...rest] = args;
+  // A snake_case word is an image tool; its own --help reads the tool's
+  // schema, and the word help is a value it may take, not a request for
+  // the CLI's usage.
+  if (command && isToolName(command)) {
+    return runTool(args);
+  }
   // A caller reaching for help is asking the same question wherever the word
   // lands, and `image add --help` answering that it needs an image id is no
   // answer at all.
@@ -143,6 +189,10 @@ export async function main(args) {
     await serveImagesMcp(findProjectRoot, mcpImage);
     return;
   }
+  if (command === "list") {
+    await listTools(rest);
+    return;
+  }
   const projectRoot = findProjectRoot();
   if (command === "image") {
     const [subcommand, ...imageArgs] = rest;
@@ -193,29 +243,5 @@ export async function main(args) {
     }
     throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
   }
-  const { image, rest: commandArgs } = takeImageOption(rest);
-  if (command === "pharo") {
-    const [toolName, argumentsJson, ...extra] = commandArgs;
-    if (toolName === "list") {
-      if (argumentsJson || extra.length > 0) throw new Error("pharo list does not accept arguments");
-      console.log(JSON.stringify(
-        await listImageTools(projectRoot, readRunningImage(projectRoot, image)),
-        null,
-        2,
-      ));
-      return;
-    }
-    if (!toolName || extra.length > 0) {
-      throw new Error("pharo requires one tool name and an optional JSON object");
-    }
-    const result = await callImageTool(
-      projectRoot,
-      readRunningImage(projectRoot, image),
-      toolName,
-      parseToolArguments(argumentsJson),
-    );
-    console.log(JSON.stringify(result, null, 2));
-    return exitCodeForToolResult(result);
-  }
   throw new Error(`Unsupported command: ${command}\n${usage()}`);
 }

package/src/gateway.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { PlexusGateway } from "@evref-bl/plexus/gateway";
 import { loadProjectState } from "@evref-bl/plexus";
+import { toolContractFrom } from "./mcpYaml.js";
 import {
   selectRunningImage,
   unappliedPharoMcpPin,
@@ -65,6 +66,38 @@ export async function listImageTools(projectRoot, running) {
   return gateway.refreshPharoTools();
 }
 
+// PLexus adds its routing handle to every schema it lists; a caller never
+// passes it, so the CLI neither offers nor describes it.
+function withoutRouting(tool) {
+  const { required: listed = [], ...schema } = tool.inputSchema ?? {};
+  const properties = { ...(schema.properties ?? {}) };
+  delete properties.mcpServerId;
+  const required = listed.filter((name) => name !== "mcpServerId");
+  return { ...tool, inputSchema: { ...schema, properties, ...(required.length ? { required } : {}) } };
+}
+
+export async function listAdvertisedTools(projectRoot, running) {
+  return (await listImageTools(projectRoot, running)).map(withoutRouting);
+}
+
+/**
+ * A tool's contract: from the advertised list when it is there, otherwise
+ * from tool_get, which reaches the rest of the catalogue.
+ */
+export async function toolContract(projectRoot, running, toolName) {
+  const advertised = (await listAdvertisedTools(projectRoot, running)).find((tool) => tool.name === toolName);
+  if (advertised) return advertised;
+  const answer = /** @type {{ isError?: boolean, content?: { text?: string }[] }} */ (
+    await callImageTool(projectRoot, running, "tool_get", { name: toolName })
+  );
+  const contract = answer?.isError ? undefined
+    : toolContractFrom((answer?.content ?? []).map((part) => part.text ?? "").join("\n"));
+  if (!contract) {
+    throw new Error(`Image ${running.imageId} has no tool ${toolName}. pharo-agent tool_search <words> finds one.`);
+  }
+  return withoutRouting(contract);
+}
+
 export function withImageSelector(tool, defaultImage) {
   const inputSchema = tool.inputSchema ?? {};
   const properties = { ...(inputSchema.properties ?? {}) };

package/src/help.js

@@ -36,7 +36,7 @@ const commands = {
   "image start": {
     usage: "image start [<id>]",
     description: "Create if needed and start an image, the default one without an id. Others keep running.\n"
-      + "On macOS with fuse-t its source mounts as files.",
+      + "On macOS and Linux its source mounts as files, unless PHARO_AGENT_PROJECTION=off.",
     example: "image start dev",
   },
   "image stop": {
@@ -44,26 +44,26 @@ const commands = {
     description: "Stop an image and its source mount, the default one without an id, or --all of them.",
     example: "image stop dev",
   },
+  list: {
+    usage: "list [--image <id>] [--json]",
+    description: "List a running image's advertised tools, one line each. tool_search finds the rest.",
+    example: "list",
+  },
+  "<tool>": {
+    usage: "<tool> [<value>] [--<argument> <value>]... [--image <id>] [--json]",
+    description: "Call an image tool. Its arguments are flags, - reads a value from stdin, and\n"
+      + "<tool> --help lists them. Prints the answer's text, or the MCP result with --json.",
+    example: "class_get Point",
+  },
   mcp: {
     usage: "mcp [--image <id>]",
     description: "Serve this project's images as a stdio MCP server, as the plugin does for a host.",
     example: "mcp --image dev",
   },
-  "pharo list": {
-    usage: "pharo list [--image <id>]",
-    description: "List a running image's advertised tools. tool_search and tool_get find the rest.",
-    example: "pharo list",
-  },
-  pharo: {
-    usage: "pharo <tool> [arguments-json] [--image <id>]",
-    description: "Call a tool in a running image with a JSON object of arguments, {} by default.\n"
-      + "Read its schema with tool_get first.",
-    example: 'pharo tool_get \'{"name":"class_search"}\'',
-  },
 };
 
 export function usage(args = []) {
-  const key = ["image", "pharo"].includes(args[0]) && args[1]
+  const key = args[0] === "image" && args[1]
     ? `${args[0]} ${args[1]}`
     : args[0];
   const command = Object.hasOwn(commands, key) ? commands[key]

package/src/hosts.js

@@ -4,7 +4,9 @@
 export const supportedHosts = [
   { id: "claude", name: "Claude Code", guide: "CLAUDE.md", plugin: true },
   { id: "codex", name: "Codex", guide: "AGENTS.md", plugin: true },
-  { id: "opencode", name: "OpenCode", guide: "AGENTS.md", plugin: false },
+  // No plugin manifest to declare the MCP server in: init writes it into the
+  // project's own configuration, which OpenCode reads for that project only.
+  { id: "opencode", name: "OpenCode", guide: "AGENTS.md", plugin: false, serverConfig: "opencode.json" },
 ];
 
 export const hostIds = supportedHosts.map((host) => host.id);

package/src/images.js

@@ -2,6 +2,7 @@ import { declareProjectImage, removeProjectImage } from "@evref-bl/plexus";
 import { configuredImages } from "./project.js";
 import {
   defaultImageId,
+  notConfigured,
   readConfig,
   readRunningImages,
   recordedImageIsRunning,
@@ -93,7 +94,7 @@ export function addImage(projectRoot, request) {
 
 export function useImage(projectRoot, id) {
   if (!configuredImages(projectRoot).some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is not configured.`);
+    throw notConfigured(projectRoot, id);
   }
   writeConfig(projectRoot, { ...readConfig(projectRoot), defaultImage: id });
   return { defaultImage: id };
@@ -101,7 +102,7 @@ export function useImage(projectRoot, id) {
 
 export function removeImage(projectRoot, id) {
   if (!configuredImages(projectRoot).some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is not configured.`);
+    throw notConfigured(projectRoot, id);
   }
   assertNotRunning(projectRoot, id, "removing it");
   removeProjectImage(projectRoot, id);

package/src/init.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
-import { guideForHost, hostList } from "./hosts.js";
+import { version } from "./gateway.js";
+import { hostList, hostNamed } from "./hosts.js";
 import {
   createProjectConfig,
   enclosingProjectRoot,
@@ -67,6 +68,47 @@ function assertGeneratedGuideCanBeUpdated(filePath) {
   }
 }
 
+// Pinned to the release that wrote the guide, as the setup skill pins its
+// npx command: a host that has no plugin has no pharo-agent on its PATH
+// either. Code mode off, because OpenCode would otherwise hide the tools
+// inside its own execute tool.
+function serverEntry() {
+  return {
+    type: "local",
+    command: ["npx", "--yes", `@evref-bl/pharo-agent@${version}`, "mcp"],
+    enabled: true,
+    codemode: false,
+  };
+}
+
+// Only mcp.pharo is ours. A configuration that may hold comments is not
+// rewritten, since parsing and writing it back would drop them.
+function readServerConfig(projectRoot, fileName) {
+  const filePath = path.join(projectRoot, fileName);
+  const byHand = `add this under "mcp" by hand:\n"pharo": ${JSON.stringify(serverEntry(), null, 2)}`;
+  if (!fs.existsSync(filePath)) {
+    if (fs.existsSync(`${filePath}c`)) {
+      throw new Error(`${filePath}c may hold comments that rewriting it would drop; ${byHand}`);
+    }
+    return { filePath, config: { $schema: "https://opencode.ai/config.json" } };
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    throw new Error(`${filePath} is not plain JSON, so rewriting it would lose what it holds; ${byHand}`);
+  }
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`${filePath} is not a JSON object; ${byHand}`);
+  }
+  return { filePath, config };
+}
+
+function writeServerConfig({ filePath, config }) {
+  const mcp = config.mcp !== null && typeof config.mcp === "object" ? config.mcp : {};
+  fs.writeFileSync(filePath, `${JSON.stringify({ ...config, mcp: { ...mcp, pharo: serverEntry() } }, null, 2)}\n`);
+}
+
 function guidance() {
   return `# Pharo work\n\nWhen the task uses Pharo, read \`pharo.AGENTS.md\` before acting.\n`;
 }
@@ -116,8 +158,8 @@ elsewhere.
 
 ## Images
 
-\`plexus.json\` declares this workspace's images. With the plugin, use the
-\`image_*\` tools; otherwise:
+\`plexus.json\` declares this workspace's images. With the \`pharo\` MCP server,
+use the \`image_*\` tools; otherwise:
 
 \`\`\`sh
 pharo-agent image templates
@@ -133,11 +175,11 @@ session's. Stop an image and remove its declaration when its subject is done.
 
 ## Tools
 
-With the plugin, an image's tools are MCP tools. Otherwise call one with
-\`pharo-agent pharo <tool> [arguments-json] [--image <id>]\`, or serve them
-with \`pharo-agent mcp\`. An image lists its common tools; \`tool_search\` and
-\`tool_get\` find the rest. On macOS with fuse-t, \`image start\` also mounts
-the source under \`.pharo-agent/mounts\`.
+With the \`pharo\` MCP server, an image's tools are MCP tools. Otherwise run
+one as \`pharo-agent <tool> --<argument> <value>\`: \`<tool> --help\` lists its
+arguments, and a value of \`-\` is read from stdin. \`pharo-agent list\` names
+the common tools; \`tool_search\` finds the rest. On macOS and Linux,
+\`image start\` also mounts the source under \`.pharo-agent/mounts\`.
 
 ${pharoRouting()}
 `;
@@ -162,10 +204,11 @@ function resolveInitProjectRoot(cwd) {
 
 /** @param {{ host: string, mountRoot?: string, cwd?: string }} options */
 export function initialize({ host, mountRoot, cwd = process.cwd() }) {
-  const guideName = guideForHost(host);
-  if (!guideName) {
+  const hostEntry = hostNamed(host);
+  if (!hostEntry) {
     throw new Error(`--host must be ${hostList()}`);
   }
+  const guideName = hostEntry.guide;
 
   const { projectRoot, createdProjectConfig } = resolveInitProjectRoot(cwd);
   const directory = pluginDirectory(projectRoot);
@@ -173,6 +216,7 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   const pharoGuidePath = path.join(projectRoot, "pharo.AGENTS.md");
   assertGeneratedGuideCanBeUpdated(pharoGuidePath);
   assertManagedBlockCanBeUpdated(path.join(projectRoot, guideName));
+  const serverConfig = hostEntry.serverConfig && readServerConfig(projectRoot, hostEntry.serverConfig);
   if (createdProjectConfig) {
     createProjectConfig(projectRoot);
   }
@@ -189,6 +233,7 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   copyDirectory(path.join(templates, "pharo-references"), path.join(directory, "references"));
   copyDirectory(path.join(templates, "pharo-skills"), path.join(directory, "skills"));
   updateManagedBlock(path.join(projectRoot, guideName), guidance());
+  if (serverConfig) writeServerConfig(serverConfig);
 
-  return { projectRoot, guideName, createdProjectConfig };
+  return { projectRoot, guideName, createdProjectConfig, ...(serverConfig && { serverConfig: hostEntry.serverConfig }) };
 }

package/src/live.js

@@ -22,47 +22,65 @@ import {
   writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.10.3";
+export const pifsRelease = "v0.11.0";
 
-// fuse-t ships as a macOS installer package, so it lands in /usr/local
-// whatever Homebrew's prefix is. The unversioned symlink is what the daemon
-// links against.
-export const fuseLibraryPath = "/usr/local/lib/libfuse-t.dylib";
+// Set to `off`, no image mounts a source projection, wherever it runs.
+const projectionVariable = "PHARO_AGENT_PROJECTION";
+
+// The systems PIFS releases a daemon for.
+const projectedPlatforms = ["darwin", "linux"];
 
 /**
- * Whether a source projection can be mounted here.
+ * Whether to ask the image for a source projection.
+ *
+ * Whether this machine can mount is the PIFS daemon's to say: macOS needs
+ * nothing, Linux needs fuse3, and the daemon names what is missing. A
+ * projection that fails leaves the image running with that reason as its
+ * warning, so this answers no only where asking is wasted, on a system PIFS
+ * has no daemon for, or forbidden.
  *
- * PIFS needs macOS and fuse-t, which is a kernel-adjacent install the user
- * has to approve. PLexus and the Pharo MCP run anywhere, so until this was
- * checked, `image start` mounted unconditionally and then stopped the image
- * when the mount failed -- every image on Linux and Windows, and on any Mac
- * without fuse-t. The image and its tools were never the part that could not
- * work.
+ * A machine that could mount may still be one that must not, so the
+ * environment can turn projections off before anything is asked.
  *
- * @param {{ platform?: string, exists?: (path: string) => boolean }} [host]
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   platform?: string,
+ * }} [host]
  */
 export function projectionAvailability(host = {}) {
+  const setting = (host.env ?? process.env)[projectionVariable];
   const platform = host.platform ?? process.platform;
-  const exists = host.exists ?? fs.existsSync;
-  if (platform !== "darwin") {
+  if (setting === "off") {
+    return {
+      available: false,
+      reason: `Source projections are turned off by ${projectionVariable}=off.`,
+    };
+  }
+  if (setting) {
+    // Any other value fails safe: an opt-out that ignored a typo, or a 0,
+    // would mount on the very machine that asked not to be mounted on.
     return {
       available: false,
-      reason: "A source projection needs macOS and fuse-t, which this platform"
-        + ` (${platform}) cannot provide.`,
+      reason: `Source projections are off: ${projectionVariable} takes only off,`
+        + ` and is ${JSON.stringify(setting)}. Unset it to mount them where the platform allows.`,
     };
   }
-  if (!exists(fuseLibraryPath)) {
+  if (!projectedPlatforms.includes(platform)) {
     return {
       available: false,
-      reason: "A source projection needs fuse-t, which is not installed."
-        + " Install it with `brew install --cask fuse-t`.",
+      reason: `PIFS mounts source projections on macOS and Linux, not on this platform (${platform}).`,
     };
   }
   return { available: true };
 }
 
+// The daemon's own reasons end without a period.
+function sentence(text) {
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
 export function projectionUnavailableWarning(imageId, reason) {
-  return `${reason} Image ${imageId} is running with its Pharo tools and no`
+  return `${sentence(reason)} Image ${imageId} is running with its Pharo tools and no`
     + " source projection; read and edit its code through the tools.";
 }
 
@@ -73,71 +91,67 @@ export function projectionUnavailableWarning(imageId, reason) {
 export const pifsSelectors = ["startMountedAt:named:", "stopOn:"];
 
 export function pifsStartCode(mountPath, imageName) {
-  return `Metacello new
-	baseline: 'PharoImageFS';
-	repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
-	load: 'Core'.
-((Smalltalk globals at: #PIFSServer)
-	startMountedAt: ${smalltalkString(mountPath)} asFileReference
-	named: ${smalltalkString(imageName)}) port`;
-}
-
-export function pifsStopCode(projectionPort) {
-  return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
+  // A projection that cannot mount answers why, as a string, rather than
+  // failing the evaluation: the reason is the daemon's, and becomes the
+  // warning of an image that keeps running.
+  return `[ Metacello new
+		baseline: 'PharoImageFS';
+		repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
+		load: 'Core'.
+	((Smalltalk globals at: #PIFSServer)
+		startMountedAt: ${smalltalkString(mountPath)} asFileReference
+		named: ${smalltalkString(imageName)}) port ]
+	on: Error
+	do: [ :error | error messageText asString ]`;
 }
 
-// `mount` prints one "<source> on <path> (<options>)" line per mount, with the
-// path resolved, so a project under a symlink is looked for by its real path.
-export function isMountedAt(mountPath, mountTable) {
-  let realPath = mountPath;
-  try {
-    realPath = path.join(fs.realpathSync(path.dirname(mountPath)), path.basename(mountPath));
-  } catch {
-    // No parent directory, so nothing can be mounted there either.
-  }
-  return mountTable
-    .split("\n")
-    .some((line) => line.includes(` on ${mountPath} (`) || line.includes(` on ${realPath} (`));
-}
-
-function currentMountTable() {
-  return spawnSync("mount", [], { encoding: "utf8" }).stdout ?? "";
-}
-
-function unmount(mountPath) {
-  // What PIFSServer>>stopDaemon runs when it stops a projection itself.
-  if (spawnSync("umount", [mountPath], { stdio: "ignore" }).status !== 0) {
-    spawnSync("diskutil", ["unmount", mountPath], { stdio: "ignore" });
-  }
+/**
+ * What a projection start answered: the port serving it, why PIFS could not
+ * mount, or nothing readable.
+ *
+ * @param {string | undefined} printString
+ * @returns {{ port: number } | { reason: string } | undefined}
+ */
+export function projectionStartOutcome(printString) {
+  // The value comes first; MCP appends warnings, the Transcript and a
+  // truncation mark on the lines after it.
+  const text = printString ?? "";
+  const digits = /^(\d+)(?:\n|$)/.exec(text);
+  if (digits && Number(digits[1]) > 0) return { port: Number(digits[1]) };
+  // A string prints quoted, its quotes doubled, and a long one is cut short
+  // of its closing quote, before the truncation mark.
+  const quoted = /^'((?:[^']|'')*)(?:'|$)/.exec(text);
+  if (!quoted) return undefined;
+  const literal = quoted[1].split("\n[truncated")[0].replaceAll("''", "'").trim();
+  return {
+    reason: `${sentence(literal)} Set ${projectionVariable}=off to start images without trying to mount.`,
+  };
 }
 
 /**
- * Unmount a projection whose image is gone.
+ * Unmount the projection of an image that is gone, when nothing else will.
  *
- * The mount is served by a PIFS daemon, a process of its own that reads the
- * source over HTTP from the image. PIFS unmounts it from inside the image when
- * it stops, which an image that crashed or was closed never does: the mount
- * stays, every read in it fails with an I/O error, and it holds the path
- * against the next projection. Unmounting is enough; the daemon exits with its
- * mount.
+ * Records written before this one name no PIFS release: fuse-t's daemon
+ * served their projection, and it outlives its image. A later daemon
+ * unmounts on its own once its image is gone. A path with nothing mounted
+ * just fails to unmount.
  *
- * @param {string | undefined} mountPath
- * @param {{ mountTable?: () => string, unmount?: (path: string) => void }} [host]
- * @returns {boolean} whether something was unmounted
+ * @param {{ mountPath?: string, pifsRelease?: string, [key: string]: unknown } | undefined} record
+ * @param {(mountPath: string) => void} [unmount]
+ * @returns {boolean} whether it tried
  */
-export function releaseProjectionMount(mountPath, host = {}) {
-  const mountTable = host.mountTable ?? currentMountTable;
-  if (mountPath === undefined || !isMountedAt(mountPath, mountTable())) return false;
-  (host.unmount ?? unmount)(mountPath);
-  if (isMountedAt(mountPath, mountTable())) {
-    throw new Error(
-      `The source projection of an image that is gone is still mounted at ${mountPath},`
-        + ` and could not be unmounted. Run umount ${JSON.stringify(mountPath)}, then try again.`,
-    );
-  }
+export function releaseFuseTMount(record, unmount = (mountPath) => {
+  spawnSync("umount", [mountPath], { stdio: "ignore" });
+}) {
+  if (record?.mountPath === undefined || record.pifsRelease !== undefined) return false;
+  unmount(record.mountPath);
   return true;
 }
 
+export function pifsStopCode(projectionPort) {
+  return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
+}
+
 function namedPrintString(value) {
   // Structured results name the print string, somewhere under the envelope,
   // and reach us either as an object or as JSON inside a text part.
@@ -255,16 +269,12 @@ export async function startAgentImage(projectRoot, imageId) {
     // The image this record names has exited. Forget it and start again,
     // rather than hand back an endpoint nothing answers and call it running.
     const { [resolved]: exited, ...remaining } = runningImages;
+    releaseFuseTMount(exited);
     runningImages = remaining;
     writeRunningImages(projectRoot, runningImages);
     restarted = true;
   }
   if (projectionAvailability().available) {
-    // This project has no live image at this mount path now: none was
-    // recorded, or the one recorded has exited. Whatever is still mounted
-    // there was left by an image that is gone, and would hold the path
-    // against the projection about to be mounted.
-    releaseProjectionMount(resolveMountPath(projectRoot, readConfig(projectRoot), resolved));
     fetchPifsRelease(pifsCloneDirectory(projectRoot));
   }
   const launcher = new ScopedPharoLauncher({ projectRoot });
@@ -297,11 +307,24 @@ export async function startAgentImage(projectRoot, imageId) {
     return { ...record, created, warning: pharoMcpWarning(withoutMcp) };
   }
   const unappliedPin = unappliedPharoMcpPin(image);
-  const projection = projectionAvailability();
-  if (!projection.available) {
+  const record = { statePath: started.statePath, imageId: image.id, mcpServerId };
+  const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
+  const availability = projectionAvailability();
+  /** @type {{ port?: number, reason?: string }} */
+  let projection = availability;
+  if (availability.available) {
+    try {
+      projection = await startProjection(projectRoot, record, mountPath, image.imageName);
+    } catch (error) {
+      // Nothing says whether PIFS mounted, so stop the image rather than keep
+      // a mount nothing records: its daemon unmounts once the image is gone.
+      await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
+      throw error;
+    }
+  }
+  if (projection.reason !== undefined) {
     // The image and its tools are the point; the projection is the extra this
-    // package bundles where the platform allows it.
-    const record = { statePath: started.statePath, imageId: image.id, mcpServerId };
+    // package bundles where the machine allows it.
     writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
     return {
       imageId: image.id,
@@ -313,25 +336,11 @@ export async function startAgentImage(projectRoot, imageId) {
       ].filter(Boolean).join("\n"),
     };
   }
-
-  const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
-  fs.mkdirSync(path.dirname(mountPath), { recursive: true });
-  const record = {
-    statePath: started.statePath,
-    imageId: image.id,
-    mcpServerId,
-    mountPath,
-  };
-  let projectionPort;
-  try {
-    projectionPort = await startProjection(projectRoot, record, image.imageName);
-  } catch (error) {
-    // The projection is half-started at best and nothing records it yet, so
-    // stop the image rather than leave an image and a mount nothing owns.
-    await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
-    throw error;
-  }
-  writeRunningImages(projectRoot, { ...runningImages, [resolved]: { ...record, projectionPort } });
+  const projectionPort = projection.port;
+  writeRunningImages(projectRoot, {
+    ...runningImages,
+    [resolved]: { ...record, mountPath, projectionPort, pifsRelease },
+  });
   return {
     imageId: image.id,
     created,
@@ -356,17 +365,16 @@ export function pharoMcpWarning(image) {
     + " drive it with the Pharo command line instead.";
 }
 
-async function startProjection(projectRoot, record, imageName) {
+async function startProjection(projectRoot, record, mountPath, imageName) {
   const result = await callImageTool(projectRoot, record, "image_evaluate", {
-    code: pifsStartCode(record.mountPath, imageName),
+    code: pifsStartCode(mountPath, imageName),
   });
-  const projectionPort = Number(resultPrintString(result));
-  if (!Number.isInteger(projectionPort) || projectionPort < 1) {
-    throw new Error(
-      `PIFS did not report a projection port: ${JSON.stringify(result).slice(0, 500)}`,
-    );
+  // A refusal is PIFS's own: it stopped what it had started.
+  const outcome = projectionStartOutcome(resultPrintString(result));
+  if (!outcome) {
+    throw new Error(`PIFS did not report a projection port: ${JSON.stringify(result).slice(0, 500)}`);
   }
-  return projectionPort;
+  return outcome;
 }
 
 async function stopOneImage(projectRoot, runningImages, imageId) {
@@ -374,19 +382,18 @@ async function stopOneImage(projectRoot, runningImages, imageId) {
   let projectionError;
   // An image started without MCP has no projection to stop, and no route to
   // ask over either.
-  if (record.projectionPort !== undefined) {
+  if (record.projectionPort !== undefined && recordedImageIsRunning(record)) {
     try {
-      if (recordedImageIsRunning(record)) {
-        await callImageTool(projectRoot, record, "image_evaluate", {
-          code: pifsStopCode(record.projectionPort),
-        });
-      } else {
-        // PIFS stops a projection from inside its image, and this one is gone.
-        releaseProjectionMount(record.mountPath);
-      }
+      await callImageTool(projectRoot, record, "image_evaluate", {
+        code: pifsStopCode(record.projectionPort),
+      });
     } catch (error) {
       projectionError = error;
     }
+  } else {
+    // A gone image has no one to ask, and its projection's daemon unmounts
+    // on its own, unless fuse-t's served it.
+    releaseFuseTMount(record);
   }
   const stopped = await runLifecycle(
     () => stopProjectImage({ projectRoot, imageId }),

package/src/mcpServer.js

@@ -75,7 +75,7 @@ const projectTools = [
     name: "image_start",
     description:
       "Start an image, creating it the first time. Its tools are listed once "
-      + "it answers. On macOS with fuse-t its source also mounts as files.",
+      + "it answers. On macOS and Linux its source also mounts as files.",
     inputSchema: {
       type: "object",
       properties: {

package/src/mcpYaml.js

@@ -0,0 +1,102 @@
+// tool_get answers a tool's contract as YAML, written by MCP's MCPYamlWriter,
+// and through PLexus that text is all there is: no structured content. The
+// writer's subset is small and fixed, so it is read here rather than with a
+// YAML library: block mappings indented by two spaces, `{}` and `[]`, flow
+// lists of scalars, block lists whose entries sit at their key's indent, and
+// scalars that are either plain words or JSON (quoted strings, numbers, true,
+// false, null).
+
+function indentOf(line) {
+  return line.length - line.trimStart().length;
+}
+
+function scalar(text) {
+  const value = text.trim();
+  if (value.startsWith("\"")) return JSON.parse(value);
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+function flowList(text) {
+  const inner = text.trim().slice(1, -1);
+  const items = [];
+  let current = "";
+  let quoted = false;
+  for (let index = 0; index < inner.length; index += 1) {
+    const character = inner[index];
+    if (quoted && character === "\\") {
+      current += character + inner[index + 1];
+      index += 1;
+      continue;
+    }
+    if (character === "\"") quoted = !quoted;
+    if (!quoted && character === ",") {
+      items.push(scalar(current));
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  if (current.trim()) items.push(scalar(current));
+  return items;
+}
+
+// A key is a plain word or a JSON string, followed by a colon and then a
+// space or the end of the line.
+const keyPattern = /^("(?:[^"\\]|\\.)*"|[^\s"][^:]*?):(?: (.*))?$/;
+
+function inlineValue(text) {
+  const value = text.trim();
+  if (value === "{}") return {};
+  if (value.startsWith("[")) return flowList(value);
+  return scalar(value);
+}
+
+function parseMapping(lines, start, indent) {
+  const mapping = {};
+  let index = start;
+  while (index < lines.length && indentOf(lines[index]) === indent && !lines[index].trimStart().startsWith("- ")) {
+    const match = keyPattern.exec(lines[index].slice(indent));
+    if (!match) throw new Error(`Unreadable tool contract line: ${lines[index]}`);
+    const key = match[1].startsWith("\"") ? JSON.parse(match[1]) : match[1];
+    index += 1;
+    if (match[2] !== undefined) {
+      mapping[key] = inlineValue(match[2]);
+    } else if (index < lines.length && indentOf(lines[index]) === indent && lines[index].trimStart().startsWith("- ")) {
+      [mapping[key], index] = parseSequence(lines, index, indent);
+    } else {
+      [mapping[key], index] = parseMapping(lines, index, indent + 2);
+    }
+  }
+  return [mapping, index];
+}
+
+function parseSequence(lines, start, indent) {
+  const sequence = [];
+  let index = start;
+  while (index < lines.length && indentOf(lines[index]) === indent && lines[index].trimStart().startsWith("- ")) {
+    const entry = lines[index].slice(indent + 2);
+    if (keyPattern.test(entry)) {
+      const nested = [`${" ".repeat(indent + 2)}${entry}`, ...lines.slice(index + 1)];
+      const [mapping, consumed] = parseMapping(nested, 0, indent + 2);
+      sequence.push(mapping);
+      index += consumed;
+    } else {
+      sequence.push(inlineValue(entry));
+      index += 1;
+    }
+  }
+  return [sequence, index];
+}
+
+/** The contract tool_get answered, or undefined when the text holds none. */
+export function toolContractFrom(text) {
+  const lines = String(text).split("\n");
+  const start = lines.findIndex((line) => line === "tool:");
+  if (start === -1) return undefined;
+  const [contract] = parseMapping(lines, start + 1, 2);
+  return contract;
+}

package/src/runtime.js

@@ -81,10 +81,26 @@ export function defaultImageId(projectRoot) {
   );
 }
 
+/** The error for an image id this project does not declare, naming the ones it does. */
+export function notConfigured(projectRoot, imageId) {
+  const ids = configuredImages(projectRoot).map((image) => image.id);
+  if (ids.length === 0) {
+    return new Error(`Image ${imageId} is not configured, and no image is yet. Declare one with pharo-agent image add.`);
+  }
+  let defaultId;
+  try {
+    defaultId = defaultImageId(projectRoot);
+  } catch {
+    defaultId = undefined;
+  }
+  const named = ids.map((id) => (id === defaultId ? `${id} (the default)` : id)).join(", ");
+  return new Error(`Image ${imageId} is not configured. This project declares ${named}.`);
+}
+
 export function resolveImageId(projectRoot, imageId) {
   if (imageId === undefined) return defaultImageId(projectRoot);
   if (!configuredImages(projectRoot).some((image) => image.id === imageId)) {
-    throw new Error(`Image ${imageId} is not configured.`);
+    throw notConfigured(projectRoot, imageId);
   }
   return imageId;
 }

package/src/toolCommand.js

@@ -0,0 +1,216 @@
+// An image tool called from the shell, the way an agent reaches for it:
+// `pharo-agent class_get Point`, `pharo-agent method_compile --class Point
+// --source - <<'EOF'`. The flags are the tool's own arguments, read from its
+// schema, so a number reaches the image as a number and a boolean flag needs
+// no value. An argument that is itself an object takes JSON as its value.
+import fs from "node:fs";
+
+// The CLI's own options, which no tool argument can shadow.
+export const cliOptions = new Set(["--image", "--json", "--help"]);
+
+/** A word the CLI reads as a tool: every image tool is snake_case. */
+export function isToolName(word) {
+  return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(word);
+}
+
+function kebab(name) {
+  return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function typesOf(property) {
+  return [property?.type].flat().filter(Boolean);
+}
+
+function flagsText(schema) {
+  return Object.keys(schema?.properties ?? {}).map((name) => `--${name}`).join(", ") || "none";
+}
+
+/** The property a bare value fills: the one required, or the only one. */
+export function positionalProperty(schema) {
+  const required = schema?.required ?? [];
+  if (required.length === 1) return required[0];
+  const names = Object.keys(schema?.properties ?? {});
+  return required.length === 0 && names.length === 1 ? names[0] : undefined;
+}
+
+function propertyNamed(flag, schema, toolName) {
+  const properties = schema?.properties ?? {};
+  const name = Object.keys(properties).find((each) => each === flag || kebab(each) === flag);
+  if (!name) {
+    throw new Error(`${toolName} has no argument --${flag}. Its arguments: ${flagsText(schema)}.`);
+  }
+  return name;
+}
+
+function scalar(value, property, name, toolName) {
+  const types = typesOf(property);
+  if (types.includes("integer") || types.includes("number")) {
+    const number = Number(value);
+    if (value.trim() === "" || !Number.isFinite(number)) {
+      throw new Error(`${toolName} --${name} takes a number, not ${JSON.stringify(value)}.`);
+    }
+    return number;
+  }
+  if (types.includes("boolean") && !types.includes("string")) {
+    if (value === "true" || value === "false") return value === "true";
+    throw new Error(`${toolName} --${name} is true or false, not ${JSON.stringify(value)}.`);
+  }
+  if (types.includes("object") && !types.includes("string")) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      throw new Error(`${toolName} --${name} takes a JSON object.`);
+    }
+  }
+  return value;
+}
+
+// An array argument gathers each use of its flag; an argument that takes a
+// string or an array of them, such as method_compile's source, is a string
+// until the flag comes a second time.
+function assign(parsed, name, value, property, toolName) {
+  const types = typesOf(property);
+  if (types.includes("array")) {
+    const item = scalar(value, property.items ?? {}, name, toolName);
+    if (!Object.hasOwn(parsed, name)) {
+      parsed[name] = types.includes("string") ? value : [item];
+    } else {
+      parsed[name] = [parsed[name]].flat().concat(item);
+    }
+    return;
+  }
+  if (Object.hasOwn(parsed, name)) {
+    throw new Error(`${toolName} takes --${name} once.`);
+  }
+  parsed[name] = scalar(value, property, name, toolName);
+}
+
+/**
+ * The tool arguments the words give. `schema` is the tool's input schema;
+ * `readStdin` answers standard input, for a value written as `-`.
+ */
+export function toolArguments(toolName, words, schema, readStdin = () => fs.readFileSync(0, "utf8")) {
+  const properties = schema?.properties ?? {};
+  const flags = {};
+  let stdinUsed = false;
+  const valueOf = (word) => {
+    if (word !== "-") return word;
+    if (stdinUsed) throw new Error(`${toolName} reads one value from stdin, not two.`);
+    stdinUsed = true;
+    return readStdin().replace(/\r?\n$/, "");
+  };
+
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index];
+    if (word.startsWith("--") && word.length > 2) {
+      const [flag, inline] = word.slice(2).split(/=(.*)/s, 2);
+      const negated = flag.startsWith("no-") && !Object.hasOwn(properties, flag)
+        && !Object.keys(properties).some((each) => kebab(each) === flag);
+      const name = propertyNamed(negated ? flag.slice(3) : flag, schema, toolName);
+      const property = properties[name];
+      const types = typesOf(property);
+      if (types.includes("boolean") && !types.includes("string")) {
+        if (inline !== undefined) assign(flags, name, inline, property, toolName);
+        else if (words[index + 1] === "true" || words[index + 1] === "false") {
+          assign(flags, name, words[index + 1], property, toolName);
+          index += 1;
+        } else {
+          assign(flags, name, negated ? "false" : "true", property, toolName);
+        }
+        continue;
+      }
+      if (negated) throw new Error(`${toolName} --${name} is not a boolean, so --no-${flag.slice(3)} means nothing.`);
+      let value = inline;
+      if (value === undefined) {
+        value = words[index + 1];
+        if (value === undefined) throw new Error(`${toolName} --${name} needs a value; - reads it from stdin.`);
+        index += 1;
+      }
+      assign(flags, name, valueOf(value), property, toolName);
+      continue;
+    }
+    const positional = positionalProperty(schema);
+    if (!positional) {
+      throw new Error(`${toolName} takes its arguments as flags: ${flagsText(schema)}.`);
+    }
+    // Bare words for a text argument are one text, as a shell splits
+    // `tool_search repository commit` into two.
+    const types = typesOf(properties[positional]);
+    if (Object.hasOwn(flags, positional) && types.includes("string") && !types.includes("array")) {
+      flags[positional] = `${flags[positional]} ${valueOf(word)}`;
+      continue;
+    }
+    assign(flags, positional, valueOf(word), properties[positional], toolName);
+  }
+  return flags;
+}
+
+/** What a tool answered, as the text it wrote for a reader. */
+export function resultText(result) {
+  const texts = (result?.content ?? [])
+    .filter((part) => part?.type === "text" && typeof part.text === "string")
+    .map((part) => part.text);
+  if (texts.length > 0) return texts.join("\n");
+  return JSON.stringify(result?.structuredContent ?? result ?? {}, null, 2);
+}
+
+function firstLine(text) {
+  return String(text ?? "").split("\n", 1)[0].trim();
+}
+
+// What a list has room for: the first sentence, which every tool's
+// description opens with what it does.
+function firstSentence(text) {
+  const line = firstLine(text);
+  const end = line.search(/\.(\s|$)/);
+  return end === -1 ? line : line.slice(0, end + 1);
+}
+
+/** One line per tool, then where the rest of the catalogue is. */
+export function toolListing(tools) {
+  const width = Math.max(0, ...tools.map((tool) => tool.name.length));
+  return [
+    ...tools.map((tool) => `${tool.name.padEnd(width)}  ${firstSentence(tool.description)}`),
+    "",
+    "These are the advertised tools. pharo-agent tool_search <words> finds the rest;",
+    "pharo-agent <tool> --help shows a tool's arguments.",
+  ].join("\n");
+}
+
+function typeText(property) {
+  const types = typesOf(property);
+  if (types.includes("array")) {
+    return `<${typesOf(property.items).join("|") || "value"}>, repeatable`;
+  }
+  if (types.includes("boolean")) return "";
+  return `<${types.join("|") || "value"}>`;
+}
+
+/** A tool's own usage, from its schema. */
+export function toolUsage(tool) {
+  const schema = tool.inputSchema ?? {};
+  const required = new Set(schema.required ?? []);
+  const positional = positionalProperty(schema);
+  const entries = Object.entries(schema.properties ?? {}).map(([name, property]) => {
+    const head = [`--${name}`, typeText(property), required.has(name) ? "(required)" : ""]
+      .filter(Boolean).join(" ");
+    return { head, description: firstLine(property.description) };
+  });
+  const width = Math.max(0, ...entries.map((entry) => entry.head.length));
+  const usageLine = `pharo-agent ${tool.name}${positional ? ` [<${positional}>]` : ""}`
+    + `${entries.length ? " [--<argument> <value>]..." : ""} [--image <id>] [--json]`;
+  return [
+    "Usage:",
+    `  ${usageLine}`,
+    "",
+    firstLine(tool.description) ? String(tool.description).trim() : "",
+    ...(entries.length ? ["", "Arguments:", ...entries.map((entry) => `  ${entry.head.padEnd(width)}  ${entry.description}`)] : []),
+    "",
+    [
+      positional ? `A bare value is --${positional}.` : "",
+      Object.values(schema.properties ?? {}).some((property) => typesOf(property).includes("boolean"))
+        ? "A flag without a type is true alone, false as --no-<flag>." : "",
+      "A value of - is read from stdin. --json prints the MCP result.",
+    ].filter(Boolean).join(" "),
+  ].join("\n");
+}