External tools

Add extra catalog tools as tool sets: one directory, one tools.json, one runner.

~/.crystal/tools/<directory>/tools.json
<workspace>/.crystal/tools/<directory>/tools.json

A project directory of the same name replaces the home set. "enabled": false in tools.json leaves the directory in place and does not load it (default true). "externalTools": false in config.json skips discovery. When true, the field is omitted from the written file, same as skills.

The set identity is the directory name: 1–64 characters, a letter, then letters, digits, _, ., or -. There is no JSON name or id. The model-facing name is tools[].name (exec) or ITool.Definition.Name (dotnet). Built-in names win. Default catalogs is Plan and Work. "catalogs": ["work"] is Work only.

Runner	Behavior
exec	ProcessStartInfo.ArgumentList. No shell template. Stdin is the fenced arguments object (default on). An argv map turns scalar properties into flags. Working directory is the workspace root.
dotnet	A framework-dependent library that implements Crystal.Tools.ITool or Crystal.Multimodal.Tools.IMultimodalTool. Public non-abstract tools load in one isolated context for that set.

Each exec child receives CRYSTAL_WORKSPACE, CRYSTAL_SESSION, CRYSTAL_APPROVAL, CRYSTAL_TOOL_DATA (global data directory), and CRYSTAL_PROJECT_DATA (project data directory). "output": "content" makes stdout JSON with text and optional images (base64 or a workspace path). Text-only turns reject image results. Image-capable turns attach them through the same marker path as other tools.

A dotnet tool that implements CrystalCode.Tools.IHostTool or IHostMultimodalTool receives a ToolHostContext on each call: workspace root, session id, approval mode, and the set’s global and project data directories. Tools that do not implement those interfaces are unchanged. Shared types are Crystal, Crystal.Tools, and CrystalCode.Tools. Other dependencies stay private to the set.

Every external tool is at least Write + Workspace and still goes through ToolInvocationPolicy. Authors may set approval to always. Home tools follow that declaration by default. Project tools use host policy unless configured otherwise.

A dotnet tool may implement IHostToolApprovalClassifier when write paths are inside arguments. The host merges that result with its own classification. The result can only raise risk or authority. Failures fail closed. Classification has its own two-second budget and can be cancelled. A timed-out or cancelled classifier stays disabled until tools reload. The host writes the summary. It does not use the tool’s wording.

Command	Effect
/tools	Lists the effective catalog and approval, and marks tools that supply a classifier
/tools home|project author|host	Changes source trust
/tools on|off|reload	Controls discovery
/tools enable|disable|show <directory>	Changes one tool set
crystal tools list|show|enable|disable	Same outside a session. Spectre.Console table unless --format text

Full auto-passes a workspace-bounded external write. Edit does not. Manifest fields and the dotnet publish layout are in External tools.