ToolChange manifest lint

Manifest-first PR security for agent tool catalogs — deterministic lint in <5s, no AST or runtime probes in CI.

Prerequisites: Python 3.10+ and the open-source driftguard repo. No DriftGuard watches required.

What you will build

1. Export tools.json from your tool sources.
2. Lint against a committed baseline on every PR.
3. Add the GitHub composite action and optional pre-commit hook.

Step 1 — Install ToolChange

cd driftguard/packages/toolchange
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Step 2 — Export a manifest

Generate or refresh tools.json from a Python tool module:

toolchange export --out tools.json \
  --source agents/billing/tools.py \
  --tool-name stripe_create_refund \
  --scope write \
  --schema-json '{"type":"object","properties":{"amount":{"type":"number"}}}'

Commit tools.json and a frozen tools.baseline.json for PR diffs.

Step 3 — Lint locally

toolchange lint --manifest tools.json --baseline tools.baseline.json --repo-root .

Checks include schema diff vs baseline, stale source hashes, injection patterns in descriptions, and write-scope enforcement.

Gate 3 alpha rollout: add --advisory to report findings without failing the build.

Step 4 — GitHub Actions

Copy the composite action from the OSS repo (.github/actions/toolchange):

jobs:
  toolchange:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ./.github/actions/toolchange
        with:
          manifest: tools.json
          baseline: tools.baseline.json
          repo-root: .

Breaking manifest changes fail the required check (TC-L07). Cloud-hosted lint API (POST /v1/toolchange/lint) is available with toolchange_org entitlement for hosted workflows.

Step 5 — Pre-commit hook (optional)

cp packages/toolchange/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Override paths with TOOLCHANGE_MANIFEST and TOOLCHANGE_BASELINE. The hook runs only when manifest or baseline files are staged.

Troubleshooting

Next steps

• FuseGuard loop fuse — runtime protection after CI lint
• OSS ToolChange README