# tools ## Catalog discovery - `brigade tools init` writes gitignored `.brigade/tools.toml` with local examples for portable slash commands and superpowers. - `brigade tools list`, `show `, and `search ` inspect logical tool entries across source families such as `skill`, `slash-command`, `superpower`, `mcp`, `openapi`, `graphql`, `script`, and `custom`. - `brigade tools describe ` and `brigade tools contracts` inspect schema-backed call contracts, permissions, effects, approval mode, env labels, and argument templates. ```bash brigade tools init brigade tools list brigade tools show simplify brigade tools search simplify brigade tools describe simplify brigade tools contracts ``` ## Call planning and approval - `brigade tools call plan --args ...` validates local JSON args against the configured input schema and returns a redacted wrapper-friendly call plan without executing the tool. - `brigade tools call queue/list/show/approve/reject/hold` stores planned calls in `.brigade/tools/calls.jsonl` for local review. Approval changes status only and never executes a tool. - `brigade tools call run ` and `brigade tools call run --next` execute approved, unblocked local `script` calls and approved local `mcp` calls, then write local receipts and stdout/stderr logs under `.brigade/tools/runs/`. ```bash brigade tools call plan simplify --args '{"path":"README.md"}' brigade tools call queue simplify --args '{"path":"README.md"}' brigade tools call list brigade tools call show brigade tools call approve brigade tools call reject --reason "not needed" brigade tools call hold --reason "needs review" brigade tools call run brigade tools call run --next ``` ## Run history and checkpoints - `brigade tools run list/show/latest` inspects local execution receipts, and `brigade tools run replay ` creates a new pending reviewed replay candidate after revalidating current contract, source, runtime, and policy state. Replay never reruns directly. - `brigade tools checkpoint list/show/approve/reject/resume` reviews script-requested local checkpoints under `.brigade/tools/checkpoints/`; resume requires explicit checkpoint approval and revalidates runtime and policy gates. ```bash brigade tools run list brigade tools run show brigade tools run latest brigade tools run replay brigade tools checkpoint list brigade tools checkpoint show brigade tools checkpoint approve --choice continue brigade tools checkpoint reject --reason "not safe" brigade tools checkpoint resume ``` ## Runtimes and policy - `brigade tools runtime init/list/show/status/start/stop/restart/doctor` manages explicit local runtimes used by portable tool calls, writing PID files and logs under `.brigade/tools/runtime/`. - `brigade tools policy init/show/doctor` manages host-local execution policy, including allowed effects, timeout caps, runtime allow-lists, approval modes, and environment label bindings. ```bash brigade tools runtime init brigade tools runtime list brigade tools runtime status brigade tools runtime start brigade tools runtime stop brigade tools runtime doctor brigade tools policy init brigade tools policy show brigade tools policy doctor ``` ## Projections, apply, and doctor - `brigade tools plan` previews exact projection creates, updates, skips, unmanaged conflicts, and local-edit conflicts for all configured harness targets. - `brigade tools apply ` and `brigade tools apply --all` explicitly write managed harness projections. Use `--dry-run` to preview writes and `--force` only to overwrite unmanaged or locally edited projection files. - `brigade tools doctor` reports missing sources, manifests, schemas, invalid contracts, missing examples, bad argument templates, projections, unmanaged projections, locally edited managed projections, stale projection fingerprints, MCP config issues, stale health files, unsafe auth/env field names, and high-risk command shapes. - `brigade tools import-issues` turns catalog health issues into local `tool-catalog` work imports with stable fingerprints and dismiss-until-changed behavior. Built-in tool projections from quickstart and `brigade tools defaults` are scoped to the workspace's selected harnesses plus the neutral `scripts/` folder, so a `--harnesses codex` setup does not get folders for every supported harness. The managed `.gitignore` block written by `tools defaults`, `tools init`, and `tools pack import` covers the handoff-inbox entries for every selected harness. ```bash brigade tools plan brigade tools plan simplify brigade tools apply simplify --dry-run brigade tools apply simplify brigade tools apply --all brigade tools doctor brigade tools import-issues ``` ## Projection parity and sync - `brigade tools parity status` reports projection-parity closeout state, and `brigade tools parity closeout` reviews current projection parity issues. Use `--reason` to record a review or defer reason and `--defer` to mark issues deferred instead of reviewed. - `brigade tools sync plan` plans reviewed add-only projection sync without writing, and `brigade tools sync apply` applies it. Use `--write` to write reviewed add-only projections, `--all` to apply all configured tool projections, `--dry-run` to plan writes without changing files, and `--force` to allow intentional overwrites through managed apply. ```bash brigade tools parity status brigade tools parity closeout --reason "reviewed" brigade tools parity closeout --defer --reason "later" brigade tools sync plan brigade tools sync apply --write brigade tools sync apply --all --write brigade tools sync apply --dry-run ``` Tool catalog inspection, call planning, call approval review, run history inspection, and checkpoint review are non-executing, and projection writes are always explicit through `brigade tools apply`. Tool call execution is explicit through `brigade tools call run`, limited to approved local `script` entries and approved local `mcp` entries with already-running managed runtimes. Brigade does not connect to remote MCP servers, fetch OpenAPI or GraphQL schemas, store auth, install schedulers, send approval notifications, or auto-sync harness configs. Keep tokens, secrets, private URLs, and host-private paths out of public catalog templates.