# Architecture

Pi Toolbelt is a local CLI gateway for Pi agents.

The core idea is simple:

```text
Pi agent / LLM
   │ asks for a provider operation
   ▼
Pi Toolbelt extension
   │ validates arguments and calls local CLI wrapper
   ▼
pi-toolbelt CLI
   │ applies provider policy, redaction, JSON envelopes, approval gates
   ▼
Official/local provider CLI
   │ owns auth and talks to the provider API
   ▼
Provider service
```

## What Toolbelt owns

Toolbelt owns the agent-facing safety layer:

- provider discovery and inventory
- operation classification: read-only, mutating, destructive, blocked
- secret-shaped input rejection
- command argument construction
- output redaction and truncation
- redaction of secret-shaped values
- structured JSON result envelopes around provider output
- future audit/ledger hooks
- approval gates for mutations

## What provider CLIs own

Provider CLIs own provider-specific behavior:

- login and authentication
- OAuth/device flows
- OS keychain integration
- API request signing
- provider-specific config files
- refresh tokens/session handling
- raw API compatibility

This is the main security and maintenance benefit. Toolbelt should not become a second auth store for every service. It should wrap the CLIs users already trust.

## Auth model

Authentication stays in the official CLI, OS keychain, local config, or local environment. Toolbelt does not need raw API keys or OAuth tokens from the user or from the LLM.

The LLM receives operation results so it can help the user. It should not receive reusable authentication material.

Example:

- Good: `deployment failed`, `PR checks failed`, `invoice count: 12`, `service status: healthy`
- Not allowed: API keys, OAuth tokens, cookies, private keys, passwords, auth headers

## Built-in adapters vs custom providers

Toolbelt can support services in two ways:

1. **Built-in adapter** — shipped with Toolbelt for common CLIs and common operations.
2. **Custom provider definition** — user supplies a config that tells Toolbelt how to call an installed CLI safely.

The product goal is broad: any useful local CLI can become agent-safe once Toolbelt knows its commands, risk tiers, and output handling.

## CLI installation through Pi

Users should be able to ask Pi to install missing CLIs:

```text
Install the official Vercel CLI and then configure Toolbelt to use it.
```

Pi can inspect the OS, choose the right package manager, install the CLI, verify `--version`, guide login, and run Toolbelt status checks. Toolbelt should document installation commands, but the user experience should be conversational.

## When no official CLI exists

If a service has no official CLI, create one first and then wrap it with Toolbelt.

Recommended path:

1. Use an existing community CLI if trustworthy.
2. Generate a CLI with CLI-Anything: https://github.com/HKUDS/CLI-Anything
3. Ensure the generated CLI has `--json`, auth isolation, tests, and clear command help.
4. Add a Toolbelt provider definition that classifies safe/mutating/blocked operations.

Toolbelt should be the policy gateway, not the generator. CLI-Anything or a hand-built CLI creates the command surface; Toolbelt makes that command surface safe for agents.