# tools

Use this to keep one reviewed catalog of the tools your agents can call, with approval before anything runs.

## Catalog discovery

- `brigadestack tools init` writes gitignored `.brigade/tools.toml` with local examples for portable slash commands and superpowers.
- `brigadestack tools list`, `show <tool-id>`, and `search <query>` inspect logical tool entries across source families such as `skill`, `slash-command`, `superpower`, `mcp`, `openapi`, `graphql`, `script`, and `custom`.
- `brigadestack tools describe <tool-id>` and `brigadestack tools contracts` inspect schema-backed call contracts, permissions, effects, approval mode, env labels, and argument templates.

```bash
brigadestack tools init
brigadestack tools list
brigadestack tools show simplify
brigadestack tools search simplify
brigadestack tools describe simplify
brigadestack tools contracts
```

## Call planning and approval

- `brigadestack tools call plan <tool-id> --args ...` validates local JSON args against the configured input schema and returns a redacted wrapper-friendly call plan without executing the tool.
- `brigadestack 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.
- `brigadestack tools call run <call-id>` and `brigadestack 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
brigadestack tools call plan simplify --args '{"path":"README.md"}'
brigadestack tools call queue simplify --args '{"path":"README.md"}'
brigadestack tools call list
brigadestack tools call show <call-id>
brigadestack tools call approve <call-id>
brigadestack tools call reject <call-id> --reason "not needed"
brigadestack tools call hold <call-id> --reason "needs review"
brigadestack tools call run <call-id>
brigadestack tools call run --next
```

## Run history and checkpoints

- `brigadestack tools run list/show/latest` inspects local execution receipts, and `brigadestack tools run replay <run-id>` creates a new pending reviewed replay candidate after revalidating current contract, source, runtime, and policy state. Replay never reruns directly.
- `brigadestack 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
brigadestack tools run list
brigadestack tools run show <run-id>
brigadestack tools run latest
brigadestack tools run replay <run-id>
brigadestack tools checkpoint list
brigadestack tools checkpoint show <checkpoint-id>
brigadestack tools checkpoint approve <checkpoint-id> --choice continue
brigadestack tools checkpoint reject <checkpoint-id> --reason "not safe"
brigadestack tools checkpoint resume <checkpoint-id>
```

## Runtimes and policy

- `brigadestack 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/`.
- `brigadestack 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
brigadestack tools runtime init
brigadestack tools runtime list
brigadestack tools runtime status
brigadestack tools runtime start <runtime-id>
brigadestack tools runtime stop <runtime-id>
brigadestack tools runtime doctor
brigadestack tools policy init
brigadestack tools policy show
brigadestack tools policy doctor
```

## Projections, apply, and doctor

- `brigadestack tools plan` previews exact projection creates, updates, skips, unmanaged conflicts, and local-edit conflicts for all configured agent tool targets.
- `brigadestack tools apply <tool-id>` and `brigadestack tools apply --all` explicitly write managed agent tool projections. Use `--dry-run` to preview writes and `--force` only to overwrite unmanaged or locally edited projection files.
- `brigadestack 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.
- `brigadestack 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 `brigadestack tools defaults` are scoped to the workspace's selected agent tools plus the neutral `scripts/` folder, so a `--harnesses codex` setup does not get folders for every supported agent tool. The managed `.gitignore` block written by `tools defaults`, `tools init`, and `tools pack import` covers the handoff-inbox entries for every selected agent tool.

```bash
brigadestack tools plan
brigadestack tools plan simplify
brigadestack tools apply simplify --dry-run
brigadestack tools apply simplify
brigadestack tools apply --all
brigadestack tools doctor
brigadestack tools import-issues
```

## Projection parity and sync

- `brigadestack tools parity status` reports projection-parity closeout state, and `brigadestack 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.
- `brigadestack tools sync plan` plans reviewed add-only projection sync without writing, and `brigadestack 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
brigadestack tools parity status
brigadestack tools parity closeout --reason "reviewed"
brigadestack tools parity closeout --defer --reason "later"
brigadestack tools sync plan
brigadestack tools sync apply --write
brigadestack tools sync apply --all --write
brigadestack tools sync apply --dry-run
```

`brigadestack tools apply` writes projections. `brigadestack tools call run` executes approved local `script` entries and approved local `mcp` entries with already-running managed runtimes. BrigadeStack does not connect to remote MCP servers, fetch OpenAPI or GraphQL schemas, store auth, or send approval notifications. Keep tokens, secrets, private URLs, and host-private paths out of public catalog templates.