fiber

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:

EffectMeaning
readsobserves something without changing it
writeschanges something that persists after the call
executesruns a program
networksends 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 answersWhen
a fast path, a session grant or a standing rulethe call matches one
the reviewereverything 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").

  1. The credential deny: a call whose paths touch Fiber home's credentials/ is refused. See Credentials.
  2. A standing deny matching this call: refused. No model call, no question.
  3. A standing ask matching this call: a human is asked.
  4. 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_confined is allowed here, and a guarded one goes on to step 5.
  5. A session grant matching this call: allowed.
  6. A standing allow matching this call: allowed.
  7. 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:

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.

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:

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 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

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.

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:

  1. answers an approval with reply, on any live session socket. The rejection names reply and its target session, not the source session;
  2. sends prompt, steer, reply or sandbox to 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;
  3. 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