Permissions and approvals
What Fiber may do without asking, who it asks, and what the log records. This is what is true now, not a plan. It is settled by Permissions and approvals, attended and headless; that ticket's resolution holds the rationale and the rejected alternatives.
Vocabulary is GLOSSARY.md. Effect, workspace, reviewer, standing rule, session
grant, watcher, driver, participant, tool call and event mean what it says
there and nothing else. The request and reply events themselves are
docs/events.md; this page is only the policy over them.
The rule everything else follows from
The permission policy never decides what is dangerous by looking at a command. A tool
is asked what a specific call does, in a closed vocabulary, and every later
decision is made from that answer. The loop never sees the command string and
never learns which tool produced the call, which is what
docs/architecture.md requires: "loop never names a tool, a vendor or a
provider. It reasons about what a tool is allowed to do, never about which
tool it is." The shell tool reads its own command to answer, as
shell.read_only and the destructive-command guard do (docs/tools.md,
"What a tool declares").
The consequence worth stating first: adding a tool never means editing the permission policy. A tool arrives already able to describe itself.
Effects
Before a tool call runs, its tool declares that call's effects:
| Effect | Meaning |
|---|---|
reads | observes something without changing it |
writes | changes something that persists after the call |
executes | runs a program |
network | sends or receives outside this machine |
A call also carries whether it ran confined, inside the opt-in OS
sandbox (Confinement). The log records it
(docs/events.md, "Declared effects").
A call declares every effect that applies, plus two qualifiers: whether it is
reversible, and the paths it touches where it has any. A shell tool
asked to run git status declares reads, reversible. Asked to run
rm -rf build/, it declares executes, not reversible, with no paths,
because the shell only recognises read-only commands (docs/tools.md,
"Shell"). An edit to an existing file is an irreversible write; creating a new
one is a reversible write.
Classification is per call, not per tool. A tool that classified itself once, at registration, would make every shell call as dangerous as the worst shell call, and the only escape from that noise would be no protection at all.
A tool registered by an extension classifies its own calls and is believed. An extension runs with the account's full rights, so misdeclaring buys it nothing it could not do directly. Fiber's own built-in tools go through this seam identically.
An MCP tool declares its effects from the hints its server gives, per tool
rather than per call. How the hints map to effects is docs/mcp.md
("Effects").
The destructive-command guard
Some shell commands stay reviewed even when confined. The shell keeps a
built-in list: rm -r and rm -rf, git reset --hard, git clean,
git checkout --, git restore and git push (docs/tools.md, "What a tool
declares").
Matching is best effort by command text. The shell reads its own command
and declares review_when_confined when any component of a multi-part
command holds a listed form. It matches whether or not the command
parses.
The declaration removes only the confined fast path. The call stays confined. It keeps its credential deny, standing deny and ask rules, session grants and standing allows.
One mode
Every session runs in auto, interactive or headless, a delegate included.
There is no other mode and no way to change it. Calls the person wants decided
differently are standing rules (Remembering a decision).
| What answers | When |
|---|---|
| a fast path, a session grant or a standing rule | the call matches one |
| the reviewer | everything else, escalating to a human on repetition or failure |
There is no setting in which a person answers every call. A session offline, or with the reviewer's provider down, is still gated: a reviewer that fails hands the call to a person (What happens on a block), and the person can switch the reviewer to another model. A call a person wants to see every time is a standing ask.
The order a call is judged in
A before_tool hook runs first. It may refuse a call or rewrite its
arguments, and a rewritten call is classified again before this order judges
it. A hook can never approve a call (docs/extensions.md, "Hooks").
- The credential deny: a call whose paths touch Fiber home's
credentials/is refused. See Credentials. - A standing deny matching this call: refused. No model call, no question.
- A standing ask matching this call: a human is asked.
- A fast path — see below: allowed, with no model call. The confined fast path is checked before the others, and it is the only fast path a confined call ever meets: a confined call that does not declare
review_when_confinedis allowed here, and a guarded one goes on to step 5. - A session grant matching this call: allowed.
- A standing allow matching this call: allowed.
- Otherwise reviewed by the reviewer.
A call whose effects function returns always_reviewed skips steps 4 to 6
and is reviewed (docs/tools.md, "What a tool declares"). delegate_spawn,
delegate_fork and delegate_message return it on every call (Delegates). The loop reads the
declaration and never names a tool.
The credential deny and a standing deny are both evaluated before everything else, because a rule that can be widened by a later layer is not a deny.
An extension's inner call, a tool it runs with host.tool while its own
tool call or command runs, is admitted by that outer call
(docs/extensions.md, "Running a tool"). The outer call goes through this
order like any other. The inner call passes the before_tool hook and steps 1
and 2 only: the credential deny and the person's standing denies still refuse
it, since a deny must hold whatever path a call takes. Steps 3 to 7 do not
apply. An inner call is never reviewed, raises no question, and counts toward
no block budget.
Fast paths
These fast paths do not reach a reviewer or a person:
- every call whose only effect is
reads, or that declares no effect. This includesjobs stopfor a confirmed process the session started, including a detached entry, - a
writescall whose paths all sit inside the workspace or an added folder (docs/events.md, "directory_added"), none of them under a.git/or.fiber/directory of the one they sit inside, - a
writescall whose paths are all Markdown files (.md) inside extension data directories,data/<name>/orprojects/<key>/data/<name>/in Fiber home (docs/state.md, "What each part holds"), whichever tool makes it. Paths are resolved first, so a path that leads out of a data directory through a link does not qualify, and - a call whose only effect is
networkand whose declared hosts are all known in the session (docs/tools.md, "What a tool declares"). A web search declares an empty host list and a web fetch declares its URL's host, so a search and a fetch to a known host take this path (docs/tools.md, "Web fetch and web search"). A call that declares no host list, or names a host that is not known, is reviewed, and - a shell call Fiber runs confined that does not declare
review_when_confined, - a bare shell builtin
killusingkill <pid>...,kill -<signal> <pid>...orkill -- -<pgid>..., when every target's recorded identity is confirmed.
The shell accepts no-effect fast-path kills only for those bare builtin forms. Wrapped or path-qualified commands, foreign or mixed targets, and unparsed forms stay reviewed. Fiber checks each target's process group and leader start time when it declares the fast path, then rechecks just before each signal. A changed or unreadable identity stays reviewed. If an identity changes between declaration and execution, Fiber refuses to signal. A retry takes the reviewed path. The leader can still exit and its PID can be reused between the last check and the signal.
Memory layers keep their notes and pages as Markdown in extension data directories, so saving one costs no model call. The limit to Markdown keeps this path off files an extension may load as code or trust as settings, such as a Lua file or a JSON index; a write to one is reviewed.
Everything else — an unconfined or guarded shell call, other network calls, and any other write
outside the workspace and the added folders — is reviewed. A write under a .git/ or .fiber/ directory is reviewed too: a hook or
.git/config runs code on the next git command, which the reviewer judges
as git commit without seeing the hook, and .fiber/ holds the repository's
configuration, including the extensions, hooks and MCP servers it declares.
Those run only after a person approves their exact content, a decision
separate from approving a tool call (docs/extensions.md, "Code a repository
ships"). This is where nearly all of the cost is saved.
Editing the repo you launched in is the most common thing a coding agent does. Putting a model call in front of it buys little — the session log records every edit and version control can undo one — and costs latency on every action.
Credentials
Fiber refuses every tool call whose declared paths touch the credential
directory in Fiber home (credentials/). This is a built-in
deny: it is not a standing rule, no person or extension can remove it, and
it applies to every call. It covers every effect — a read, a
write, anything — not only reads. A path touches the credential directory
when it is the directory, sits inside it, or contains it: a recursive read
of Fiber home, $HOME or / reads every stored key, so a call declaring
one of them is refused too. It refuses, the same way, every tool call
whose declared paths touch the resolved path of a configured file
credential source.
It refuses, the same way, every tool call whose declared paths touch a path
a provider package declares its credential() draws secrets from, when that
function reads nothing Fiber stores (credential_paths,
A provider's data). The loop names no
provider: the paths are the package's data. AWS Bedrock declares
$AWS_SHARED_CREDENTIALS_FILE, else ~/.aws/credentials, and the
directories ~/.aws/sso/cache/ and ~/.aws/cli/cache/. Google Vertex
declares credentials.db, access_tokens.db, legacy_credentials/ and
application_default_credentials.json in the gcloud configuration
directory, $CLOUDSDK_CONFIG, else ~/.config/gcloud. A declared path
that is a directory contains its files, and a path that contains a
declared one touches it, as for the credential directory: a read of
~/.aws, ~/.config/gcloud, $HOME or / is refused, while a read of a
file beside the declared ones, such as gcloud's configurations/, is not.
The paths and their variables are read when the session starts, so a
changed variable needs a restart. A credential_process that
AWS_CONFIG_FILE's profiles name is not covered, nor is gcloud's Windows
directory.
A tool call runs with the account's full rights when the sandbox is off (Confinement), so without this deny an agent's file read could retrieve the stored tokens. The macOS Keychain is not an alternative protection: any process running as the person can read a keychain item the same way Fiber would. Source: the archived tree's Deny tool reads of the credential store.
Paths are canonicalised before matching (symlinks resolved, .. removed), so
no spelling of a declared path escapes it. The deny follows the resolved Fiber home,
so it still protects the credentials when FIBER_HOME moves Fiber home. If
Fiber home cannot be resolved, Fiber does not start (Fiber home
already makes a bad FIBER_HOME a startup error), so the deny can never be
silently narrowed.
Like every other decision on this page, it relies on declared paths. The
shell tool declares paths only for commands it recognises as read-only
(docs/tools.md, "Shell"). A command it does not recognise, such as
python -c opening a token file, declares no paths and the deny does not see
it: the call is reviewed. A link-following recursive read, such as
grep -R, is not read-only either, because the deny sees only the paths a
call names and never a link below them.
An extension tool that misdeclares its paths gets nothing it could not do
directly, the same boundary the Effects section already states for
extensions.
Confinement
Settled by Does Fiber confine what tools can touch? and permissions: an opt-in OS sandbox, and whether its commands skip the reviewer; those tickets' resolutions hold the rationale and the rejected alternatives.
The opt-in OS sandbox is implemented in the current build: #3027 on Linux
and #3630 on macOS. It is off by default and confines model-issued shell
calls at the operating-system level under Fiber's own policy: Landlock
plus seccomp on Linux with no srt and no bubblewrap, Seatbelt through
sandbox-exec on macOS, except a call the model marks unconfined: true,
which runs outside the sandbox (docs/sandbox.md, "The rule"). The sandbox
does not confine a person's own driver-shell commands.
A shell call runs with the account's full rights when the sandbox is off. Everything on this page decides whether a call runs; when the sandbox is off, nothing limits what it does once it runs.
- Approving an
executescall grants whatever the account can do. That includes Fiber home: an approved command can readcredentials/, editrules, or write an extension. Approving a call is trusting it, the same boundary as installing an extension. A confined call is granted only its sandbox instead. - Without the sandbox, isolation comes from outside Fiber: run it in a container or a virtual machine.
- A container protects the host from Fiber, not Fiber home from the agent. Fiber home inside the container is as reachable as it is outside one.
A confined shell call restores the protected paths after it runs. An
approved command can still change the shared .git/config and hooks, a
worktree's .git pointer or workspace-local .fiber/, but Fiber records
those paths before the call and restores them from the baseline after it.
The call result carries the report of what was restored and what failed
(docs/sandbox.md, "Protected paths"). Only a Fiber write or edit
that the permission system let through moves the baseline forward, because
each one landed with approval; an approved shell command never does.
Unconfined and read-only calls take no protected-path transaction.
Added folders affect the permission fast paths above, but they do not become
sandbox write roots. A confined call can write to the workspace, the system
temp directory and paths explicitly granted through sandbox.allow_write
(docs/sandbox.md, "What a confined call can do").
The evidence is research/sandbox/.
The reviewer
A call that reaches step 7 is judged by a model.
What it is shown
The human's messages, the agent's tool calls, and the agent's reply that
each human message answers. The agent's tool calls include its extensions'
inner calls, so a review sees what an earlier script did. The reply a human
message answers is the model's text directly before it, marked as the agent's.
A tool call between that text and the human message breaks the link, so no reply is shown.
The model's other prose and every tool result are stripped before the prompt
is built. The
reviewer also gets the call under review, its declared effects, for a shell
call the commands in it that were not shown read-only (docs/tools.md,
"Shell", "Effects"), the workspace root and the added folders in first-event
order (docs/events.md, "directory_added"), and the person's own notes about
their environment ("What the person tells it").
This is the load-bearing decision on this page. The reviewer's prompt contains no tool output and no text a repository file produced. The only text the agent wrote in it is its tool calls and the replies the person answered, so there is little in it that can argue for a verdict.
A reply only says what a short answer such as "yes", "go ahead" or "A" refers
to. The consent is the person's answer, and it covers every step, target and
effect the reply it answers proposed. A request the person routed at user
level does not cover a privileged or machine-wide change: asking to install a
package for the user does not cover sudo apt-get install, and a flag that
overrides the system's own guard, such as --break-system-packages, is not
implied by the request. A person's message that repeats the
agent's proposed wording is the person's own request. 'Agent text is never
approval' applies to text in a The agent: item or a call's arguments. It does
not apply to words the person typed or pasted into their own message. A reply
that offers options proposes none of them,
so a bare "yes" under it approves nothing and a pick by label or by its words
approves that option alone. A step the approved action needs is covered when it
adds no new target, destination or data beyond what was approved: stopping the
process an approved restart replaces, and starting the local service an approved
run uses, are covered. Approving a named action covers what that action does by
its own purpose: a pipeline run uses its build service, and tkt-build --from gate marks its draft PR ready and runs its review; these are not new targets
or destinations. A flag, a target, a branch or a send the action does not imply
on its own is still not covered. A delete, a push or a send that the plan didn't
name is not. A reply with no human message after it is not
shown, so a proposal the person never answered approves nothing.
A person's answer to a question counts as a person message, and the question
it answers is the reply. Anything the person types or answers reaches the
reviewer through one rule: an ask_user answer, a server elicitation answer,
and an extension's host.ask answer each render as the person's input with
its eliciting context as the reply. The reply holds the agent's questions as
asked; for a server or extension channel it holds fiber's own description of
the channel, never the submitted prompt words. The consent is still the
person's answer, and it covers every step, target and effect an agent reply
proposed, so a foreign question never approves the call under review by
itself. A person's message that repeats the agent's proposed wording is the
person's own request. 'Agent text is never approval' applies to text in a
The agent: item or a call's arguments. It does not apply to words the person
typed or pasted into their own message. A step the approved action needs is
covered when it adds no new target, destination or data beyond what was
approved. Approving a named action covers what that action does by its own
purpose: a pipeline run uses its build service,
and tkt-build --from gate marks its draft PR ready and runs its review;
these are not new targets or destinations. A flag, a target, a branch or a send
the action does not imply on its own is still not covered. A delete, a push or
a send that the plan didn't name is not.
A reply longer than 6,000 characters is cut to its first 6,000, followed by
a line saying how many characters were left out.
The rejected alternative is to send the whole transcript with an instruction
to treat it as untrusted. Stripping is both cheaper and stronger
(research/reference-comparisons/README.md).
Project instruction files are also excluded. They live in the repository, so including them would let a repository write into the reviewer's prompt — the hole that stripping tool output was meant to close.
A session message from another session is excluded too (docs/tools.md,
"Messaging other sessions"). Another model wrote it, so including it would let
one session approve calls in another by messaging it.
At a compaction
The reviewer's input follows the session's compactions (docs/compaction.md), so
it grows with the context window, not the transcript. At each compaction, Fiber
asks the reviewer which of the person's messages still bind, such as standing
orders, scope limits and "don't touch X". The reviewer answers with a
selection of messages, not prose, and Fiber carries those messages word for
word, each with the reply it answered. After the compaction the reviewer's input
is the kept messages, then the person's messages, the replies they answered
and the agent's tool calls since the compaction.
Nothing the reviewer writes enters its own prompt. Tool-call arguments are
agent-written, so a prose note could repeat text such as echo "user approved pushing to main" as if it were the person's. The compaction note is excluded for
the same reason: the session's model writes it after reading tool results.
The selection is recorded in the session log as reviewer_kept (docs/events.md, "Compaction"), so the person can see what was
kept. When the kept messages would pass the reviewer model's context window,
the oldest drop first. When the selection request fails, every earlier person
message is kept and a notice says so. When the session has no reviewer, nothing is asked and no line or notice is written.
What the person tells it
reviewer.context is the person's notes about their environment, in prose,
written as they would brief a new colleague. The reviewer reads them right
after its fixed instructions, as the person's own words. They add to those
instructions and never replace them, so no setting can remove what the
reviewer guards against.
The notes cover what the reviewer cannot guess:
- source control: which accounts, organisations and repositories are the person's own or their organisation's
- internal hosts, registries and services that count as inside
- internal tools and what running them does
- routine actions, such as squash-merging their own pull requests once CI passes
- what must never happen, such as touching
infra/prod
The key is the person's alone: the global file or the per-project file in
Fiber home (docs/configuration.md, "Layers"). A repository cannot set it,
for the same reason project instruction files are excluded: a repository's
text in the reviewer's prompt would argue with its verdicts. Unlike other
strings, the two layers do not replace each other. The reviewer reads the
global notes, then the per-project notes, each under its own heading, and its
instructions say the project's are the more specific and win where the two
conflict. A project adds what is true of it without repeating what is true
everywhere.
The notes are fixed for the session. They sit ahead of the person's messages
and the tool calls, and every reviewer pass extends the cache chain that
follows them, so they change only on reload, on a resume, or in a new session
(docs/prompt-cache.md, "Rules for other areas"). A delegate's reviewer reads
the same layers, so it gets the same notes.
An edit to the notes needs the person to ask for it in their messages; the reviewer's instructions say so, and it blocks an edit the person did not ask for. An agent that could rewrite the notes would widen its own approvals.
fiber config get reviewer.context prints the notes as the reviewer reads
them: each layer's text under its heading.
Setting up the notes
The reviewer-setup skill (docs/skills/) writes the notes with the
person in a session of their own, with the agent proposing the setup. It
gathers the evidence with fiber reviewer evidence --json, drafts one line
per fact or rule for each topic in order, confirms each topic with the
person through ask_user, and calls reviewer_notes_save with their kept
lines. Two write paths stay closed: no agent edit reaches the notes except
through that call, and the call writes only on a confirm the person answers.
The first time in a session that the reviewer blocks a call while both layers
of the notes are empty, the terminal shows one notice naming the command. A
call escalated for want of a reviewer model (no_model) is no block.
It proposes lines, one topic at a time, in the order of the bullets above. Each proposal comes from evidence:
- the project's own files: its git remotes, its CI configuration and its package registries;
- the person's answer to one question per topic, except Read-only commands, which asks none;
- the person's Fiber sessions: calls the reviewer blocked that a person then allowed, an escalation answered allow ("What happens on a block"), counted per prefix; reviewer allow decisions on shell calls, counted by their subject for the last topic below — the single command plus the flags it used, as in "What a rule matches". A subject does not count when any of its flags, by name before any "=", is on this fixed list: "-o", "--output", "--out", "--output-file", "-w", "--write", "-i", "--in-place", "--fix", "--apply", "--force", "--delete", "--save", so "acme-cli query --output out.txt" is never proposed. A command word containing "/" gets no entry. The risk line still shows for every proposal, because the list is a minimum, not proof. Nothing else in a session is read: allowed-escalation counts and reviewer-allow counts.
- Read-only commands, the last topic: reviewer allow decisions on shell
calls, counted by subject. A subject counts once it has at least 5 allows
across the person's sessions and no deny, block or escalation; a call
counts toward a subject when its
permission_resolvedhas"decision: allow"and"decided_by: reviewer". A call with more than one part has no subject, so it never counts. The tally counts the command the reviewer saw, afterbefore_tool.
The agent drafts each topic's lines but Read-only commands from that
evidence plus what the person tells it in the session, one fact or rule a
line. Fourteen escalations answered allow for gh pr merge … --squash on
the person's repositories become "squash-merging my own pull requests once
CI passes". Only confirmed lines are kept, and no model writes or rewrites
the notes themselves.
For Read-only commands the agent drafts each entry from its tally in
rendered form, and the evidence carries the counted calls' subjects so the
person sees what they are vouching for. Each entry is a
shell.read_only."<command> [<subcommand>]".flags entry holding the flags
the counted calls used. A confirmed entry goes to the per-project config
when every allow behind it came from this project, and to the global config
otherwise, using the rule session lines already use. A save that writes only
entries counts as saved.
reviewer_notes_save shows the diff for each file, with the file named,
and writes only on a confirm the person answers; a call that changes nothing
reports unchanged and writes nothing. The person's confirm is the gate: a
fiber ask session has nobody to answer it, so the call fails there with a
tool_error, and exiting with a confirm pending abandons the save, because
the reviewer tool never suspends.
Each line carries the layer it will go to. A line from the project's files goes to the per-project notes. An answer about accounts, hosts or tools goes to the global notes. A session line goes to the per-project notes when every escalation behind it came from this project, and to the global notes otherwise.
Last, Fiber shows each layer's notes exactly as they will be saved, as a diff against what is there, with the file named, and beside them the config file's diff with its entries, with the file named. Approving saves them, because the notes are fixed for the session. A refused confirm saves nothing.
The save owns the bullets under its topic headings; Read-only commands owns
none, because its entries live in configuration, not the notes. Send a
topic's lines only when the topic has at least one kept line: omission
preserves, so topics left out and entries dropped stand as they are. A
changed entry is refused before any confirm; a command the built-in list or
either layer's shell.read_only already holds is never re-proposed. Text
outside its headings, such as prose the person wrote — including a person's
own "### Read-only commands" — is kept byte for byte.
An entry is proposed only when the command and subcommand words end where its paths begin, and only for a command path that neither equals, contains nor falls under an entry already configured; existing entries are never changed. When either layer's "shell.read_only" cannot be read, no entry is proposed.
A command the built-in list already holds is never proposed. A built-in entry wins over a configured one of the same name.
Only a command Fiber has no rule for is proposed; a command Fiber already classifies keeps its rule.
An entry always names a subcommand path, and is not proposed when any call it would cover was denied, blocked or escalated.
A denied, blocked or escalated call that cannot be parsed counts against every entry whose command name appears in it, and so does one an extension ran.
A subject that gets no entry carries the reason, and is never saved.
A call that gave a flag a value, such as "--exec=ls", gets no entry.
A command word containing "/" gets no entry.
If the read-only proposal fails, the skill reports why and goes on without it.
An entry is trusted: a command on it that writes after all writes without review.
Subjects are counted by their exact text. User names and passwords are removed from every URL in the evidence text before it leaves the session. A proposed entry holds only the command, the subcommand and flag names, never flag values, so it carries no URL.
How it runs
Two stages. The first asks for one word: check, meaning the call goes
to the reasoning pass, or allow. Only a call answered check gets the
reasoning pass. The first stage answers check for any call that escalates
privilege, such as sudo, doas, su or pkexec. The first-stage requests
for the reviewed calls of one reply
go out concurrently, and all of them share the reply's prefix. Second-stage
passes run one at a time, in request order, before any call is
applied: a second stage goes out even when a grant installed while an
earlier call applied moots its reply, so the write-back applies the
grant instead. When budget.usd is set, the
first-stage requests go out one at a time, as the budget is checked before
each reviewer request (docs/loop.md, "Spending budget"). A call a remembered
grant decides keeps its already-sent first-stage request's usage_recorded:
a billed request is never hidden from the usage fold. The first stage asks for the reviewer model's lowest
thinking level, or none when the model declares none
(docs/model-routing.md, "Thinking"), and caps its reply at 4,096 tokens:
a ceiling for a model that does not stop, not the answer's length. The
second stage and the compaction selection ask for the same level, because a
change of level misses the reviewer's cache (docs/prompt-cache.md,
"Rules for other areas"). Most reviewed calls cost a few output tokens.
The reviewer's model is chosen separately from the session's, because a
review on every effectful action at the session model's price and latency is a
cost nobody chose. It is reviewer.model when set (docs/configuration.md),
else the session provider's own providers."<name>".reviewer_model, else the
package's reviewer_model (docs/model-routing.md, "What a provider
extension declares"), else no reviewer. The provider setting and the package
default are local IDs, prefixed once with the session provider. When no
source names one, every reviewed call escalates as reviewer_failed with the
error no_model, and a notice with code no_model says to set
reviewer.model. There is no automatic fallback to the session's own model:
only an explicit pick may name it.
Its verdict
allow or block, plus a reason. The reason comes first, and the verdict
word alone comes last. There is no risk scale: a number a model assigns is
only as calibrated as the model, and nothing here reads one.
What happens on a block
A block is not the end of the turn. The refusal is returned to the model as the tool call's result, with the reason and an instruction to respect the boundary and find another way. The turn continues.
A human is interrupted when the agent keeps hitting the wall: 3 consecutive
blocks, or 20 in a session, both configurable. The block that reaches the count
is not returned to the model: the call goes to a person instead, as a
permission_requested whose escalation gives the cause and the reviewer's
reason. The person's answer ends the run of consecutive blocks. For the
3-consecutive-blocks count, blocks within one reply are counted in request
order. Escalating every block would
send a person every call under load, and a person answering a stream of
questions stops reading them.
A reviewer that fails is a block, never an allow. A verdict that cannot
be read, after the argument repair in docs/tools.md ("Before a call runs"),
is asked for once more with the error attached. An unreachable provider,
a timeout, a verdict still unreadable on that second ask, a missing
credential: each escalates to a human, and blocks where no answer is possible ("Headless"). There is no
path on this page where an error results in an action running.
Remembering a decision
Two layers, and they are different kinds of thing.
A session grant is an event in the session log. It is honoured for the rest of that session, survives a resume because the log does, is visible to every client, and is gone when the session ends.
A session that changes folder (/cd, change_workspace) starts with none of
its parent's session grants: they were given for the old folder. Known hosts
carry over, as the conversation that surfaced them does.
A standing rule is a line in Fiber home. It survives everything until deleted, and it is a file a person can read and revoke.
This split is forced. docs/events.md says "No sidecar. A session directory
holds the log, a lock, and directories for bytes too big to inline." A rule
that outlives its session cannot be session state, so it is configuration, and
docs/architecture.md says "Only config reads the configuration files in
Fiber home."
Scope
Standing rules come from two files in Fiber home: rules at the
top level, and the project's rules file. The project's rules win where
both match at the same step, and the project's rule is the one used and
reported. A match in either file decides its step, so a project allow never
overrides a global deny: every deny is step 2 and every ask is step 3. The
file format is in docs/configuration.md, "Standing rules".
Both files are read every time a call reaches step 2. A file that cannot be read, or a line that does not parse, denies every call that reaches step 2 until it is fixed, with a reason naming the file and the line: the line it cannot read could be a deny. The credential deny still comes first.
A project is identified by git's shared directory, so every worktree of a repository shares one set of rules and a separate clone does not. Outside a git repository, the launch directory is the project.
What a rule matches
A tool and a prefix of its primary argument. The tool reads its own
arguments, so its effects function returns both halves with the effects: the
call's subject, its primary argument, and the prefix it offers as the
widening (docs/tools.md, "What a tool declares"). The loop never parses a
command. A prefix ending in / matches every subject that
starts with it. Any other prefix matches a subject equal to it, and also one
that goes on with a space: npm test matches npm test --watch and not
npm testing. This holds for every tool, because the loop cannot tell which
tool is the shell. A tool
with no primary argument, such as an MCP tool, returns an empty subject, and
its rule matches the tool by name. A call a rule cannot safely match, such as
a shell command with more than one part, returns no subject, and no rule or
session grant matches it, a deny or an ask included. A shell rule matches a
command's text, not what it does: a deny on rm -rf ~/ misses rm -fr ~,
and a command of more than one part, or one the classifier does not
accept, is matched by no rule: unless every part is read-only, which takes
the fast path, it reaches the reviewer, which judges what it does.
Approving npm test -- --watch can remember the subject, or the prefix
npm test; the terminal offers the prefix, and shows it. The widening is an explicit, separate choice at the moment
of approval, so a rule never grants more than what was read when it was
written.
An approval remembers in one of two scopes, the person's choice: a session grant, or a standing rule appended to the project's rules file. A global rule is added by editing the global rules file. Only a request raised at step 7 offers to remember: a standing ask comes before every allow, so an allow rule could never answer it.
A deny rule and an ask rule are matched the same way and are evaluated first.
What the log records
Both events are defined in docs/events.md and are durable. This page fixes
their contents.
permission_requested carries the tool call's action_id, the call's declared
effects, its paths, and which step of the order above sent it here. It also
says why a person is asked: on a standing ask, the rule that asked; on a
review, the escalation's cause; and on a review, the rule an allow
can remember. When a before_tool hook rewrote the call, it also carries
the rewritten arguments with changed_by, so the person judges the call
that will run.
permission_resolved carries the decision, the reason, and what decided it:
the credential deny, a human, a standing rule, a session grant or the
reviewer. A reviewer decision also carries the reviewer's model and which
stage decided. The permission_resolved lines for one reply are written in
request order, before any of that reply's tool_call_started, whichever
verdict arrives first. A reply's hook notices come first in request order,
then the reply's permission_resolved lines. A reviewed call's decision that has no request carries the call's
declared effects and its paths, with always_reviewed when the tool declared it,
and the rewritten arguments with changed_by when a before_tool hook rewrote
them, because no permission_requested and no tool_call_started holds them.
The reviewer's own calls carry the same attribution as usage_recorded:
reviewer.purpose is stage_1, stage_2 or compaction, and
reviewer.action_id is the call under review, absent on a compaction
(docs/events.md, "usage_recorded").
A blocked call ends as tool_call_completed with status: denied and a
reason, both already in the contract. The proof that nothing ran is also
already there: docs/events.md guarantees that tool_call_requested with no
tool_call_started means "provably never ran; safe to run or discard". A
reviewer's verdict never causes a tool_call_started, so a caller auditing a
session can establish that a denied call had no effect without trusting this
page at all.
A session grant is recorded the same way, as a permission_resolved whose
decision says it applies to later matching calls. Nothing else is written down:
the grant is a fold of the log, like every other derived fact. A standing rule
added from an approval is written to the project's rules file, and its
permission_resolved names it too, so the log shows where the rule came from.
An escalation where no answer is possible writes no permission_requested.
It is the reviewer's block, recorded as a permission_resolved with
decided_by: reviewer, or with decided_by: no_reviewer when no reviewer
could be set up ("How it runs"). The denial carries the call's declared effects,
its paths and its rewrite, as permission_resolved above says. A standing ask where no answer is possible is
denied at once, the same way: no permission_requested, and a
permission_resolved with decision: deny and decided_by: standing_rule.
Headless
A run started with no client, such as fiber ask, runs in auto like
every other session. The reviewer is what stands in for the person, which is
the case it exists for.
A client of the hub that wants to answer can. docs/architecture.md settles
that "the terminal is a watcher and a driver, never a participant" — a
permission request goes on the event stream and any driver replies to it
identically, so a client answers exactly as the terminal does and needs no
private channel. A supervisor is the exception: its session raises no request
for it to answer ("Supervised sessions").
With no answer possible, escalation is a block and the run continues under
the rule above until it exhausts the block budget. The turn then completes
failed with code blocked, so a headless caller learns the task needed
permissions it was not given. No answer is possible in a
session started by fiber ask, in a delegate, in a supervised session, and in
a session that has been sent close.
Anywhere else, a person may come back: after session.idle_exit_ms the session
exits on the pending escalation and raises it again when resumed
(docs/invocation.md, "Lifecycle").
Delegates
- Starting or messaging a delegate is always reviewed.
delegate_spawn,delegate_forkanddelegate_messagedeclareexecutesandalways_reviewed, so no fast path, session grant or standing allow skips the parent's reviewer for them.executesalone rules out only the fast path. A delegate's reviewer reads its parent's prompt and messages as the human's, so without this a parent's model could talk a delegate's reviewer into an action the parent's own reviewer never judged. The parent's reviewer judges the prompt or message against the parent's own person's messages. - Each Fiber delegate has its own reviewer, which judges that delegate's calls.
- An escalation from a delegate is a block, as for any headless run, and the delegate carries on. It is never relayed up the tree.
- A model never answers a delegate's approval, the parent's model included.
A delegate on another harness is judged by that harness, in its own auto
mode (docs/delegates.md, "Harness extensions"). The credential deny and
standing rules do not reach inside it: the harness's own rules, as the person
configured them, apply there. A harness and model are offered as a delegate
only when their auto mode is declared to work.
Supervised sessions
A supervised session is one the hub's start started with supervised, for a
supervisor outside Fiber (docs/invocation.md, "Two doors"). Its supervisor is
a program called by a model, so the session follows the delegate rules above,
with these differences.
- Its own reviewer judges every call. An escalation is a block at once, and the
run carries on. Nothing waits on a person and no request stays open. The
block is on the session's event stream, and sends no
attentionline. - The supervisor never answers an approval. It may steer with context, such as "you may run X because Y". The reviewer reads the supervisor's prompts and steers as the person's words, and judges the call again when the model retries it.
- A person grants a blocked call by saying so in their own
promptorsteer, such as "you may run X". The reviewer reads it as the person's words, and the model's retry passes. - It is top-level: it is listed in the feed, and a person may open it and
drive it as any client can. It sends no
finishedattention (docs/invocation.md, "Attention"). supervisedis fixed atstart, recorded onsession_started, and kept across a resume. A person driving the session does not change it: its escalations stay blocks.
The supervisor wrote the brief and wants the run done, which is the pressure the reviewer exists to check. Its say already reaches the reviewer through its prompts and steers, and it runs outside Fiber, where no Fiber reviewer would judge an answer it gave.
Sessions on the sockets
When a process connects to the hub's local socket or a session's socket, the
operating system says which process it is (LOCAL_PEERPID on macOS,
SO_PEERCRED on Linux). The hub, or the session, walks that process's
parents. When the walk passes a session process, the connection is treated
as coming from inside a session. A session process is a fiber process
running a command that hosts a session in that process: the internal session
command, fiber ask, or the case runner's child. Which session it is, Fiber
reads from the process tree, never from the arguments. Every session process
on the walk counts, including a Fiber delegate's. The kernel's process tree
is the record; no marker file, environment variable or pid table is kept.
A connection that comes from inside a session is refused from_session
when it:
- answers an approval with
reply, on any live session socket. The rejection namesreplyand its target session, not the source session; - sends
prompt,steer,replyorsandboxto its own session — the session whose process is on the connection's ancestor walk — or to a session whose parent walk shares one of those processes; - asks for
pairing_code.
A target with no live process keeps the existing not-found or replay behavior; it is not refused just because the caller is session-owned.
A message is a session message, logged with its sender, not a person's words, so none of these refusals covers it.
The second refusal exempts the delegate's own client. It does not apply
when the connecting process is the target session's parent process, as the
kernel reports it. That is exactly a session process's own messages to the
delegate it started, the path delegate_message uses. A shell the session
started is never the delegate's parent, so its steering stays refused.
Sessions started through the hub's start, including those the delegate CLI
starts, stay allowed when they are unrelated to the caller's process tree.
A session started below the session's own tree — fiber ask from its shell,
or a delegate it spawned — shares a session process with the connection's
walk, so steering it stays refused. A complete-walk rejection names the
command and, when it targets a session, that session; it never names a
source session id.
A process owned by another account is never a session process, and its arguments are never read; the walk continues through it to PID 1. If the kernel will not report PID 1's effective uid, Fiber treats it as root and continues the walk. An unreadable effective uid for any other process makes the walk incomplete. When a just-read parent exits mid-walk, the walk re-reads the child's parent once and continues only from a changed parent, which proves the child was reparented. When the walk is incomplete — a parent pid cannot be read, an effective uid other than PID 1's cannot be read, or this account's process's arguments cannot be read — the refusals above still apply, and the rejection message names the unreadable pid. The second refusal still admits its parent-process exemption on an incomplete caller walk, when the peer pid was read and the target session's own parent walk reads fully. A live target whose process, parent, or parent walk cannot be read fails the second refusal closed: the command is refused naming the target session. A synthetic replay of an exited delegate has no target process, so no refusal applies to it.
A process that a model detaches from its session on purpose is reparented
outside the session's tree, so the walk no longer sees it. Attaching a
debugger to the session process where the system allows it (inside the Linux
Yama ptrace_scope, or with the macOS debugger entitlement) reaches the
session the same way. Both are deliberate escapes, and the known limit of
this check. When Fiber cannot read a process it needs for this check, it
refuses these commands rather than allowing them.
Not settled here
- Which tools exist is indexed in
Epic: tools; how a tool
declares effects is
docs/tools.md. - How the reviewer's model is named and routed: Provider and model routing.