# Tool catalog

`brigadestack tools` keeps one catalog of the callable tools, slash commands, skills, superpowers, scripts, and MCP configs your agent tools use. It inspects local files, reports health, writes projection files for each agent tool, and supervises local runtimes for approved script and MCP calls. It does not connect to remote MCP servers, fetch schemas, store auth, or install schedulers. An approved MCP call runs the configured local stdio command for that one call. (Runtime MCP server configs are managed by `brigadestack mcp`.)

The local config is gitignored:

```text
.brigade/tools.toml
```

Create it with:

```bash
brigadestack tools init
```

`brigadestack tools defaults` merges BrigadeStack's built-in portable tools (`simplify`, `superpowers`, `frontend`, `antislop`) into an existing catalog.

## Commands

```bash
brigadestack tools defaults
brigadestack tools list
brigadestack tools list --json
brigadestack tools show simplify
brigadestack tools search simplify
brigadestack tools describe simplify
brigadestack tools contracts
brigadestack tools call plan simplify --args '{"path":"README.md"}'
brigadestack tools call plan simplify --args-json args.json
brigadestack tools call queue simplify --args '{"path":"README.md"}'
brigadestack tools call queue simplify --args-json args.json
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
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>
brigadestack tools runtime init
brigadestack tools runtime list
brigadestack tools runtime show <runtime-id>
brigadestack tools runtime status
brigadestack tools runtime start <runtime-id>
brigadestack tools runtime stop <runtime-id>
brigadestack tools runtime restart <runtime-id>
brigadestack tools runtime doctor
brigadestack tools policy init
brigadestack tools policy show
brigadestack tools policy doctor
brigadestack tools plan
brigadestack tools plan simplify
brigadestack tools apply simplify --dry-run
brigadestack tools apply simplify
brigadestack tools apply --all
brigadestack tools sync plan
brigadestack tools sync apply
brigadestack tools parity status
brigadestack tools parity closeout
brigadestack tools pack build
brigadestack tools pack list
brigadestack tools pack show <pack-id>
brigadestack tools pack import <pack-id>
brigadestack tools pack archive <pack-id>
brigadestack tools doctor
brigadestack tools doctor --json
brigadestack tools import-issues
```

`defaults` merges BrigadeStack's built-in portable tools into the local catalog. `list`, `show`, and `search` inspect configured entries. `describe` and `contracts` inspect schema-backed call contracts. `call plan` validates arguments and returns a safe call plan without executing anything. `call queue` stores a plan for local review, and `call approve`, `reject`, and `hold` update review status only. `call run` executes approved script and MCP calls and writes local receipts. `run list`, `show`, and `latest` inspect receipts, and `run replay` queues a pending replay candidate without executing it. `checkpoint` commands review and resume local pause records. `runtime` commands manage local runtimes. `policy` commands inspect host-local execution gates and env label bindings. `plan` previews projection writes without touching files. `apply` writes projections and requires either one tool id or `--all`. `sync plan` and `sync apply` plan and apply a reviewed projection sync. `parity status` and `parity closeout` inspect and close out projection parity issues. `pack` builds and inspects local portable tool packs. `doctor` reports catalog health issues. `import-issues` writes those issues into the normal work import inbox as `tool-catalog` task imports with stable source fingerprints.

## Config Shape

Each logical tool is a TOML table:

```toml
[[tool]]
id = "simplify"
name = "Simplify"
family = "slash-command"
enabled = true
description = "Portable simplify command."
source_path = "tools/simplify.md"
manifest_path = "tools/simplify.manifest.json"
schema_path = "tools/simplify.schema.json"
command = "brigadestack tools show simplify"
auth_label = "local-user"
timeout = 30
input_schema_path = "tools/simplify.input.schema.json"
output_schema_path = "tools/simplify.output.schema.json"
examples_path = "tools/simplify.examples.json"
permissions = ["read-files"]
effects = ["local-read"]
approval_mode = "on-request"
cwd = "."
env_labels = ["SAFE_ENV"]
argument_template = { path = "{path}", mode = "--mode={mode}" }
runtime_id = "local-helper"
requires_runtime = false
runtime_health_path = ".brigade/tools/runtime/local-helper.json"
supported_harnesses = ["claude", "codex", "opencode"]
projections = { claude = ".claude/commands/simplify.md", codex = ".codex/skills/simplify/SKILL.md" }
health_path = ".brigade/tools/simplify-health.json"
fingerprint = "source-fingerprint"
```

Fields:

- `id`: stable logical tool id.
- `name`: display name.
- `family`: one of `skill`, `slash-command`, `superpower`, `mcp`, `openapi`, `graphql`, `script`, or `custom`.
- `enabled`: true or false.
- `description`: safe short description for humans and wrappers.
- `source_path`: local source file for the portable entry.
- `manifest_path`: optional local manifest path.
- `schema_path`: optional local JSON schema or tool schema path.
- `command`: optional command label. Required for `script` and `custom` entries.
- `auth_label`: safe label only, such as `local-user` or `github-readonly`.
- `timeout`: expected timeout in seconds.
- `input_schema_path`: optional JSON Schema path for call arguments. Required for `call plan`.
- `output_schema_path`: optional JSON Schema path for wrapper output expectations.
- `examples_path`: optional local examples file.
- `permissions`: safe labels for needed capabilities.
- `effects`: safe labels for expected effects such as `local-read`.
- `approval_mode`: `never`, `on-request`, or `always`.
- `cwd`: optional local working directory label or relative path.
- `env_labels`: safe environment labels only, never values.
- `argument_template`: table of call-plan argument names to template strings such as `{path}`.
- `runtime_id`: optional id of a local runtime from `.brigade/tools/runtimes.toml`.
- `requires_runtime`: true when `call run` must refuse execution unless that runtime is running and healthy.
- `runtime_health_path`: optional local runtime health file label or path.
- `supported_harnesses`: configured agent tools that should have projections.
- `projections`: per-agent-tool projection target paths.
- `health_path`: optional local health summary file used for stale-health checks.
- `fingerprint`: optional source fingerprint when the source file is generated elsewhere.

Supported agent tool labels are local conventions. BrigadeStack recognizes an extensible set of agent tool labels: `claude`, `codex`, `opencode`, `antigravity`, `pi`, `cursor`, `aider`, `goose`, `continue`, `copilot`, `qwen`, `kimi`, `adal`, `openhands`, `grok`, `amp`, `crush`, `hermes`, `openclaw`, `mcp`, and `scripts`. The `supported_harnesses` block in `brigadestack tools init` output is the source of truth.

## Runtime Supervisor

Runtimes are local processes that approved script and MCP calls can depend on. They are configured in a gitignored file:

```text
.brigade/tools/runtimes.toml
```

Create a starter config with:

```bash
brigadestack tools runtime init
```

Each runtime is a TOML table:

```toml
[[runtime]]
id = "local-helper"
name = "Local Helper"
enabled = true
command = "python3 -m http.server 8765"
cwd = "."
port = 8765
health_command = "python3 --version"
health_path = ".brigade/tools/runtime/local-helper.json"
pid_path = ".brigade/tools/runtime/local-helper.pid"
log_path = ".brigade/tools/runtime/local-helper.log"
timeout = 10
```

Runtime commands:

- `brigadestack tools runtime list` and `show <runtime-id>` inspect config and current process state.
- `brigadestack tools runtime status` reports running, stopped, and stale runtime states.
- `brigadestack tools runtime start <runtime-id>` starts one runtime with `shell=False`, writes PID metadata, and writes stdout/stderr logs under `.brigade/tools/runtime/`.
- `brigadestack tools runtime stop <runtime-id>` stops only a process with matching BrigadeStack runtime metadata.
- `brigadestack tools runtime restart <runtime-id>` stops then starts the same runtime.
- `brigadestack tools runtime doctor` reports stale PID files, port conflicts, missing cwd, high-risk commands, failed health checks, and missing runtime config.

BrigadeStack refuses high-risk runtime command shapes, detects already-running runtimes, detects stale PID files, and warns when configured ports are already in use. `doctor`, `brief`, and `work run` do not start runtimes.

When a tool has `requires_runtime = true`, `brigadestack tools call run` refuses execution unless the configured runtime exists, is running, is managed by Brigade metadata, and passes health checks. Receipts include the runtime id and runtime snapshot used for the run.

## Execution Policy

Execution policy is host-local and gitignored:

```text
.brigade/tools/policy.toml
```

Create a starter policy with:

```bash
brigadestack tools policy init
```

The policy shape is:

```toml
allowed_families = ["script"]
allowed_effects = ["local-read", "local-write"]
denied_effects = ["remote-mutation", "secret-read"]
required_approval_modes = ["on-request", "always"]
max_timeout = 60
allowed_runtimes = ["local-helper"]
env_bindings = { SAFE_ENV = "SAFE_ENV" }
```

Policy fields:

- `allowed_families`: optional allow-list for tool families that can run.
- `allowed_effects`: optional allow-list for effect labels.
- `denied_effects`: effect labels that always block planning and execution.
- `required_approval_modes`: allowed approval modes for executable calls.
- `max_timeout`: maximum allowed call timeout in seconds.
- `allowed_runtimes`: optional allow-list for runtime ids.
- `env_bindings`: maps safe env labels from tool config to process environment variable names.

When a policy file exists, `brigadestack tools call plan` and `brigadestack tools call run` report policy blockers for denied effects, effects outside the allow-list, disallowed families, missing env bindings, missing process env values, timeout caps, disallowed runtimes, and approval-mode mismatches. A missing policy is a health issue for executable contract-backed tools, but it does not break older read-only catalog workflows.

For env bindings, BrigadeStack reads the current process environment at execution time and passes values to the script under the configured label name. It never stores env values in `.brigade/tools/calls.jsonl`, receipts, logs, docs, or work imports. Receipts include the policy decision and env labels used, with values redacted.

`brigadestack tools policy doctor` checks the policy file directly. `brigadestack tools doctor`, `brigadestack work brief`, and `brigadestack tools import-issues` also surface missing policy, missing env labels, denied effects, timeout caps, approval-mode blockers, and runtime/policy mismatches.

## Projection Planning And Apply

`brigadestack tools plan` expands configured `supported_harnesses` and `projections` into exact projection actions. Each projection reports:

- logical tool id
- source family
- harness
- source path
- projection path
- source fingerprint
- expected projection fingerprint
- status
- action

Projection statuses are:

- `missing`: target file is absent and can be created
- `current`: managed projection matches the current source
- `stale`: managed projection is safe to update from changed source or changed renderer output
- `unmanaged`: target exists without BrigadeStack projection metadata
- `conflicted`: managed target has local edits
- `missing_source`: source file cannot be read

`brigadestack tools apply <tool-id>` and `brigadestack tools apply --all` write only `create` and `update` actions. `--dry-run` reports writes without touching files. `--force` is required to overwrite unmanaged files or managed projections with local edits. `doctor`, `brief`, `work run`, and `import-issues` do not apply projections.

`brigadestack tools sync plan` plans a reviewed projection sync without writing, and `brigadestack tools sync apply` applies a reviewed projection sync. `brigadestack tools parity status` shows projection parity closeout state, and `brigadestack tools parity closeout` closes out current projection parity issues.

Managed projection files start with a Brigade metadata header containing:

- logical tool id
- source family
- harness
- source fingerprint
- projection fingerprint
- generated-at timestamp

For `slash-command`, `skill`, and `superpower` entries, BrigadeStack writes the source content behind that metadata header. For `script` entries, BrigadeStack writes a safe reference projection with the command label and source excerpt. For `mcp` entries in the tool catalog, BrigadeStack writes a documentation stub only. Runtime MCP server configs are written by the separate `brigadestack mcp` subsystem.

## Portable Tool Packs

`brigadestack tools pack` builds and inspects local portable tool packs:

- `brigadestack tools pack build` builds a local portable tool pack from the catalog.
- `brigadestack tools pack list` lists local portable tool packs.
- `brigadestack tools pack show <pack-id>` shows one local portable tool pack.
- `brigadestack tools pack import <pack>` imports catalog entries and source files from a portable tool pack directory containing `tool-pack.json`.
- `brigadestack tools pack archive <pack-id>` archives one local portable tool pack.

## Contracts And Call Planning

Contracts let wrappers understand how a portable tool should be called without invoking it. BrigadeStack supports a practical local subset of JSON Schema:

- root object schemas
- `required`
- scalar types: `string`, `number`, `integer`, `boolean`, and `null`
- arrays with `items`
- enums
- boolean `additionalProperties`

Unsupported schema keywords are reported as contract health issues. `brigadestack tools call plan` accepts inline JSON with `--args` or a file with `--args-json`, validates it against `input_schema_path`, renders `argument_template`, and returns a redacted plan with:

- tool id, family, command label, cwd, timeout, auth label, and env labels
- rendered argument mapping
- permissions and effects
- approval mode and approval requirement
- blockers for invalid args, missing schemas, missing commands, unsafe labels, and conflicted or unmanaged projections

Call planning does not invoke the command, start daemons, start MCP servers, resolve approvals, fetch remote schemas, or store auth.

## Call Approval Queue

`brigadestack tools call queue` stores planned calls in:

```text
.brigade/tools/calls.jsonl
```

Each queued call stores:

- status: `pending`, `approved`, `rejected`, or `held`
- redacted args and rendered argument mapping
- contract metadata, approval mode, permissions, and effects
- blockers from call planning
- projection summary
- source and contract fingerprints
- created and reviewed timestamps
- review reason when rejected or held

Equivalent valid plans dedupe while pending or approved. Rejected calls can be requeued only when args or the contract fingerprint changes. Blocked plans require `--include-blocked` to enter the queue, and blocked calls cannot be approved. Approval never executes a tool.

`brigadestack tools doctor` warns on stale pending approvals, approved calls whose contract or source fingerprint has gone stale, blocked queued calls, and held or rejected calls. `brigadestack work brief` shows pending approval count and the highest-priority call approval issue. `brigadestack tools import-issues` routes call approval health problems into `tool-catalog` imports.

## Call Execution Receipts

`brigadestack tools call run <call-id>` executes exactly one approved call. `brigadestack tools call run --next` runs the oldest approved call. Execution is intentionally narrow:

- only `script` and `mcp` family calls run
- the call must be `approved`
- blockers must be empty
- approval, args, contract, source, and projection fingerprints must still match
- completed calls cannot be run again
- commands run with `shell=False`

For script calls, BrigadeStack parses the configured `command`, appends rendered `argument_template` values in stable key order, uses the configured `cwd` when present, and applies the configured timeout. It does not resolve auth, fetch secrets, run OpenAPI or GraphQL calls, or execute unapproved queue entries.

For MCP calls, BrigadeStack requires an approved `mcp` family call with `runtime_id`, `mcp_tool_name`, `input_schema_path`, timeout, permissions, effects, and approval mode. The configured runtime must already be running, managed by Brigade metadata, healthy, and allowed by policy. BrigadeStack then runs the configured local stdio command with `shell=False`, sends JSON-RPC `initialize`, `tools/list`, and `tools/call`, validates that the requested MCP tool is listed, and records the redacted request and response in the receipt. This starts the local stdio command for that call, but it does not connect to remote MCP servers or start the runtime for you.

Each run writes a receipt and raw local logs under:

```text
.brigade/tools/runs/
```

Receipts include call id, tool id, family, status, timestamps, duration, exit code, timeout status, command label, cwd, redacted args and rendered arguments, redacted stdout/stderr summaries, stdout/stderr log paths, contract/source/call/approval fingerprints, approval metadata, permissions, effects, runtime snapshot, policy decision, env labels used, and projection summary. MCP receipts also include server id, tool name, request id, redacted request payload, redacted response summary, and MCP response count. Raw stdout and stderr logs stay local and gitignored.

## Run History And Replay

Run history commands read only from `.brigade/tools/runs/`:

- `brigadestack tools run list` summarizes receipts by status.
- `brigadestack tools run show <run-id>` shows one receipt by id or unique prefix.
- `brigadestack tools run latest` shows the newest receipt.
- `brigadestack tools run replay <run-id>` creates a new pending call from the receipt's redacted args after revalidating the current tool contract, source fingerprint, projection summary, runtime requirement, and policy decision.

Replay queues a pending call. It does not execute the command or mark the call approved. Operators or wrappers must review and approve the new call through the normal approval queue, then run it with `brigadestack tools call run`. Replay uses only the redacted receipt args, so secret env values and secret-looking argument values are not recovered from logs or receipts.

`brigadestack tools doctor` warns on failed or timed-out runs, malformed receipts, missing stdout/stderr log files, and replay candidates blocked by stale tool, runtime, or policy state. `brigadestack work brief` surfaces the highest-priority run-history issue, and `brigadestack tools import-issues` routes run-history problems into `tool-catalog` imports.

## Execution Checkpoints

Approved script tools can request an operator checkpoint by writing a JSON file under the directory in `BRIGADE_TOOL_CHECKPOINT_DIR`. BrigadeStack also passes `BRIGADE_TOOL_CALL_ID` and `BRIGADE_TOOL_RUN_ID` to the script so checkpoint writers can include the current call and run id.

Checkpoint JSON supports:

- `id`, optional. BrigadeStack generates one when absent
- `reason`
- `requested_action`
- `prompt` or `operator_prompt`
- `context`, redacted before storage
- `choices` or `allowed_resume_choices`
- `created_at`, optional
- `expires_at`, optional

When a run writes a checkpoint, BrigadeStack normalizes the file into `.brigade/tools/checkpoints/`, marks the call `waiting`, and writes a waiting receipt linked to the checkpoint. `brigadestack tools checkpoint approve <checkpoint-id> --choice <choice>` marks the checkpoint approved and moves the call to `resume-pending`. `brigadestack tools checkpoint resume <checkpoint-id>` then revalidates the call, contract, source, projection, runtime, and policy state before executing. Resume receipts include the original call id, original run id, checkpoint id, resume run id, selected choice, and checkpoint approval metadata.

Checkpoint approval does not execute anything. Checkpoint resume is not triggered by `doctor`, `brief`, `work run`, or `call run`. BrigadeStack redacts checkpoint context and does not store process env values in checkpoints, receipts, logs, imports, or docs.

`brigadestack tools doctor` warns on stale, expired, rejected, blocked, and failed checkpoints. `brigadestack work brief` surfaces the highest-priority checkpoint issue, and `brigadestack tools import-issues` routes checkpoint problems into `tool-catalog` imports.

## Health Checks

`brigadestack tools doctor` reports:

- missing source, manifest, schema, projection, or health files
- invalid schema JSON
- invalid or unsupported contract schemas
- missing call contracts for command-backed tools
- missing examples
- bad argument templates
- missing required script or custom commands
- command labels that do not resolve on the current host
- high-risk command shapes such as shell pipes into `sh`, `bash -c`, `sudo`, or `rm -rf`
- parity gaps where a supported harness lacks a projection target
- missing, stale, unmanaged, or locally edited projection files
- stale health files
- unsafe auth or env field names in the local config
- stale or blocked tool call approvals
- approved tool calls with stale source or contract fingerprints
- failed tool call executions
- tool call executions left running too long
- failed or timed-out run receipts
- failed MCP executions, malformed JSON-RPC responses, and MCP tool-list mismatches
- malformed run receipts and missing run log files
- run replay candidates blocked by current tool, runtime, or policy state
- stale, expired, rejected, blocked, or failed checkpoints
- missing, stopped, stale, unhealthy, or unmanaged required runtimes
- runtime config, cwd, command, PID, port, and health-check issues
- missing execution policy for executable contract-backed tools
- policy blockers for effects, timeouts, approval modes, runtimes, families, and env labels
- MCP config issues in local JSON files with `mcpServers`

MCP discovery is structural. BrigadeStack summarizes server count and server ids, checks for missing commands and timeout metadata, and flags broad shell-like command shapes. MCP execution runs only approved calls through `brigadestack tools call run`, against local runtimes.

## Work Inbox Routing

`brigadestack tools import-issues` creates local work imports with:

- `source = "tool-catalog"`
- logical tool id
- source family
- issue type
- harness and projection target when relevant
- safe issue detail
- stable source item key and fingerprint

Repeated imports dedupe equivalent pending or promoted issues. Dismissed tool-catalog imports stay dismissed until the issue fingerprint changes.

## Keep secrets out of the catalog

Keep all catalog state local and gitignored. Do not put tokens, passwords, raw credentials, URLs with embedded secrets, private hostnames, or host-private paths in public templates. BrigadeStack reports unsafe field names without copying their values into command output, work imports, session artifacts, docs, or handoffs.

`brigadestack tools call run` executes approved local `script` entries and approved local `mcp` entries with already-running managed runtimes, and records local receipts. Call planning, approval review, run history inspection, and checkpoint review do not execute anything. Replay creates a pending call that still goes through the approval, runtime, and policy gates. Execution policy is host-local and gitignored. BrigadeStack does not store secrets, connect to remote MCP servers, run OpenAPI or GraphQL calls, install schedulers, fetch remote schemas, store auth, send notifications, or mutate remote services.