feat: add readonly mode with bash safety and spawn child filtering

[ofriw]

Note: This PR was generated by an AI agent. If you'd like to talk with other humans, drop by our Discord!

---

Readonly Mode — Safety Net for AI Agent Operations

Context

The agent had unrestricted filesystem access. Any operation — reading config, exploring code, reviewing a PR — could accidentally overwrite files, rm -rf something important, or npm install unwanted dependencies. There was no way to constrain it to read-only operations short of not using it.

What This Changes

This PR introduces a readonly mode — a guardrail that, when active, prevents the agent from modifying the filesystem. The agent can still read everything, navigate, search, debug, and plan. It just can't write (except to the OS's temp dir).

Three ways to activate it:

• Manual: /readonly command or Ctrl+Shift+R shortcut — instant toggle
• Startup: pi --readonly flag — locks down from the first turn
• Declarative: Skill files and prompt commands can set readonly: true in their YAML frontmatter — readonly activates automatically when that skill/command is invoked. Think "review my PR" = readonly, "implement this feature" = unrestricted.

How It Works (Two-Layer Enforcement)

Layer 1 — OS Sandbox (macOS sandbox-exec, Linux bubblewrap): Wraps bash commands in a kernel-enforced sandbox that denies file writes outside the OS temp directory. This is the real enforcement — the OS stops writes at the syscall level.

Layer 2 — Command Pattern Classifier (all platforms, fallback): Parses bash commands and classifies each segment — allows reads and temp-directory writes, blocks anything that modifies the project. Recursively unwraps sudo, env, eval, exec to inspect the real payload. Blocks package managers (npm install, pip install, etc.) unconditionally — they write to unpredictable locations.

On macOS/Linux both layers work together (classifier runs first for a clear block reason, then sandbox wraps if allowed).

Critical — please read: Pattern classification is theoretically impossible to make complete. Shell injection, eval chains, interpreter inline code (python -c "..."), xargs wrapping — bypasses are inherent to the problem, not bugs in the implementation. The classifier is a best-effort guardrail, not a security boundary. On macOS/Linux, the OS sandbox provides real enforcement underneath. On Windows, only the classifier applies — which means readonly there is fundamentally a best-effort guardrail and cannot be hardened to real enforcement without OS-level sandboxing support.

The Hard Part — Handoff Integration

Readonly mode creates a tension: if handoff is blocked, the user is trapped in a session they can't escape. The solution is a narrow, explicit bypass:

• User types /handoff <direction> → a temporary bypass flag is set
• Agent can call the handoff tool once (write/edit remain blocked)
• After compaction completes, the bypass is cleared
• The fresh context resumes in readonly mode (state persists in the session branch)
• If the agent never calls handoff, the bypass auto-cancels after 5 turns

This means readonly is never a trap, but accidental handoffs don't happen either.

What Was Removed

• Fragile test assertions that counted internal warnings — they broke on unrelated refactors
• Manual state stubs in the watchdog test — now exercises the real /handoff command path

Infrastructure Along the Way

These aren't readonly-specific but live on this branch:

• Husky pre-commit hook: Catches type errors before CI
• Dep bump 0.78.1 → 0.79.6: SDK fixes and features
• audit-ci migration: Controlled npm advisory management
• Cross-platform path fixes: fileURLToPath, path.join for Windows
• System prompt tune: Clearer "Plan then execute" guidance

Breaking Changes? None.

Readonly defaults to off. Every new module is opt-in additive. Existing sessions, skills, prompts, and workflows are completely unaffected.

Value to the Project

• Safe exploration: Review PRs, audit dependencies, explore unfamiliar code — without risk of accidental writes
• Policy as code: Teams can mark review/audit skills as readonly: true in their skill definitions
• CI integration: pi --readonly for automated read-only workflows
• Peace of mind: A safety net that's always available, never in the way

---

Attached is an agent optimized description of the changes in this PR - AGENT_REVIEW.md

[grzegorznowak]

Summary: GH-2’s readonly-mode safety value is aligned, but concrete bash mutation bypasses and a no-UI toggle crash mean the PR should not merge as-is.

Business / Product Assessment

Verdict: REQUEST CHANGES

Strengths

• The PR implements the requested opt-in readonly mode with a CLI flag, /readonly toggle, persisted branch entries, and runtime blocking for write/edit/handoff tools. Sources: work/pr_context.json:5, index.ts:63, index.ts:72, index.ts:127
• Readonly behavior is propagated to spawned children by filtering write/edit and installing a readonly bash override when bash is inherited. Sources: spawn/index.ts:269, spawn/index.ts:274, spawn/index.ts:278
• User-facing guidance was added through a status indicator and readonly-specific nudges so the mode is visible to users and the agent. Sources: tui.ts:54, index.ts:306, index.ts:318

In Scope Issues

• Readonly bash still allows concrete mutation paths through git mixed commands and unparsed command substitution. Sources: readonly-bash.ts:45, readonly-bash.ts:239, readonly-bash.ts:241, readonly-bash.ts:242, readonly-bash.ts:312

  High severity · Medium likelihood

  Why: Readonly mode is sold as blocking destructive bash during exploratory sessions. git branch new-name, git tag v1, or git status $(git add .) can still mutate repository state while readonly is enabled.

  Assumptions / Preconditions: The agent invokes bash while readonly mode is active.

  Downgrade Factors: This PR describes readonly as guardrails rather than a security boundary, but these are ordinary git commands an agent may plausibly use.

  Code Trail: The classifier splits only on shell separators and quote state, not command substitution. A segment is sent to the git allowlist only when the whole trimmed segment starts with git. Separately, branch and tag mixed policies accept any non-flag argument, which includes ref-creating forms.

  Reproduction: In readonly mode, ask bash to run git branch review-temp or git status $(git add .). The classifier path can return safe instead of blocking the mutation.

• /readonly is not safe in no-UI contexts and can throw after partially applying state. Sources: index.ts:69, index.ts:72, index.ts:73, index.ts:74, tui.ts:32

  Medium severity · Medium likelihood

  Why: The toggle mutates state and persists an entry before unconditionally calling ctx.ui.notify. In a headless command context, users can end up with readonly toggled and persisted even though the command failed.

  Assumptions / Preconditions: /readonly or the idle shortcut is invoked with ctx.hasUI === false or without ctx.ui.

  Downgrade Factors: Most interactive use likely has a UI, but other commands in this extension already support no-UI operation.

  Code Trail: toggleReadonly flips state.readonlyEnabled, sets readonlyNudgePending, and appends agenticoding-readonly; updateIndicators no-ops when there is no UI, then ctx.ui.notify is dereferenced without checking ctx.hasUI.

  Reproduction: Invoke the registered readonly command with a context shaped like { hasUI: false, getContextUsage: () => null }. State is changed before the notify call throws.

Out of Scope Issues

• None.

Technical Assessment

Verdict: REQUEST CHANGES

Input Boundary Shape Risk Assessment

Status: Triggered
Boundary: raw tool-call input and persisted session branch entries -> stricter readonly command and rehydration assumptions.
Evidence / mitigation: event.input.command is cast directly to string before classification, and the classifier immediately expects string-like behavior; tests cover valid { command: string } inputs but not missing or malformed bash input. Branch rehydration also scans raw branch entries, though current issue evidence is strongest at the bash tool boundary. Sources: index.ts:136, index.ts:137, readonly-bash.ts:45, agenticoding.test.ts:3994

Strengths

• The readonly classifier is factored behind a reusable isSafeReadonlyCommand API and is reused by both parent tool-call blocking and child bash override enforcement. Sources: readonly-bash.ts:307, index.ts:138, spawn/index.ts:141
• The PR adds focused static coverage for tool blocking, child tool filtering, session rehydration, readonly nudges, shortcut gating, and state reset. Sources: agenticoding.test.ts:3922, agenticoding.test.ts:4005, agenticoding.test.ts:4183, agenticoding.test.ts:4604

In Scope Issues

• The parent bash tool boundary does not validate command before classification. Sources: index.ts:136, index.ts:137, readonly-bash.ts:45, agenticoding.test.ts:3994

  Medium severity · Medium likelihood

  Why: A malformed bash tool payload should be blocked cleanly in readonly mode. Instead, missing command can throw, and some non-string values can be treated as empty/safe because the runtime cast does not validate shape.

  Assumptions / Preconditions: The framework or model supplies malformed bash tool input while readonly mode is active.

  Downgrade Factors: Normal bash calls likely provide { command: string }, and existing tests cover that happy path.

  Code Trail: The tool-call handler casts event.input.command to string and passes it to isSafeReadonlyCommand. splitUnquotedShellSegments then reads cmd.length, so the boundary depends on runtime string shape without a guard.

  Reproduction: Call the readonly tool_call handler with { toolName: "bash", input: {} } or a non-string command. The handler does not return a controlled readonly block result.

Out of Scope Issues

• None.

Reusability

• buildChildToolNames remains exported and testable, keeping child tool inheritance and readonly filtering easy to validate independently. Sources: spawn/index.ts:126, agenticoding.test.ts:4005
• buildNudge centralizes readonly/topic guidance, with tests for readonly topic, no-topic, and boundary-hint cases. Sources: watchdog.ts:15, agenticoding.test.ts:3354, agenticoding.test.ts:3373

---

review generated with CURe v. 0.7.3 · multi-stage - stages: 4 · sha 6540936 · model gpt-5.5/high · tok 8m/82k/8m · session agenticoding-pi-agenticoding-pr7-20260528-053241-21cc · 16m32s