# Add Bounds to an agent

Bounds decides an AI agent's tool call before it runs. It refuses a call that
breaks the policy, records the verdict in a signed hash-chained ledger, and
keeps the decision local. Free and unlimited on your machine.

This file is written for an agent to follow. Run the steps yourself; the user
does not need to open a dashboard. Start in observe mode and do not enforce
until the user has seen the refusals.

## 1. Connect

From the project the agent works in:

```sh
npx attesso connect --write --mode observe --json
```

This initializes the local ledger if needed, writes the mode file, wires every
harness it detects, and writes the agent instructions. It is idempotent.
Use `--mode off` to connect without recording or `--mode enforce` only after
the user approves enforcement.

A plan without writing anything:

```sh
npx attesso connect --mode observe --json
```

Status is machine-readable:

```sh
npx attesso status --json
```

The result tells you whether the ledger is initialized, the active mode, which
harnesses are wired, and which need a manual step. `connected` is true only
when a harness is wired and the mode is not `off`.

For a local view of the same ledger:

```sh
npx attesso ui
```

It starts on `127.0.0.1:8197`, follows new decisions as they are appended, and has
no account, no hosted data, and no snapshot file. `Ctrl-C` stops it. Use it to
read real refusals, not to bypass the signed record.

When the workspace is on a paid plan, mirror the next decisions to the hosted
view (the local ledger stays authoritative). In the local UI, open **Workspace >
Connect workspace**; `npx attesso sync` then uses that saved connection:

```sh
npx attesso ui
# Workspace > Connect workspace, then:
npx attesso sync
npx attesso sync --watch
```

The URL and key are stored in `~/.config/attesso/config.json` with mode 0600.
Explicit `--url` / `--key` win, then `ATTESSO_SYNC_URL` / `ATTESSO_API_KEY`, then
that file.

When the workspace publishes hosted rules, verify and apply the signed bundle:

```sh
npx attesso policy pull --apply
```

The command sends at most 50 summary rows, advances `.attesso/sync.json` only
after the server confirms, and is safe to retry. `--watch` keeps the hosted
mirror current every five seconds for the rest of the session.

## 2. Choose the permission mode

```sh
npx attesso mode observe
npx attesso mode enforce
npx attesso mode off
```

- `observe` records every verdict and never blocks. Use this first.
- `enforce` refuses a violating call with the harness's native refusal.
- `off` exits before reading the ledger.

Mode changes apply to the next tool call; the agent process does not restart.
A hook whose mode file is invalid must fail closed, not silently allow.

### Open a run and cap its spend

A task can run for days; a budget on it counts the whole conversation. A run is the unit the agent and the budget share. Open one when the work starts, close it when the work ends:

```sh
npx attesso run start --goal "fix the failing test"
npx attesso run status --json
npx attesso budget --tokens 200000 --usd 0.50 --enforce
npx attesso run end --outcome success --note "the test passes"
```

`run start` and `run end` write signed markers and a `run.json` pointer; every decision in between carries the run id. The markers are not decisions: counts, usage, the flow and the hosted sync leave them out. `run end` records `success`, `failed`, `abandoned` or `unknown`. The budget rule sums the measured tokens and cost recorded under the active run and refuses with `BUDGET_EXCEEDED` on the next execute, write or send; a usage report is never blocked. `--enforce` makes that rule block while the mode is still observe. Without an active run the budget falls back to the task id.

Do not leave a run open across unrelated work; close it with the outcome that actually happened, including `failed` or `abandoned`.

## 3. Scope file paths

Path rules apply to file tools, not to shell commands. Shell and execute are a
separate capability and remain unscoped unless the harness sandbox covers them.

A deployment that wants the hook to refuse every execute capability can add
`"shell_scope": "deny"` to `paths.json`. That is a denial, not a command
sandbox; it does not inspect the command.

`paths.json` beside the ledger:

```json
{
  "version": 1,
  "allowed_roots": [
    { "path": "~/project", "access": ["read", "write"] }
  ],
  "exclusions": ["**/.env", "**/.ssh/**"]
}
```

Write it through the CLI so it is validated and published atomically:

```sh
npx attesso paths --set paths.json
npx attesso paths --json
```

Rules:

- a root grants `read` or `write`; write implies read
- exclusions always win; they are checked before roots
- parent traversal is refused
- a symlink inside a root cannot escape it
- a file tool with no resolvable path is refused
- an unreadable or invalid `paths.json` fails closed and must be fixed

## 4. Wire a custom harness

Any harness with a pre-tool hook can call Bounds. The contract is one JSON
object on stdin. Exit 2 refuses; exit 0 allows.

```sh
npx attesso hook --observe    # record, never block
npx attesso hook              # refuse according to the mode
```

The payload is the native harness shape:

```json
{
  "hook_event_name": "pre_tool_call",
  "session_id": "task-1",
  "tool_name": "read_file",
  "tool_input": { "path": "~/project/src/index.ts" }
}
```

Harnesses with automatic wiring through `connect`:

| Harness | Native refusal |
|---|---|
| Hermes | exit 2 with a message |
| Claude Code, Codex | `hookSpecificOutput.permissionDecision: deny` |
| Cursor | `permission: deny` |
| Cline | `{ cancel: true, errorMessage }` |
| Gemini | `{ decision: deny, reason }` |

Codex requires its own `/hooks` review and trust step. A changed command is
untrusted again. Cline hooks are off until enabled in its Features settings.
Cursor and other unlisted harnesses use the generic stdin/stdout contract.

## 5. Rules

`.attesso/rules.json` is the policy language:

```json
{
  "version": 1,
  "rules": [
    {
      "id": "no-send-after-untrusted-read",
      "deny": { "capabilities": ["send"] },
      "if_path": { "trust": "untrusted", "capability": "read", "within_minutes": 30 }
    },
    {
      "id": "no-loop-3",
      "max_repeats": 3,
      "deny": { "capabilities": ["execute"] }
    },
    {
      "id": "steps-40",
      "max_steps": 40,
      "deny": { "all": true }
    },
    {
      "id": "run-budget",
      "max_tokens": 200000,
      "deny": { "capabilities": ["execute", "write", "send"] },
      "enforce": true
    }
  ]
}
```

A repeat means the same tool with the same arguments. It is keyed on a digest,
never on the tool name alone. A path rule can look back at the task history;
that is what catches a permitted read followed by a permitted send.

Any rule can set `"enforce": true`. In observe mode that rule alone blocks; every other rule keeps recording. Use it to turn on one rule you have replayed and accepted without turning the whole gate on. A run budget is a rule: `max_tokens` and `max_cost_usd` cap the measured spend under the active run; the `budget` command writes it.

Start with the balanced profile. Move to strict only when the user wants
writes or shell commands treated as part of the untrusted path.

## 6. Read a refusal

```sh
npx attesso explain 41
```

It prints the entry, the rule that fired, and the step that tainted the task.
Do not retry a refused call unchanged. Take another path, or ask the user
whether the rule is wrong.

Refusal codes include `PATH_DENIED`, `STEP_LIMIT`, `REPEAT_LIMIT`,
`BUDGET_EXCEEDED`, `ACTION_MISMATCH`, `ABOVE_MAXIMUM`, `VALUE_NOT_ALLOWED`,
`VALUE_MISMATCH`, `OUTSIDE_DATE_RANGE`, and `REQUIRED_ATTRIBUTE_MISSING`.

### Local preview

The hook records a small redacted preview beside the signed entry: command,
path, URL, query, recipient and argument key names. File contents, message
bodies and patch text are not stored; secrets are redacted before the write.

```sh
npx attesso detail 41
npx attesso detail 41 --json
npx attesso verify --details
```

`detail` checks the entry signature and the preview hash before printing.
`--json` names `verified`, `none`, `missing`, `changed` or `unavailable`; the
last three exit 2. `verify --details` exits 2 when a preview changed. The
preview is local, mode 0700, and never syncs, bundles or enters a packet; a
failed write never blocks the call. `--delete` removes it and leaves the signed
entry valid.

## 7. Verify the record

```sh
npx attesso report
npx attesso verify
npx attesso verify --details
npx attesso prove 41 --out receipt.json
npx attesso verify-receipt receipt.json
npx attesso packet 41 --out packet.json
npx attesso verify-packet packet.json --replay
```

`verify` recomputes the hash chain and signatures. `report` groups actions and
refusals by task. A receipt proves the entry is in the log whose head the local
key signed; it verifies without the ledger.

## 8. Limits

- A local key proves the file was not edited. It does not prove a human
  approved the action, and a stranger cannot check it without trusting the key
  beside the log.
- Hosted evidence, signed by Attesso and verified against published keys, is a
  separate capability.
- Path scope covers file tools. It is not an OS sandbox for shell.
- A blocked call can add a model turn. Do not describe it as token savings
  without a paired measurement.
- The preview is local and redacted, not a payload archive. It is not in a
  receipt or packet; a preview you disclose can be checked against the
  `detail_hash` in the signed entry.
- A run budget stops spend at the next tool call, not mid-call.
- Do not enable enforcement when the user has not reviewed the observe
  refusals.

## 9. MCP-only clients

If your client can speak MCP but has no shell, add the control server once in
the host's server configuration:

```sh
npx attesso-control-mcp --dir .attesso
```

It is a stdio server, not an HTTP endpoint. It supports `bounds_status`,
`bounds_connect`, `bounds_mode`, `bounds_paths_get` and `bounds_paths_set`.
Connect and mode are limited to `observe` and `off`. Enforcement and path
widening require the human CLI, and the control server cannot authorize itself.
The existing `attesso-mcp` command is a different thing: it is a proxy for an
upstream tool server.
