Part of the runner protocol. docs/protocol.md has the rules for all of it and which file each section is in.
A patch file is code. Importing it runs it, and its hooks, live state
functions and worktree setup then run by themselves, so without a gate
opening a thread in a repo someone else wrote would run that repo's code
before you'd said a word. The runner only imports a project's patch file
(src/patch-trust.ts) once that version of it is trusted, the way VS
Code and Claude Code ask before running a folder's code. Until then it's
in patches with untrusted and hash, and gives nothing: no actions,
panels or hooks, no live functions, and no worktree for new threads.
- On Windows, for now, a trusted patch runs nothing by itself: its
actions run when clicked, but its hooks, worktree
setupandteardownare dropped as it loads, and a live function'sshrefuses every command. The patch'sliveErrorsays so. Following a script there still has gaps a repo written against it could use (clicksOnlyinsrc/platform.ts). Home patches and Threadbear's own, which load without a hash, are as on a Mac. A schedule's check in a repo's folder (outside Threadbear's own checkout) doesn't run there either, approved or not: the run goes ahead without it and says why. The rule is read once as the runner starts. - Trust is kept per folder (the one holding
.threadbear/) as the SHA-256 hashes of the patch files trusted there, inpatch-trust.jsonin the data dir.untrustedis"new"when nothing from that folder is trusted and"changed"when an earlier version was: a pull brought a new one, and it's asked about again. - A git worktree counts as its main checkout, so a thread's worktree of
a trusted repo isn't asked about. Only one git made: its
.gitfile and the repo's record of it must name each other, so a folder can't claim to be a worktree of a trusted repo. The.gitmust be a plain file (a symlink to another worktree's, from a zip say, makes no worktree), and the record must name that very entry,<folder>/.git. - A patch file a Claude thread's agent writes with an Edit or Write call
on Full access, inside the thread's own folder, is trusted as that edit
left it: the agent can run anything in the folder already. Not in Ask
or Auto, where it couldn't: there the write waits for Mike like any
other, and the edit asks first (below, "Agent writes that run as
code"). The mode is the one the call went through on, recorded with
it, not the thread's when the result comes, so switching to Full access
after approving an edit in Ask doesn't trust it. Only the thread
folder's own patches (its
.threadbear/patches) and files inside that folder count: another project's patch, a tool patch, or a repo's under a thread in a folder above it (~,~/dev) waits too. Only an edit the CLI says it made counts, when its successful result comes in, never the diff shown to approve one, so a denied or failed edit trusts nothing. And only the bytes it wrote: the hash of the file rebuilt from the result (a Write's content, an Edit applied to the original text it reports), which the file must still have, in the same read the trust hash is made from. A file written over after that (a command run straight after the edit) isn't covered, and one the result can't be rebuilt for waits. An Edit or MultiEdit vouches only for what it changed: the rest of the file is the text it started from (the result's original), so it counts only when that was bytes trusted before (a version of a trusted patch or helper, or another such edit's), or when there was no file or an empty one. A Write is all the agent's. So a one-line Edit to a cloned repo's patch, or to a helper a pull changed, trusts nothing. Nor does one edit vouch for files it didn't write: the patch is trusted only when every other file its hash covers (its helpers, the scripts it names) is bytes that were part of a version trusted while the runner has run, or another such edit's. A patch Codex writes waits for Mike: its result doesn't say what bytes it wrote, so a command could have replaced the file before the runner read it. One written another way, like a shell heredoc or agit pull, waits. - Always trusted:
~/.threadbear/patchesand Threadbear's own checkout (the release'scheckout, else the one the runner runs from). patches.trusttrusts what the app showed, by hash. Clients show a waiting patch with a way to read its file and trust it.- A runner's first start with this (no
patch-trust.jsonyet) trusts the patch files of every thread's folder and every project's as they are, since it was already running them.
The hash covers the patch file and the local files it imports, and
theirs in turn (specifiers starting ./, ../ or /), so a pull that
changes only a helper is asked about too, and helpers lists them so the
app can say what else would run. It also covers any existing file the
patch or a helper names in a path starting ./ or ../, anywhere in its
text, from the patch's own folder or the folder holding .threadbear/
(where commands run), each place that has it: the script a worktree
setup, check, hook or action run calls, so a pull that changes only
that script asks again. What a named script runs in turn is followed
and hashed too (below, "What a script runs"), and a named file that
isn't there yet changes the hash when it turns up. The hash is SHA-256
over the JSON of ["threadbear-patch-3", <the patch file's SHA-256>, [[<path from the patch's folder>, <its SHA-256 or "missing">], ...]],
sorted by path, for every patch, helpers or not: JSON quotes each
string, so no two sets of files read the same. (Version 2 joined
<path> <hash> lines with newlines, and a folder named
lib.sh <hash>\nz could stand in for two files: Gautam's scan, 6 Nov.)
A patch that reaches a file whose path holds a newline or another
control character isn't loaded at all (below).
Only code is hashed. A file the patch, a helper or a script merely
names (a string, an argument, $(cat VERSION), < data.txt into
anything but a shell) goes in the hash only if it looks runnable: an extension of .sh, .bash,
.zsh, .ksh, .command, .js, .mjs, .cjs, .ts, .mts,
.cts, .tsx, .jsx, .py, .rb or .pl, the executable bit, or a
#! first line; a missing one counts only with one of those
extensions, or with no extension in a command's place (./bin/tool).
Anything else (./state.json, .cache/state.json by the repo's
absolute path, notes, pictures, folders) is data and isn't, so a patch
that writes its own state file isn't asked about again after every
run. What something runs, sources or loads is hashed whatever it looks
like: an import, a file sh, bash, node or bun is given
(sh ./x.json), a sourced file, the package.json, .npmrc and
the like a package script runs from, a Makefile. The limit: a hashed
script's behaviour can still depend on the data files it reads, which
can change without asking. Trusting a script trusts what it does with
its data, so a script that runs what a data file says (sh -c "$(cat cmd.txt)") still fails closed, as below. A command that runs by itself
(a setup or hook) must still be one hashed script, so naming a data
file there refuses the patch as before. Packages (node:fs, anything
npm installed in node_modules) aren't followed: they're the folder's
dependencies. A package the repo commits is its own code, though (below,
"Committed node_modules").
A patch whose code can't all be seen isn't loaded at all, trusted or not,
and has error (not untrusted) saying why, as a stored hash can't vouch
for code it didn't cover: one that loads code by a name worked out as it
runs (import(name), import(`./${x}`), require('./a' + b), any
createRequire, node:module, node:vm, node:worker_threads, eval,
a data: or # specifier), in the patch file or a helper, one the runner
can't parse, or one that reaches more than 100 local files. Loads are read
from the parsed syntax (oxc), so comments and strings don't count either way. patches.trust can't trust it; changing it to plain
imports can. An agent's Edit or Write to a helper carries on the trusted
patches that import it, as it does for the patch file (only with the
helper as that edit left it, and an Edit only of the helper as it was
trusted); it doesn't trust a patch that's still waiting. A trust file
from an earlier version (version: 1 or 2) is
read as it is, but its patch hashes are kept apart (legacy: in front,
written back as version 3) so none can match a version 3 one, and every
patch it trusted is asked about again ("changed"), once: nothing is
carried over, as an old hash can't tell apart the file sets it was
fooled by. (An old helper-less hash is the file's own SHA-256, so an old
patch whose text was a version 3 hash's JSON would otherwise match the
patch that JSON names.) Each trusted version of a patch is a module graph
of its own: the patch, its helpers and the packages its repo commits are
imported at their own paths with that version's id as the query
(?tb=<id>, from the patch's path and hash), with their import edges kept
under those URLs, so a new version loads its own helpers at once and no
version is ever handed another's helper or follows another's edges, a
late import() included (Daybreak 131, 15 Nov 2026). Node keeps CommonJS
by path whatever the query, so a trusted patch's graph refuses a CommonJS
file (a .cjs, or a .js with require and module.exports); one
written with import and export (.ts, .js, .mjs) loads, and a
bare import of a package the repo commits loads only while the
package.json Node resolved it by is this version's, byte for byte.
What's imported is what was hashed. The hash is made from one read of
each file, and a trusted patch and its helpers are imported from those
bytes (src/verified-imports.ts, Node's module hooks), never read from
the folder again, so a command that rewrites one between the check and
the import changes nothing that runs. Imports are told apart by how
they're written: a local one (./, ../, /, file:) loads the very
file the hash followed it to, from the hashed bytes, whatever a symlink
points at by then (into node_modules too), and one the hash didn't
follow refuses the patch; a bare one (a package, node:fs) resolves
as Node resolves it, unhashed, as packages are the folder's dependencies,
and must land in a builtin or in that package's own folder in a
node_modules (node_modules/zod/...), else it refuses the patch. Node resolves a bare name through the nearest
package.json's own name and exports before node_modules (so a
patch importing its own package's name is refused outright), so a
pull that renamed the repo's package zod sent import 'zod' to one of
the repo's scripts (Gautam's scan, 6 Nov); a workspace package (a link
in node_modules to packages/x, which Node follows) is a file of the
repo's that nothing hashed in the same way, so it refuses the patch too.
# imports are refused for the same reason (above).
Committed node_modules. A repo can commit its own
node_modules/zod (git add -f gets past .gitignore), and import 'zod' from a trusted patch then ran whatever a later pull put there,
unasked. So files git tracks under any node_modules folder of the
repo, submodules included (inactive ones too, as their files are on
disk), are the repo's own code: once the patch, a helper, or a script one
of its commands runs has any bare import that isn't a builtin, every one
of them is hashed with the patch and followed for its own imports like a
helper, and the patch's imports of them are served from those bytes.
All of them, not only the named package's folder: Node also finds
node_modules/payload.js for require('payload'), a package a pull adds
later, or one in a parent folder, and an installed package may import a
committed one, and on a Mac node_modules finds a committed
NODE_MODULES too. Packages npm installed (untracked, ignored) aren't
hashed, so an install never asks again (Mike's call, 7 Nov). A package
manager finds them without any import naming one, so npm run, yarn x,
npm install, npm rebuild, npx x, npx -c x, node --import x (a #
mapping or a URL there can't be followed) and a package's
node_modules/.bin put on PATH by hand count as a bare import does, once a
node_modules is on the way up from where they run. An install's and a
rebuild's lifecycle scripts run from a committed package's own folder, so
they're followed from there, past node_modules too, and a file committed
under .bin is followed as what runs, as a shell would. A workspace or file: package isn't
under node_modules at all: npm links it there, so its files are the
repo's. A script a command runs that has any bare import hashes and follows
every such package linked into a node_modules on the way up, not only one
it names, as an installed package may import one (and a package script or
npx running its bin follows that), each file of it but its own
node_modules, up to 300, as its package.json decides which an import
loads. One holding a link or a native addon can't be followed, nor a
committed or linked package whose exports, main, module or bin, or a
bare import itself (wsp/payload, or payload for a file of that name in
node_modules), names a file that isn't
JavaScript, or a pattern that doesn't end in it, and nor can a script that
requires a file of the repo's by a name that isn't JavaScript or JSON:
Node runs any of those as CommonJS, and what it loads wouldn't be followed.
Nor can a script that imports its own package by name, where the
nearest package.json has that name and an exports: that package.json
is noticed, not hashed, as an install writes it, so a pull that renames the
repo's package shows the next time the patch is looked at or a chip pressed.
(A patch's own import of one is refused, above.) The index files git keeps (each
submodule's too, and each submodule's .git, so checking one out later
shows) are watched, so a pull that starts tracking node_modules/zod
over an installed copy asks again, and the module hook
refuses a committed file under node_modules that a patch's import
reaches but the hash didn't cover. When git can't say what it tracks (it
fails, or the folder isn't a git checkout but has a node_modules, which
could be from npm or from the zip), a link the repo commits under
node_modules, a committed native addon (.node), or more than 100
committed files under node_modules, the patch isn't loaded at all
(error). git runs with core.fsmonitor off, so a folder's own
.git/config can't make that run anything; so does every other git the
runner runs in a thread's folder (the Claude settings check's listing of
skills, worktrees, moves), all through runner/src/safe-git.ts. A move's
git goes further (untrustedGit, below under "Moving a thread", Git). A cached hash holds only while every file it was
made from has the same inode, size, mode, mtime and ctime (a write
can't put ctime back), every path to one still leads to the same real
file, and nothing that was missing has turned up. A hook or setup
runs its script from the folder, so the patch is hashed afresh just
before it runs, and it's skipped with a system.note if that isn't the
version that was trusted.
So trust covers the bytes of the patch and the code it names, checked
right before they run. What a trusted script does as it runs (the files
it reads, copies or generates, like cp ./payload.txt ./stage.sh && sh ./stage.sh) is trusted with it, and a change another process makes
while it runs isn't caught: the same as running a shell script you've
reviewed.
A new thread's worktree setup runs only when the worktree's own copy of
the patch, with the files it names as they are there, is a trusted
version, and it's that copy's setup that runs: the worktree is main's
commit, which can differ from the main checkout that was trusted.
Otherwise the setup is skipped with a system.note saying why, and the
thread starts in the worktree anyway. A worktree's teardown is read the
same way, from the worktree's copy as the thread's branch has it when the
thread is archived or deleted: a teardown changed on the branch (a commit,
a pull) is a version nobody trusted, so it doesn't run, and a
system.note (a notice, for a deleted thread) says so.
Commands that run by themselves. A project patch's worktree setup
and teardown and its hooks run without anyone pressing anything, so the hash has to
cover what they run, and it can only see a path written in the patch.
So each must be one script and plain words: a ./ or ../ path from
the folder holding .threadbear/ (for a patch file that's a link into
another folder, the one holding the link, where its commands run, and
where what its scripts run is followed from too), to an existing file inside the repo
(the git toplevel) that the hash covered, then arguments made only of
letters, digits and _ @ % + = : , . / -. Anything a shell would work
out first (cd scripts && ./setup.sh, FOO=1 ./x, sh -c, bash x.sh,
npm run x, npx tsc, pipes, ;, $(...), quotes, globs, a path
worked out in code) could run a file the hash never saw, so the patch
isn't loaded at all, trusted or not: its error starts Not run:,
names the command and says to put the steps in a script. The runner then
runs the script by its absolute path (a hook's exec), every word
quoted, from the folder holding .threadbear/ (cd '<folder>' && '<script>' ...), so it's the hashed file that runs, and the folder its
own relative paths were followed from: a hook in a thread in a subfolder
runs the patch folder's ./scripts/x.sh from the patch folder, not the
subfolder's. Home's patches and Threadbear's own checkout are trusted
whatever they hold, so their commands run as written.
What a script runs. A trusted ./setup.sh that runs ./helper.sh
must not run a changed helper unasked, so from every script a patch
names, the runner follows what it can run or read in the repo and hashes
it with the patch (runner/src/script-trust.ts), up to 300 files and 12
scripts deep:
- Shell scripts (by
#!or.sh/.bash/.zsh), read with a small shell lexer: a command that's a path (./helper.sh,"$(dirname "$0")/x.sh",${0%/*}/x,"$DIR/x"afterDIR="$(cd "$(dirname "$0")" && pwd)"or$(git rev-parse --show-toplevel)),source/.,sh/bash/zshwith a file or a literal-c,node/bun/deno/tsxwith a file, whatenv,exec,nice,nohup,timeout,taskpolicy,xargs,find -execand the like run,trapwith literal code, and the$(...)s in words, assignments and unquoted here-docs. Acdto a path it can work out is followed, so later relative paths resolve. - Package scripts by a literal name:
npm run x,npm test,yarn x,pnpm x,bun run xhash the nearestpackage.jsonand follow that script (and itspre/post) as shell from the package's folder, a program in it thatnode_modules/.binleads to a file of the repo's included;npm ci/install(any package manager) follows the lifecycle scripts (preinstall,postinstall,prepare...) of the package, its workspaces and itsfile:dependencies;npx x/bunx xhashpackage.json..npmrc,.yarnrc(.yml),bunfig.toml,.pnpmfile.cjsandpnpm-workspace.yamlbeside it are hashed, and code they load followed. They're read a line at a time (a multiline regex over the whole file was quadratic in a run of blank lines, so a few MB of newlines held the runner before anyone was asked: Gautam's scan, 6 Nov), each once per hash, and one over 1 MB fails closed, as does a quoted path with an escape that can't be read or a YAML value that isn't a plain path (a tag, anchor, alias, block, or a flow value with a path in it). A plugin's- path:counts, and so does Yarn Classic'syarn-path ./x.cjs. make: the Makefile (and literalincludes) is hashed and every recipe line followed as shell,$(MAKE)asmake, read a line at a time, and one over 1 MB fails closed.-f/-Ccount however they're written (-fx.mk,-sf x.mk,--file=x.mk), and-f -(the Makefile from make's input) fails closed, as does anincludeof one; every-fis read, a rule's recipe after;is followed, a comment is only a comment,-Ifolders are searched for includes, each-Cgoes on from the one before, and.RECIPEPREFIXandX != cmdfail closed asSHELLdoes. A shell script over 1 MB fails closed too, and so does any file over 32 MB a patch reaches (its hash can't be made). A path into the repo by another name (/tmpfor/private/tmp) counts as the repo's.- JavaScript and TypeScript: imports, as for patch files (a package
the repo commits too, "Committed node_modules" above), and every
plain string that's the path of a file of the repo's that looks
runnable (
spawnSync('bash', ['scripts/x.sh'])). - A file redirected into a shell or
source/.(bash ... < ./steps.txt), whatever it looks like: a flag that makes the shell read commands from its input would run it. - Any other file of the repo's a script names (an argument,
< file, a./path anywhere in its text) is hashed if it looks runnable (above, "Only code is hashed").
What it can't follow, it doesn't guess at: eval, alias, bash -c or
trap with code worked out as it runs, $(cat "$f") or $(< "$f"), a
shell, node or bun reading its program from a pipe or a here-doc
(curl ... | sh), node --env-file, a $'...' with an escape in a
command or file's place, more than 8 wrappers deep, or from a path that's its input or a file it has
open (sh /dev/stdin < ./steps.txt, node -, bash -s after
--rcfile, a #! with -s, -c or -i, /dev/fd/N, /proc/self/fd/N,
/dev/tty, or anything outside the repo that isn't a plain file), a
command in a variable or a pattern ($CMD,
"$f" in a loop, ./s/*.sh), source "$1", relative paths after a
cd to somewhere worked out as it runs, npm run "$x", npx "$x",
workspace-wide runs (-w, --filter, -r), node -e, --require
of a module worked out as it runs, a file that isn't there yet
(./build/out.sh), another language (python3 x.py, a #! that isn't a
shell or Node), an awk program that runs commands, $(shell ...) or
SHELL or .SHELLFLAGS set in a Makefile (after export or
override, or for a target), and setting PATH to a folder in the repo,
BASH_ENV, NODE_OPTIONS that loads code and the like. (An empty PATH
entry, a leading or trailing : or ::, is the current folder, so that's in
the repo too; a package's node_modules/.bin is followed instead.) A worktree
setup or hook that names such a script fails closed: the patch isn't
loaded, trusted or not, and its error starts Not run: with the file,
line and what it couldn't follow. So does an action whose command reaches
one, though it runs only when pressed ("Commands a patch writes" below).
Programs on PATH and installed packages aren't followed: what one
loads from the repo by its own rules (a test runner's tests, a linter's
config, npx bddgen's config) is the folder's to change, as
node_modules is for patch files. So a script should run only tools
it's fine to run on the repo as it is then.
Commands a patch writes. An action's run isn't held to the
one-script rule: it runs only when someone presses its chip, which shows
the command. But what it runs is hashed however it names it, not only
past a ./ path: every string in the patch and its helpers (an
action's run, sh("node scripts/stats.mjs") in a live function, the
fixed parts of a template) is followed as a shell command from the
folder holding .threadbear/, as above, and every file of the repo's it
runs or loads goes in the hash (a data file it only names doesn't), so node scripts/deploy.mjs asks again when
only scripts/deploy.mjs or one of its imports changes (Daybreak
verify-fix, 5 Nov). A trusted-by-hash patch's command actions run from
the folder holding .threadbear/ (the action's folder), where they
were followed from. Each is followed again as the patch loads, and one
the hash can't vouch for refuses the whole patch, its error starting
Not run: its action: one worked out in code ('node ' + f) that reaches
a file the hash didn't cover, or one that can't be followed all the way
(eval, python3 x.py, a script that isn't there yet, a dynamic import
in a script it runs), as the follow stops at the first of those and what
comes after was never seen (Daybreak, 7 Nov). A string in a patch that
isn't an action's command can't stop anything: it may not be a command at
all. Pressing the chip checks again: the patch is hashed afresh as the
action starts, and must still be the version trusted, with the command
reaching only files that covers, from the folder it runs in (for a tool
patch, its own folder too), as a script runs from the folder and not from
the bytes that were hashed. Otherwise actions.run fails with `Didn't run
The short list of shell. A live function's command, and a folder's
Claude Code hooks and settings commands, run by themselves, and the
follower above looks for the shell tricks it knows: every review round
found one it didn't (here-docs, $'\142ash', sh /dev/stdin, env -S,
a } that zsh reads as the end of a group). So those commands are also
parsed into a small grammar and held to an explicit list of programs, and
anything outside it isn't run (src/shell-allowlist.ts; Mike's call,
7 Nov, narrowed the same day after an outside review). A fork whose
patches run something else adds it to the list there. On the list:
- Grammar, for both: simple commands of literal words,
'...'and"..."strings,\x,$NAME,${NAME},$?,$!,$#,$$,$0-$9,$@,$*,~and~/x, and$(...)whose commands are on the list too; pipes,&&,||,;and new lines;{ ...; },( ... )and!before a pipeline;name=valueon its own, for a lower-case name that isn't in the environment or one of zsh's own (path,fpath...). A lone{or}anywhere but opening or closing a group is refused, after a redirect or as a redirect's target too, as zsh and bash read it differently. - Redirects, for both, in every script too:
>and>>only to/dev/null, written just so, andN>&M. Nothing writes a file.<takes a literal path in a hook, and only/dev/nullin a live command. - Program names are compared in lower case, by the name they run as (a
path's last part, which must be what the path resolves to), so
GIT,/usr/bin/gitandgitare held to the same, and a link namedcatto/bin/shis refused. A builtin or reserved word in another case or by a path (CD,/usr/bin/cd,IF) isn't the shell's own, so it's refused. &, for a live command only: when its shell exits or times out, its whole process group gets SIGTERM, then SIGKILL 2 s later if any of it is still there (runCommand'skillGroup). A program that leaves the group (setsid,setpgid, a daemon that forks away) isn't reached; nothing on the live list does that (ssh -fisn't on it, and a fetch's automatic gc is off, below).
A live command runs only what Mike's patches run (as of 7 Nov), each in the forms they use, and every word literal: known as it's checked, not split. There is no fallback for other installed programs.
| Program | Forms |
|---|---|
| builtins | echo, true, exit <n>, test -f|-d|-e <path>, kill [-signal] <pid> where the pid is $! or a variable only ever set from it |
cat |
<path>... |
grep |
[-c] <pattern>; the pattern may be worked out as it runs if it's a quoted word starting with literal text that isn't - ("adb-$s"), so it can't be an option |
sleep |
<seconds> |
dns-sd |
-B <type> <domain> |
ssh |
-o ConnectTimeout=<n>, -o BatchMode=yes, <host>, then what runs there: read as shell and held to plain commands and pipes of launchctl list, df -h <path>..., memory_pressure -Q, tail -1, readlink <path>, echo |
git |
fetch [-q] <remote> [<ref>], merge-base --is-ancestor <rev> <rev>, rev-list --count <rev or range>, branch [-a] [--no-merged <rev>] [--sort=...] [--format=...] (no operand, as one makes a branch; only the format atoms cannvas uses, not %(signature)) |
gh |
pr list [--state ...] [--limit <n>] [--json <fields>] |
npx convex |
data <table> [--component <name>] [--prod] [--format ...] [--limit <n>], run [--prod] stats:overview or adminStats:overview; convex must be in node_modules/.bin and lead to the convex package, so npx never fetches or is pointed at something else, and not beside an .npmrc with a key outside a short list that only say where packages come from |
tandem |
waiting [--json] <path>... |
stocks |
balance, positions |
node |
<file> <words>, no options: a file of the repo's, followed and hashed, or ~/dev/me/poddle/scripts/asc-status.mjs <digits> (below) |
| a file of the repo's | by its path, a shell script or JavaScript, hashed and followed; what a script runs is held to this same list (it may also use if, while, until, for, case, comments and set -e and the like), and its #! must be a shell run plainly |
A live command that runs a file of the repo's may run beside it only what
changes nothing (echo, true, exit, kill, test, cat, grep,
sleep, dns-sd), or it could change that file first.
git and gh (which runs git) run only in a repo whose own config, its
.git/config, a worktree's config and what they include, keeps to settings
that add nothing git runs: the repository format, remotes reached over
https or ssh whose fetch fills remote-tracking refs or tags, branches,
user.name and the like. Any other (core.hooksPath, core.fsmonitor,
core.sshCommand, include.path, filter.*, diff.*, alias.*,
protocol.*, url.*, remote.*.vcs, gpg.*...) and they aren't run.
That's checked as each command starts, so every live command also runs
with git settings in its environment (GIT_CONFIG_COUNT, which needs git
2.31; an older git isn't run), which beat the repo's own whatever it says
by then: core.fsmonitor=, core.hooksPath=/dev/null,
safe.bareRepository=explicit, only the https and ssh protocols, no
submodule fetches, no saved cookies, no alternates command, no automatic gc,
your own core.sshCommand (or ssh), every credential helper turned off and
your own (system, global) put back after, and no askpass program or prompt.
Filters and diff drivers can't be turned off by name, but the repo's own are
refused above, and none of those git commands reads the working tree or makes
a diff, so your own (git-lfs) don't run either.
A script outside the repo runs only if it's on the list above and nobody
but you or root could have written it, or a live command's chip hides.
From the path as written, each folder it passes through must be yours or
root's and not writable by its group or others (a sticky one like /tmp
aside, where only an entry's owner can rename it); each link, followed as
the system does, yours or root's; the file yours or root's, a plain file,
and not writable by its group or others; and the whole path must resolve,
with no . or .. as written. On macOS, ls -led must show no access
list entry that allows anyone else to write, add to or delete from any of
them (a deny entry, as macOS puts on your home folder, is fine). On Linux an
access list's mask is the group bits, so the mode covers it; on anything else
it's refused. What that script imports isn't checked, so it's held to where
it is. If the check fails, Walkies' and StashIt's App Store chips (which run
node ~/dev/me/poddle/scripts/asc-status.mjs) hide. Threadbear's own
app-store.ts isn't held to any of this, as Threadbear's own patches aren't.
A Claude Code hook (or settings command) has a fuller list, as its text
is fixed by the hash rather than built as it runs, but no &:
- The same grammar and redirects; in a script it runs (and a package script)
also
if,while,until,for ... in,case, comments,set -e,-u,-x,-o pipefailand zsh'ssetoptof those. A script's#!must be a shell run plainly (-e,-u,-xat most). Acdto a known folder must be able to work now; one through a link, or based on${BASH_SOURCE[0]}or a sourced file's$0, which differ between shells, loses track of where it is, so a relative path after it is refused. - Builtins:
cd,echo,printf(a number format only with plain numbers, as zsh's reads them as arithmetic),true,false,:,test/[(numbers compared only when they're plain),exit,return,shift,break,continue(a plain number),read -r,waitandkill($!, a variable only ever set from it, a plain number or%1),pwd,which,type,command -v, and./sourceof a file of the repo's by a path (./lib.sh), followed as part of the same shell. - A file of the repo's (a shell script or JavaScript, followed, and hashed);
sh,bash,zsh,dashorkshwith a script, andnode,bunortsxwith a file (nodewith--no-warningsand the like at most;bunandtsxnot beside abunfig.tomlor atsconfig.jsonwithpaths, andbunnot beside a.envthat setsNODE_OPTIONSand the like);npm run x,npm test,pnpm run x,yarn run xandbun run xfor a script that's inpackage.json, followed (withpreandpost) as a script with the package'snode_modules/.binfirst on PATH, and not beside an.npmrcwith a key outside that short list, a.pnpmfile.cjs, or a YarnyarnPathor plugin;env,nohup,niceandtimeoutonly around a script of the repo's. - A script outside the repo, run by an interpreter or by its path, only if
nobody else could have written it, as above, and not a package's own program
(a path through
node_modules, asnpm-cli.js exec xruns what it's told). - Otherwise only programs that load no code from the folder, run nothing
they're handed and write no file, every word literal (
HOOK_PROGRAMS):cat,head,tail,ls,date,sleep,say(-vand-ronly, as-owrites),afplay,jq,grep,tr,wc,cut,uniq(one file, as a second is written),basename,dirname,realpath,readlink,stat,pbcopy,pbpaste,whoami,hostname,uname,tput,notify-send,logger.findwith literal words and none of-exec,-execdir,-ok,-okdir,-delete,-fprint,-fprintf,-fls.awkwith a literal program with nosystem,getline,|,>,@orENVIRON, and only-Fand-v. Nottee,cp,mv,rm,mkdir,touch,ln,chmod,mktemp,curl,wget,sed,sort,git,gh,ssh,npxorbunx.
Refused, for both: here-docs and here-strings, process substitution,
backticks, $((...)), [[, ((, globs and brace expansion outside a
case pattern, ~user, zsh's =cmd, $x[1] and $x:h, ${x:-...}
and every other ${...} form, an unquoted #, ^ or ! in a word, &>,
>|, |&, &|, a redirect with no command, functions, alias, eval,
exec, trap, export, VAR=x cmd, any other builtin of bash or zsh
(emulate, zmodload, r...), a command named by a variable whose value
isn't known, and a word worked out as it runs anywhere a program's words are
checked. Mike's own live commands all keep to it (as of 7 Nov), except
walkies-arrow's older Pixel check, which still runs perl and was already
hidden.
A patch asked about again says what changed since the version last
trusted in its folder (src/patch-changes.ts), in PatchInfo.changes:
the files whose bytes differ (changed), that its hash now covers and
didn't (added: a new helper, or one Threadbear now follows) or no longer
covers (removed); for each, the commits since then that touched it and
whether what's on disk is committed; and the lines, for a changed file
both of whose versions could be checked against their hashes (the old
side read with git cat-file from the commit trusted then, or HEAD's,
only when it hashes to what was trusted; the new side only when it still
hashes to what the ask is for). A folder whose only patch hashes are from
before version 3 gets { recheck: true }: its trust is from before the
6 Nov change to how patches are checked, so nothing says whether this
patch was trusted before (the hashes are per folder) or what changed. The thread's note names
the files too. When git takes more than five seconds, the rest are named
without commits or lines, and git isn't asked again for a minute. A file
outside the folder, or a symlink, gets no commits or "not committed", as
git can't speak for its bytes; a diff line over 1000 characters is cut
with a note saying so, never silently.
Each trusted version (when, its files by SHA-256, the repo's HEAD) is kept
in patch-trust-versions.json beside the trust file, the last five a
patch; a version trusted before this was kept goes in the next time it's
seen trusted. It only describes: nothing in it trusts anything, and a
missing or unreadable one only means the ask says less. Commit subjects,
paths and lines are the repo's text, shown as plain lines with control and
direction characters replaced, so they say who wrote a change only as
far as git can be believed: the lines are what to read.
The runner starts Claude in a thread's folder with that folder's own
settings, .claude/settings.json and .claude/settings.local.json, and
its .mcp.json (the folder's, and those of the folders above it, up to
home), and Claude loads the agents, skills and commands in .claude/agents,
.claude/skills and .claude/commands of the folder and the folders above
it (up to home), and a skill in .claude/skills anywhere under the folder
once the agent works on a file beside it (CLI 2.1.318). Some of what they
hold is a command Claude runs by itself: hooks (a SessionStart hook runs
as the CLI starts), statusLine, subagentStatusLine, fileSuggestion,
apiKeyHelper, proxyAuthHelper, awsCredentialExport, awsAuthRefresh,
gcpAuthRefresh, otelHeadersHelper, extraKnownMarketplaces (and its
alias additionalMarketplaces), an MCP server with a command or a
headersHelper, and the hooks and mcpServers in an agent's, skill's
or command's frontmatter. The settings' env counts too, as a whole:
nothing in it runs, but any variable can send Claude's traffic and the
user's login elsewhere (ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY,
HTTPS_PROXY, CLAUDE_CODE_USE_BEDROCK and its endpoint, OTEL_*
exporters) or load code (NODE_OPTIONS, PATH). In a thread that asks
before tools run (Ask or Auto), so do the parts that let tools run without
asking, as Claude applies them before the runner's approval card: the
settings' permissions (allow rules, additionalDirectories,
defaultMode, anything but deny, ask,
blockReadsOutsideWorkingDirectories and disableBypassPermissionsMode,
which only narrow), sandbox (turning it on lets sandboxed Bash run
unasked), a skill's or command's allowed-tools and an agent's
permissionMode. In Full they grant nothing more, so they don't count
there. Claude Code in a terminal asks before trusting a folder; the SDK
never does, so the runner asks instead (src/claude-trust.ts), with
patch trust's store and rules.
- On Windows, for now, a folder whose settings have any of those starts
Claude without them whatever's been trusted, as one that can't be
checked does, with nothing to trust (
clicksOnlyinsrc/platform.ts; "Trusting a folder's patches" says why). - A folder whose settings have none of those (a model, plugins switched
on, deny rules; allow rules in a Full thread) asks nothing, and nothing
changes. Nor does home, whose
.claude/settings.jsonis the user's own; a thread there starts with the user and local settings only (settingSources: ["user", "local"], home named as an extra directory for its CLAUDE.md), as the project source would have Claude pick up the.claude/skillsof any folder under home as the agent works there. Frontmatter is read as top-level keys at the left margin. - Otherwise the hash covers those parts, by file, and every file inside
the repo that they reach: each word in them that is a file there, with
a
/or without (node hook.mjs, a server's"args": ["server.js"],NODE_OPTIONS=--require ./x.js, an allow rule'sBash(./scripts/x.sh:*)), and what each command runs in turn, followed as patch trust follows a patch's commands (src/script-trust.ts: imports, shell scripts,npm run,make). Each command (a hook's,statusLine's, a helper's, an MCP server's) is also held to the short list of shell a live patch command is ("The short list of shell", under "Trusting a folder's patches"), without&; both must pass. Settings with commands and noenvor grants hash as they did before those counted, so trusting them holds. It's kept inpatch-trust.jsonin the folder's list, asclaude:<hash>, under the same folder key, so a worktree counts as its main checkout and Threadbear's own checkout is always trusted. - What the hash can't cover can't be trusted, whatever's stored: a
command that runs code it can't follow (
python -m x,node .,curl ... | sh, a command in a variable, a dynamicimport()in a script it runs), a package run by name (npx,bunx,pnpm dlx,npm exec), a test runner finding its own tests (node --test,bun test), an MCP server that sets its owncwd(its files are followed from the folder), a program on PATH, anywhere in what a command runs, that may load or run code from the folder by its own rules (a formatter, a test runner, a build tool,git, which an alias orcore.hooksPathmakes run anything) rather than a script, a shell, a JS runner, a package script, a function the script defines or a program known to do neither (echo,say,afplay,jqand the like,INERT_PROGRAMSinsrc/script-trust.ts, which the short list narrows to ones that write nothing), a file or folder in the repo named in an environment variable, or any named there by a relative path (PATH=./bin,PYTHONPATH=.,BASH_ENV=./startuporBASH_ENV=startup,NODE_OPTIONS=--require ./x.js: whatever reads the variable loads it from wherever it runs),--preserve-symlinksfor Node, a settings file that isn't plain JSON,hooksormcpServersfrontmatter that isn't YAML in the one shape read line by line (block mappings and lists, each nested deeper than its key, with one-line plain or unescaped quoted values or one-line[a, b]lists: no block scalars, escapes, anchors, tags, comments, flow mappings or quoted keys), other frontmatter that can't be read key by key, more than 300 files, or more than 20,000 folders to look through for agents, skills and commands (nested skills, outside git, or through a link to a folder). Nor can an allow rule (orallowed-tools) that covers Threadbear's own tools (mcp__threadbear...,mcp__*,*, or bypassing permissions:defaultModeor an agent'spermissionMode), in a thread that asks first. JavaScript a hook reaches that runs commands itself (child_process,Bun.spawn) is one too: what it runs isn't followed. - While that version isn't trusted, a Claude thread's
patcheshas{ id: "claude-settings", source: "claude", file, untrusted, hash, helpers?, grants? }:fileis the first file with something that runs,helpersthe other files and the scripts,grants(a thread that asks first) what they'd let run without asking, in words ("Allows Bash without asking (.claude/settings.json)"). One that can't be trusted is{ id: "claude-settings", source: "claude", file, error }instead, with no hash to trust. Codex threads don't get it. - A Claude session starts without the folder's project and local
settings (
settingSources: ["user"]), and gets back, as flag settings (the SDK'ssettings), only what can't run anything or widen access, merged as Claude merges them: the narrowingpermissionsabove,model,effortLevel,alwaysThinkingEnabled,outputStyle,language,attribution,includeCoAuthoredBy,includeGitInstructions,respectGitignore,cleanupPeriodDays,enabledPlugins,deniedMcpServers,disabledMcpjsonServers,claudeMdExcludesandskillOverrides. Flag settings sit above project ones, and Claude takes some keys from them that it ignores from a repo (processWrapper,autoMemoryDirectory,sandboxpaths), so the copy is a list of what's kept, not of what's dropped. The folder is named as an extra directory withCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1, which brings its CLAUDE.md back without its settings. What doesn't come: the folder's.claude/skills,agentsandcommands, CLAUDE.md files above the folder, and.mcp.jsonservers. The thread gets asystem.notesaying so, once per version. patches.trustwith thatfileandhashtrusts it. Trusting the version a thread that asks first was shown also trusts what it runs for a Full thread there. A session that started without them is replaced by a fresh one (resuming the same conversation) at the next message, as is one that started with them when a new version arrives that isn't trusted, or when the thread leaves Full and the folder's grants aren't trusted. A CLI's own turns between messages keep what it started with, except that a session started in Full with grants that aren't trusted for a thread that asks first (heldGrants) sends every tool call to the approval check, past the CLI's allow rules, from the moment the thread leaves Full (a PreToolUse hook answeringask).- What a command reaches is hashed up to the top of the repo, or of the
outer repo when an
.mcp.jsonor.claudefolder above the thread's folder is in one (a thread in a submodule). - An agent's Edit or Write to one of the settings files trusts them as it leaves them; to a script they name, only when an earlier version was trusted, as with a patch's helpers. Either only with the file as that edit left it, and every other file the settings' hash covers bytes trusted before or another such edit's, as for patch files. The same rules as there: only on Full access, only a file inside the thread's folder, and an Edit only of a file that was trusted bytes (or none).
Agent writes that run as code (src/code-writes.ts). Outside Full
access, permission to edit a file isn't permission to run it, so an Edit,
MultiEdit or Write by a Claude thread in Ask or Auto, or a Codex patch
outside Full access, of a file Threadbear runs by itself always asks: a patch file anywhere (.threadbear/patches,
home's included, which is trusted whatever it holds), anything under
~/.threadbear, a file a patch the runner has hashed covers (a helper, a
script it names, one it names that isn't there yet), .claude/settings*.json
(home's too), an .mcp.json, a script the thread folder's Claude settings
name, the runner's own data dir (patch-trust.json is the trust itself),
every file a schedule's check on this runner reaches from its folder (the
check's scripts, what they run in turn, absolute and linked ones, one it
names that isn't there yet; a check still running though its schedule was changed or deleted since,
here or in the runner handing over (its running marker says what and where;
an older release's that doesn't makes every edit ask until it ends),
paused and finished schedules too, as Resume and
Run now run them again unasked; read afresh at each edit, so a new or changed
check counts at once, and a check that runs something it can't follow makes
every edit in its repo ask): its approval is a digest taken just before the
shell opens them, so an edit after that would run unattended (Daybreak 126),
every Claude login's user settings (settings*.json and .claude.json in
its config folder, and ~/.claude.json, by their names whether they're
there yet or not, and what a link from them points at) and the paths their commands and the thread folder's
settings' name, there yet or not, from the login's folder or the thread's
(where hooks run), with what each command reaches as a shell runs it (the
script, quoted names included, and what it imports or runs in turn), and
for patches that load without trust (home's, Threadbear's own checkout's)
what each is a link to, imports and names, absolute or ~/ paths in it,
and what each command it runs reaches (its scripts outside the folder too)
from where its commands run: the thread's folder, or for a patch from a folder
of one of the thread's projects, that folder, as its hooks run there at the end
of the thread's turns. Its commands are what reaches somewhere a command runs
(src/patch-commands.ts): a call to the sh its live functions and items
are handed (as sh(...), ctx.sh(...), taken out as { sh } or handed to a
helper in the same file), an object's run, setup, check or teardown,
and node:child_process's exec, execFile, spawn and fork (their Sync
forms and promisify too). Each is worked out from the code as far as it
plainly can be: strings, templates, +, constants declared once with const,
path.join and the like, import.meta.dirname and .url, fileURLToPath,
homedir(), a one-line helper (quote(s)), [...].join(' ') and both sides of
a ? b : c. Anything else is a value worked out as it runs, followed as an
unset shell variable: fine as a plain argument (gh pr view ${n}), and
something it can't follow where it picks what runs (node ${script},
${bin} --help, sh -c ${x}). One command it can't follow (a script that
isn't there yet included, as the follow stops there) makes every edit ask. A
file it can't read that way (one that imports a package or a Node module that
could run something, like node:cluster, or passes sh or a child_process
function around, takes a property by a computed name, has a getter, or uses
require or import()) is read as before, and so is every other file of
that patch, as well as exactly. A default export whose actions, hooks or
worktree aren't written out as objects in it (built from JSON, or a list
changed after it's made) makes every edit ask, as its commands could be
anything. A child_process call runs
from the runner's own folder unless its cwd says otherwise, and is followed
from there. Read as before means: every string in it as a command it
might run, except for strings found only in place in the patch file's own
export default { ... } as its icon, appliesTo or worktree.keep, or an
action's, panel's or hook's title, note, icon, on, tell, prompt,
url or edited, and plain web addresses with nothing a shell would split or
expand. How a patch quotes a value it splices into a command is its own
business, then and now: what's checked is which files it runs. When a patch
makes every edit ask, the thread says so (a system.note, once per patch and
command, the first time an edit asks for it) and the patch's entry in
Patches has editsAsk: which file, the line and command, why, and what to
change. A patch's worktree setup or check doesn't count either: setup runs what's committed, in a new
worktree, and the check when a land is asked for, so neither runs what an agent
just wrote until it has got past a step that's asked about. Its teardown
does count, as it runs in the worktree as the agent left it. A repo's setup has to
keep that true: worktree-setup.sh won't npm install in the main checkout while
it has uncommitted changes. A patch using this or a getter gets none of this. A settings hook that can't be followed all
the way doesn't: those are the user's own hooks, so what they load by a
name worked out as they run, or from outside the repo they're followed
in, isn't guarded. What such a hook runs by name (npm test, a tool on PATH)
is the folder's own code, run as its owner set it up, and isn't followed.
Names are matched as written and as the disk has them (through symlinks,
a link to a file not there yet included, and without case, as macOS names
a file either way). The runner's PreToolUse hook answers ask for these,
which reaches the approval card whatever an "Always allow" rule, the
user's own allow rules or Auto's classifier would have said. The card's
title ends "(Threadbear runs this file as code)", or "(Threadbear can't tell
whether this file runs as code)" when only the catch-all above made it ask, and
its options have no
allowAlways, and an allowAlways answer counts as allow once (Codex:
the thread's file-change rule is passed over for it, and isn't added). What
it writes still isn't trusted (above): Mike trusts it in Patches. On Full
access none of this changes anything.
Built in, from the folder alone:
| patch | when | panel |
|---|---|---|
convex |
a folder with convex/ and a package.json or convex.json beside it (a bare folder called convex isn't enough) |
convex.dashboard, a url panel: https://dashboard.convex.dev/d/<name> for the CONVEX_DEPLOYMENT in .env.local (then .env), http://127.0.0.1:6790 for an anonymous local deployment, the dashboard's front page with no deployment yet. A cloud deployment's panel also has convex, with the deployment's URL from the .env.local (then .env) line ending CONVEX_URL (CONVEX_URL, VITE_CONVEX_URL, ...). Only those lines of the file are read, and a file over 64 KB is skipped as if it weren't there |
xcode |
a folder with an .xcodeproj or .xcworkspace |
xcode.simulator, an image panel drawn by panels.render |
worktree |
a thread with a worktree of its own (see Worktrees) | no panel: the action worktree.land, "Land", which runs tb land |
A client shows what it can: a url panel in a web view, an image panel
by asking panels.render now and then while it's on screen, a list
panel the same way (when it's shown and every 15 seconds while it is),
and an unknown kind as a page if it has a url.