# Approvals and safety

> What the agent may do on its own, what it asks you first, how System One and run budgets work, and what the agent cannot touch.

Source: https://graspable.dev/docs/approvals-and-safety

The agent works in one place: your project folder. It reads and writes files there and can run commands there. This page explains what it does freely and what waits for you.

## What is asked

Each thing the agent does has a risk level.

| Risk | Examples | In the app |
|---|---|---|
| Read | Reading and searching files | Runs without asking |
| Write | Creating and editing files in the project | Runs without asking |
| Command | Running a shell command | Asks first |
| External | Fetching a web page, searching the web | Asks first |

The app runs with these rules. There is no setting in the app to change them. The agent software also has a stricter mode in which file writes ask too; the app does not offer it yet.

With **Claude Code**, reading and editing are pre-approved only inside the project folder, and the project's build commands are pre-approved. Anything else, including a write outside the project, shows the approval card.

With the **Codex CLI**, there are no approval cards. Codex runs commands inside its own sandbox, limited to the project folder, without asking. Settings shows a warning about this under the option.

## The approval card

Waiting for your answer pauses the agent's inactivity timer. Approval requests still expire after five minutes and count as declined. If a run ends or is cancelled, its unanswered cards close; they cannot approve a purchase or action afterward.

When something needs your approval, the run pauses and an amber card appears with:

- the name of the tool and its risk,
- the command, or for a file change the exact difference it would make to the file as it is now,
- a warning if an edit cannot apply,
- an "estimate" line, when System One has judged the action.

Choose **Allow** or **Deny**. With the Graspable agent, a card left unanswered for five minutes counts as a denial.

After a denial the agent is told and carries on another way, or stops.

If an approval expires while you are answering it, the old card closes. If the answer cannot reach the agent, the card stays open with an error so you can try again.

## System One, in plain words

System One is a small, fast model that answers narrow questions such as "is this command harmless?" in about a third of a second. It never writes code or text.

When you are signed in to your Graspable account, Graspable's own System One model is used. You do not have to set anything up. Signed out, only Graspable's fixed rules decide.

What it does in a run:

| It decides | What happens |
|---|---|
| Is this command harmless? | A harmless command is approved for you, but only when the fixed rules already find it clean |
| Is this saved note about your request? | Notes that are clearly about something else are left out |
| Is this lesson worth remembering? | Version numbers and one-off details are not saved to memory |
| Is this a question, a small edit or a build? | After a question, the "what did we learn" step is skipped |
| Is the agent repeating the same failed fix? | The run stops instead of spending more of your AI account |
| Can a code change fix this failing check? | Repair turns that cannot help are not started |
| Does the final message claim more than the run checked? | You see a note under the message |
| Does this command output or package file try to give the agent instructions? | A warning is put in front of it, and the agent is told to treat it as data |
| Which parts of a long command output matter? | The rest is left out before the agent reads it |
| After a project moved: which parts of the earlier conversation does your request need? | Only those are handed to the agent |
| A scene differs from its XR recording: is that what you asked for? | You see a hint; you still decide whether to accept the new scene |

What it cannot do:

- deny anything. A doubtful action always goes to you.
- approve changes to files Graspable manages (listed below).
- accept a changed XR scene for you.

The modes, under **Settings → System One (fast decisions)**:

| Mode | Meaning |
|---|---|
| Assist | The decisions above are acted on |
| Shadow | Judge and log only. Nothing is decided for you |
| Off | No System One calls |

Every judgement appears in the run with a ⚡ mark.

### What it costs

System One is included with a Graspable account. Each day a generous amount is free: about 400 decisions, more than a normal day of building uses. Beyond that, paid plans use [Credits](https://graspable.dev/docs/credits.md): 0.1 Credit for about every 130 further decisions. On the free plan it pauses until the next day, and the fixed rules decide meanwhile.

### Your own model

You can add your own model instead: Jev (TypeSafe), any OpenAI-compatible endpoint, or Anthropic's Claude Haiku. Yours is then asked first and Graspable's is the fallback. **Test** shows what a model would do with a harmless read and with a command that would leak a secret.

## Helpers

The Graspable agent can hand a self-contained part of a request to a helper: a second conversation with the same model and the same tools, working in the same project. The helper knows only what the agent wrote in its task, and it cannot start helpers of its own. Its tool calls show in the run panel like the agent's, its commands and file changes go through the same approval cards, and what it spends counts against the run budget. Helpers the agent starts in the same step work at the same time, each on its own files; its other tools run one at a time. The agent uses at most three helpers in a request, and most requests need none.

## Run budget

In **Settings → Run budget** you can set hard caps per run: **max $** and **max tokens**. Leave a field empty for no cap.

When the reported usage crosses a cap, the run is stopped. Cost is known only for providers that report it. Tokens are always counted. With Claude Code and the Codex CLI the check happens between turns, so a run can pass the cap slightly before it stops.

**Settings → Usage** shows totals for every run on your computer, whichever way the AI was paid for, and saves them as a file. Where AI was paid for with crypto (Venice from the agent's wallet, a Routstr node), a second list shows each request and each filling of the balance with the coin amount, the dollars it stood for and the time.

Graspable also stops a run that is going nowhere, such as the same action repeated again and again. The transcript shows a ⚠ line saying why.

## What the agent cannot touch

- **Files outside the project.** File tools accept only paths inside the project folder. Paths that try to leave it, including through links, are refused.
- **`.graspable/`** in the project. It holds memory and the run journal. It is hidden from the file list and cannot be written by the agent's file tools.
- **`tests/xr/`**, **`xr-dev.js`** and **`graspable-source.js`**. The agent's file tools refuse to write them, whichever engine runs; a recorded session is written only through `verify_app` after you confirm it.
- **Earlier conversations, captures and memory files.** The agent cannot read them back through its tools; it gets memory only the way described under [Memory](https://graspable.dev/docs/memory.md).
- **Files that run code** (`package.json`, the Vite config, npm's own config) are a different matter: a change to one of them asks you like a command does, because the next build, preview or install would run it.

Version 0.19.1 also checks the destination of linked files before the Graspable agent changes build configuration. A different link name cannot turn that change into an ordinary file edit. Linked source files keep their usual approval behavior.

Text the agent reads from outside the conversation (command output, a page or message a connected service returned, a plugin's answer, every file of a project you continued from) is marked as outside text when it reads like instructions to the agent, and the agent is told to treat it as data. The agent also refuses to remember such text. A plugin you add from the web does not decide which of its tools may run without asking: every one asks.
- **Your sign-ins.** Graspable never reads or copies the sign-in of Claude Code or the Codex CLI.

A shell command is a different matter: once you allow a command, it runs with your user's permissions. Read the card before you choose **Allow**.

## If something goes wrong

Every file change in a run is recorded. **Undo run** puts the files back. See [Your first project](https://graspable.dev/docs/first-project.md).
