Built-in tools

artifactize ships a set of tools written in Rust that behave the same on Linux, macOS and Windows, except for how a path’s spelling on disk is checked (see Paths). Declare one by name with builtin instead of writing a script or calling an OS program such as cat or xdg-open. Built-in tools run inside artifactize, so they do not need the artifactize-tools command on PATH; that command and artifactize tools offer the filesystem/program tools to scripts and runtime evals. The project-aware graph tool is available only as a declared review tool in artifactize, not in the standalone tools CLI.

[views.agent_tools]
read = { builtin = "read" }                                       # the model picks the path
grep = { builtin = "grep" }
style = { builtin = "read", args = ["DEV-CODING.md"] }                 # one fixed file
spec = { builtin = "section", args = ["spec.md"] }                # the model passes only the heading
install = { builtin = "section", args = ["spec.md", "Install"] }  # one fixed section
reqs = { builtin = "read", args = ["reqs/requirements.md"] }      # in the child folder reqs
structure = { builtin = "graph", args = [] }                    # current project entity tree
cargo_help = { builtin = "help", args = ["cargo", "build"] }      # cargo build --help

[views.human_tools]
open = { builtin = "open", args = ["{artifactPath}/notes.md"] }   # kind = "launch"
viewer = { builtin = "graph", kind = "launch", args = [] }       # existing desktop graph view
docs = { builtin = "open", args = ["https://artifactize.dev/docs/"] }
notes = { builtin = "read", args = ["notes.md"] }                 # kind = "output"
summary = { builtin = "section", args = ["{reqs}/requirements.md", "Summary"] }

A built-in declaration takes builtin, args (optional for the Agent tools that take model input) and an optional description; each tool has a default description. A Human built-in may also name its kind, which must match the tool (open and graph launch, every other tool prints output) or config check rejects it. Built-ins take no timeout_ms, command, protocol or input_schema. The reviewer sees each tool as <name>_<artifactId>, as with command tools.

Tools

Without args, an Agent tool takes the model’s input; the input, result and limits of read, list, glob, grep and view_image are in Agent tools. Fixed args remove the model input, except section with one argument. Fixed Agent list returns a structured JSON content block; fixed read, section and help return text blocks:

• read prints a UTF-8 file, at most 64 KiB; a longer file ends with [output truncated]. It validates only the bounded prefix it inspects: NUL or invalid UTF-8 there is refused, but such bytes later in a truncated file may go undetected. The CLI fixed read has the same limit.
• list prints one page of the folder’s sorted entries as JSON, like the model’s list.
• section prints one section of a Markdown file. It finds the first heading whose text equals heading exactly, at any level (# or underlined headings; headings inside code blocks do not count). The section runs from that heading to the next heading of the same or a higher level, so nested sections are included. When no heading matches, the error lists the headings the file has. The file may be up to 8 MiB; the printed section, up to 64 KiB.
• help runs program subcommand... --help and prints its output. The program is a literal program or path. Bare names use PATH (with PATHEXT on Windows). Unlike scoped command-tool executables, help uses ordinary program lookup: absolute paths, parent-relative paths and executable symlinks are accepted. Relative paths start at the declaring Artifact’s folder; subcommand arguments are forwarded unchanged, without scope resolution. The program runs in that folder with empty stdin and gets no private output or temporary directories. For an Agent, it runs in the author’s environment minus every ARTIFACTIZE_* variable (matched ignoring case). For a Human, it runs in the reviewer’s whole environment, ARTIFACTIZE_* variables included, such as an ARTIFACTIZE_REMOTE_TOKEN credential. It must finish within 10 seconds, exit 0 and print at most 64 KiB, stdout and stderr together. It runs a real program, so name only programs you trust.
• open (Human only) opens one file, folder or http:///https:// URL in the desktop’s default application: xdg-open on Linux and WSL, open on macOS, the Windows shell (ShellExecute) on Windows. The target is passed as one argument, never through a shell. Other URL schemes, such as file: or mailto:, are refused. The result only records that the application was started; the application belongs to the reviewer and keeps running. On Linux, WSL and macOS, the opener itself must exit successfully within three seconds: an unavailable opener, timeout or nonzero opener exit is a tool error. This acknowledgement deadline is not a lifetime limit on the opened application.

view_image

view_image is an Agent-only tool with required model input {"path":"board.png"}. The path is a logical path inside its admitted Artifact scope, with the usual no-traversal and no-symlink checks. It reads a nonempty regular file and returns an embedded image block (type, base64 data, mimeType), not a printed filename.

Detection checks signatures and container framing, not the extension; it does not decode pixels or fully validate image contents. Supported signatures are PNG, JPEG and WebP; unsupported signatures, GIF/BMP and animated PNG are refused. The image-file bytes must be at most 4 MiB inclusive after any base64 decoding, not a bound on decoded pixel memory. The image-result contract explains normalization and the same MIME/size checks for command tools; only those command tools can name files in their private output directory.

Current project graph

Declare builtin = "graph", args = [] on any Artifact; no graph Artifact is required. It always reads the entire current project’s declarations, not the selected review’s historical Run or only its scope. It does not read source contents, start an eval or add dependencies. The two audience-specific tools use exactly the extraction that produces the graph fingerprint:

• Agent: no model input ({} only). Prints a name-based, cycle-safe tree of Artifacts and their evals, the complete extracted definitions/evaluation criteria, the graph fingerprint, and labeled arrows from input to consumer.
• Human: kind = "launch". Starts artifactize-desktop graph --repo PATH using the normal detached application handoff. artifactize-desktop must be installed and discoverable through the program search path. The viewer reuses the monitor’s existing graph renderer and keyboard/zoom interactions, but shows current declarations rather than Run verdicts. Expand Structure and evaluation criteria for the same complete text tree as the Agent sees; Refresh or Ctrl+R/F5 reloads declarations. This works before any Run exists. The tool returns a launch acknowledgement, not an approval; the viewer keeps running when the calling tool finishes.

Paths in args

Filesystem targets must stay inside the scope admitted to the actual review:

• Fixed Agent tools use logical paths relative to the declaring Artifact, which may lead into a child folder (reqs/requirements.md). Discovery and config check validate these targets against that Artifact’s child scope, rejecting missing or out-of-scope targets. Calls check them again.
• Human tools accept the same logical paths, and also {artifactPath} or {artifactPath}/path and {name} or {name}/path, where name is an Artifact, as in Human tools. A --flag= prefix is not accepted. Discovery and config check validate reference names and target existence against the workspace, not the narrower review scope. An existing {other}/file can therefore pass configuration validation without being a child. Preflight and calls require that other is admitted to the actual Human eval scope, so the eval references {other} itself; an Artifact-only tool check uses just that Artifact’s child scope. Tool operands never add dependencies or expand that scope.

Filesystem targets refuse absolute paths, .., symlinks and special files at configuration validation and on every call. open additionally accepts HTTP(S) URLs. help takes a literal program or path plus subcommand arguments, without placeholders; those are program arguments, not filesystem targets for these scope checks.

Reuse

Tool declarations, including a built-in’s name and args, are not part of the reuse key: a tool is a way of viewing an Artifact. Changing a tool reuses earlier verdicts, and a new artifactize release that changes how a built-in behaves does too. To review again when the file a tool reads changes, cover that file in the fingerprint; the default artifactsum covers the Artifact’s own files.

artifactize-tools CLI

artifactize tools exposes the same current-directory tools on every install, including the Microsoft Store package. Non-Store channels also put artifactize-tools next to artifactize; either spelling uses the same parser and runner, output and exit codes, including artifactize tools --version. The existing artifactize tools check checks declared review tools rather than running a current-directory tool.

For runtime evals, fingerprint scripts and your own scripts:

artifactize tools read DEV-CODING.md             # also: artifactize-tools read DEV-CODING.md
artifactize-tools list [PATH]
artifactize-tools glob PATTERN [PATH]
artifactize-tools grep [--glob GLOB] [--case-insensitive] PATTERN [PATH]
artifactize-tools section spec.md "Install"
artifactize-tools help cargo build          # cargo build --help
artifactize-tools open notes.md             # or an http(s) URL

There is no Artifact scope outside a review, so the current directory is the scope. Filesystem targets for read/list/glob/grep/section/open must be relative and stay below it; . names the directory itself and is the default for list/glob/grep. Absolute targets, .. and symlinks are refused, even when a link points inside. This is not a restriction on help’s literal executable or subcommand arguments: its ordinary lookup accepts absolute/parent paths and executable symlinks as explained above. Only open accepts a URL, and only http:// or https://.

read, section and help print text with the limits above; list, glob and grep print the JSON result of the Agent tool. From the command line, help runs the program with your terminal’s environment minus every ARTIFACTIZE_* variable, and with no private temporary or output directory. A tool error goes to stderr with exit 1; invalid usage exits 2. artifactize-tools --help and artifactize-tools SUBCOMMAND --help describe each subcommand. The facade uses artifactize tools --help and artifactize tools SUBCOMMAND --help. artifactize tools help PROGRAM SUBCOMMAND... is the built-in help tool, not clap’s help-navigation command.