Guardrails

This page describes the guardrails level, which is off until a .fettler.json has a guardrails section. At the tools level, the launch folder is the tree and the client's own file tools still work beside Fettler. A guardrails section replaces the launch folder with the trees you declare. fettle setup guardrails then denies the client's built-in file, shell and output tools, so Fettler is the only route to a file.

An assistant given guardrails cannot wander, because everything outside the trees is refused. Every path it touches must sit inside a tree, a folder you named ahead of time. Outside those trees it may not write, read, list, or even learn that a file exists. There is no current folder to change, no path that climbs out of a tree, and no shell to go round it. So the assistant cannot open a sibling project, an old copy or your home folder, read the wrong thing, and answer from it.

fettledeclared trees · no shell

The workstation, drawn

These two drawings show one machine with guardrails on. The first is the disk: the folders a developer has, which ones the assistant may enter, and every way off the machine. The second is the mechanism that holds that arrangement in place. The first answers what the assistant can reach, and the second answers how that is enforced.

No command produced this arrangement. A person wrote every line of it into two short files at the top of the project. They are a checked-in .fettler.json and an uncommitted .fettler.local.json beside it. Both are printed in full under the map, so you can trace every block to the line that put it there.

⛶ Full screen

Here is what drew it. Read these two files beside the map. Every lit block above is a line below, and every dark block is dark because no line mentions it.

// .fettler.json - checked in, travels with the project
{
  "guardrails": {
    "trees": {
      "work": {
        "path": ".",
        "can": ["list", "read", "create", "update", "rename", "delete", "execute"]
      }
    },
    "tasks": {
      "build":   { "run": "pwsh -File build.ps1 build", "cwd": "." },
      "test":    { "run": "pwsh -File build.ps1 test",  "cwd": "." },
      "feature": { "run": "pwsh -File scripts/shoddy-branch.ps1 feature hebdenbridge", "cwd": "." },
      "ship":    { "run": "pwsh -File scripts/shoddy-branch.ps1 ship -Yes", "cwd": "." }
    }
  }
}

// .fettler.local.json - not checked in; this machine's own trees
{
  "guardrails": {
    "trees": {
      "requirements": {
        "path": "../shoddy-planning/requirements",
        "can": [],
        "scopes": {
          "backlog":    { "can": ["list", "read", "create", "update", "rename"] },
          "inprogress": { "can": ["list", "read", "create", "update", "rename"] },
          "cancelled":  { "can": [] },
          "completed":  { "can": [] }
        }
      }
    }
  }
}

The table matches the map to the files. It includes the three things on the map that no line in either file could have put there.

Here is how it is held. The next drawing shows the same arrangement as three boundaries. They are what the assistant is, the one program between it and the disk, and the disk as the declared trees present it.

⛶ Full screen

• The model boundary has a part that persuades and a part that enforces. The instruction files persuade the assistant to use Fettler. The deny list in the client's settings enforces it. The built-in tools are denied by name, and Fettler's tools have different names, so denying Read does not deny mcp__fettler__read.
• The tool boundary is fixed before the model says anything. The server reads its trees from .fettler.json, and no tool takes a root or a configuration file as an argument. The files that govern the tool and the model are refused by every write. That is the rule that makes every other rule hold.
• The filesystem boundary is what remains. Outside the declared trees and the folders fettle found, nothing exists for the assistant. A path there is refused in the same words whether or not a file is there.

Turning guardrails on

Write the guardrails section yourself, before you run anything. fettle setup guardrails writes a starter section when the file has none, but it declares only the launch folder as work. A file nobody read is still the boundary you are running under. Each step below needs the one before it.

# 1. write a "guardrails" section in .fettler.json      <- your trees; nothing below writes them
# 2. add your machine's own trees to .fettler.local.json   <- not checked in
# 3. add "tasks" if anything needs running
fettle doctor                                            # what is wired, and what goes round it
fettle setup guardrails claude-code --local --dry-run    # what would change
fettle setup guardrails claude-code --local --hooks      # change it
fettle doctor                                            # confirm, and see what is left by hand

Run doctor again at the end. setup clears each finding whose fix is to add something. A finding whose fix is to remove something, such as 2.6, 2.7, 2.11, 2.14 or B.17, is still there afterwards. You remove those entries yourself, in an editor.

Declare your trees

A tree is a name, a path, and a list of what may be done there. You may declare more than one, and a folder of code plus a sibling folder is the ordinary case. Put them under trees in the guardrails section of .fettler.json, at the top of the project, and check the file in.

{
  "guardrails": {
    "trees": {
      "work": { "path": "." }
    }
  }
}

That is the smallest useful section. Here is a fuller one, with a second tree kept read-only and one folder inside it hidden:

{
  "guardrails": {
    "trees": {
      "work": { "path": "." },
      "requirements": {
        "path": "../shoddy-requirements",
        "can": ["list", "read"],
        "scopes": {
          "backlog":           { "can": ["list", "read", "create", "update", "rename"] },
          "backlog/cancelled": { "can": [] }
        }
      }
    }
  }
}

The defaults

The defaults are the narrow ones, and only the file can widen them. The reference gives the full rules.

• A guardrails section with no trees is refused. To use the launch folder as the tree, leave the section out and stay at the tools level.
• Paths are relative, forward-slashed, and read from the file's own folder. That is what lets the file be checked in. The spelling table has the cases.
• A tree that does not exist is a startup failure. So the checked-in file should name only trees that travel with the project. Anything else belongs in the overlay below.
• A tree may not be called scratch, tool-results or memory. fettle gives those names to the client's folders, which it opens at every level.

Scopes and hidden folders

A scope states permissions for one folder inside a tree, and it replaces what the tree grants. It does not add to the tree. A scope naming create and nothing else grants create and nothing else, not even read. Saying it at a depth has the rules for scopes inside scopes.

A scope with an empty can list is hidden. find and search do not show it, and a path into it is refused in the same words as a path outside every tree. In the example above, backlog may be reorganised but never deleted, and backlog/cancelled does not exist for the assistant.

A worked guardrails file

On the left is a whole guardrails file, and on the right is what roots says with it in place. Notice that the guardrails line now names the file. The work tree grants execute because the file says so, and the shoddy tree is read-only by default.

// C:\github\app\.fettler.json
{
  "guardrails": {
    "trees": {
      "work": {
        "path": ".",
        "can": ["list", "read", "create",
                "update", "rename", "delete",
                "execute"],
        "scopes": {
          "secrets": { "can": [] }
        }
      },
      "shoddy": { "path": "../shoddy" }
    },
    "tasks": {
      "build": {
        "run": "pwsh -NoProfile -File app-build.ps1",
        "cwd": "."
      }
    }
  }
}

$ fettle roots
levels
  tools         on, always
  guardrails    on, from C:\github\app\.fettler.json
  screenings    off

trees
work          C:\github\app  (default)
              can: list read create update rename delete execute
              branch: main (local)
              secrets  can: nothing
shoddy        C:\github\shoddy
              can: list read
              branch: main (local)

found by fettle
scratch       C:\Users\you\AppData\Local\Temp\claude\...\scratchpad
              ...
tool-results  C:\Users\you\.claude\projects\c--github-app\...\tool-results
              ...
memory        C:\Users\you\.claude\projects\c--github-app\memory
              ...

declared by C:\github\app\.fettler.json

The folders fettle found are still there. Guardrails replace the launch folder with your trees, and they leave the client's folders open. The client's folders describes each one.

The personal overlay

An uncommitted .fettler.local.json beside the project file is merged over it. Your machine's own trees go there, so they never appear in anybody else's checkout. Keep it out of source control.

• The overlay merges section by section. It may hold any of the three sections, and each one it holds is merged over the same section in the project file.
• Inside a section, an entry named in both files is the overlay's entirely. A tree named in both takes the overlay's version, not a mix of fields. Nobody reading two files side by side could say what a field-by-field merge produced.
• An entry only one file names is kept. So the overlay can add a tree without repeating the project's trees.

A changed file applies on the next call. The server re-reads the file it found before every call, so you do not restart anything. The server still cannot widen its own boundary, because it refuses to write that file.

Declare your tasks

Declare a task only if something in this project needs running. run starts only what the file declares, and it never builds a shell command. It also needs the tree to grant execute, which is never a default.

{
  "guardrails": {
    "trees": {
      "work": { "path": ".", "can": ["list", "read", "create", "update", "rename", "delete", "execute"] }
    },
    "replacements": {
      "feature-branch": "hebdenbridge"
    },
    "tasks": {
      "build":   { "run": "pwsh -File shoddy-build.ps1" },
      "gate":    { "run": "node scripts/gate/driver.mjs gate --resume", "cwd": "." },
      "sign":    { "run": "signtool sign /f \"C:\\keys\\my cert.pfx\" bin/app.exe" },
      "feature": { "run": "pwsh -File scripts/shoddy-feature.ps1 new {feature-branch}" }
    }
  }
}

• Name the program that is installed. A task naming pwsh on a machine that has only Windows PowerShell fails when it starts, not when you declare it.
• A task takes no arguments from its caller. A variant is a second declared task, or a value the file declares. The command grammar is exact about quoting and backslashes.
• A value that changes each time goes in replacements. Today's branch name is a fresh string each time, so it cannot be a second task. Declare its name once, write it in braces on the command line, and keep the value in the overlay. Values the file supplies has the rules.
• cwd is optional. It is the folder the task runs in. It defaults to the top of the default tree, and it must sit inside a tree like any other path.
• Start script and task names with your project's own name. Use shoddy-build.ps1 rather than build.ps1, and a checkin task rather than commit. The client's own permission check reads these names, and it can refuse a task named with a bare git word as if it were that git command.

Run fettle setup guardrails

fettle setup guardrails <client> | --all [--local | --global] [--hooks] [--deny] [--dry-run] [--force] [--command PATH]

  clients: claude-code · claude-desktop · vscode-copilot · github-copilot

The level is the first word. fettle setup tools writes the registration and nothing else, and installing it covers it. fettle setup guardrails writes the files on this page and never registers. The old spelling, fettle setup claude-code, is refused, and the message shows the new spellings.

The deny list

The deny list names the client's built-in tools that could reach a file without Fettler. It lives in the client's settings, such as .claude/settings.json. Setup writes it at --local, and it never writes settings.local.json, because that file is somebody's own and is not committed. Here is the list it writes for Claude Code:

{
  "permissions": {
    "deny": ["Read", "Write", "Edit", "NotebookEdit", "Grep", "Glob",
             "Bash", "PowerShell", "Monitor",
             "BashOutput", "TaskOutput"]
  }
}

• The deny is by tool name, and Fettler's tools have other names. Denying Read does not deny mcp__fettler__read. So the deny sends the assistant to Fettler rather than leaving it with no tools.
• Tools that start work of their own are not denied. An agent or a skill runs its own tools, and whether the deny list reaches that work is the client's decision. fettle knows these tools by name, so 2.18 does not report them, but it leaves them open.
• The list of tools is dated. doctor prints the date it was last checked against a real client. Finding 2.18 reports any tool a settings file names that this fettle does not know.

The shell is denied by name, never by command

No list of writing commands can close a shell, so the shell itself is denied. echo x > file turns any command into one that writes a file. python -c does the same, and so does a redirect on any command at all. A list of forbidden commands could never be finished.

Denying the three shell names is short and closed, like denying the six file tools. What cannot be finished is the list of commands behind them, and that is the allow list's job. Deny the shell, then allow back the few commands this project needs:

{
  "permissions": {
    "allow": ["Bash(git status:*)", "Bash(git diff:*)"],
    "deny":  ["Read", "Write", "Edit", "NotebookEdit", "Grep", "Glob",
              "Bash", "PowerShell", "Monitor",
              "BashOutput", "TaskOutput"]
  }
}

• Build and git commands through the shell stop when the deny lands. Setup says so in its report. Allow back each command you need, or declare it as a task, which runs through Fettler with execute.
• Never allow back a command that writes files. An allow entry such as Bash(rm:*) or PowerShell(Set-Content:*) runs without a prompt, and it is a complete route round the trees. doctor reports each one as 2.6.

On deny versus allow

Whether a deny beats an allow is the client's decision, and fettle cannot see it. fettle is a separate program, so it cannot watch how another program resolves its rules. So doctor reports the conflict, as B.17, and names the fix that is right either way: remove the allow entry.

• A narrowed shell allow beside the shell deny is not a conflict. allow: Bash(git status:*) with deny: Bash is the shape the section above asks for, so B.17 leaves it alone.
• A narrowed allow on a file tool is still a hole. Read(//c/work/**) beside a denied Read is reported, because reading is what Fettler does. doctor reports an allow on a replaced tool as 2.7.
• Setup never removes an allow entry. It is your own configuration, so setup names the entries that conflict and leaves them for you.

The instruction block

The instruction block tells the assistant how to work here, and the deny list makes it so. Setup writes the block into the client's instruction file, such as CLAUDE.md, between markers it can find again. The block holds a tools paragraph, which says to call roots first and that there is no working folder. setup guardrails adds the guardrails paragraph, as written:

**Guardrails are on.** The built-in Read, Write, Edit, NotebookEdit, Grep and
Glob are denied. Use the Fettler tools for every file operation.

**A tree may be read-only.** A scope inside a tree may allow more or less
than the tree does. Running a declared task needs `execute`, which is never
a default.

`.fettler.json` and `.fettler.local.json` say what Fettler may do. Fettler
does not write them. A person edits them.

Running setup again rewrites the block between its markers and changes nothing else in the file. CLAUDE.md is not a governed file, because it persuades rather than permits, and an assistant keeping a project's instructions up to date is ordinary work.

The session hook

The session hook runs fettle doctor --hook each time a session starts. It is for Claude Code only, and you ask for it with --hooks. When nothing is wrong it prints nothing. When something is wrong, it prints the broken or missing registrations and the serious findings, then the line run: fettle doctor.

• It always exits 0. A check that could stop a session from starting would soon be removed.
• It is added once, however often you run setup. It does not depend on whether the deny list needed changing, so asking for it on a project already denied still adds it.
• It names the fettle you ran setup with, by its full path, unless --command names another.

The entry it adds to the client's settings file:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [
          { "type": "command", "command": "\"C:\\tools\\fettle\\fettle.exe\" doctor --hook", "timeout": 10 }
      ] }
    ]
  }
}

Every flag, and what it decides

What it will and will not correct

• It merges into JSON and never overwrites. These files hold other servers, other permission grants and other hooks. Setup adds its own entries, keeps everything else, and makes a backup at <file>.fettler-backup before its first write.
• It does not remove your policy. An existing allow entry is your own configuration, and removing it changes how you work. Setup names the entries that conflict and leaves them.
• It creates a guardrails section, and never changes one. Creating one where none exists is a starting point. Rewriting one is the escape that the governed-file refusal closes, so it belongs to a person with an editor.
• Running it twice changes nothing. A registration or entry that already says something different needs --force, so setup never quietly reshapes somebody else's choice.

Run fettle doctor

doctor reports one section per level, and it reports findings only for a level that is on. A finding is a way round the boundary, with a number and the fix that clears it. At the tools level its section shows the registrations, the client's folders and any companions. With guardrails on, it adds the guardrails section below. It never writes anything, and it never prints a secret.

$ fettle doctor
fettle 2.1.0  C:\tools\fettle\fettle.exe
on PATH: C:\tools\fettle\fettle.exe

tools  on, always
  claude-code     global  healthy   registered; runs C:\tools\fettle\fettle.exe
                          C:\Users\you\.claude.json
  claude-code     repo    absent    'fettler' is not registered in this file
                          C:\github\app\.mcp.json
  scratch: C:\Users\you\AppData\Local\Temp\claude\c--github-app\...\scratchpad, found as ...

guardrails  on, from C:\github\app\.fettler.json
  tool inventory dated 2026-08-20. Check 2.8 does not know tools added to the client since then
  - 2.8  deny does not list the built-in Read, Write, Edit, NotebookEdit, Grep, Glob, Bash, PowerShell, Monitor, BashOutput, TaskOutput. Run: fettle setup guardrails claude-code --local
      C:\github\app\.claude\settings.json
  - 2.17  1 other MCP server is registered here: sparky. ...
      C:\Users\you\.claude.json

screenings  off

Exit 0 means healthy, 1 means warnings, and 2 means broken. A broken registration and finding 2.19 are the two things that give exit 2. ! marks a serious finding, and - marks one worth knowing. Everything doctor can report gives a row for each finding, with the edit that clears it.

Finding 2.11, two spellings of one project folder, belongs to the tools level and is reported there. Finding 2.15 is retired, and its number is not reused, because fettle now opens the scratch folder itself.

How 2.8 reads the client's files

2.8 judges the deny list the way the client merges its files. A deny in .claude/settings.json holds whatever .claude/settings.local.json says. So a tool counts as missing only when no project-level settings file of that client denies it. The finding names .claude/settings.json, which is the file fettle setup guardrails CLIENT --local writes. Running that command clears the finding.

When a companion's folder is inside a tree

A companion reads and writes every file under its folder, with none of Fettler's rules. With guardrails off, that is one line of fact. With guardrails on, doctor reports 2.19 as serious when the companion's folder sits in any of these places:

• Inside a declared tree. The tree's permissions and scopes mean nothing to the companion. A folder that is exactly a declared tree is reported as a fact instead, because the two share files on purpose.
• Inside a screened tree or scope. The companion reads those files with no screen.
• In a folder that holds a governed file. The companion could rewrite the file that turns guardrails on and off.

The fix is to move the companion's folder outside every tree. Change the --root in its registration. Do not deny the companion, because that would remove the thing it is for.

The four verdicts

Verify the guardrails hold

Prove the boundary holds. Do not trust that it does. Correct wiring and a boundary that holds are two different claims, and only the second one matters. Ask the assistant to do each of these, and watch what comes back.