Toolkit Discovery

A toolkit is a workbook tagged :toolkit:. The runtime discovers toolkits by querying for all workbooks in scope with that tag using OQL.parse_headlines, then reading their :PROPERTIES: drawers to build the manifest.

What is a toolkit

A toolkit is a .org file that describes a CLI tool (or set of tools) the agent loop can invoke via the shell tool. The :toolkit: tag on the top heading signals that this workbook is not just a document — it is an executable interface.

Toolkits are CLIs on PATH plus skill files (Org documents that describe the CLI's subcommands and expected outputs). Agents discover them, read the skill files, and call the CLIs. No new ToolRegistry entries, no special agent APIs — just shell calls.

Manifest properties

The top-level heading of a toolkit carries all discovery metadata in its :PROPERTIES: drawer:

Property	Required	Description
`EXEC`	yes	Path or name of the CLI binary to invoke
`BUILD_SRC`	no	Source file or directory to compile this toolkit
`BUILD_LANG`	no	Language of `BUILD_SRC` (e.g. `rust`, `zig`)
`CAPS`	no	Space-separated capability tags (e.g. `read write network`)
`CLI_BIN`	no	Explicit binary name on PATH (if different from `EXEC`)
`ARG_MODE`	no	`positional` or `flags` (default: `positional`)
`SHA256`	no	Expected SHA-256 of the compiled binary (integrity check)

Example:

* My Toolkit :toolkit:
  :PROPERTIES:
  :EXEC:      my-tool
  :CAPS:      read network
  :CLI_BIN:   my-tool
  :ARG_MODE:  flags
  :END:

** Usage
   Describe subcommands here. Agents read this section to know how to call the tool.

Discovery flow

Workbooks.Toolkits (runtime/host/toolkits.ex) calls OQL.parse_headlines on all .org files in the toolkit search path.
Headings with :toolkit: in their tags are collected.
Their :PROPERTIES: drawers are read to build Manifest structs.
wb toolkit list shows the discovered manifests.
Agents receive the manifest list at session start and use it to decide which CLIs are available.

Security model

Toolkits are read-only by default. The manifests are loaded and inspected, but the EXEC binary is not run unless WB_TOOLKIT_EXEC=1 is set in the environment. This prevents accidental or malicious toolkit execution when the runtime is in inspection mode.

WB_TOOLKIT_EXEC=1 wb run "use my-tool to process data.org"

SHA256 integrity checking: if SHA256 is set in the manifest, the runtime verifies the compiled binary against it before execution. A mismatch causes the toolkit to be marked as unavailable.

Toolkit search path

By default the runtime searches:

./toolkits/ — local toolkits in the current workdir
~/.workbooks/toolkits/ — user-level toolkits
Any paths in WB_TOOLKIT_PATH (colon-separated)

Listing and inspecting toolkits

wb toolkit list          # all discovered toolkits
wb toolkit show my-tool  # detail for a specific toolkit
wb toolkit install <url> # clone a toolkit from a git URL

wb toolkit show prints the full manifest including CAPS, EXEC, and the skill text the agent would read.

Progressive disclosure

Toolkits that follow the progressive-disclosure pattern expose subcommands as level-2 headings in the toolkit .org file. Each heading describes a subcommand, its args, and its expected output format. Agents read the heading content to understand how to call the tool without needing to parse --help output.

* my-tool :toolkit:
  :PROPERTIES:
  :EXEC: my-tool
  :END:

** process <file>
   Processes an org file. Outputs JSON to stdout.

   Expected output:
   #+begin_src json
   {"status": "ok", "records": [...]}

#+end_src