Repository navigation
Product Book Readonly
Part of the Product Book. Observable product behaviour at
pi-schematic@36bd569(main, 2026-10-12).
Readonly gives a Pi coding-agent session a research posture: the agent can continue to inspect material and delegate work, but ordinary editing and filesystem mutation are restricted. This is useful when the task is to understand or review rather than change a project. The posture applies to both the main agent and children it starts, with different safeguards for direct editing tools and shell commands. It is a coding guardrail, not a hardened security boundary.
In an interactive session, the operator can type /readonly to toggle the posture. Ctrl+Shift+R also toggles it, but only while the agent is idle. A toggle records the new setting in the session and notifies the operator. Without an attached user interface, /readonly does nothing. The startup flag --readonly is another way to begin in this posture; it is a boolean flag and is off by default.
The setting survives more than one turn. When a session resumes, or when the operator navigates the session tree with /tree, pi-schematic restores the active branch's latest saved readonly setting. If that branch has no saved setting, --readonly can supply the initial on state. A saved off state takes precedence over --readonly on resumption: the flag does not silently overwrite the branch's recorded choice.
A prompt or skill can also declare readonly: true or readonly: false in its frontmatter—the metadata at the beginning of that prompt or skill. In an interactive invocation, the former enables readonly and the latter disables it. This change takes effect when the agent is about to start, not as soon as the slash-command input appears. The value must be a boolean; pi-schematic ignores an invalid value with a warning. A prompt or skill carrying this setting is not executed if invoked while the agent is streaming; the interface warns that it requires an idle agent. Headless or RPC input does not apply this interactive slash-command frontmatter behavior.
Readonly does not remove the main agent's write and edit tools from its advertised tool list. Instead, the readonly guard blocks a call to either at use time with an explicit reason. Shell access through bash remains available for non-mutating commands, so research is not reduced to a blank toolset. The shell guard also permits filesystem writes inside the operating system's temporary directory. This is an exception for that location, not permission to edit the project.
Before launching a bash command, a classifier checks it for recognized write redirects and filesystem mutations aimed outside that temporary directory. It blocks known package-manager mutation commands even when they target a temporary path. The shell guard rejects an unsafe classified command before launch, including on systems with an operating-system sandbox. A blocked bash call reports both its reason and the original command; when readonly is on, a bash command that is not a string is rejected as invalid input. These checks distinguish the direct-tool prohibition from the narrower shell policy: a read command can proceed, but recognizable attempts to change files outside the allowed temporary area cannot.
Where a functional sandbox is available, the shell guard has an additional filesystem layer. On macOS, sandbox-exec denies file writes outside allowed operating-system temporary paths and /dev/null. On Linux, functional bwrap presents a read-only root with writable temporary storage. The classifier still runs first in both cases; the sandbox does not replace command classification.
Linux without functional bwrap falls back to classification alone. Windows has no syscall-level readonly sandbox here, so it too relies on the classifier. That distinction matters when interpreting the word “readonly”: the classifier recognizes many common mutations but does not inspect everything a process might do. For example, interpreter one-liners such as node -e or python -c can write programmatically without their embedded operations being parsed by the classifier, and a piped xargs command can receive mutation arguments from standard input after classification. Unknown commands are allowed by the classifier. If an operating-system sandbox rejects a filesystem write, the resulting command can produce a readonly-specific notice mentioning /readonly or the OS temporary directory. Readonly is therefore a guardrail for coding-agent activity, not a promise of confinement against adversarial commands.
A spawned child—a separate agent asked to take on part of the work—inherits the parent's readonly posture at spawn time. Unlike the parent, a readonly child does not receive write or edit in its tool list. Its bash commands pass through the same readonly command guard as the parent's. A child cannot call handoff, whether or not readonly is on.
Handoff is the mechanism for continuing work in a new context. Readonly normally blocks an agent-initiated handoff, but the operator can explicitly type /handoff <direction> to reserve a temporary exception. That exception allows the handoff without removing the write/edit guard. There is a narrower path through the notebook, which holds the active topic for the session: changing an existing topic with /notebook <topic> can authorize a readonly handoff only when estimated context usage reaches the 30,000-token eligibility threshold. A too-small or unknown estimate is not eligible; before the threshold, the human topic change is advisory rather than immediate handoff authorization. A topic boundary initiated by the agent cannot grant this exception. After a successful handoff, if readonly remains enabled, the next context is told about it again.
While readonly is on, the status bar displays 🔒 readonly; it disappears when the posture is turned off. The agent also receives a one-shot hidden context nudge when readonly changes, rather than a repeated warning on every turn. At 70% or more context usage, the readonly interface warning points same-topic work toward spawning a child and different-topic work toward an eligible handoff trigger. /notebook remains exempt from workflow frontmatter interception, leaving the operator able to inspect or change the active topic while readonly. These cues make the posture visible, but they do not change its limits: the tools and shell safeguards described above define what it actually guards.
PB-READONLY-01 … 45 — 45 atomic behaviour rows
| ID | Behaviour | Evidence |
|---|---|---|
| PB-READONLY-01 |
/readonly toggles readonly on or off in the interactive session. |
index.ts:493-518 |
| PB-READONLY-02 |
Ctrl+Shift+R toggles readonly only when the agent is idle. |
index.ts:521-526 |
| PB-READONLY-03 |
--readonly is a boolean startup flag, off by default. |
index.ts:487-491 |
| PB-READONLY-04 | A session without saved readonly entries starts readonly when --readonly is true. |
readonly-rehydration.ts:27-33 |
| PB-READONLY-05 | An interactive prompt or skill with readonly: true enables readonly when invoked. |
frontmatter-cache.ts:96-117, index.ts:225-250
|
| PB-READONLY-06 | An interactive prompt or skill with readonly: false disables readonly when invoked. |
frontmatter-cache.ts:96-117, index.ts:225-250
|
| PB-READONLY-07 | Readonly frontmatter takes effect at before_agent_start, rather than at initial slash-command input. |
index.ts:644-647, index.ts:756-761
|
| PB-READONLY-08 | Readonly frontmatter requires a boolean value; invalid values are ignored with a warning. |
frontmatter-cache.ts:101-117, frontmatter-cache.ts:203-218, index.ts:229-236
|
| PB-READONLY-09 | A prompt/skill with readonly frontmatter invoked during streaming is not executed; the UI warns that it requires an idle agent. |
index.ts:427-440, notifications.ts:170-172
|
| PB-READONLY-10 | Headless/RPC input does not apply interactive slash-command readonly frontmatter. |
index.ts:210-217, index.ts:614-617
|
| PB-READONLY-11 |
/readonly does nothing when no UI is attached. |
index.ts:493-494 |
| PB-READONLY-12 | A toggle records its new posture in the session. | index.ts:493-507 |
| PB-READONLY-13 | Resuming a session or navigating /tree restores the latest saved readonly posture on the active branch. |
readonly-rehydration.ts:13-26, index.ts:955-957, index.ts:966-978
|
| PB-READONLY-14 | A saved off posture overrides --readonly when that branch is resumed. |
readonly-rehydration.ts:19-33 |
| PB-READONLY-15 | While readonly is on, calling write is blocked with an explicit reason instead of silently succeeding. |
index.ts:584-591, notifications.ts:54-55
|
| PB-READONLY-16 | While readonly is on, calling edit is blocked with an explicit reason instead of silently succeeding. |
index.ts:584-591, notifications.ts:54-55
|
| PB-READONLY-17 | Parent write and edit remain advertised but are blocked at call time. |
index.ts:573-590 |
| PB-READONLY-18 | Readonly bash permits non-mutating commands. |
readonly-bash.ts:14-24, readonly-bash.ts:112-140
|
| PB-READONLY-19 | Readonly bash permits filesystem writes inside the OS temporary directory. |
readonly-bash.ts:16-23, os-sandbox.ts:117-145
|
| PB-READONLY-20 | The command classifier blocks recognized write redirects outside the OS temporary directory. | readonly-bash.ts:125-128 |
| PB-READONLY-21 | The command classifier blocks recognized filesystem mutations targeting outside the OS temporary directory. |
readonly-bash.ts:130-131, readonly-bash.ts:259-267
|
| PB-READONLY-22 | Known package-manager mutation commands are blocked even when pointed at a temporary path. |
readonly-bash.ts:23-26, readonly-bash.ts:287-295
|
| PB-READONLY-23 | A blocked bash tool call reports the reason and original command. |
notifications.ts:29-31, index.ts:600-604
|
| PB-READONLY-24 | A non-string bash command is rejected as invalid input while readonly is on. | readonly-bash.ts:1092-1099 |
| PB-READONLY-25 | macOS uses sandbox-exec when functional, denying file writes outside allowed OS-temp paths and /dev/null. |
os-sandbox.ts:38-43, os-sandbox.ts:75-88, os-sandbox.ts:129-146
|
| PB-READONLY-26 | Linux uses functional bwrap when available, presenting a read-only root and writable temporary storage. |
os-sandbox.ts:38-45, os-sandbox.ts:56-73, os-sandbox.ts:207-229
|
| PB-READONLY-27 | Linux without functional bwrap falls back to command classification alone. |
os-sandbox.ts:38-48, readonly-bash.ts:1100-1114
|
| PB-READONLY-28 | Windows has no syscall-level readonly sandbox here; bash relies on the command classifier alone. |
os-sandbox.ts:38-48, readonly-bash.ts:1100-1114
|
| PB-READONLY-29 | The classifier checks commands even when an OS sandbox is available; a classified unsafe command is rejected before launch. | readonly-bash.ts:1100-1107 |
| PB-READONLY-30 | A spawned child inherits the parent's readonly posture at spawn time. |
spawn/index.ts:437-458, spawn/index.ts:466-483
|
| PB-READONLY-31 | A readonly child does not receive write or edit in its tool list. |
spawn/index.ts:244-252, spawn/index.ts:482-484
|
| PB-READONLY-32 | A readonly child's bash runs through the same readonly command guard as the parent's. |
spawn/index.ts:255-277, index.ts:600-608
|
| PB-READONLY-33 | Children cannot call handoff, including while readonly. |
spawn/index.ts:238-241 |
| PB-READONLY-34 | Readonly blocks an agent-initiated handoff unless a temporary exception is pending. |
index.ts:593-598, notifications.ts:57-58
|
| PB-READONLY-35 |
/handoff <direction> reserves the temporary handoff exception in readonly mode without removing the write/edit guard. |
handoff/command.ts:26-49, notifications.ts:83-85
|
| PB-READONLY-36 | Changing an existing notebook topic through /notebook <topic> can authorize a readonly handoff only if usage meets the handoff threshold. |
notebook/topic.ts:30-41, index.ts:651-665, readonly-boundary.ts:19-25
|
| PB-READONLY-37 | The handoff eligibility threshold is 30,000 estimated context tokens; a too-small or unknown context is not eligible. |
handoff/eligibility.ts:1-2, handoff/eligibility.ts:22-38
|
| PB-READONLY-38 | A human topic change before that threshold is advisory until eligible, rather than immediately authorizing handoff. |
index.ts:855-872, notifications.ts:93-99
|
| PB-READONLY-39 | An agent-originated topic boundary cannot grant a readonly handoff exception. |
readonly-boundary.ts:19-32, index.ts:855-858
|
| PB-READONLY-40 | After successful handoff, a still-enabled readonly posture is reannounced to the next context. |
handoff/tool.ts:154-165, index.ts:825-845
|
| PB-READONLY-41 | The status bar shows 🔒 readonly while readonly is enabled and removes it when disabled. |
tui.ts:64-68 |
| PB-READONLY-42 | Toggling readonly notifies the operator of the new posture. |
index.ts:505-514, notifications.ts:66-75
|
| PB-READONLY-43 | The agent receives a one-shot hidden context nudge when readonly changes, rather than a repeated readonly warning every turn. |
index.ts:825-848, index.ts:849-872
|
| PB-READONLY-44 | At 70%+ context, the TUI warning in readonly mode directs same-topic work to spawn and different-topic work to an eligible handoff trigger. | tui.ts:72-85 |
| PB-READONLY-45 |
/notebook is exempt from workflow frontmatter interception, so the operator can inspect or change the active topic while readonly. |
index.ts:132-136, index.ts:626-627, index.ts:651-677
|