# Capabilities


A capability is a named permission. Gated operations call for a capability before
they run; the call proceeds only if the current subject holds it.

kli is fully permissioned by default. The default subject passes every capability
check, so every gated operation runs. There is no interactive approval prompt.
Restriction is configured up front through the `capabilities` array in
`settings.json` (see [Restricting with settings](#restricting-with-settings)
below).

## Capability vocabulary

Capability names are lowercase strings with a slashed namespace, for example
`file/read` or `manifest/install`. The names below make up the vocabulary the
shipped tools and operations draw on.

### Tools

| Capability | Gates |
|---|---|
| `file/read` | The `read`, `find`, and `search` tools. |
| `file/write` | The `write` tool. |
| `file/edit` | The `edit` tool. |
| `process/exec` | The `bash` tool. |
| `image/eval` | The `eval` tool, which evaluates Common Lisp in the running image. |
| `tools/standard` | Convenience name for the four file and process capabilities. See [Implication rules](#implication-rules). |

### Extension lifecycle

| Capability | Gates |
|---|---|
| `manifest/install` | Activating an extension (installing its contributions). |
| `manifest/retract` | Deactivating an extension (retracting its contributions). |
| `image/recode` | Replacing an extension's source in place (deactivate then reactivate). |
| `manifest/install-remote` | Installing a remote extension with `/install`. |
| `image/load-dep` | A grant in the dependency-load implication chain. No shipped operation checks it directly. |
| `image/load-native` | The native-load grant carried by a remote install. No shipped operation checks it directly. |

### Credentials

| Capability | Gates |
|---|---|
| `auth/register-reference` | Recording a credential for a provider. |
| `auth/resolve-secret` | Reading a stored secret value. |
| `auth/read-metadata` | Inspecting the credential store (provider list, reference metadata; never secret values). |
| `auth/forget-secret` | Deleting a stored credential. |

## Implication rules

A coarse capability implies finer ones. Granting a capability grants its full
closure, computed transitively at subject construction. Holding any capability in
the table below grants every capability it implies.

| Capability | Implies |
|---|---|
| `tools/standard` | `file/read`, `file/write`, `file/edit`, `process/exec` |
| `image/recode` | `manifest/install`, `manifest/retract` |
| `manifest/install-remote` | `manifest/install`, `image/eval` |
| `image/load-native` | `image/load-dep`, `image/eval` |
| `image/load-dep` | `image/eval` |

Implications compose. Granting `manifest/install-remote` also grants
`manifest/install` and `image/eval`; granting `image/load-native` grants
`image/load-dep` and, through it, `image/eval`.

## Gated operations

| Operation | Required capability |
|---|---|
| Invoke a tool | Each capability listed in the tool's metadata (the table above). |
| Activate an extension | `manifest/install` |
| Deactivate an extension | `manifest/retract` |
| Recode an extension | `image/recode` (implies `manifest/install` and `manifest/retract`) |
| Install a remote extension (`/install`) | `manifest/install-remote` |
| Register a credential | `auth/register-reference` |
| Resolve a credential | `auth/resolve-secret` |
| Inspect the credential store | `auth/read-metadata` |
| Forget a credential | `auth/forget-secret` |

A gated operation whose capability the subject lacks signals an error and does
not run.

## Restricting with settings

The `capabilities` key in `settings.json` sets the authority of every agent. Its
value is an array of capability name strings.

| Value | Effect |
|---|---|
| Key absent | The default subject applies. Every capability check passes. |
| Array of capability names | The subject holds exactly the implication-closure of those names. Capabilities outside the closure are denied. |
| Empty array `[]` | The subject holds nothing. Every gated operation is denied. |
| Any non-array value | The value is ignored with a warning, and the default subject applies. |

A restricting array denies only gated operations. Operations that check no
capability run regardless.

```json
{
  "capabilities": ["file/read", "process/exec"]
}
```

This subject can run the `read`, `find`, `search`, and `bash` tools. It cannot
write or edit files, evaluate Lisp, change extensions, or read credentials.
Granting `tools/standard` instead would grant all four file and process
capabilities through the implication rules above.

The `capabilities` key is read under the active profile overlay like every other
setting; see [Settings](/kli/config/settings) and
[Profiles](/kli/config/profiles).