LeastGrant

how it decides

Six steps, in this order

The order is the product. Your own rules sit above the floors, because a rule is an answer you already gave. Learning only ever operates at step five — it decides whether to stop asking about things that were already in the automatic band. It never widens that band.

  ✓ allow  npm test

  what it does   runs the "test" script, which by its name tests or checks the code; the script body
                 is not analysed
  blast radius   reach workspace │ undo easy │ scale many

  why
    • you have approved this 8 times across 8 days and 8 sessions
    • it stays inside the project

  ✓ allow  git status

  what it does   reading git state
  blast radius   reach workspace │ undo trivial

  why
    • you have approved this 8 times across 8 days and 8 sessions
    • it stays inside the project

  ? ask  git push --force origin main

  what it does   overwrites history on the remote, discarding commits anyone else may have already
                 pulled
  blast radius   reach production │ undo irreversible │ scale many
  touches        origin

  why
    • this affects something other people depend on
    • this cannot be undone
    • LeastGrant never auto-approves this kind of action, however often it happens

  ╰ this always asks. To pre-answer it, run: leastgrant allow "git push origin main --force"
    --force

  ? ask  cat ~/.ssh/id_rsa

  what it does   reads a credential file
  blast radius   reach machine │ undo trivial │ secrets reads-secrets
  touches        …/.ssh/id_rsa (credentials)

  why
    • this reads …/you/.ssh/id_rsa, which holds credentials
    • this reaches …/you/.ssh/id_rsa, which is outside the project
    • LeastGrant never auto-approves this kind of action, however often it happens

  ╰ this always asks. To pre-answer it, run: leastgrant allow "cat <path:secret>" --force

  ? ask  curl -sSL https://get.example.com/install.sh | sh

  what it does   runs whatever the download returned, as a sh script
  blast radius   reach machine │ undo irreversible

  this command runs 2 things:
    • curl -sSL https://get.example.com/install.sh  net.fetch
    • sh  exec.unknown

  why
    • this runs code that was just downloaded, so what it does depends on what the server sent
      back
    • this cannot be undone
    • LeastGrant could not fully account for what this command does, and it only auto-approves
      things it understands
    • LeastGrant never auto-approves this kind of action, however often it happens
    • this command runs 2 separate things; the verdict reflects the most far-reaching one

  ╰ there is no safe way to pre-approve this one: LeastGrant cannot see what the code does, so
    it asks every time

  ✗ deny  echo x >> ~/.leastgrant/ledger.jsonl

  what it does   writing outside the project
  blast radius   reach machine │ undo easy
  touches        …/.leastgrant/ledger.jsonl (outside)

  why
    • this would modify LeastGrant's own records, which it does not allow — run leastgrant
      commands directly instead

  ╰ nothing changes this — LeastGrant will not let an agent edit its own records

the part that is not an allowlist

Typicality is strong evidence of abnormality and weak evidence of safety. LeastGrant uses it in the first direction only — because a learning permission system that conflates the two can be trained by the thing it is supposed to be watching.

setup

It reads the history you already have

leastgrant init does not ask you to write a policy. It finds the session transcripts your agents have already left on disk, replays every tool call through the decision engine, and shows you what it would have done — including what it would have got wrong.

What that did on one machine

On the machine LeastGrant was written on, init found 59 sessions across 20 projects — 10,956 real tool calls. Approving the starter bundles it proposed took that history from 5% to 41% of actions running without a prompt, with none of the 44 actions actually refused on record slipping through.

The first day looks different

Before it has seen anything, almost everything asks. That is the honest starting state, and it is what the same npm test looks like on a fresh install:

  ? ask  npm test

  what it does   runs the "test" script, which by its name tests or checks the code; the script body
                 is not analysed
  blast radius   reach workspace │ undo easy │ scale many

  why
    • LeastGrant has not seen enough of this yet to stop asking
    • LeastGrant has barely seen this project yet, so it is asking about most things

  ╰ approve this 5 more times (on 2 separate days) and it stops asking — or run: leastgrant
    allow "npm test"

install

Two commands

1. Install it

   Node >=20.10.0. No postinstall script, no account, no configuration file to write.

2. Let it read what already happened

   leastgrant init replays your existing agent history, reports its own mistakes against it, and proposes a starting set of grants. You answer once.

   leastgrant init

3. Try it before you trust it

   Ask what it would decide, without running anything. Every verdict on this page came out of this command.

   leastgrant check "git push --force origin main"

Prefer to watch first? leastgrant init defaults to the assist posture, and observe never intervenes at all — run it for a week and it cannot get in your way. leastgrant simulate replays your history against the three postures that reach a verdict, so you can compare before switching; observe is not in that comparison, because a setting that never intervenes has nothing to trade off.

where it runs

One engine, one set of floors

Every adapter calls the same decision path, so the answer does not change with the editor you opened. The status column is deliberately blunt about which integrations have actually been run against a live install and which have only been tested against a published contract.

One caveat that does not fit in a table. Cursor's beforeReadFile event takes allow or deny and has no "ask", so an unfamiliar read is allowed there rather than blocked — turning every unrecognised file read into a hard failure would make the integration unusable. A read of something LeastGrant recognises as a credential is still blocked, and shell commands and MCP calls get the full allow/ask/deny. The full matrix spells this out.

what it is not

It is not a sandbox

It answers a question the agent asks it. It does not confine a process, intercept syscalls, or contain anything already running. And it fails open: if the hook crashes or times out, the agent runs the tool call anyway. That is the hook contract, not a choice — LeastGrant is a reliable veto and a best-effort grant, and it is designed around that asymmetry.

The complete version — what it defends against, what it does not, the adversarial model for the learning itself, and what the v0.2.0 audit left standing — is in the threat model. The security page is the short version, including how to report something.