Repository navigation
Spec2Contract Readonly
Grzegorz Nowak edited this page Oct 10, 2026
·
2 revisions
The Readonly area of the Product Book covers the session readonly posture: how it is toggled
(/readonly, Ctrl+Shift+R, --readonly, prompt/skill frontmatter), how it is persisted and
rehydrated, how it guards tools and bash, how it crosses into spawned children and handoff, and how
it is surfaced in the TUI. Its left space is PB-READONLY-01 … PB-READONLY-45 (45 rows). Contracts
are carried mainly by the readonly fixture family T25–T31 (toggle, frontmatter, bash classifier,
spawn, rehydration, handoff, os-sandbox), with secondary seals from T01, T08, T12, T32,
T43, T44, T46 and the T49 e2e lifecycle.
| Claim ID | Assertion (terse) | Fixture(s) | Status | Notes |
|---|---|---|---|---|
| PB-READONLY-01 |
/readonly toggles readonly on or off in the session. |
T25 | ✅ asserted |
readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations" / "readonly toggle off restores write, handoff, and bash access". |
| PB-READONLY-02 |
Ctrl+Shift+R toggles readonly only while the agent is idle. |
T25 | ✅ asserted |
readonly-mode.test.ts — "readonly shortcut only toggles while idle" (handler no-ops when isIdle() false, blocks write when true). |
| PB-READONLY-03 |
--readonly boolean startup flag, off by default. |
T29 | ✅ asserted |
readonly-rehydration.test.ts — "returns false for empty branch with no CLI flag" / "returns true for empty branch with CLI flag" (default-off and set-on behaviour). Aspect: default value. |
| PB-READONLY-03 |
--readonly declared as a boolean flag. |
— | Aspect: flag declaration/type. Would seal it: assert the registered flag descriptor is { type: "boolean", default: false } via the test host flag registry. |
|
| PB-READONLY-04 | Session with no saved readonly entries starts readonly when --readonly is true. |
T29 | ✅ asserted |
readonly-rehydration.test.ts — "returns true for empty branch with CLI flag" (empty branch has no entries). |
| PB-READONLY-05 | Interactive prompt/skill with readonly: true enables readonly when invoked. |
T26 | ✅ asserted |
readonly-frontmatter.test.ts — "single /name input activates readonly frontmatter", "/skill:name activates readonly from skill frontmatter", "suffixed /name command activates readonly frontmatter", "dotted /name command activates readonly frontmatter". |
| PB-READONLY-06 | Interactive prompt/skill with readonly: false disables readonly when invoked. |
T26 | ✅ asserted |
readonly-frontmatter.test.ts — "deferred readonly disable emits a one-shot context nudge" (enabled via /readonly, then /nudge-off disables and emits [readonly] disabled); "readonly: false frontmatter keeps readonly disabled and stays silent when already disabled". |
| PB-READONLY-07 | Frontmatter takes effect at before_agent_start, not at initial slash input. |
T26 | ✅ asserted |
readonly-frontmatter.test.ts — "input handler queues a prompt command even when the registry is unavailable until before_agent_start", "before_agent_start skips readonly cache population while no slash-command toggle is pending", "queued slash commands are consumed FIFO across before_agent_start calls". |
| PB-READONLY-08 | Readonly frontmatter requires a boolean; invalid values ignored with a warning. | T26, T32 | ✅ asserted |
readonly-frontmatter.test.ts — "invalid /prompt readonly value records a warning for the prompt source", "invalid /skill:name readonly value records a warning", "malformed /prompt frontmatter records a parse warning"; frontmatter-cache.test.ts — "populateFromSkills returns null for non-boolean readonly frontmatter", "records invalid readonly value issues". |
| PB-READONLY-09 | Prompt/skill invoked during streaming is not executed; UI warns it needs an idle agent. | T26 | ✅ asserted |
readonly-frontmatter.test.ts — "streaming readonly frontmatter is blocked without a delayed toggle" (result {action:"handled"}, no posture change, notification readonly frontmatter requires an idle agent). |
| PB-READONLY-10 | Headless/RPC input does not apply interactive slash-command readonly frontmatter. | T26 | ✅ asserted |
readonly-frontmatter.test.ts — "headless /name frontmatter stays a no-op through the deferred pipeline", "extension input stays a no-op when hasUI is false". Aspect: headless; RPC path not separately distinguished. |
| PB-READONLY-11 |
/readonly does nothing when no UI is attached. |
T25 | ✅ asserted |
readonly-mode.test.ts — "readonly toggle is a no-op in headless mode" (hasUI:false; write stays unblocked). |
| PB-READONLY-12 | A toggle records its new posture in the session. | T26 | ✅ asserted |
readonly-frontmatter.test.ts — "one readonly entry is appended per consumed queued toggle" (pi-schematic-readonly entry with data.enabled), "deferred readonly enable emits a one-shot context nudge". Note: assertion is on the deferred/frontmatter toggle path; the /readonly command append is exercised indirectly via resume/rehydration. |
| PB-READONLY-13 | Resuming a session or /tree restores the latest saved posture on the active branch. |
T29, T30 | ✅ asserted |
readonly-rehydration.test.ts — "uses a persisted readonly entry when present", "picks the latest entry (true wins)", "picks the latest entry (false wins)"; readonly-handoff.test.ts — "session resume restores readonly enforcement from persisted state", "session tree re-announces readonly even when the rehydrated value is unchanged". |
| PB-READONLY-14 | A saved off posture overrides --readonly on resume. |
T29 | ✅ asserted |
readonly-rehydration.test.ts — "uses a persisted readonly entry when present" (entry enabled:false with CLI flag true → false), "falls back to the CLI flag when no valid readonly entry exists". |
| PB-READONLY-15 | While readonly is on, write is blocked with an explicit reason. |
T25, T43 | ✅ asserted |
readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy" (reason READONLY_WRITE_EDIT_BLOCK_REASON). |
| PB-READONLY-16 | While readonly is on, edit is blocked with an explicit reason. |
T25, T43 | ✅ asserted |
readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy", "block reasons use 'Readonly mode:' prefix". |
| PB-READONLY-17 | Parent write/edit remain advertised but are blocked at call time. |
T25, T43 | ✅ asserted | Aspect: call-time block. readonly-mode.test.ts — "readonly toggle on blocks …"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy". |
| PB-READONLY-17 | Parent write/edit stay advertised in the tool list while readonly is on. |
— | Aspect: advertisement. Child filtering is asserted (T28) but the parent keeps the tools; would seal it: assert the parent's registered tool list still contains write/edit while readonly. |
|
| PB-READONLY-18 | Readonly bash permits non-mutating commands. | T27 | ✅ asserted |
readonly-bash-classifier.test.ts — "allows bash reads and non-mutating commands", "allows readonly-safe git inspection subcommands", "allows piped read commands", "allows sudo commands that only read". |
| PB-READONLY-19 | Readonly bash permits filesystem writes inside the OS temp dir. | T27, T31 | ✅ asserted |
readonly-bash-classifier.test.ts — "allows bash writes to temp dir", "allows hidden-file globs inside temp dir", "blocks cwd-relative downloads outside temp but allows inside temp"; os-sandbox.test.ts — "sandbox allows writes through a symlinked temp path". |
| PB-READONLY-20 | Classifier blocks recognized write redirects outside temp. | T27 | ✅ asserted |
readonly-bash-classifier.test.ts — "blocks write redirects outside temp dir", "blocks heredoc redirects outside temp", "blocks command substitutions that write outside temp". |
| PB-READONLY-21 | Classifier blocks recognized filesystem mutations outside temp. | T27 | ✅ asserted |
readonly-bash-classifier.test.ts — "blocks bash writes outside temp dir", "classifies git commands correctly", "blocks git branch creation", "blocks git tag creation", "blocks chained commands that write outside temp". |
| PB-READONLY-22 | Known package-manager mutations blocked even pointed at a temp path. | T27 | ✅ asserted |
readonly-bash-classifier.test.ts — "blocks package managers unconditionally". |
| PB-READONLY-23 | A blocked bash call reports the reason and the original command. | T27, T43 | ✅ asserted |
notifications.test.ts — "bash and sandbox consumers use centralized readonly copy" (result.reason === buildReadonlyBashBlockReason(verdict.reason, command), which embeds Command: <cmd>), "block reasons use 'Readonly mode:' prefix"; readonly-bash-classifier.test.ts — block assertions on the real tool_call path. |
| PB-READONLY-24 | A non-string bash command is rejected as invalid input while readonly is on. | T27, T28 | ✅ asserted |
readonly-bash-classifier.test.ts — "blocks malformed bash input without throwing"; readonly-spawn.test.ts — "readonly bash guard rejects non-string commands". |
| PB-READONLY-25 | macOS uses sandbox-exec when functional, denying writes outside temp and /dev/null. |
T31 | ✅ asserted |
os-sandbox.test.ts — "buildMacProfile rejects paths containing quotes", "wrapped command blocks non-temp writes and allows temp writes", "sandbox allows writes to /dev/null". Note: the wrapped-command assertions are platform-gated (if (!canUseOsSandbox()) return), so they seal the macOS sandbox-exec path only when run on macOS. |
| PB-READONLY-26 | Linux uses functional bwrap, read-only root + writable temp. |
T31 | ✅ asserted |
os-sandbox.test.ts — "quotes dynamic Linux sandbox paths for the outer shell" (--bind <temp> <temp>), "bwrap executes a quoted bind path without shell injection", "wrapped command blocks non-temp writes and allows temp writes". Note: bwrap execution is platform-gated to Linux. |
| PB-READONLY-27 | Linux without functional bwrap falls back to classifier alone. |
T27 | ✅ asserted | Aspect: classifier-alone behaviour. readonly-bash-classifier.test.ts — all allow/block tests go through applyReadonlyBashGuard, which classes mutations and allows reads with no OS sandbox. |
| PB-READONLY-27 | The classifier-alone selection when bwrap is unavailable. |
— | Aspect: fallback selection. Would seal it: stub canUseOsSandbox() to false and assert the guard returns allow for reads and a classified block for mutations (no sandbox action). |
|
| PB-READONLY-28 | Windows has no syscall-level sandbox; bash relies on classifier alone. | T27 | ✅ asserted | Aspect: classifier-alone behaviour. readonly-bash-classifier.test.ts — allow/block suite exercises the no-sandbox classifier path. |
| PB-READONLY-28 | Windows selecting classifier-only enforcement (no syscall sandbox). | — | Aspect: Windows platform selection. Would seal it: force platform win32 / canUseOsSandbox()===false and assert no sandbox wrapping while mutable commands are still classified-blocked. |
|
| PB-READONLY-29 | Classifier checks commands even with an OS sandbox; unsafe rejected before launch. | T27, T43 | ✅ asserted |
notifications.test.ts — "bash and sandbox consumers use centralized readonly copy" asserts applyReadonlyBashGuard(mutation).action === "block" (not sandbox) unconditionally; readonly-handoff.test.ts — assertNonTempBashBlocked requires block:true before execution. |
| PB-READONLY-30 | A spawned child inherits the parent's readonly posture at spawn time. | T28, T01 | ✅ asserted |
readonly-spawn.test.ts — "readonly child authority note communicates readonly inheritance", "real readonly child omits write/edit and blocks a non-temp bash write"; spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (prompt carries inherit readonly authority). |
| PB-READONLY-31 | A readonly child does not receive write/edit in its tool list. |
T28, T01 | ✅ asserted |
readonly-spawn.test.ts — "filterReadonlyToolNames removes write and edit in readonly mode", "real readonly child omits write/edit …"; spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (seenConfig.tools excludes write/edit). |
| PB-READONLY-32 | A readonly child's bash runs through the same readonly guard as the parent's. | T28 | ✅ asserted |
readonly-spawn.test.ts — "readonly bash guard blocks non-temp writes and allows temp writes" (same applyReadonlyBashGuard), "real readonly child … blocks a non-temp bash write" (READONLY_BASH_BLOCKED). |
| PB-READONLY-33 | Children cannot call handoff. |
T28, T01 | ✅ asserted |
readonly-spawn.test.ts — "buildChildToolNames excludes spawn and handoff from inherited tools", "real readonly child …" (observed tool sets exclude handoff/spawn); spawn.test.ts — child tools exclude handoff. |
| PB-READONLY-34 | Readonly blocks agent-initiated handoff unless a temporary exception is pending. |
T25, T30 | ✅ asserted |
readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, …"; readonly-handoff.test.ts — "blocked readonly handoff never invokes compaction". |
| PB-READONLY-35 |
/handoff <direction> reserves the exception without removing the write/edit guard. |
T30 | ✅ asserted |
readonly-handoff.test.ts — "/handoff command creates temporary bypass for handoff tool only" (handoff unblocked; write stays blocked; non-temp bash blocked); "after handoff compaction, bypass is cleared and readonly persists". |
| PB-READONLY-36 |
/notebook <topic> can authorize a readonly handoff only if usage meets the threshold. |
T30, T46, T08 | ✅ asserted |
readonly-handoff.test.ts — "readonly topic boundary creates the same bypass contract as explicit /handoff", "readonly topic boundary derives eligibility from percentage when tokens are unavailable", "readonly topic boundary stays advisory until handoff is eligible"; watchdog.test.ts — "eligible readonly human topic boundary auto-creates handoff bypass equivalent to /handoff"; notebook.test.ts — "readonly /notebook boundary notification explains deferred handoff eligibility". |
| PB-READONLY-37 | Threshold is 30,000 estimated tokens; too-small/unknown is not eligible. | T12, T30 | ✅ asserted |
handoff-eligibility.test.ts — "handoff eligibility prefers explicit tokens" (MIN_HANDOFF_TOKENS; -1 ineligible), "estimates tokens from percent and context window" (14.9999% ineligible), "rejects malformed or unestimable usage"; readonly-handoff.test.ts — "readonly human topic boundary promotes exactly at the token threshold". |
| PB-READONLY-38 | Human topic change before the threshold is advisory until eligible, not an immediate authorization. | T30, T08, T46 | ✅ asserted |
readonly-handoff.test.ts — "readonly topic boundary stays advisory until handoff is eligible", "advisoryDelivered flag prevents repeated advisory nudges for ineligible boundary"; notebook.test.ts — "readonly /notebook boundary notification explains deferred handoff eligibility"; watchdog.test.ts — "context injects readonly handoff guidance after explicit user /handoff". |
| PB-READONLY-39 | An agent-originated topic boundary cannot grant the exception. | T30 | ✅ asserted |
readonly-handoff.test.ts — "readonly agent topic transitions cannot promote or remain queued", "readonly agent topic boundary is not promoted to handoff bypass". |
| PB-READONLY-40 | After successful handoff, a still-enabled readonly posture is reannounced to the next context. | T30, T49 | ✅ asserted |
readonly-handoff.test.ts — "the handoff summary stays readonly-free and the fresh context relearns readonly live", "after handoff compaction, bypass is cleared and readonly persists"; real-host.test.ts (e2e) — "handoff queues the successor instruction and re-announces readonly in its turn", "readonly lifecycle: handoff bypass clears after compaction while readonly persists". |
| PB-READONLY-41 | Status bar shows 🔒 readonly while enabled and removes it when disabled. |
T44 | ✅ asserted |
tui-indicators.test.ts — "updateIndicators shows readonly indicator when enabled" (lock emoji + "readonly"), "updateIndicators hides readonly indicator when disabled". |
| PB-READONLY-42 | Toggling readonly notifies the operator of the new posture. | T26, T43 | ◐ partly asserted |
notifications.test.ts — "summary constants use '[readonly]' prefix", "composition chain: READONLY_ENABLED_STATUS contains READONLY_BASH_SCOPE"; readonly-frontmatter.test.ts — "readonly success notifications use the exact slash-command source" (frontmatter-initiated toggles). Missing portion: the /readonly command / Ctrl+Shift+R themselves calling ctx.ui.notify with READONLY_ENABLED_STATUS / READONLY_DISABLED_NOTIFICATION — readonly-mode.test.ts uses a no-op notify, so that emission is not asserted. |
| PB-READONLY-43 | The agent gets a one-shot hidden context nudge on change, not a repeated warning each turn. | T25, T26, T46 | ✅ asserted |
readonly-mode.test.ts — "toggle delivers an activation nudge via context hook", "toggle off delivers a deactivation nudge"; readonly-frontmatter.test.ts — "deferred readonly enable emits a one-shot context nudge" (second hook returns none); watchdog.test.ts — "context hook suppresses watchdog after readonly toggle nudge is drained". |
| PB-READONLY-44 | At 70%+, the readonly TUI warning directs same-topic work to spawn and different-topic to eligible handoff. | T44 | ◐ partly asserted |
tui-indicators.test.ts — "updateIndicators shows readonly-specific warning widget at 70%+ context" (asserts widget mentions readonly, spawn, explicit /handoff) and "hides widget below 70% context". Missing portion: the explicit same-topic→spawn / different-topic→eligible-handoff mapping text; the test asserts keyword presence only. |
| PB-READONLY-45 |
/notebook is exempt from workflow frontmatter interception while readonly. |
T26 | ✅ asserted |
readonly-frontmatter.test.ts — "/notebook bypasses deferred frontmatter lookup" (with "/readonly bypasses…" and "/handoff bypasses…"). |
No PB-READONLY row is entirely ⚠️; every claim has at least one representing fixture. The
following contract surfaces within a row have no test:
-
PB-READONLY-03—--readonlyis declared as abooleanflag (type/default descriptor). Would seal it: assert the registered flag descriptor{ type: "boolean", default: false }via the test host. -
PB-READONLY-17— the parent keepswrite/editadvertised while readonly. Would seal it: assert the parent tool list still containswrite/editafter/readonly(only the call-time block is covered). -
PB-READONLY-27— Linux-without-functional-bwrapfallback selection. Would seal it: stubcanUseOsSandbox()false and assert nosandboxaction (classifierallowfor reads,blockfor mutations). -
PB-READONLY-28— Windows classifier-only selection (no syscall sandbox). Would seal it: force platformwin32/canUseOsSandbox()false and assert classifier-only enforcement with no wrapping.
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 45 | 49 | 43 | 2 | 4 |