test(app): reproduce ignored bare folder links

Retain the failed UI reproduction from issue #7206 without changing production behavior.

.gitignore

@@ -85,6 +85,8 @@ valknut-report.json/
 packages/server/src/server/fixtures/dictation/dictation-debug-largest.wav
 packages/server/src/server/fixtures/dictation/dictation-debug-largest.transcript.txt
 packages/protocol/src/generated/validation/*.aot.ts
+packages/protocol/src/generated/validation/ws-outbound-schema-metadata.ts
+packages/protocol/codegen/generated/
 
 /artifacts
 packages/desktop/.cache/

CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## 0.12.0-beta.1 - 2026-10-16
+
+Background workspaces, a new Markdown renderer with selection across paragraphs on phones, a reworked phone layout, and close to 100 fixes.
+
+**Before upgrading:** `paseo run --background` is deprecated in favor of `--no-wait`, and `paseo permit allow` and `deny` now exit non-zero when the daemon doesn't confirm within 15 seconds
+
+### Added
+
+- Added background workspaces, hidden from the sidebar unless Show background is on ([#5039](https://github.com/getpaseo/paseo/pull/5039), [#7141](https://github.com/getpaseo/paseo/pull/7141) by [@gpambrozio](https://github.com/gpambrozio), [@marvin-ambrozio](https://github.com/marvin-ambrozio))
+- Added a Send feedback button to the diff pane, so review comments reach an agent without opening its chat ([#6455](https://github.com/getpaseo/paseo/pull/6455))
+- Added a fullscreen composer on phones ([#6531](https://github.com/getpaseo/paseo/pull/6531), [#6902](https://github.com/getpaseo/paseo/pull/6902), [#6945](https://github.com/getpaseo/paseo/pull/6945), [#6987](https://github.com/getpaseo/paseo/pull/6987), [#7130](https://github.com/getpaseo/paseo/pull/7130), [#7170](https://github.com/getpaseo/paseo/pull/7170))
+- Added the sender's name to messages one agent sends another ([#6373](https://github.com/getpaseo/paseo/pull/6373))
+- Added Claude Mythos 5.1 when the installed Claude Code advertises it ([#6403](https://github.com/getpaseo/paseo/pull/6403))
+- Added option previews to Claude question cards ([#6171](https://github.com/getpaseo/paseo/pull/6171) by [@gabrielgiordan](https://github.com/gabrielgiordan))
+- Added `paseo usage` to show account quotas, balances, and reset times from the CLI ([#6474](https://github.com/getpaseo/paseo/pull/6474))
+
+### Improved
+
+- Changed text selection in replies on iOS and Android to cross paragraphs, headings, and lists ([#6973](https://github.com/getpaseo/paseo/pull/6973))
+- Added a copy button to code blocks on iOS and Android ([#6973](https://github.com/getpaseo/paseo/pull/6973))
+- Changed wide Markdown tables on iOS and Android to scroll sideways ([#6973](https://github.com/getpaseo/paseo/pull/6973))
+- Changed phone layouts to a floating header ([#6431](https://github.com/getpaseo/paseo/pull/6431))
+- Moved New agent and New terminal on phones into the tab switcher ([#6431](https://github.com/getpaseo/paseo/pull/6431))
+- Moved workspace scripts on phones into ⋯ → Scripts, which shows what is running ([#7122](https://github.com/getpaseo/paseo/pull/7122))
+- Changed phones to open files and subagents in a closable sheet, with Open as tab for subagents ([#6827](https://github.com/getpaseo/paseo/pull/6827), [#6885](https://github.com/getpaseo/paseo/pull/6885), [#6958](https://github.com/getpaseo/paseo/pull/6958))
+- Changed diff comments on phones to open in a sheet instead of an editor inside the code ([#6455](https://github.com/getpaseo/paseo/pull/6455))
+- Changed Settings on phones to large tiles grouped into App and Host ([#7129](https://github.com/getpaseo/paseo/pull/7129))
+- Reduced rendering work in long chats while a reply streams ([#7052](https://github.com/getpaseo/paseo/pull/7052) by [@colonelpanic8](https://github.com/colonelpanic8))
+- Made reopening the sidebar about 45% faster ([#7157](https://github.com/getpaseo/paseo/pull/7157))
+- Changed Gitea and Forgejo fork PR checkouts to include the fork owner in the branch name, such as `bob/patch-1` ([#6829](https://github.com/getpaseo/paseo/pull/6829) by [@alexanderadam](https://github.com/alexanderadam))
+
+### Plugins
+
+- Fixed plugins that import Paseo protocol types failing to install with "Could not resolve type dependency" ([#7023](https://github.com/getpaseo/paseo/pull/7023))
+- Fixed `providers.waitForReady` throwing in plugins on the mobile app ([#6760](https://github.com/getpaseo/paseo/pull/6760) by [@GeorgeR](https://github.com/GeorgeR))
+- Fixed the chat outline not jumping to prompts rendered by a timeline plugin ([#6690](https://github.com/getpaseo/paseo/pull/6690) by [@lukeRRD](https://github.com/lukeRRD))
+- Fixed Escape stopping the running agent instead of first closing an open plugin preview ([#7110](https://github.com/getpaseo/paseo/pull/7110) by [@RRD-dev](https://github.com/RRD-dev), [@luoph](https://github.com/luoph))
+
+### Fixed
+
+- Fixed iOS replies with list items that render blank, and text that keeps a stale width after a resize or rotation ([#6973](https://github.com/getpaseo/paseo/pull/6973))
+- Fixed plugin hosts, the CLI, and the desktop app growing to about 1 GB of memory after running for 30 to 75 minutes ([#6847](https://github.com/getpaseo/paseo/pull/6847) by [@babo-jeonguk](https://github.com/babo-jeonguk))
+- Fixed the daemon running out of memory during long OpenCode v2 reply or reasoning streams ([#6262](https://github.com/getpaseo/paseo/pull/6262))
+- Fixed archived ACP agents starting a provider process that kept running each time their timeline loaded ([#6766](https://github.com/getpaseo/paseo/pull/6766) by [@apple-ouyang](https://github.com/apple-ouyang))
+- Fixed oversized attachments disconnecting the host in a loop instead of failing with a size error ([#6285](https://github.com/getpaseo/paseo/pull/6285))
+- Fixed Download in Files failing on hosts connected over relay, SSH, or a socket ([#6595](https://github.com/getpaseo/paseo/pull/6595) by [@odoo-mvds](https://github.com/odoo-mvds), [@YASICJUNWOO](https://github.com/YASICJUNWOO), [@JrDw0](https://github.com/JrDw0))
+- Fixed Changes showing no diff lines with custom Git diff settings, such as `color.diff=always` or an external diff command ([#6536](https://github.com/getpaseo/paseo/pull/6536), [#6562](https://github.com/getpaseo/paseo/pull/6562) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed an incomplete font name in Appearance breaking the app's styling ([#6695](https://github.com/getpaseo/paseo/pull/6695))
+- Fixed the Linux desktop window never appearing when the hidden window renders no frames ([#6726](https://github.com/getpaseo/paseo/pull/6726) by [@EhEo](https://github.com/EhEo))
+- Fixed opening another agent or workspace stalling while a different agent on the same host is streaming ([#7074](https://github.com/getpaseo/paseo/pull/7074) by [@colonelpanic8](https://github.com/colonelpanic8))
+- Fixed agent creation showing an error and a retry draft when the provider rejected the first prompt ([#6379](https://github.com/getpaseo/paseo/pull/6379))
+- Fixed parent agents missing the finish notification when a child finished its first turn very quickly ([#6008](https://github.com/getpaseo/paseo/pull/6008) by [@ahmet-izgi](https://github.com/ahmet-izgi))
+- Fixed parent agents being told a child finished when its task was stopped or reloaded ([#6660](https://github.com/getpaseo/paseo/pull/6660) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed Codex chats containing U+2028 or U+2029 failing to reopen on Node 24 ([#5999](https://github.com/getpaseo/paseo/pull/5999) by [@grahameger](https://github.com/grahameger), [@jtsang4](https://github.com/jtsang4), [@kotusenka](https://github.com/kotusenka))
+- Fixed Add Project directory search hanging the daemon on macOS when it entered `~/Library` ([#5789](https://github.com/getpaseo/paseo/pull/5789) by [@lardissone](https://github.com/lardissone))
+- Fixed New workspace failing with "Invalid mode" when the saved mode isn't offered by the provider ([#5847](https://github.com/getpaseo/paseo/pull/5847) by [@mcowger](https://github.com/mcowger))
+- Fixed answering multi-select OpenCode v2 questions failing with "Invalid answer" ([#6149](https://github.com/getpaseo/paseo/pull/6149) by [@gammons](https://github.com/gammons))
+- Fixed browser screenshots failing the turn on OpenCode v2 agents ([#6330](https://github.com/getpaseo/paseo/pull/6330))
+- Fixed OpenCode v2 agents receiving "HTTP 500" instead of the Paseo tool error ([#6519](https://github.com/getpaseo/paseo/pull/6519))
+- Fixed rewinding a Claude conversation failing with "Session not found" when the provider sets `CLAUDE_CONFIG_DIR` ([#6325](https://github.com/getpaseo/paseo/pull/6325))
+- Fixed imported Claude Code sessions taking their first prompt as the name instead of their `/rename` title ([#6930](https://github.com/getpaseo/paseo/pull/6930) by [@platanus-kr](https://github.com/platanus-kr))
+- Fixed a wrongly shaped answer to a Claude question reporting success and discarding the question ([#6936](https://github.com/getpaseo/paseo/pull/6936) by [@thomasvan](https://github.com/thomasvan))
+- Fixed Cursor agents showing no plan usage in their context details ([#6353](https://github.com/getpaseo/paseo/pull/6353) by [@gengjiawen](https://github.com/gengjiawen))
+- Fixed the Claude context meter counting only output tokens when a proxy reports input usage at the end of the response ([#6703](https://github.com/getpaseo/paseo/pull/6703) by [@kywoo26](https://github.com/kywoo26))
+- Fixed the Claude context meter showing a 1M maximum after switching back to a 200k model ([#6814](https://github.com/getpaseo/paseo/pull/6814))
+- Fixed the context meter staying empty during the first turn on custom Claude `[1m]` models ([#6767](https://github.com/getpaseo/paseo/pull/6767))
+- Fixed a schedule never running again after one of its runs could not be recorded ([#6334](https://github.com/getpaseo/paseo/pull/6334))
+- Fixed schedules sharing a cron minute running a slot twice and skipping the next occurrence ([#6532](https://github.com/getpaseo/paseo/pull/6532) by [@keithpk](https://github.com/keithpk))
+- Fixed Committed showing no changes for worktrees created from an existing branch ([#6462](https://github.com/getpaseo/paseo/pull/6462) by [@cr-2takumax](https://github.com/cr-2takumax))
+- Fixed Discard and commit diffs in Changes for workspaces opened at a repository subdirectory ([#6777](https://github.com/getpaseo/paseo/pull/6777), [#6801](https://github.com/getpaseo/paseo/pull/6801), [#6882](https://github.com/getpaseo/paseo/pull/6882) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed renamed and edited files showing every line as added in Changes ([#6559](https://github.com/getpaseo/paseo/pull/6559))
+- Fixed renamed files opened from a commit showing as new files ([#6895](https://github.com/getpaseo/paseo/pull/6895))
+- Fixed Changes showing no diff for filenames containing quotes, backslashes, or tabs ([#6583](https://github.com/getpaseo/paseo/pull/6583) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed Changes dropping removed lines that start with `--`, such as SQL comments ([#6569](https://github.com/getpaseo/paseo/pull/6569) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed the Diff tab staying on a spinner after the first edit in a clean workspace ([#6745](https://github.com/getpaseo/paseo/pull/6745))
+- Fixed worktree creation failing after running `git init` in a project added before Git ([#6785](https://github.com/getpaseo/paseo/pull/6785))
+- Fixed new worktrees not opening the terminals configured in `paseo.json` after setup ([#6999](https://github.com/getpaseo/paseo/pull/6999) by [@davidyang](https://github.com/davidyang))
+- Fixed a service newly added to `paseo.json` failing to start until the daemon restarted ([#6542](https://github.com/getpaseo/paseo/pull/6542))
+- Fixed workspace service URLs returning 502 when the service listens only on IPv6 localhost ([#6753](https://github.com/getpaseo/paseo/pull/6753) by [@marcelocastrobarbosa](https://github.com/marcelocastrobarbosa))
+- Fixed terminals that could not be closed when their command was missing or exited immediately ([#6792](https://github.com/getpaseo/paseo/pull/6792) by [@KiraPC](https://github.com/KiraPC))
+- Fixed CJK terminal text gaining spaces between characters after returning to a workspace ([#6452](https://github.com/getpaseo/paseo/pull/6452) by [@jasonhnd](https://github.com/jasonhnd), [@liujin0506](https://github.com/liujin0506), [@seob717](https://github.com/seob717))
+- Fixed the self-hosted web app failing to connect through a reverse proxy on port 80 or 443 ([#6638](https://github.com/getpaseo/paseo/pull/6638) by [@kiawin](https://github.com/kiawin))
+- Fixed assistant file links with spaces or non-ASCII characters failing with ENOENT ([#6520](https://github.com/getpaseo/paseo/pull/6520) by [@apple-ouyang](https://github.com/apple-ouyang), [@sunshinehomeyu-blip](https://github.com/sunshinehomeyu-blip))
+- Fixed local images in agent replies failing to load when their path contains spaces or non-ASCII characters ([#6877](https://github.com/getpaseo/paseo/pull/6877))
+- Fixed Markdown file previews not showing images referenced by relative paths ([#6750](https://github.com/getpaseo/paseo/pull/6750) by [@apple-ouyang](https://github.com/apple-ouyang))
+- Fixed iOS sidebar rows staying highlighted and swallowing the next tap after a brief hold ([#7159](https://github.com/getpaseo/paseo/pull/7159) by [@kassamkhoja](https://github.com/kassamkhoja))
+- Fixed Android chats scrolling when you long-press to select text ([#7131](https://github.com/getpaseo/paseo/pull/7131) by [@RRD-dev](https://github.com/RRD-dev), [@luoph](https://github.com/luoph))
+- Fixed sidebar rows, footer buttons, and Settings items showing no feedback when tapped on touch devices ([#7150](https://github.com/getpaseo/paseo/pull/7150))
+- Fixed Page Up and Page Down not scrolling the chat after clicking a message ([#7033](https://github.com/getpaseo/paseo/pull/7033) by [@panta82](https://github.com/panta82))
+- Fixed Add Project keyboard selection moving to directories scrolled out of view ([#7081](https://github.com/getpaseo/paseo/pull/7081) by [@superheher](https://github.com/superheher))
+- Fixed Enter replacing an email address in the composer with a file mention ([#6471](https://github.com/getpaseo/paseo/pull/6471) by [@jasonhnd](https://github.com/jasonhnd))
+- Fixed letter shortcuts not running with non-Latin keyboard layouts such as Russian ([#6755](https://github.com/getpaseo/paseo/pull/6755))
+- Fixed shortcut recording saving the QWERTY key instead of the typed letter on layouts such as Dvorak ([#6652](https://github.com/getpaseo/paseo/pull/6652))
+- Fixed rebinding Jump to tab or Jump to workspace keeping only the pressed number instead of 1–9; record existing overrides again ([#7065](https://github.com/getpaseo/paseo/pull/7065) by [@dbunk903](https://github.com/dbunk903))
+- Fixed Previous and Next workspace shortcuts stopping at workspace 9 ([#6586](https://github.com/getpaseo/paseo/pull/6586) by [@IEatCodeDaily](https://github.com/IEatCodeDaily))
+- Fixed unreadable Android status bar icons in the Light theme and after the system theme changes ([#6707](https://github.com/getpaseo/paseo/pull/6707) by [@terayang](https://github.com/terayang))
+- Fixed the pairing QR code getting clipped on iOS and Android ([#6758](https://github.com/getpaseo/paseo/pull/6758) by [@fdkevin0](https://github.com/fdkevin0))
+- Fixed a `write EPIPE` error dialog on Linux desktop when the launcher stops reading console output ([#6639](https://github.com/getpaseo/paseo/pull/6639))
+- Fixed `paseo permit allow` and `deny` reporting success over SSH while the request stayed pending ([#6607](https://github.com/getpaseo/paseo/pull/6607) by [@budivoogt](https://github.com/budivoogt))
+- Fixed files and folders whose names start with two dots, like `..notes.txt`, being hidden and rejected ([#6604](https://github.com/getpaseo/paseo/pull/6604), [#6720](https://github.com/getpaseo/paseo/pull/6720) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed Markdown previews dropping table rows after a `<` that isn't HTML, such as `List<Item>` ([#6370](https://github.com/getpaseo/paseo/pull/6370) by [@gengjiawen](https://github.com/gengjiawen))
+- Fixed a literal heading tag appearing when an HTML heading contains a linked image ([#6650](https://github.com/getpaseo/paseo/pull/6650))
+- Fixed Astro diffs with an empty `{}` expression failing to render ([#6763](https://github.com/getpaseo/paseo/pull/6763))
+- Fixed slash command argument hints missing from autocomplete for ACP providers ([#6920](https://github.com/getpaseo/paseo/pull/6920) by [@bwestlund17](https://github.com/bwestlund17))
+- Fixed terminal profiles configured with the `agy` icon showing a generic bot instead of the Antigravity icon ([#6938](https://github.com/getpaseo/paseo/pull/6938) by [@noahg9](https://github.com/noahg9))
+- Fixed the Pi thinking level not updating when a Pi extension changes it ([#6741](https://github.com/getpaseo/paseo/pull/6741))
+- Fixed Pi subagents from `@tintinweb/pi-subagents` staying running after their turn limit ([#6594](https://github.com/getpaseo/paseo/pull/6594) by [@Chen-DaYi](https://github.com/Chen-DaYi))
+- Fixed manual `/compact` on OMP agents showing no progress and leaving the context meter stale ([#6106](https://github.com/getpaseo/paseo/pull/6106))
+- Fixed voice mode TTS rejecting model and voice names from OpenAI-compatible servers ([#6060](https://github.com/getpaseo/paseo/pull/6060) by [@khimaros](https://github.com/khimaros))
+- Fixed the xhigh thinking option showing "Extra high" instead of its configured label ([#6005](https://github.com/getpaseo/paseo/pull/6005) by [@EliorFureraj](https://github.com/EliorFureraj))
+- Fixed the Remove button going off screen for long custom model names in provider settings ([#6507](https://github.com/getpaseo/paseo/pull/6507))
+- Fixed the starting-ref picker not finding GitLab merge requests and issues by number ([#6525](https://github.com/getpaseo/paseo/pull/6525))
+- Fixed the starting-ref picker hiding change requests that match only in their description ([#6558](https://github.com/getpaseo/paseo/pull/6558))
+- Fixed @-mentions not finding plan files under `.cursor/plans` ([#6641](https://github.com/getpaseo/paseo/pull/6641) by [@chyendongnhanh338](https://github.com/chyendongnhanh338))
+- Fixed Paseo replacing a symlinked `config.json` with a regular file when saving settings ([#6023](https://github.com/getpaseo/paseo/pull/6023))
+- Fixed the published config schema rejecting valid settings such as `agentProfiles` and `plugins` ([#6621](https://github.com/getpaseo/paseo/pull/6621) by [@ragokan](https://github.com/ragokan))
+- Fixed duplicating a folder turning its relative symlinks into absolute links to the original ([#6771](https://github.com/getpaseo/paseo/pull/6771) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed renaming an untracked file like `[id].tsx` failing when a tracked file matches it as a pattern ([#6573](https://github.com/getpaseo/paseo/pull/6573) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed saving workspace files with long names failing with `ENAMETOOLONG` ([#6658](https://github.com/getpaseo/paseo/pull/6658) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed worktree creation and Changes failing for projects whose folder name ends in a space ([#6686](https://github.com/getpaseo/paseo/pull/6686))
+- Fixed merging a worktree when the base branch's worktree path contains a newline or ends in a space ([#6668](https://github.com/getpaseo/paseo/pull/6668) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed `paseo agent ls` listing only the first 200 agents ([#6033](https://github.com/getpaseo/paseo/pull/6033) by [@hteo1337](https://github.com/hteo1337))
+- Fixed `paseo worktree ls` and `paseo worktree archive` failing with "cwd or repoRoot is required" ([#6467](https://github.com/getpaseo/paseo/pull/6467) by [@jasonhnd](https://github.com/jasonhnd))
+- Fixed `paseo worktree ls` listing an archived worktree for up to 15 seconds ([#6545](https://github.com/getpaseo/paseo/pull/6545) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed `paseo logs --since` printing activity from before the requested timestamp ([#6514](https://github.com/getpaseo/paseo/pull/6514) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed `paseo logs --follow` splitting words across lines as text streams in ([#6528](https://github.com/getpaseo/paseo/pull/6528) by [@fiorelorenzo](https://github.com/fiorelorenzo))
+- Fixed `paseo logs` printing reasoning after the reply that followed it ([#6546](https://github.com/getpaseo/paseo/pull/6546))
+- Fixed the daemon keeping files open after a canceled HTTP download ([#6567](https://github.com/getpaseo/paseo/pull/6567) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed Linux desktop windows showing a generic icon instead of the Paseo icon ([#6645](https://github.com/getpaseo/paseo/pull/6645) by [@whme](https://github.com/whme), [@panta82](https://github.com/panta82))
+- Fixed Google Play listing Android devices without a camera as incompatible ([#6339](https://github.com/getpaseo/paseo/pull/6339))
+- Fixed `nix build .#desktop` running out of memory on Macs with less than 15 GB of RAM ([#6537](https://github.com/getpaseo/paseo/pull/6537) by [@truelecter](https://github.com/truelecter))
+- Fixed usage providers changing places after Refresh all ([#6947](https://github.com/getpaseo/paseo/pull/6947) by [@sleroq](https://github.com/sleroq))
+- Fixed the OpenCode Go usage icon being nearly invisible on dark themes ([#6362](https://github.com/getpaseo/paseo/pull/6362) by [@az33zy](https://github.com/az33zy))
+
 ## 0.11.4 - 2026-10-15
 
 [Hoplite](https://hoplite.sh) joins Paseo as our first sponsor through the company sponsorship program. Hoplite builds cloud coding agents that turn tasks from GitHub, Linear, Slack and more into pull requests. Thank you to the Hoplite team for supporting Paseo.

docs/android.md

@@ -205,12 +205,12 @@ adb exec-out screencap -p > screenshot.png
 
 Stable tag pushes like `v0.1.0` trigger:
 
-- The EAS GitHub app on Expo servers (iOS + Android production builds + store submit). There is no workflow file in this repo for it.
+- The EAS GitHub app on Expo servers, using `packages/app/.eas/workflows/release-mobile.yml` (iOS + Android production builds and distribution).
 - `.github/workflows/android-apk-release.yml` on GitHub Actions (APK asset on GitHub Release).
 
-iOS auto-submits to App Store review via a Fastlane lane after EAS uploads to TestFlight. Android auto-submits to the Play Store via EAS-managed credentials.
+iOS distributes the same build to external TestFlight testers and App Store review; see [Mobile builds (EAS)](release.md#mobile-builds-eas) for the review paths. Android auto-submits to the Play Store via EAS-managed credentials.
 
-Beta tags like `v0.1.1-beta.1` only trigger the GitHub APK workflow. They publish a GitHub prerelease APK for testing and do not submit to the stores.
+Beta tags like `v0.1.1-beta.1` trigger the GitHub APK workflow and EAS `Release iOS Beta`. They publish a GitHub prerelease APK and distribute iOS through TestFlight without submitting to production stores.
 
 `android-v*` tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. The GitHub APK workflow supports `workflow_dispatch` with an existing `tag` input so you can rebuild without cutting a new tag.
 

docs/mobile-testing.md

@@ -300,16 +300,33 @@ done
 
 ### Android audio focus interruptions
 
-Voice mode uses the custom `expo-two-way-audio` Android module, so incoming calls and other system audio owners must be tested with emulator/system commands, not a JS-only test. To verify that voice resume handles denied audio focus without crashing:
+Use native instrumentation for audio interruptions. JS-only tests cannot prove Android focus,
+input silencing, or route recovery. The module's `android/src/androidTest` suite runs through
+Gradle's `connectedDebugAndroidTest` task and uses real `AudioManager` and `AudioRecord` instances.
+Run the microphone-privacy cases on Android 12 or newer.
+
+Verify these distinct outcomes:
+
+- Dictation continues when another media owner takes permanent, temporary, or ducking focus.
+- Disabling microphone access pauses audio delivery without discarding the dictation. Enabling
+  access resumes it. Starting dictation while access is disabled waits for the same recovery.
+- Returning from music controls resumes dictation without pausing music again. Cancelling a
+  backgrounded recording must prevent the lifecycle callback from restarting it.
+- Two-way voice still stops coherently on focus loss. Keep the incoming-call check below: it
+  exercises denied focus during lifecycle resume, beyond an ordinary media takeover.
 
 ```bash
-adb shell am start -n sh.paseo/.MainActivity
-# Start voice mode in an existing composer, then background Paseo with Home.
+# Start voice mode in an existing composer, then background Paseo.
 adb emu gsm call 5551234
-# Foreground Paseo while the call is still ringing.
+# Foreground Paseo while the call is still ringing, then end the simulated call.
+adb emu gsm cancel 5551234
 ```
 
-Expected result: Paseo does not throw `RuntimeException: Audio focus request failed`; native audio reports an interruption and voice mode stops or pauses coherently.
+Expected result: no `RuntimeException: Audio focus request failed`, and voice mode stops or pauses
+coherently. Repeat with dictation: it must retain captured audio and recover microphone access.
+Use browser/device automation to operate the app; the commands above only control emulator telephony.
+
+This fix requires a rebuilt native app. An OTA update on an older binary retains legacy capture.
 
 ### Releasing the audio session when idle
 

docs/protocol-validation.md

@@ -6,7 +6,9 @@ The reason is mobile performance. A captured 353 KB provider snapshot cost about
 
 ## Runtime Path
 
-`packages/protocol/src/validation/ws-outbound.ts` is the shipped boundary. It calls the generated `WSOutboundMessageSchema.safeParse` and returns the validated data. It does not normalize, repair, or re-validate the generated result.
+`packages/protocol/src/validation/ws-outbound.ts` is the shipped boundary. It validates the envelope with a generated validator that checks only each session message's `type` tag, then runs the generated validator for that one message type and returns the validated data. Issue paths from the message validator, including nested union branches, are prefixed with `message`, so callers see the same issues as when one validator covered the whole envelope. It does not normalize, repair, or re-validate the generated result.
+
+Keep one generated function per message type. zod-aot inlines every nested schema into the function it compiles, so compiling `WSOutboundMessageSchema` as a whole produced one 11 MB function. On V8 (daemon clients, plugin hosts, the CLI, and Electron), the Maglev tier compiled that function once it was hot, allocating about 800 MB and stalling for seconds, and compiled it again after each deoptimization. Hermes has no JIT, so mobile never showed it. `packages/protocol/tests/validation/ws-outbound.test.ts` fails if a generated function grows past 1 MB.
 
 Generated validators preserve unknown keys where Zod object parsing strips them. The client dispatch path uses known `type` and payload fields, so this passthrough behavior is accepted for inbound messages. The wire format is unchanged.
 
@@ -16,11 +18,10 @@ Provider model normalization is a parser-side compatibility shim in the client c
 
 The protocol package owns generation.
 
-- `packages/protocol/codegen/ws-outbound.compile.ts` is the build-time zod-aot discovery entry.
-- `packages/protocol/scripts/generate-validation-aot.mjs` runs the exact-pinned compiler and applies the small local compiler patches before generation.
+- `packages/protocol/src/validation/ws-outbound-envelope.ts` defines the tag-only envelope schema and exposes the session message schemas that get their own validators.
+- `packages/protocol/scripts/generate-validation-aot.mjs` writes the zod-aot discovery entry and the runtime schema metadata, runs the exact-pinned compiler, and applies the small local compiler patches before generation. It also emits the `type` → validator map the boundary dispatches through.
 - `packages/protocol/scripts/watch-validation-aot.mjs` reruns generation while editing protocol sources.
-- `packages/protocol/src/generated/validation/ws-outbound.aot.ts` is generated runtime code and is gitignored.
-- `packages/protocol/src/validation/ws-outbound-schema-metadata.ts` is runtime schema metadata for zod-aot fallback/default references.
+- `packages/protocol/codegen/generated/ws-outbound.compile.ts`, `packages/protocol/src/generated/validation/ws-outbound.aot.ts`, and `packages/protocol/src/generated/validation/ws-outbound-schema-metadata.ts` are generated and gitignored. The metadata module lets generated code reach schema fallback/default values.
 
 Generation runs from protocol-owned lifecycle hooks: `prebuild`, `pretypecheck`, `pretest`, and `watch`. Installs do not run generation: published packages consume protocol from prebuilt `dist`, and local build/typecheck/test flows generate the source file at the point it is actually needed.
 

docs/release.md

@@ -305,12 +305,14 @@ macOS 13 maps to Darwin 22. The two values use different version domains; do not
 iOS and Android store builds are not in `.github/workflows`. They are triggered by the EAS GitHub app the moment the `v*` tag is pushed:
 
 - **Android (Play Store)** — EAS builds with profile `production` and auto-submits to the Play Store via `eas submit` (EAS-managed credentials, no Fastlane).
-- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads to TestFlight, and a Fastlane lane submits the build for App Store review.
+- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads once through a `testflight` job, distributes the build to the `Paseo Beta` external group with Beta App Review submission, and a Fastlane lane submits that same build for App Store review.
 - **Android APK (GitHub Release asset)** — separate, via `.github/workflows/android-apk-release.yml`. This is the only Android-related workflow that lives in this repo.
 
 EAS uses the local app version source. `packages/app/app.config.js` derives the native version from the package version. Android `versionCode` is `major * 1_000_000 + minor * 1_000 + patch`. iOS reserves 1,000 build slots per app version: beta `N` uses slot `N`, and stable uses slot `999`. For example, `0.2.6-beta.2` appears in App Store Connect as version `0.2.6` build `2006002`; stable uses build `2006999`. Rebuilding the same tag produces the same native build number; if a store has already accepted a binary and you need a different binary, cut the next beta or patch instead of relying on EAS remote auto-increment.
 
-Beta tags run `Release iOS Beta`. The workflow uploads the build to TestFlight, distributes it to the persistent `Paseo Beta` external group, and submits it for Beta App Review. Testers and the group are managed once in App Store Connect; releases require no dashboard action.
+Stable tags run `Release Mobile`; beta tags run `Release iOS Beta`. Both distribute to the persistent `Paseo Beta` external group and submit for Beta App Review, so testers receive stable releases as well as betas. Testers, the group, and required TestFlight test information are managed once in App Store Connect.
+
+Stable iOS releases use one binary for two Apple review paths: Beta App Review for external TestFlight distribution and App Store review. [Apple says](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers) the first submitted build requires a full TestFlight review; later builds for the same version might not. Do not assume a stable patch skips review.
 
 There is no mobile-release workflow under `.github/workflows`. The EAS GitHub app reads the workflows under `packages/app/.eas/workflows` and handles tag triggering directly.
 
@@ -334,7 +336,7 @@ npx eas build:list --platform android --limit 5 --non-interactive --json
 # Inspect a specific build.
 npx eas build:view <build-id>
 
-# Inspect the full release workflow, including submit_ios, submit_android,
+# Inspect the full release workflow, including distribute_ios, submit_android,
 # and submit_ios_for_review.
 npx eas workflow:view <workflow-run-id> --json
 
@@ -347,17 +349,17 @@ npx eas build:view <build-id> --json | jq '.logFiles[]'
 
 A build's `gitCommitHash` must match the release tag commit. `status` walks through `NEW` → `IN_QUEUE` → `IN_PROGRESS` → `FINISHED` (or `ERRORED`/`CANCELED`). The EAS workflow run's `gitCommitHash` and `trigger` must also match the release tag.
 
-Once a build is `FINISHED`, EAS still has release-critical work to do: Android must submit to the Play Store, and iOS must upload to TestFlight **and** submit the build for App Store review. The release is not done until all platforms are on their way through the stores.
+Once a build is `FINISHED`, EAS still has release-critical work to do: Android must submit to the Play Store, and iOS must distribute to the external TestFlight group with Beta App Review submission **and** submit the same build for App Store review. The release is not done until all platforms are on their way through the stores.
 
 For the `Release Mobile` EAS workflow, these jobs must pass:
 
 - `build_ios` — iOS binary built
-- `submit_ios` — iOS binary uploaded to App Store Connect/TestFlight
+- `distribute_ios` — iOS binary uploaded once, added to `Paseo Beta`, and submitted for Beta App Review
 - `submit_ios_for_review` — iOS build submitted for App Store review via Fastlane
 - `build_android` — Android store binary built
 - `submit_android` — Android binary submitted to the Play Store
 
-Do not treat `build_ios: SUCCESS` or `submit_ios: SUCCESS` as a completed iOS release. `submit_ios_for_review: FAILURE` means the iOS release is blocked even if the build is visible in TestFlight.
+Do not treat `build_ios: SUCCESS` or `distribute_ios: SUCCESS` as a completed iOS release. `submit_ios_for_review: FAILURE` means the iOS release is blocked even if the build is visible in TestFlight.
 
 To confirm the submission landed, inspect the EAS workflow with `npx eas workflow:view <workflow-run-id> --json`. App Store Connect (review state for the matching version/build) and the Play Console track are the final ground truth.
 
@@ -380,8 +382,9 @@ Windows, and Android APK assets are present along with the channel manifests
 (`latest-mac.yml`, `latest-linux.yml`, and `latest.yml` for stable;
 `beta-mac.yml`, `beta-linux.yml`, and `beta.yml` for beta).
 
-For stable releases, also confirm every required mobile build, upload, store
-submission, and review-submission job for the release commit. For betas, confirm
+For stable releases, also confirm every required mobile build, external
+TestFlight distribution, Beta App Review submission, and store submission job
+for the release commit. For betas, confirm
 the beta EAS workflow completed its TestFlight distribution and Beta App Review
 path. Delete the heartbeat only after every applicable checklist item passes,
 then report the release as shipped.
@@ -396,7 +399,7 @@ Pattern:
   "timezone": "UTC",
   "maxRuns": 120,
   "expiresIn": "24h",
-  "prompt": "Resume the vX.Y.Z release babysit for commit <sha>. Check npm tags; every GitHub Actions run for the release branch and tag; the published GitHub Release body, expected desktop/APK assets, and channel manifests; the Docker image; and the matching EAS workflow. Completion requires every applicable checklist item. For stable, require build_ios, submit_ios, submit_ios_for_review, build_android, and submit_android to succeed. For beta, require the beta TestFlight distribution and Beta App Review path. If work is pending, wait for the next heartbeat. If a failure can be retried safely for the same version, follow the failed-release procedure; otherwise report the blocker. When every applicable completion-checklist item passes, delete THIS heartbeat, report shipped, and stop.",
+  "prompt": "Resume the vX.Y.Z release babysit for commit <sha>. Check npm tags; every GitHub Actions run for the release branch and tag; the published GitHub Release body, expected desktop/APK assets, and channel manifests; the Docker image; and the matching EAS workflow. Completion requires every applicable checklist item. For stable, require build_ios, distribute_ios (Paseo Beta external distribution and Beta App Review submission), submit_ios_for_review, build_android, and submit_android to succeed. For beta, require the beta TestFlight distribution and Beta App Review path. If work is pending, wait for the next heartbeat. If a failure can be retried safely for the same version, follow the failed-release procedure; otherwise report the blocker. When every applicable completion-checklist item passes, delete THIS heartbeat, report shipped, and stop.",
 }
 ```
 
@@ -680,7 +683,7 @@ Every entry covers `previous stable release → release source`: first beta, lat
 - [ ] GitHub `Release Notes Sync` is green and the release body matches the stable changelog entry
 - [ ] EAS `Release Mobile` workflow for the same tag is green
 - [ ] EAS iOS `build_ios` completes for the same tag
-- [ ] EAS iOS `submit_ios` succeeds, uploading the build to App Store Connect/TestFlight
+- [ ] EAS iOS `distribute_ios` succeeds, uploading the binary once, distributing it to `Paseo Beta`, and submitting it for Beta App Review
 - [ ] EAS iOS `submit_ios_for_review` succeeds, putting the build into App Store review
 - [ ] EAS Android `build_android` completes for the same tag
 - [ ] EAS Android `submit_android` succeeds, putting the build on its Play Store track

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-Sw9WSOnvebpXgty0WACJrRq+pkKuynLMxJg6D/SnyRk=
+sha256-1WmrHvE68Lzyil4On7xtsPMQTODXZ3Jb3/juUg3nHi4=

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -36349,7 +36349,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -37469,12 +37469,12 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.11.2",
-        "@getpaseo/protocol": "0.11.2",
-        "@getpaseo/server": "0.11.2",
+        "@getpaseo/client": "0.12.0-beta.1",
+        "@getpaseo/protocol": "0.12.0-beta.1",
+        "@getpaseo/server": "0.12.0-beta.1",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -37721,10 +37721,10 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
-        "@getpaseo/protocol": "0.11.2",
-        "@getpaseo/relay": "0.11.2",
+        "@getpaseo/protocol": "0.12.0-beta.1",
+        "@getpaseo/relay": "0.12.0-beta.1",
         "zod": "^4.4.3"
       },
       "devDependencies": {
@@ -37735,7 +37735,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -37979,7 +37979,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -38875,7 +38875,7 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@codemirror/language": "6.12.4",
         "@codemirror/legacy-modes": "^6.5.3",
@@ -38904,14 +38904,14 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@agentclientprotocol/sdk": "^1.4.0",
         "use-sync-external-store": "^1.6.0"
       },
       "devDependencies": {
-        "@getpaseo/client": "0.11.2",
-        "@getpaseo/protocol": "0.11.2",
+        "@getpaseo/client": "0.12.0-beta.1",
+        "@getpaseo/protocol": "0.12.0-beta.1",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.1.0",
@@ -38921,8 +38921,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.11.2",
-        "@getpaseo/protocol": "0.11.2",
+        "@getpaseo/client": "0.12.0-beta.1",
+        "@getpaseo/protocol": "0.12.0-beta.1",
         "react": "~19.1.0",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -38944,7 +38944,7 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "semver": "^7.8.5",
         "zod": "^4.4.3"
@@ -38971,7 +38971,7 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "base64-js": "^1.5.1",
         "tweetnacl": "^1.0.3",
@@ -39189,16 +39189,16 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
         "@anthropic-ai/claude-agent-sdk": "0.3.246",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.11.2",
-        "@getpaseo/highlight": "0.11.2",
-        "@getpaseo/plugin": "0.11.2",
-        "@getpaseo/protocol": "0.11.2",
-        "@getpaseo/relay": "0.11.2",
+        "@getpaseo/client": "0.12.0-beta.1",
+        "@getpaseo/highlight": "0.12.0-beta.1",
+        "@getpaseo/plugin": "0.12.0-beta.1",
+        "@getpaseo/protocol": "0.12.0-beta.1",
+        "@getpaseo/relay": "0.12.0-beta.1",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
@@ -40119,7 +40119,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -41727,7 +41727,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.11.2",
+      "version": "0.12.0-beta.1",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [

packages/app/.eas/workflows/release-mobile.yml

@@ -23,13 +23,16 @@ jobs:
       platform: android
       profile: production
 
-  submit_ios:
-    name: Submit iOS
+  distribute_ios:
+    name: Distribute iOS to TestFlight
     needs: [build_ios]
-    type: submit
+    type: testflight
     params:
       build_id: ${{ needs.build_ios.outputs.build_id }}
       profile: production
+      external_groups:
+        - Paseo Beta
+      submit_beta_review: true
 
   submit_android:
     name: Submit Android
@@ -41,7 +44,7 @@ jobs:
 
   submit_ios_for_review:
     name: Submit iOS for App Store review
-    needs: [build_ios, submit_ios]
+    needs: [build_ios, distribute_ios]
     environment: production
     runs_on: macos-medium
     steps:

packages/app/e2e/browser/bare-folder-links.repro.spec.ts

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test, type Page } from "../support/fixtures";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+async function openFolderLink(page: Page) {
+  await page
+    .getByTestId("assistant-message")
+    .getByRole("link", { name: "Open folder", exact: true })
+    .click();
+}
+
+async function expectFolderContents(page: Page) {
+  await expect(page.getByTestId("file-explorer-tree-scroll")).toBeVisible();
+  await expect(
+    page.getByTestId("file-explorer-tree-scroll").getByText("guide.md", { exact: true }),
+  ).toBeVisible();
+}
+
+test("an explicit Markdown folder link without ./ opens its contents", async ({ page }) => {
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "bare-folder-link-repro-",
+    title: "Bare folder link reproduction",
+    initialPrompt: "Show the folder link",
+    featureValues: { mockAssistantResponse: "[Open folder](docs/guides)" },
+  });
+  try {
+    await mkdir(path.join(session.cwd, "docs/guides"), { recursive: true });
+    await writeFile(path.join(session.cwd, "docs/guides/guide.md"), "# Folder link destination\n");
+    await session.client.waitForFinish(session.agentId, 30_000);
+    await openAgentRoute(page, session);
+    await openFolderLink(page);
+    await expectFolderContents(page);
+  } finally {
+    await session.cleanup();
+  }
+});

packages/app/e2e/browser/open-project-scroll.spec.ts

@@ -0,0 +1,42 @@
+import { type Page } from "@playwright/test";
+import { test, expect } from "../support/fixtures";
+
+async function openProjectHome(page: Page) {
+  await page.goto("/open-project");
+  await expect(page.getByText("Add a project", { exact: true })).toBeVisible();
+}
+
+async function scrollToHomeFooter(page: Page) {
+  await page.mouse.move(160, 350);
+  await page.mouse.wheel(0, 1500);
+}
+
+async function expectHomeActionsReachable(page: Page) {
+  const providers = page.getByTestId("open-project-setup-providers");
+  const community = page.getByRole("button", { name: "Community", exact: true });
+  await expect(providers).toBeInViewport({ ratio: 1 });
+  await expect(community).toBeInViewport({ ratio: 1 });
+  const providerBounds = await providers.boundingBox();
+  const communityBounds = await community.boundingBox();
+  expect(providerBounds).not.toBeNull();
+  expect(communityBounds).not.toBeNull();
+  expect(communityBounds!.y).toBeGreaterThanOrEqual(providerBounds!.y + providerBounds!.height);
+}
+
+test("home actions remain reachable on a short phone screen", async ({ page }, testInfo) => {
+  await page.setViewportSize({ width: 320, height: 568 });
+  await openProjectHome(page);
+  await scrollToHomeFooter(page);
+  await expectHomeActionsReachable(page);
+  await page.screenshot({ path: testInfo.outputPath("home-scrolled.png") });
+});
+
+test("home actions fit on a desktop screen without overlap", async ({ page }) => {
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await openProjectHome(page);
+  await expectHomeActionsReachable(page);
+  await expect(page.getByTestId("open-project-setup-providers")).toHaveCSS(
+    "-webkit-app-region",
+    "none",
+  );
+});

packages/app/e2e/browser/question-prompt-pagination.spec.ts

@@ -1,5 +1,16 @@
+import { fork } from "node:child_process";
+import path from "node:path";
+import { expect } from "@playwright/test";
+import { z } from "zod";
 import { test } from "../support/fixtures";
-import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import { expectVisibleAgentSurfacesIdle } from "../support/helpers/agent-stream";
+import { buildSeededHost } from "../support/helpers/daemon-registry";
+import { killProcessTree } from "../support/helpers/spawn-node";
+import {
+  buildAgentRoute,
+  openAgentRoute,
+  seedMockAgentWorkspace,
+} from "../support/helpers/mock-agent";
 import {
   chooseQuestionOption,
   continueToNextQuestion,
@@ -130,3 +141,204 @@ test.describe("Question prompt pagination", () => {
     }
   });
 });
+
+const questionDaemonMessage = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("ready"), port: z.number(), serverId: z.string() }),
+  z.object({
+    type: z.literal("attempt"),
+    requestId: z.string(),
+    response: z.unknown(),
+    sessionId: z.string(),
+  }),
+  z.object({
+    type: z.literal("resolved"),
+    requestId: z.string(),
+    response: z.unknown(),
+    sessionId: z.string(),
+    pendingRequestIds: z.array(z.string()),
+  }),
+  z.object({ type: z.literal("error"), error: z.string() }),
+]);
+
+type QuestionResponseAttempt = Extract<z.infer<typeof questionDaemonMessage>, { type: "attempt" }>;
+
+type QuestionResolution = Extract<z.infer<typeof questionDaemonMessage>, { type: "resolved" }>;
+
+interface QuestionRetryControl {
+  attempts: QuestionResponseAttempt[];
+  resolutions: QuestionResolution[];
+  releaseFirstResponse(): void;
+}
+
+const retryTest = test.extend<{
+  questionClient: QuestionRetryControl;
+}>({
+  questionClient: async ({ page }, provide, testInfo) => {
+    const serverDir = path.resolve(__dirname, "../../../server");
+    const child = fork(path.join(serverDir, "src/server/test-utils/question-response-daemon.ts"), {
+      cwd: serverDir,
+      execArgv: ["--import", "tsx"],
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    const output: string[] = [];
+    child.stdout?.on("data", (data: Buffer) => output.push(data.toString()));
+    child.stderr?.on("data", (data: Buffer) => output.push(data.toString()));
+    const ready = Promise.withResolvers<{ port: number; serverId: string }>();
+    const attempts: QuestionResponseAttempt[] = [];
+    const resolutions: QuestionResolution[] = [];
+    child.on("message", (message: unknown) => {
+      const parsed = questionDaemonMessage.parse(message);
+      switch (parsed.type) {
+        case "ready":
+          ready.resolve(parsed);
+          break;
+        case "attempt":
+          attempts.push(parsed);
+          break;
+        case "resolved":
+          resolutions.push(parsed);
+          break;
+        case "error":
+          ready.reject(new Error(parsed.error));
+          break;
+      }
+    });
+    child.once("exit", (code) => ready.reject(new Error(`Question daemon exited with ${code}`)));
+    const timeout = setTimeout(
+      () => ready.reject(new Error("Question daemon startup timed out")),
+      20_000,
+    );
+    try {
+      const daemon = await ready.promise;
+      clearTimeout(timeout);
+      const session = await seedMockAgentWorkspace({
+        port: daemon.port,
+        repoPrefix: "question-retry-",
+        title: "Question response retry",
+        initialPrompt: "Emit synthetic questions.",
+      });
+      try {
+        await page.goto("/", { waitUntil: "commit" });
+        const serverId = daemon.serverId;
+        const host = buildSeededHost({
+          serverId,
+          endpoint: `127.0.0.1:${daemon.port}`,
+          label: "Question retry host",
+          nowIso: new Date().toISOString(),
+        });
+        await page.evaluate((extraHost) => {
+          localStorage.setItem("@paseo:e2e-extra-hosts", JSON.stringify([extraHost]));
+        }, host);
+        await page.goto(buildAgentRoute(session.workspaceId, session.agentId, serverId), {
+          waitUntil: "commit",
+        });
+        await waitForQuestionPrompt(page, 120_000);
+        await provide({ attempts, resolutions, releaseFirstResponse: () => child.send("release") });
+      } finally {
+        await session.cleanup();
+      }
+    } finally {
+      clearTimeout(timeout);
+      await killProcessTree(child);
+      if (testInfo.status !== testInfo.expectedStatus) {
+        await testInfo.attach("question-daemon", {
+          body: output.join(""),
+          contentType: "text/plain",
+        });
+      }
+    }
+  },
+});
+
+retryTest(
+  "failed question submission preserves answers and allows retry",
+  async ({ page, questionClient }, testInfo) => {
+    retryTest.setTimeout(180_000);
+    const card = page.getByTestId("question-form-card");
+    await chooseQuestionOption(page, "App");
+    await chooseQuestionOption(page, "Behind feature flag");
+    await fillQuestionAnswer(page, {
+      question: SUCCESS_QUESTION,
+      answer: "Preserve my answers after a failed submission.",
+    });
+    await card.getByRole("button", { name: "Submit" }).click();
+    await expect(card.getByRole("progressbar")).toBeVisible();
+    await expectQuestionPrimaryActionDisabled(page, "Submit");
+    await expect(card.getByRole("button", { name: "Dismiss" })).toBeDisabled();
+    await expect(card.getByRole("tab").first()).toBeDisabled();
+    await expect(card.getByRole("textbox")).not.toBeEditable();
+    questionClient.releaseFirstResponse();
+    await expectQuestionPrimaryActionEnabled(page, "Submit");
+    await card.screenshot({ path: testInfo.outputPath("submission-failed.png") });
+    await expect(card.getByRole("alert")).toHaveText("Could not send your response. Try again.");
+    await expect(card.getByRole("progressbar")).toHaveCount(0);
+    await expect(card.getByRole("button", { name: "Submit" })).toHaveText("Submit");
+    await expectQuestionDismissEnabled(page);
+    await openQuestion(page, { index: 1, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "App");
+    await openQuestion(page, { index: 2, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "Behind feature flag");
+    await openQuestion(page, { index: 3, total: TOTAL_QUESTIONS });
+    await expect(card.getByRole("textbox")).toHaveValue(
+      "Preserve my answers after a failed submission.",
+    );
+    await submitQuestionAnswers(page);
+    await expectVisibleAgentSurfacesIdle(page);
+    await expect.poll(() => questionClient.attempts.length).toBe(2);
+    expect(questionClient.attempts[1]).toEqual(questionClient.attempts[0]);
+    await expect
+      .poll(() => questionClient.resolutions)
+      .toEqual([{ ...questionClient.attempts[1], type: "resolved", pendingRequestIds: [] }]);
+    expect(questionClient.attempts[1].response).toMatchObject({
+      behavior: "allow",
+      updatedInput: {
+        answers: {
+          surface: "App",
+          rollout: "Behind feature flag",
+          success: "Preserve my answers after a failed submission.",
+        },
+      },
+    });
+    await page.screenshot({ path: testInfo.outputPath("submission-retried.png") });
+  },
+);
+
+retryTest(
+  "failed question dismissal allows an immediate retry",
+  async ({ page, questionClient }, testInfo) => {
+    retryTest.setTimeout(180_000);
+    const card = page.getByTestId("question-form-card");
+    questionClient.releaseFirstResponse();
+    await chooseQuestionOption(page, "App");
+    await chooseQuestionOption(page, "Behind feature flag");
+    await fillQuestionAnswer(page, {
+      question: SUCCESS_QUESTION,
+      answer: "Start with the internal team.",
+    });
+    await card.getByRole("button", { name: "Dismiss" }).click();
+    await expect(card.getByRole("alert")).toHaveText("Could not send your response. Try again.");
+    await expect(card.getByRole("progressbar")).toHaveCount(0);
+    await expect(card.getByRole("button", { name: "Dismiss" })).toHaveText("Dismiss");
+    await expectQuestionDismissEnabled(page);
+    await expectQuestionPrimaryActionEnabled(page, "Submit");
+    await card.screenshot({ path: testInfo.outputPath("dismissal-failed.png") });
+    await openQuestion(page, { index: 1, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "App");
+    await openQuestion(page, { index: 3, total: TOTAL_QUESTIONS });
+    await expect(card.getByRole("textbox")).toHaveValue("Start with the internal team.");
+    await expect(card.getByRole("alert")).toBeVisible();
+    await card.getByRole("button", { name: "Dismiss" }).click();
+    await expect(card).toHaveCount(0);
+    await expectVisibleAgentSurfacesIdle(page);
+    await expect.poll(() => questionClient.attempts.length).toBe(2);
+    expect(questionClient.attempts[1]).toEqual(questionClient.attempts[0]);
+    await expect
+      .poll(() => questionClient.resolutions)
+      .toEqual([{ ...questionClient.attempts[1], type: "resolved", pendingRequestIds: [] }]);
+    expect(questionClient.attempts[1].response).toEqual({
+      behavior: "deny",
+      message: "Dismissed by user",
+    });
+    await page.screenshot({ path: testInfo.outputPath("dismissal-retried.png") });
+  },
+);

packages/app/e2e/browser/sidebar-mobile-menu-sheets.spec.ts

@@ -21,6 +21,15 @@ test("project and workspace kebabs open action sheets on compact layouts", async
     await page.getByRole("button", { name: "Open menu", exact: true }).click();
     await waitForSidebarHydration(page);
 
+    await page.getByTestId("sidebar-display-preferences-menu").click();
+    await expect(page.getByRole("menuitem")).toHaveText([
+      /^Grouping/,
+      /^Title/,
+      "Show",
+      "Show background",
+    ]);
+    await closeMenuSheet(page);
+
     await page
       .getByTestId(`sidebar-project-kebab-${projectEquivalenceViewKey(seeded.projectKey)}`)
       .click();

packages/app/e2e/browser/sidebar-project-filter.spec.ts

@@ -29,6 +29,16 @@ test.describe("Sidebar project filter", () => {
       await expect(alphaRow).toBeVisible({ timeout: 30_000 });
       await expect(betaRow).toBeVisible({ timeout: 30_000 });
 
+      await page.getByTestId("sidebar-display-preferences-menu").click();
+      await expect(page.getByRole("menuitem")).toHaveText([
+        /^Grouping/,
+        /^Title/,
+        "Show",
+        "Project",
+        "Show background",
+      ]);
+      await closeSidebarDisplayPreferences(page);
+
       await openSidebarProjectFilter(page);
       await expect(page.getByTestId("sidebar-project-filter-all")).toBeVisible();
       await toggleProjectFilter(page, alpha.projectKey);

packages/app/e2e/browser/terminal-profile-icons.spec.ts

@@ -0,0 +1,71 @@
+import { ACP_PROVIDER_ICON_SVGS } from "../../src/assets/acp-provider-icons";
+import { expect, test, type Page } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { openNewWorkspaceComposer } from "../support/helpers/new-workspace";
+import { openLaunchMenu } from "../support/helpers/new-workspace-launch";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+// Harmless commands: this journey opens the profile menu without launching them.
+test.use({
+  e2eDaemonConfig: {
+    version: 1,
+    daemon: {
+      terminalProfiles: [
+        { id: "antigravity", name: "Antigravity artwork", command: "/bin/sh", icon: "agy" },
+        { id: "cursor", name: "Cursor artwork", command: "/bin/sh", icon: "cursor" },
+        { id: "unknown", name: "Unknown artwork", command: "/bin/sh", icon: "unknown-icon" },
+      ],
+    },
+  },
+});
+
+function profileIcon(page: Page, name: string) {
+  return page.getByRole("menuitem", { name: new RegExp(`^${name} artwork`) }).locator("svg");
+}
+
+async function expectBundledArtwork(page: Page, name: string, artwork: string) {
+  const icon = profileIcon(page, name);
+  await expect(icon).toBeVisible();
+  const expectedPaths = await page.evaluate((xml) => {
+    const document = new DOMParser().parseFromString(xml, "image/svg+xml");
+    return Array.from(document.querySelectorAll("path"), (path) => path.getAttribute("d")!);
+  }, artwork);
+  await expect(icon.locator("path")).toHaveCount(expectedPaths.length);
+  for (const [index, path] of expectedPaths.entries()) {
+    await expect(icon.locator("path").nth(index)).toHaveAttribute("d", path);
+  }
+  await expect(icon).toHaveAttribute("width", "14");
+  await expect(icon).toHaveAttribute("height", "14");
+  const terminalColor = await page
+    .getByRole("menuitem", { name: "Terminal", exact: true })
+    .locator("svg")
+    .evaluate((element) => getComputedStyle(element).stroke);
+  await expect(icon.locator("path").first()).toHaveCSS("fill", terminalColor);
+}
+
+async function expectUnknownArtworkFallback(page: Page) {
+  const icon = profileIcon(page, "Unknown");
+  await expect(icon).toBeVisible();
+  await expect(icon.locator('path[d="M12 8V4H8"]')).toHaveCount(1);
+}
+
+test("terminal profiles show bundled artwork while unknown icons keep the Bot fallback", async ({
+  page,
+}) => {
+  const workspace = await seedWorkspace({ repoPrefix: "terminal-icons-" });
+  try {
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await openNewWorkspaceComposer(page, {
+      projectKey: workspace.projectKey,
+      projectDisplayName: workspace.projectDisplayName,
+    });
+    await openLaunchMenu(page);
+    await expectBundledArtwork(page, "Antigravity", ACP_PROVIDER_ICON_SVGS.agy);
+    await expectBundledArtwork(page, "Cursor", ACP_PROVIDER_ICON_SVGS.cursor);
+    await expectUnknownArtworkFallback(page);
+  } finally {
+    await workspace.cleanup();
+  }
+});

packages/app/e2e/mobile/agent-device/native-composer-fullscreen.ios.ad

@@ -0,0 +1,18 @@
+context platform=ios timeout=60000 retries=0
+# Start with an empty composer in an idle chat or new-agent draft on an iPhone with the software keyboard enabled.
+# Expand a long draft with the keyboard open; Exit fullscreen must remain reachable.
+open sh.paseo.debug
+wait "editable=true" 60000
+fill "editable=true" "iOS fullscreen composer smoke.\n\nLine 1: Check that the composer keeps this draft when expanded and collapsed.\nLine 2: Check that the composer keeps this draft when expanded and collapsed.\nLine 3: Check that the composer keeps this draft when expanded and collapsed.\nLine 4: Check that the composer keeps this draft when expanded and collapsed.\nLine 5: Check that the composer keeps this draft when expanded and collapsed.\nLine 6: Check that the composer keeps this draft when expanded and collapsed.\nLine 7: Check that the composer keeps this draft when expanded and collapsed.\nLine 8: Check that the composer keeps this draft when expanded and collapsed.\nLine 9: Check that the composer keeps this draft when expanded and collapsed.\nLine 10: Check that the composer keeps this draft when expanded and collapsed.\nLine 11: Check that the composer keeps this draft when expanded and collapsed.\nLine 12: Check that the composer keeps this draft when expanded and collapsed.\nLine 13: Check that the composer keeps this draft when expanded and collapsed.\nLine 14: Check that the composer keeps this draft when expanded and collapsed."
+press "label=\"Fullscreen\""
+wait "label=\"Exit fullscreen\" role=button" 5000
+is visible "label=\"Exit fullscreen\" role=button"
+press "label=\"Exit fullscreen\" role=button"
+wait "label=\"Fullscreen\" role=button" 5000
+is visible "label=\"Fullscreen\" role=button"
+press "label=\"Fullscreen\""
+wait "label=\"Exit fullscreen\" role=button" 5000
+is visible "label=\"Exit fullscreen\" role=button"
+press "label=\"Exit fullscreen\" role=button"
+wait "label=\"Fullscreen\" role=button" 5000
+is visible "label=\"Fullscreen\" role=button"

packages/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "private": true,
   "main": "index.ts",
   "scripts": {

packages/app/src/agent-stream/view.tsx

@@ -1531,11 +1531,17 @@ function PermissionRequestCard({
   );
 
   if (request.kind === "question") {
+    const responseFailed =
+      permissionMutation.isError &&
+      permissionMutation.variables?.agentId === permission.agentId &&
+      permissionMutation.variables?.requestId === permission.request.id;
+    const responseError = responseFailed ? t("message.question.responseFailed") : null;
     return (
       <QuestionFormCard
         permission={permission}
         onRespond={handleResponse}
         isResponding={isResponding}
+        responseError={responseError}
       />
     );
   }

packages/app/src/audio/audio-engine-types.ts

@@ -2,6 +2,7 @@ export interface AudioEngineCallbacks {
   onCaptureData(pcm: Uint8Array): void;
   onVolumeLevel(level: number): void;
   onInterruption?(): void;
+  onCaptureAvailabilityChange?(available: boolean): void;
   onError?(error: Error): void;
 }
 
@@ -25,3 +26,8 @@ export interface AudioEngine {
   clearQueue(): void;
   isPlaying(): boolean;
 }
+
+export interface AudioEngineOptions {
+  traceLabel?: string;
+  captureMode?: "conversation" | "dictation";
+}

packages/app/src/audio/audio-engine.native.ts

@@ -1,4 +1,9 @@
-import type { AudioEngine, AudioEngineCallbacks, AudioPlaybackSource } from "./audio-engine-types";
+import type {
+  AudioEngine,
+  AudioEngineCallbacks,
+  AudioEngineOptions,
+  AudioPlaybackSource,
+} from "./audio-engine-types";
 
 import { createAudioPlayer, setAudioModeAsync } from "expo-audio";
 import { File, Paths } from "expo-file-system";
@@ -8,7 +13,7 @@ import { playPcm16 } from "./pcm";
 
 export function createAudioEngine(
   callbacks: AudioEngineCallbacks,
-  _options?: { traceLabel?: string },
+  options?: AudioEngineOptions,
 ): AudioEngine {
   const native = require("@getpaseo/expo-two-way-audio");
 
@@ -47,6 +52,12 @@ export function createAudioEngine(
   const interruptionSubscription = native.addExpoTwoWayAudioEventListener(
     "onAudioInterruption",
     (event: { data: string }) => {
+      if (event.data === "capture_paused" || event.data === "capture_resumed") {
+        if (refs.captureActive) {
+          callbacks.onCaptureAvailabilityChange?.(event.data === "capture_resumed");
+        }
+        return;
+      }
       if (event.data !== "blocked") {
         return;
       }
@@ -180,7 +191,10 @@ export function createAudioEngine(
       try {
         await ensureMicrophonePermission();
         await ensureInitialized();
-        const isRecording = native.toggleRecording(true);
+        const isRecording =
+          options?.captureMode === "dictation"
+            ? native.startDictation()
+            : native.toggleRecording(true);
         if (!isRecording) {
           throw new Error(
             "Microphone capture could not start because Android audio focus is unavailable.",
@@ -201,6 +215,7 @@ export function createAudioEngine(
       refs.captureActive = false;
       refs.muted = false;
       callbacks.onVolumeLevel(0);
+      callbacks.onCaptureAvailabilityChange?.(true);
       releaseSessionIfIdle();
     },
 

packages/app/src/audio/audio-engine.web.ts

@@ -1,6 +1,11 @@
 import { parsePcmSampleRate, resampleToPcm16 } from "./pcm";
 import { isElectronRuntime } from "@/desktop/host";
-import type { AudioEngine, AudioEngineCallbacks, AudioPlaybackSource } from "./audio-engine-types";
+import type {
+  AudioEngine,
+  AudioEngineCallbacks,
+  AudioEngineOptions,
+  AudioPlaybackSource,
+} from "./audio-engine-types";
 
 import { createPlaybackQueue } from "./playback";
 
@@ -46,7 +51,7 @@ async function decodeAudioData(context: AudioContext, buffer: ArrayBuffer): Prom
 
 export function createAudioEngine(
   callbacks: AudioEngineCallbacks,
-  _options?: { traceLabel?: string },
+  _options?: AudioEngineOptions,
 ): AudioEngine {
   const refs: {
     playbackContext: AudioContext | null;

packages/app/src/components/dictation-controls.tsx

@@ -87,7 +87,9 @@ export function DictationControls({
       <View style={styles.meterWrapper}>
         <VolumeMeter volume={volume} isMuted={false} isSpeaking={false} orientation="horizontal" />
       </View>
-      <Text style={timerTextStyle}>{formatDuration(duration)}</Text>
+      <Text style={timerTextStyle}>
+        {status === "paused" ? t("message.dictation.paused") : formatDuration(duration)}
+      </Text>
       <View style={styles.actionGroup}>
         <Pressable
           onPress={handleCancel}
@@ -210,6 +212,11 @@ export function DictationOverlay({
           />
           <Text style={overlayTimerTextStyle}>{formatDuration(duration)}</Text>
         </View>
+        {status === "paused" ? (
+          <Text numberOfLines={2} style={overlayTranscriptTextStyle}>
+            {t("message.dictation.paused")}
+          </Text>
+        ) : null}
         {isFailed ? (
           <Text numberOfLines={2} style={overlayTranscriptTextStyle}>
             {errorText

packages/app/src/components/provider-icons.ts

@@ -3,6 +3,7 @@ import { providerSnapshotIcons } from "@/data/provider-icons";
 import { Bot, PackagePlus } from "lucide-react-native";
 import { createElement, useCallback, type ComponentType } from "react";
 import { SvgXml } from "react-native-svg";
+import { TERMINAL_PROFILE_ICON_NAMES } from "@getpaseo/protocol/provider-icon-names";
 import { ClaudeIcon } from "@/components/icons/claude-icon";
 import { CodexIcon } from "@/components/icons/codex-icon";
 import { CopilotIcon } from "@/components/icons/copilot-icon";
@@ -10,6 +11,7 @@ import { MiniMaxIcon } from "@/components/icons/minimax-icon";
 import { OpenCodeIcon } from "@/components/icons/opencode-icon";
 import { OmpIcon } from "@/components/icons/omp-icon";
 import { PiIcon } from "@/components/icons/pi-icon";
+import { ACP_PROVIDER_ICON_SVGS } from "@/assets/acp-provider-icons";
 import { ACP_PROVIDER_CATALOG } from "@/data/acp-provider-catalog";
 import { resolveProviderIconName } from "@/components/provider-icon-name";
 
@@ -31,10 +33,17 @@ const BUILTIN_PROVIDER_ICONS: Record<string, ProviderIconComponent> = {
   pi: PiIcon as unknown as ProviderIconComponent,
 };
 
-const CATALOG_ICON_SVGS = new Map(
+const CATALOG_ICON_SVGS = new Map<string, string>(
   ACP_PROVIDER_CATALOG.flatMap((entry) => (entry.iconSvg ? [[entry.id, entry.iconSvg]] : [])),
 );
 
+for (const name of TERMINAL_PROFILE_ICON_NAMES) {
+  const iconSvg = (ACP_PROVIDER_ICON_SVGS as Record<string, string | undefined>)[name];
+  if (iconSvg) {
+    CATALOG_ICON_SVGS.set(name, iconSvg);
+  }
+}
+
 const catalogIconComponents = new Map<string, ProviderIconComponent>();
 const snapshotIconComponents = new Map<string, ProviderIconComponent>();
 

packages/app/src/components/question-form-card.browser.test.tsx

@@ -58,6 +58,7 @@ function mountCard(question: Record<string, unknown>) {
         permission={buildPermission(question)}
         onRespond={onRespond}
         isResponding={false}
+        responseError={null}
       />,
     ),
   );

packages/app/src/components/question-form-card.tsx

@@ -1,3 +1,4 @@
+import { Alert } from "@/components/ui/alert";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useState, useCallback, useMemo, useRef, type RefObject } from "react";
 import { View, Text, Pressable, type PressableStateCallbackType } from "react-native";
@@ -27,6 +28,7 @@ interface QuestionFormCardProps {
   permission: PendingPermission;
   onRespond: (response: AgentPermissionResponse) => void;
   isResponding: boolean;
+  responseError: string | null;
 }
 
 const IS_WEB = isWeb;
@@ -339,7 +341,12 @@ function QuestionOtherInput({
   );
 }
 
-export function QuestionFormCard({ permission, onRespond, isResponding }: QuestionFormCardProps) {
+export function QuestionFormCard({
+  permission,
+  onRespond,
+  isResponding,
+  responseError,
+}: QuestionFormCardProps) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const isMobile = useIsCompactFormFactor();
@@ -438,7 +445,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
   ]);
 
   const handleDeny = useCallback(() => {
-    if (!questions) return;
+    if (!questions || isResponding) return;
     setRespondingAction("dismiss");
     if (shouldSubmitEmptyOnDismiss(questions)) {
       onRespond({
@@ -454,7 +461,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
       behavior: "deny",
       message: "Dismissed by user",
     });
-  }, [questions, onRespond, otherTexts, permission.request.input, selections]);
+  }, [questions, isResponding, onRespond, otherTexts, permission.request.input, selections]);
 
   const handleSelectQuestion = useCallback((index: number) => {
     setActiveQuestionIndex(index);
@@ -487,6 +494,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
     [theme.colors.surface2, theme.colors.surface1, theme.colors.borderAccent],
   );
 
+  const pendingAction = isResponding ? respondingAction : null;
   const primaryDisabled = isResponding || (isLastQuestion ? !allAnswered : !activeQuestionAnswered);
   const primaryActionLabel = isLastQuestion
     ? t("message.question.submit")
@@ -550,7 +558,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
   const dismissLabel = resolveDismissLabel(questions, t("common.actions.dismiss"));
   const selected = selections[resolvedActiveQuestionIndex] ?? new Set<number>();
   const otherText = otherTexts[resolvedActiveQuestionIndex] ?? "";
-  const showTextInput = activeQuestion ? questionShowsTextInput(activeQuestion) : false;
+  const showTextInput = questionShowsTextInput(questions[resolvedActiveQuestionIndex]);
 
   return (
     <View style={containerStyle} testID="question-form-card">
@@ -604,6 +612,8 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
         </View>
       ) : null}
 
+      {responseError ? <Alert variant="error" description={responseError} size="sm" /> : null}
+
       <View style={actionsContainerStyle}>
         <Pressable
           style={dismissButtonStyle}
@@ -613,7 +623,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           accessibilityLabel={dismissLabel}
           testID="question-form-dismiss"
         >
-          {respondingAction === "dismiss" ? (
+          {pendingAction === "dismiss" ? (
             <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
           ) : (
             <View style={styles.actionContent}>
@@ -631,7 +641,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           accessibilityLabel={primaryActionLabel}
           testID="question-form-primary-action"
         >
-          {respondingAction === "submit" ? (
+          {pendingAction === "submit" ? (
             <LoadingSpinner size="small" color={theme.colors.accentForeground} />
           ) : (
             <View style={styles.actionContent}>

packages/app/src/components/sidebar/display-preferences/menu.tsx

@@ -301,13 +301,6 @@ export function SidebarDisplayPreferencesMenu(): ReactElement {
           sheetTitle={t("sidebar.display.heading")}
           testID="sidebar-display-preferences-content"
         >
-          <MenuItem
-            selected={preferences.showBackground}
-            closeOnSelect={false}
-            onSelect={preferences.toggleBackground}
-          >
-            {t("sidebar.display.showBackground")}
-          </MenuItem>
           <MenuSubTrigger
             id="grouping"
             value={t(GROUPING_LABEL_KEYS[preferences.grouping])}
@@ -366,6 +359,14 @@ export function SidebarDisplayPreferencesMenu(): ReactElement {
               </MenuSubTrigger>
             </>
           ) : null}
+          <MenuSeparator />
+          <MenuItem
+            selected={preferences.showBackground}
+            closeOnSelect={false}
+            onSelect={preferences.toggleBackground}
+          >
+            {t("sidebar.display.showBackground")}
+          </MenuItem>
         </MenuSurface>
       </MenuRoot>
       <WorkspaceLabelManagerModal visible={managerOpen} onClose={closeManager} />

packages/app/src/hooks/use-dictation-audio-source.native.ts

@@ -14,6 +14,7 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
   const onErrorRef = useRef(config.onError);
   const onInterruptionRef = useRef(config.onInterruption);
   const [volume, setVolume] = useState(0);
+  const [isPaused, setIsPaused] = useState(false);
   const engineRef = useRef<ReturnType<typeof createAudioEngine> | null>(null);
 
   const getOrCreateEngine = useCallback(() => {
@@ -21,20 +22,24 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
       return engineRef.current;
     }
 
-    engineRef.current = createAudioEngine({
-      onCaptureData: (pcm) => {
-        onPcmSegmentRef.current(Buffer.from(pcm).toString("base64"));
+    engineRef.current = createAudioEngine(
+      {
+        onCaptureData: (pcm) => {
+          onPcmSegmentRef.current(Buffer.from(pcm).toString("base64"));
+        },
+        onVolumeLevel: (level) => {
+          setVolume(level);
+        },
+        onError: (error) => {
+          onErrorRef.current?.(error);
+        },
+        onInterruption: () => {
+          onInterruptionRef.current?.();
+        },
+        onCaptureAvailabilityChange: (available) => setIsPaused(!available),
       },
-      onVolumeLevel: (level) => {
-        setVolume(level);
-      },
-      onError: (error) => {
-        onErrorRef.current?.(error);
-      },
-      onInterruption: () => {
-        onInterruptionRef.current?.();
-      },
-    });
+      { captureMode: "dictation" },
+    );
     return engineRef.current;
   }, []);
 
@@ -67,5 +72,6 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
     start,
     stop,
     volume,
+    isPaused,
   };
 }

packages/app/src/hooks/use-dictation-audio-source.types.ts

@@ -8,4 +8,5 @@ export interface DictationAudioSource {
   start: () => Promise<void>;
   stop: () => Promise<void>;
   volume: number;
+  isPaused: boolean;
 }

packages/app/src/hooks/use-dictation-audio-source.web.ts

@@ -442,6 +442,7 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
       },
       stop,
       volume,
+      isPaused: false,
     }),
     [start, stop, volume],
   );

packages/app/src/hooks/use-dictation.shared.ts

@@ -1,6 +1,6 @@
 import { i18n } from "@/i18n/i18next";
 
-export type DictationStatus = "idle" | "recording" | "uploading" | "failed";
+export type DictationStatus = "idle" | "recording" | "paused" | "uploading" | "failed";
 
 export interface UseDictationOptions {
   client: import("@getpaseo/client/internal/daemon-client").DaemonClient | null;

packages/app/src/hooks/use-dictation.ts

@@ -461,7 +461,7 @@ export function useDictation(options: UseDictationOptions): UseDictationResult {
     volume: audio.volume,
     duration,
     error,
-    status,
+    status: status === "recording" && audio.isPaused ? "paused" : status,
     startDictation,
     cancelDictation,
     confirmDictation,

packages/app/src/i18n/resources/ar.ts

@@ -360,6 +360,7 @@ export const ar: TranslationResources = {
       details: "تفاصيل",
     },
     dictation: {
+      paused: "تمت مقاطعة الميكروفون. في انتظار الاستئناف…",
       start: "بدء الإملاء الصوتي",
       cancel: "إلغاء الإملاء",
       retry: "أعد محاولة الإملاء",
@@ -369,6 +370,7 @@ export const ar: TranslationResources = {
       failedRetry: "فشل الإملاء. اضغط على إعادة المحاولة.",
     },
     question: {
+      responseFailed: "تعذر إرسال ردك. حاول مرة أخرى.",
       submit: "يُقدِّم",
       next: "التالي",
       answerPlaceholder: "اكتب إجابتك...",

packages/app/src/i18n/resources/en.ts

@@ -357,6 +357,7 @@ export const en = {
       details: "Details",
     },
     dictation: {
+      paused: "Microphone interrupted. Waiting to resume…",
       start: "Start voice dictation",
       cancel: "Cancel dictation",
       retry: "Retry dictation",
@@ -366,6 +367,7 @@ export const en = {
       failedRetry: "Dictation failed. Tap retry.",
     },
     question: {
+      responseFailed: "Could not send your response. Try again.",
       submit: "Submit",
       next: "Next",
       answerPlaceholder: "Type your answer...",

packages/app/src/i18n/resources/es.ts

@@ -365,6 +365,7 @@ export const es: TranslationResources = {
       details: "Detalles",
     },
     dictation: {
+      paused: "Micrófono interrumpido. Esperando para reanudar…",
       start: "Iniciar dictado de voz",
       cancel: "Cancelar dictado",
       retry: "Reintentar el dictado",
@@ -374,6 +375,7 @@ export const es: TranslationResources = {
       failedRetry: "El dictado falló. Toca reintentar.",
     },
     question: {
+      responseFailed: "No se pudo enviar tu respuesta. Inténtalo de nuevo.",
       submit: "Entregar",
       next: "Siguiente",
       answerPlaceholder: "Escribe tu respuesta...",

packages/app/src/i18n/resources/fr.ts

@@ -365,6 +365,7 @@ export const fr: TranslationResources = {
       details: "Détails",
     },
     dictation: {
+      paused: "Microphone interrompu. En attente de reprise…",
       start: "Démarrer la dictée vocale",
       cancel: "Annuler la dictée",
       retry: "Relancer la dictée",
@@ -374,6 +375,7 @@ export const fr: TranslationResources = {
       failedRetry: "La dictée a échoué. Appuyez sur Réessayer.",
     },
     question: {
+      responseFailed: "Impossible d’envoyer votre réponse. Réessayez.",
       submit: "Envoyer",
       next: "Suivant",
       answerPlaceholder: "Saisissez votre réponse…",

packages/app/src/i18n/resources/ja.ts

@@ -365,6 +365,7 @@ export const ja: TranslationResources = {
       details: "詳細",
     },
     dictation: {
+      paused: "マイクが中断されました。再開を待っています…",
       start: "音声入力を開始",
       cancel: "音声入力をキャンセル",
       retry: "音声入力を再試行",
@@ -374,6 +375,7 @@ export const ja: TranslationResources = {
       failedRetry: "音声入力に失敗しました。再試行をタップしてください。",
     },
     question: {
+      responseFailed: "回答を送信できませんでした。もう一度お試しください。",
       submit: "送信",
       next: "次へ",
       answerPlaceholder: "回答を入力...",

packages/app/src/i18n/resources/ko.ts

@@ -361,6 +361,7 @@ export const ko: TranslationResources = {
       details: "세부 정보",
     },
     dictation: {
+      paused: "마이크가 중단되었습니다. 재개를 기다리는 중…",
       start: "음성 받아쓰기 시작",
       cancel: "받아쓰기 취소",
       retry: "받아쓰기 다시 시도",
@@ -370,6 +371,7 @@ export const ko: TranslationResources = {
       failedRetry: "받아쓰기에 실패했습니다. 다시 시도하려면 누르세요.",
     },
     question: {
+      responseFailed: "응답을 보내지 못했습니다. 다시 시도해 주세요.",
       submit: "제출",
       next: "다음",
       answerPlaceholder: "답변을 입력하세요...",

packages/app/src/i18n/resources/pt-BR.ts

@@ -364,6 +364,7 @@ export const ptBR: TranslationResources = {
       details: "Detalhes",
     },
     dictation: {
+      paused: "Microfone interrompido. Aguardando para retomar…",
       start: "Iniciar ditado por voz",
       cancel: "Cancelar ditado",
       retry: "Tentar ditado novamente",
@@ -373,6 +374,7 @@ export const ptBR: TranslationResources = {
       failedRetry: "Falha no ditado. Toque para tentar novamente.",
     },
     question: {
+      responseFailed: "Não foi possível enviar sua resposta. Tente novamente.",
       submit: "Enviar",
       next: "Próximo",
       answerPlaceholder: "Digite sua resposta...",

packages/app/src/i18n/resources/ru.ts

@@ -364,6 +364,7 @@ export const ru: TranslationResources = {
       details: "Подробности",
     },
     dictation: {
+      paused: "Микрофон прерван. Ожидание возобновления…",
       start: "Начать диктовку голосом",
       cancel: "Отменить диктовку",
       retry: "Повторить диктовку",
@@ -373,6 +374,7 @@ export const ru: TranslationResources = {
       failedRetry: "Диктовка не удалась. Нажмите «Повторить».",
     },
     question: {
+      responseFailed: "Не удалось отправить ответ. Попробуйте ещё раз.",
       submit: "Отправить",
       next: "Далее",
       answerPlaceholder: "Введите ответ...",

packages/app/src/i18n/resources/zh-CN.ts

@@ -360,6 +360,7 @@ export const zhCN: TranslationResources = {
       details: "详情",
     },
     dictation: {
+      paused: "麦克风已中断，正在等待恢复…",
       start: "开始语音听写",
       cancel: "取消听写",
       retry: "重试听写",
@@ -369,6 +370,7 @@ export const zhCN: TranslationResources = {
       failedRetry: "听写失败。点按重试。",
     },
     question: {
+      responseFailed: "未能发送你的回复，请重试。",
       submit: "提交",
       next: "下一步",
       answerPlaceholder: "输入你的回答...",

packages/app/src/keyboard/shift/internal/translate.ios.tsx

@@ -1,5 +1,5 @@
-import { useMemo, type ReactNode } from "react";
-import { Animated, type ViewProps } from "react-native";
+import { useMemo, useEffect, type ReactNode } from "react";
+import { Animated, useAnimatedValue, type ViewProps } from "react-native";
 import { useKeyboardAnimation } from "react-native-keyboard-controller";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
@@ -32,9 +32,23 @@ export function KeyboardTranslateView({
       }),
     [bottomClearance, height, insets.bottom, progress],
   );
+  // Fullscreen resizes this view while disabling translation. iOS Fabric can
+  // reapply its previous transform during that layout commit. Keep the graph
+  // attached and apply the mode on the native animation frame; a static zero or
+  // setValue during the React commit gets overwritten by the resize.
+  const enabledValue = useAnimatedValue(enabled ? 1 : 0);
+  useEffect(() => {
+    const animation = Animated.timing(enabledValue, {
+      toValue: enabled ? 1 : 0,
+      duration: 0,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [enabled, enabledValue]);
   const keyboardStyle = useMemo(
-    () => ({ transform: [{ translateY: enabled ? translateY : 0 }] }),
-    [enabled, translateY],
+    () => ({ transform: [{ translateY: Animated.multiply(translateY, enabledValue) }] }),
+    [enabledValue, translateY],
   );
 
   return (

packages/app/src/screens/open-project-screen.tsx

@@ -1,7 +1,7 @@
 import { useHosts, useHostRuntimeLastError } from "@/runtime/host-runtime";
 import { useCallback, useEffect, useState, type ComponentType } from "react";
 import { useTranslation } from "react-i18next";
-import { View, Text, Pressable } from "react-native";
+import { View, Text, Pressable, ScrollView } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useRouter } from "expo-router";
 import { FolderOpen, Inbox, Plug, Smartphone } from "lucide-react-native";
@@ -18,11 +18,12 @@ import {
   HEADER_INNER_HEIGHT_MOBILE,
   HEADER_TOP_PADDING_MOBILE,
 } from "@/constants/layout";
-import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import { PairDeviceModal } from "@/desktop/components/pair-device-modal";
 import { buildSettingsHostSectionRoute } from "@/utils/host-routes";
 
+const WINDOW_CONTENT_DATASET = { "window-content": "" };
+
 export function OpenProjectScreen() {
   const { t } = useTranslation();
   const hosts = useHosts();
@@ -61,51 +62,56 @@ export function OpenProjectScreen() {
   return (
     <View style={styles.container}>
       <MenuHeader borderless />
-      <View style={styles.content}>
-        <TitlebarDragRegion />
-        <View style={styles.logo}>
-          <PaseoLogo size={52} />
-        </View>
-        {hosts.map((host) => (
-          <HostError key={host.serverId} serverId={host.serverId} label={host.label} />
-        ))}
-        <View style={styles.tiles}>
-          <HomeTile
-            icon={FolderOpen}
-            title={t("openProject.tiles.addProject.title")}
-            description={t("openProject.tiles.addProject.description")}
-            onPress={handleOpenPicker}
-            testID="open-project-submit"
-            accent
-          />
-          <HomeTile
-            icon={Inbox}
-            title={t("openProject.tiles.importSession.title")}
-            description={t("openProject.tiles.importSession.description")}
-            onPress={importSession.open}
-            testID="open-project-import-session"
-          />
-          <HomeTile
-            icon={Plug}
-            title={t("openProject.tiles.setupProviders.title")}
-            description={t("openProject.tiles.setupProviders.description")}
-            onPress={handleOpenProviders}
-            testID="open-project-setup-providers"
-          />
-          {localServerId ? (
+      <ScrollView
+        style={styles.scroll}
+        contentContainerStyle={styles.scrollContent}
+        dataSet={WINDOW_CONTENT_DATASET}
+      >
+        <View style={styles.content}>
+          <View style={styles.logo}>
+            <PaseoLogo size={52} />
+          </View>
+          {hosts.map((host) => (
+            <HostError key={host.serverId} serverId={host.serverId} label={host.label} />
+          ))}
+          <View style={styles.tiles}>
             <HomeTile
-              icon={Smartphone}
-              title={t("openProject.tiles.pairDevice.title")}
-              description={t("openProject.tiles.pairDevice.description")}
-              onPress={handleOpenPairDevice}
-              testID="open-project-pair-device"
+              icon={FolderOpen}
+              title={t("openProject.tiles.addProject.title")}
+              description={t("openProject.tiles.addProject.description")}
+              onPress={handleOpenPicker}
+              testID="open-project-submit"
+              accent
             />
-          ) : null}
+            <HomeTile
+              icon={Inbox}
+              title={t("openProject.tiles.importSession.title")}
+              description={t("openProject.tiles.importSession.description")}
+              onPress={importSession.open}
+              testID="open-project-import-session"
+            />
+            <HomeTile
+              icon={Plug}
+              title={t("openProject.tiles.setupProviders.title")}
+              description={t("openProject.tiles.setupProviders.description")}
+              onPress={handleOpenProviders}
+              testID="open-project-setup-providers"
+            />
+            {localServerId ? (
+              <HomeTile
+                icon={Smartphone}
+                title={t("openProject.tiles.pairDevice.title")}
+                description={t("openProject.tiles.pairDevice.description")}
+                onPress={handleOpenPairDevice}
+                testID="open-project-pair-device"
+              />
+            ) : null}
+          </View>
         </View>
-      </View>
-      <View style={styles.communityRow}>
-        <CommunityLinks />
-      </View>
+        <View style={styles.communityRow}>
+          <CommunityLinks />
+        </View>
+      </ScrollView>
       <PairDeviceModal
         serverId={localServerId ?? ""}
         visible={isPairDeviceOpen}
@@ -176,18 +182,21 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: theme.colors.surface0,
     userSelect: "none",
   },
+  scroll: {
+    flex: 1,
+  },
+  scrollContent: {
+    flexGrow: 1,
+  },
   content: {
     position: "relative",
-    flex: 1,
+    flexGrow: 1,
+    flexShrink: 0,
     justifyContent: { xs: "flex-start", md: "center" },
     alignItems: "center",
     gap: 0,
     padding: theme.spacing[6],
     paddingTop: { xs: theme.spacing[12], md: theme.spacing[6] },
-    paddingBottom: {
-      xs: HEADER_INNER_HEIGHT_MOBILE + HEADER_TOP_PADDING_MOBILE + theme.spacing[6],
-      md: HEADER_INNER_HEIGHT + theme.spacing[6],
-    },
   },
   logo: {
     marginBottom: theme.spacing[8],
@@ -238,10 +247,8 @@ const styles = StyleSheet.create((theme) => ({
     lineHeight: 18,
   },
   communityRow: {
-    position: "absolute",
-    left: 0,
-    right: 0,
-    bottom: {
+    flexShrink: 0,
+    paddingBottom: {
       xs: HEADER_INNER_HEIGHT_MOBILE + HEADER_TOP_PADDING_MOBILE + theme.spacing[2],
       md: HEADER_INNER_HEIGHT + theme.spacing[2],
     },

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "bin": {
     "paseo": "bin/paseo"
@@ -28,9 +28,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.11.2",
-    "@getpaseo/protocol": "0.11.2",
-    "@getpaseo/server": "0.11.2",
+    "@getpaseo/client": "0.12.0-beta.1",
+    "@getpaseo/protocol": "0.12.0-beta.1",
+    "@getpaseo/server": "0.12.0-beta.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",

packages/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo client SDK package",
   "files": [
     "dist",
@@ -39,8 +39,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.11.2",
-    "@getpaseo/relay": "0.11.2",
+    "@getpaseo/protocol": "0.12.0-beta.1",
+    "@getpaseo/relay": "0.12.0-beta.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {

packages/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "private": true,
   "description": "Paseo desktop app (Electron wrapper)",
   "homepage": "https://paseo.sh",

packages/expo-two-way-audio/android/build.gradle

@@ -36,8 +36,14 @@ android {
   defaultConfig {
     versionCode 1
     versionName "0.1.0"
+    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   }
   lintOptions {
     abortOnError false
   }
 }
+
+dependencies {
+  androidTestImplementation 'androidx.test:runner:1.6.2'
+  androidTestImplementation 'androidx.test.ext:junit:1.2.1'
+}

packages/expo-two-way-audio/android/src/androidTest/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+    <application>
+        <activity android:name="expo.modules.twowayaudio.AudioEngineTestActivity"
+            android:exported="true" />
+    </application>
+</manifest>

packages/expo-two-way-audio/android/src/androidTest/java/expo/modules/twowayaudio/AudioEngineTest.kt

@@ -0,0 +1,223 @@
+package expo.modules.twowayaudio
+
+import AudioEngine
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.filters.SdkSuppress
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.atomic.AtomicInteger
+
+class AudioEngineTestActivity : Activity()
+
+/** Real AudioManager and AudioRecord: focus loss is delivered by Android, never injected. */
+@RunWith(AndroidJUnit4::class)
+class AudioEngineTest {
+    private val instrumentation = InstrumentationRegistry.getInstrumentation()
+    private lateinit var activity: Activity
+    private lateinit var engine: AudioEngine
+    private lateinit var audio: AudioManager
+    private val packets = AtomicInteger()
+    private val events = CopyOnWriteArrayList<String>()
+    private val requests = mutableListOf<AudioFocusRequest>()
+
+    @Before fun setUp() {
+        val context = instrumentation.context
+        shell("pm grant ${context.packageName} android.permission.RECORD_AUDIO")
+        activity = instrumentation.startActivitySync(
+            Intent(context, AudioEngineTestActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        )
+        instrumentation.waitForIdleSync()
+        audio = activity.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        main {
+            engine = AudioEngine(activity)
+            engine.onMicDataCallback = { packets.incrementAndGet() }
+            engine.onAudioInterruptionCallback = { events.add(it) }
+        }
+    }
+
+    @After fun tearDown() {
+        shell("cmd sensor_privacy disable 0 microphone")
+        main {
+            requests.forEach { audio.abandonAudioFocusRequest(it) }
+            engine.tearDown()
+            activity.finish()
+        }
+    }
+
+    @Test fun dictationContinuesWhenMusicTakesFocus() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN)
+    }
+
+    @Test fun dictationContinuesWhenFocusIsTemporarilyLost() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
+    }
+
+    @Test fun dictationContinuesWhenAnotherAppRequestsDucking() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
+    }
+
+    @Test fun conversationStillStopsOnFocusLoss() {
+        main { assertTrue(engine.toggleRecording(true)) }
+        await("conversation microphone data") { packets.get() > 2 }
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        await("terminal conversation interruption") { events.contains("blocked") }
+        assertFalse(engine.isRecording)
+    }
+
+    @Test fun dictationStartsWhileMusicOwnsFocusAndCanBeStartedAgain() {
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        startDictation()
+        main { engine.toggleRecording(false); engine.releaseAudioSession() }
+        val stoppedAt = packets.get()
+        startDictation()
+        await("new recording data") { packets.get() > stoppedAt + 2 }
+        assertFalse(events.contains("blocked"))
+    }
+
+    @Test fun cancellingWhileBackgroundedDoesNotRestartOnResume() {
+        startDictation()
+        main {
+            engine.pauseRecordingAndPlayer()
+            engine.toggleRecording(false)
+            engine.releaseAudioSession()
+            engine.resumeRecordingAndPlayer()
+        }
+        assertFalse(engine.isRecording)
+    }
+
+    @Test fun dictationKeepsItsCaptureModeAfterBackgroundResume() {
+        startDictation()
+        main { engine.pauseRecordingAndPlayer(); engine.resumeRecordingAndPlayer() }
+        val resumedAt = packets.get()
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        await("resumed dictation data after focus loss") { packets.get() > resumedAt + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun microphonePrivacyInterruptionPreservesCaptureAndRecovers() {
+        startDictation()
+        shell("cmd sensor_privacy enable 0 microphone")
+        await("input paused") { events.contains("capture_paused") }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        // Once Android reports silencing, do not enqueue artificial silence for transcription.
+        SystemClock.sleep(100)
+        val pausedAt = packets.get()
+        SystemClock.sleep(150)
+        assertEquals(pausedAt, packets.get())
+        shell("cmd sensor_privacy disable 0 microphone")
+        await("input resumed") { events.contains("capture_resumed") }
+        await("microphone data after recovery") { packets.get() > pausedAt + 3 }
+        assertTrue(engine.isRecording)
+        assertEquals(listOf("capture_paused", "capture_resumed"), events.toList())
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun startingWithMicrophonePrivacyEnabledWaitsAndRecovers() {
+        shell("cmd sensor_privacy enable 0 microphone")
+        main { assertTrue(engine.startDictation()) }
+        await("initial input paused") { events.contains("capture_paused") }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        shell("cmd sensor_privacy disable 0 microphone")
+        await("initial input resumed") { events.contains("capture_resumed") }
+        await("microphone data") { packets.get() > 3 }
+    }
+
+    @Test fun resumingDictationDoesNotTakeFocusBackFromMusic() {
+        startDictation()
+        main { engine.pauseRecordingAndPlayer() }
+        val changes = CopyOnWriteArrayList<Int>()
+        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+            .setOnAudioFocusChangeListener({ changes.add(it) }, Handler(Looper.getMainLooper()))
+            .build()
+        requests.add(request)
+        main { assertEquals(AudioManager.AUDIOFOCUS_REQUEST_GRANTED, audio.requestAudioFocus(request)) }
+        val before = packets.get()
+        main { engine.resumeRecordingAndPlayer() }
+        await("resumed microphone data") { packets.get() > before + 3 }
+        assertTrue(engine.isRecording)
+        assertTrue("Music lost focus on dictation resume: $changes", changes.isEmpty())
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun stoppingDictationReleasesTheCommunicationRoute() {
+        startDictation()
+        await("selected communication route") { hasCommunicationRoute() }
+        main { engine.toggleRecording(false); engine.releaseAudioSession() }
+        await("normal audio mode") { audio.mode == AudioManager.MODE_NORMAL }
+        await("cleared communication route") { !hasCommunicationRoute() }
+        assertFalse(engine.isRecording)
+    }
+
+    private fun assertDictationSurvives(gain: Int) {
+        startDictation()
+        val before = packets.get()
+        val request = takeFocus(gain)
+        await("microphone data while focus is lost") { packets.get() > before + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        val during = packets.get()
+        main { audio.abandonAudioFocusRequest(request) }
+        await("microphone data after focus release") { packets.get() > during + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+    }
+
+    private fun startDictation() {
+        val before = packets.get()
+        main { assertTrue(engine.startDictation()) }
+        await("initial microphone data") { packets.get() > before + 3 }
+    }
+
+    private fun takeFocus(gain: Int): AudioFocusRequest {
+        val request = AudioFocusRequest.Builder(gain)
+            .setAudioAttributes(AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC).build())
+            .setOnAudioFocusChangeListener({}, Handler(Looper.getMainLooper()))
+            .build()
+        requests.add(request)
+        main { assertEquals(AudioManager.AUDIOFOCUS_REQUEST_GRANTED, audio.requestAudioFocus(request)) }
+        return request
+    }
+
+    private fun main(action: () -> Unit) = instrumentation.runOnMainSync(action)
+
+    private fun await(description: String, condition: () -> Boolean) {
+        val deadline = SystemClock.elapsedRealtime() + 5000
+        while (!condition() && SystemClock.elapsedRealtime() < deadline) SystemClock.sleep(20)
+        assertTrue("Timed out waiting for $description; events=$events packets=${packets.get()}", condition())
+    }
+
+    // communicationDevice reports the effective system device even after our selection is cleared.
+    // Inspect only current route clients, never the historical routing event log.
+    private fun hasCommunicationRoute(): Boolean {
+        val dump = shell("dumpsys audio")
+        assertTrue("Missing Android communication route diagnostics", dump.contains("Communication route clients:"))
+        return dump.lineSequence().any {
+            it.trimStart().startsWith("[CommunicationRouteClient: mUid: ${android.os.Process.myUid()} ")
+        }
+    }
+
+    private fun shell(command: String): String =
+        instrumentation.uiAutomation.executeShellCommand(command).use {
+            android.os.ParcelFileDescriptor.AutoCloseInputStream(it).readBytes().toString(Charsets.UTF_8)
+        }
+}

packages/expo-two-way-audio/android/src/main/java/expo/modules/twowayaudio/AudioEngine.kt

@@ -6,12 +6,14 @@ import android.media.AudioFocusRequest
 import android.media.AudioFormat
 import android.media.AudioManager
 import android.media.AudioRecord
+import android.media.AudioRecordingConfiguration
 import android.media.AudioTrack
 import android.media.MediaRecorder
 import android.media.audiofx.AcousticEchoCanceler
 import android.media.audiofx.NoiseSuppressor
 import android.os.Build
-import android.os.PowerManager
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
 import androidx.annotation.RequiresApi
 import java.util.LinkedList
@@ -34,7 +36,26 @@ class AudioEngine (context: Context) {
     private var noiseSuppressor: NoiseSuppressor? = null
     private val executorServiceMicrophone = Executors.newFixedThreadPool(1)
     private val executorServicePlayback = Executors.newFixedThreadPool(1)
-    private var speakerDevice: AudioDeviceInfo? = null
+    private enum class CaptureMode { CONVERSATION, DICTATION }
+    private var captureMode = CaptureMode.CONVERSATION
+    private val mainHandler = Handler(Looper.getMainLooper())
+    @Volatile private var captureSilenced = false
+    private val recordingCallback = object : AudioManager.AudioRecordingCallback() {
+        override fun onRecordingConfigChanged(configs: MutableList<AudioRecordingConfiguration>) {
+            if (!isRecording || !::audioRecord.isInitialized) return
+            val config = configs.firstOrNull { it.clientAudioSessionId == audioRecord.audioSessionId }
+                ?: return
+            setCaptureSilenced(config.isClientSilenced)
+        }
+    }
+    private val deviceCallback = object : android.media.AudioDeviceCallback() {
+        override fun onAudioDevicesAdded(devices: Array<out AudioDeviceInfo>) {
+            if (communicationRouteActive) updateAudioRouting()
+        }
+        override fun onAudioDevicesRemoved(devices: Array<out AudioDeviceInfo>) {
+            if (communicationRouteActive) updateAudioRouting()
+        }
+    }
     private var communicationRouteActive = false
     private var bridgeWindowStartedAtMs = System.currentTimeMillis()
     private var micEvents = 0
@@ -44,7 +65,7 @@ class AudioEngine (context: Context) {
     private var playbackWrites = 0
     private var playbackWriteBytes = 0L
 
-    var isRecording = false
+    @Volatile var isRecording = false
     private var isRecordingBeforePause = false
     var isPlaying = false
 
@@ -83,28 +104,9 @@ class AudioEngine (context: Context) {
     @SuppressLint("NewApi")
     private fun initializeAudio(context:Context) {
         audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
-        activateCommunicationRoute()
-        if (!requestAudioFocus()) {
-            handleAudioFocusBlocked()
-        }
-
-        // Listen for changes in audio routing
-        audioManager.registerAudioDeviceCallback(object:android.media.AudioDeviceCallback(){
-            override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>?) {
-                Log.d("AudioEngine", "onAudioDevicesAdded")
-                super.onAudioDevicesAdded(addedDevices)
-                if (communicationRouteActive) {
-                    updateAudioRouting()
-                }
-            }
-            override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>?) {
-                Log.d("AudioEngine", "onAudioDevicesRemoved")
-                super.onAudioDevicesRemoved(removedDevices)
-                if (communicationRouteActive) {
-                    updateAudioRouting()
-                }
-            }
-        }, null)
+        // Initialization must not interrupt music before a capture/playback operation owns a session.
+        audioManager.registerAudioDeviceCallback(deviceCallback, mainHandler)
+        audioManager.registerAudioRecordingCallback(recordingCallback, mainHandler)
 
         val bufferSize = AudioTrack.getMinBufferSize(
             SAMPLE_RATE,
@@ -125,49 +127,42 @@ class AudioEngine (context: Context) {
             bufferSize,
             AudioTrack.MODE_STREAM,
             audioManager.generateAudioSessionId()
-        ).apply {
-            play()
-        }
+        )
     }
 
+    @SuppressLint("NewApi")
     private fun updateAudioRouting() {
-        val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
-        var isExternalDeviceConnected = false
-        var selectedDevice: AudioDeviceInfo? = null
-
-        for (device in devices) {
-            if (device.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) {
-                speakerDevice = device
-            }
-            if (device.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
-                device.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
-                device.type == AudioDeviceInfo.TYPE_BLUETOOTH_A2DP ||
-                device.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO) {
-                isExternalDeviceConnected = true
-                selectedDevice = device
-                break
-            } else if (device.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) {
-                selectedDevice = device
-            }
-        }
-
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-            // Use the modern API for Android S and above
-            try {
-                selectedDevice?.let {
-                    audioManager.setCommunicationDevice(it)
-                }
-            }catch (e:Exception){
-                Log.e("AudioEngine", "Error setting communication device. Using speaker")
-                speakerDevice?.let {
-                    audioManager.setCommunicationDevice(it)
-                }
+            val devices = audioManager.availableCommunicationDevices
+            // A2DP is a music output, not a microphone route. Android chooses the matching
+            // input for a valid communication sink (including SCO and BLE headsets).
+            val selected = devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
+                it.type == AudioDeviceInfo.TYPE_BLE_HEADSET }
+                ?: devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
+                    it.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
+                    it.type == AudioDeviceInfo.TYPE_USB_HEADSET }
+                ?: devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER }
+            val routed = try {
+                selected != null && audioManager.setCommunicationDevice(selected)
+            } catch (_: IllegalArgumentException) {
+                // The device disconnected between enumeration and selection.
+                false
             }
-
+            if (!routed) audioManager.clearCommunicationDevice()
         } else {
-            // Fall back to deprecated method for older Android versions
             @Suppress("DEPRECATION")
-            audioManager.isSpeakerphoneOn = !isExternalDeviceConnected
+            val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+            // Before Android 12, A2DP signals a connected headset; start SCO to open its mic.
+            val bluetooth = devices.any { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
+                it.type == AudioDeviceInfo.TYPE_BLUETOOTH_A2DP }
+            @Suppress("DEPRECATION")
+            if (bluetooth) audioManager.startBluetoothSco() else audioManager.stopBluetoothSco()
+            @Suppress("DEPRECATION")
+            audioManager.isSpeakerphoneOn = !bluetooth && !devices.any {
+                it.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
+                    it.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
+                    it.type == AudioDeviceInfo.TYPE_USB_HEADSET
+            }
         }
     }
 
@@ -186,6 +181,8 @@ class AudioEngine (context: Context) {
         } else {
             @Suppress("DEPRECATION")
             audioManager.isSpeakerphoneOn = false
+            @Suppress("DEPRECATION")
+            audioManager.stopBluetoothSco()
         }
         audioManager.mode = AudioManager.MODE_NORMAL
     }
@@ -245,8 +242,8 @@ class AudioEngine (context: Context) {
             audioFocusRequest = null
         }
 
-        val focusRequest =
-            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
+        lateinit var focusRequest: AudioFocusRequest
+        focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                 .setAudioAttributes(
                     AudioAttributes.Builder()
                         .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
@@ -255,6 +252,7 @@ class AudioEngine (context: Context) {
                 )
                 .setAcceptsDelayedFocusGain(true)
                 .setOnAudioFocusChangeListener { focusChange ->
+                    if (audioFocusRequest !== focusRequest) return@setOnAudioFocusChangeListener
                     when (focusChange) {
                         AudioManager.AUDIOFOCUS_GAIN -> {
                             Log.d("AudioEngine", "Audio focus gained")
@@ -286,6 +284,14 @@ class AudioEngine (context: Context) {
     }
 
     private fun handleAudioFocusBlocked() {
+        // Focus governs playback. Dictation keeps its AudioRecord alive; Android's
+        // recording configuration reports real input silencing and restores it after calls.
+        if (captureMode == CaptureMode.DICTATION) {
+            stopPlayback()
+            audioFocusRequest?.let { audioManager.abandonAudioFocusRequest(it) }
+            audioFocusRequest = null
+            return
+        }
         if (isRecording) {
             stopRecording()
         }
@@ -306,11 +312,11 @@ class AudioEngine (context: Context) {
 
     @RequiresApi(Build.VERSION_CODES.Q)
     @SuppressLint("MissingPermission")
-    private fun startRecording(): Boolean {
+    private fun startRecording(requestFocus: Boolean = true): Boolean {
         activateCommunicationRoute()
-        if (!requestAudioFocus()) {
+        if (requestFocus && !requestAudioFocus()) {
             handleAudioFocusBlocked()
-            return false
+            if (captureMode == CaptureMode.CONVERSATION) return false
         }
 
         val bufferSize = AudioRecord.getMinBufferSize(SAMPLE_RATE, CHANNEL_CONFIG, AUDIO_FORMAT)
@@ -344,17 +350,27 @@ class AudioEngine (context: Context) {
 
         audioRecord.startRecording()
         isRecording = true
-        startMicSampleTap()
+        setCaptureSilenced(audioRecord.activeRecordingConfiguration?.isClientSilenced ?: false)
+        startMicSampleTap(audioRecord)
         return true
     }
 
-    private fun startMicSampleTap(){
+    private fun setCaptureSilenced(silenced: Boolean) {
+        if (captureSilenced == silenced) return
+        captureSilenced = silenced
+        if (silenced) onInputVolumeCallback?.invoke(0.0F)
+        onAudioInterruptionCallback?.invoke(if (silenced) "capture_paused" else "capture_resumed")
+    }
+
+    private fun startMicSampleTap(recorder: AudioRecord){
         executorServiceMicrophone.execute {
             val buffer = ByteArray(1024)
             try {
-                while (isRecording) {
-                    val read = audioRecord.read(buffer, 0, buffer.size)
-                    if (read > 0) {
+                while (isRecording && audioRecord === recorder) {
+                    val read = recorder.read(buffer, 0, buffer.size)
+                    if (!isRecording || audioRecord !== recorder) break
+                    if (read < 0) throw IllegalStateException("AudioRecord read failed: $read")
+                    if (read > 0 && !captureSilenced) {
                         val data = buffer.copyOf(read)
                         micEvents += 1
                         micBytes += data.size.toLong()
@@ -367,9 +383,13 @@ class AudioEngine (context: Context) {
                 Log.d("AudioEngine", "Mic sample tap stopped.")
             }catch (e: Exception){
                 Log.e("AudioEngine", "Error reading mic sample data", e)
-                isRecording = false
-                tearDown()
-                throw e
+                mainHandler.post {
+                    if (isRecording && audioRecord === recorder) {
+                        stopRecording()
+                        releaseAudioSession()
+                        onAudioInterruptionCallback?.invoke("blocked")
+                    }
+                }
             }
         }
     }
@@ -379,16 +399,31 @@ class AudioEngine (context: Context) {
         isRecording = false
         if (audioRecord.recordingState == AudioRecord.RECORDSTATE_RECORDING) {
             audioRecord.stop()
-            audioRecord.release()
         }
+        audioRecord.release()
+        echoCanceler?.release()
+        echoCanceler = null
+        noiseSuppressor?.release()
+        noiseSuppressor = null
+        setCaptureSilenced(false)
         onInputVolumeCallback?.invoke(0.0F)
     }
 
+    @RequiresApi(Build.VERSION_CODES.Q)
+    fun startDictation(): Boolean {
+        isRecordingBeforePause = false
+        if (isRecording) return true
+        captureMode = CaptureMode.DICTATION
+        return startRecording()
+    }
+
     @RequiresApi(Build.VERSION_CODES.Q)
     fun toggleRecording(value: Boolean): Boolean {
+        isRecordingBeforePause = false
         if (value == isRecording) return isRecording
 
         if (value) {
+            captureMode = CaptureMode.CONVERSATION
             return startRecording()
         } else {
             stopRecording()
@@ -401,6 +436,7 @@ class AudioEngine (context: Context) {
     @SuppressLint("NewApi")
     fun playPCMData(data: ByteArray) {
         acquireAudioSessionIfNeeded()
+        audioTrack.play()
         audioSampleQueue.add(data)
         playbackEvents += 1
         playbackQueuedBytes += data.size.toLong()
@@ -464,7 +500,7 @@ class AudioEngine (context: Context) {
     @RequiresApi(Build.VERSION_CODES.Q)
     fun pauseRecordingAndPlayer() {
         isRecordingBeforePause = isRecording
-        isRecording = toggleRecording(false)
+        stopRecording()
         audioTrack.pause()
     }
 
@@ -478,16 +514,18 @@ class AudioEngine (context: Context) {
         if (!wasRecordingBeforePause && !isPlaying) {
             return
         }
-        activateCommunicationRoute()
-        if (!requestAudioFocus()) {
-            handleAudioFocusBlocked()
-            return
+        isRecordingBeforePause = false
+        if (wasRecordingBeforePause) {
+            // Returning from music controls must not pause music the user explicitly resumed.
+            if (!startRecording(requestFocus = captureMode == CaptureMode.CONVERSATION)) return
+        } else {
+            activateCommunicationRoute()
+            if (!requestAudioFocus()) {
+                handleAudioFocusBlocked()
+                return
+            }
         }
-        isRecording = toggleRecording(wasRecordingBeforePause)
-        if (wasRecordingBeforePause && !isRecording) {
-            return
-        }
-        audioTrack.play()
+        if (captureMode == CaptureMode.CONVERSATION) audioTrack.play()
     }
 
     fun stopPlayback() {
@@ -520,7 +558,11 @@ class AudioEngine (context: Context) {
             audioManager.abandonAudioFocusRequest(request)
         }
         audioFocusRequest = null
+        audioManager.unregisterAudioDeviceCallback(deviceCallback)
+        audioManager.unregisterAudioRecordingCallback(recordingCallback)
+        audioTrack.release()
         executorServiceMicrophone.shutdownNow()
+        executorServicePlayback.shutdownNow()
     }
 
 

packages/expo-two-way-audio/android/src/main/java/expo/modules/twowayaudio/ExpoTwoWayAudioModule.kt

@@ -42,6 +42,12 @@ class ExpoTwoWayAudioModule : Module() {
              audioEngine?.isRecording ?: false
          }
 
+         Function("startDictation") {
+             val isRecording = audioEngine?.startDictation() ?: false
+             sendEvent(ON_RECORDING_CHANGE_EVENT, mapOf("data" to isRecording))
+             isRecording
+         }
+
          Function("toggleRecording") { value: Boolean ->
              audioEngine?.let { engine ->
                  val isRecording = engine.toggleRecording(value)

packages/expo-two-way-audio/ios/ExpoTwoWayAudioModule.swift

@@ -59,6 +59,12 @@ public class ExpoTwoWayAudioModule: Module {
             return audioEngine.isRecording
         }
 
+        Function("startDictation") { () -> Bool in
+            let isRecording = self.audioEngine?.toggleRecording(true) ?? false
+            self.sendEvent(ON_RECORDING_CHANGE_EVENT_NAME, ["data": isRecording])
+            return isRecording
+        }
+
         Function("toggleRecording") { (val: Bool) -> Bool in
             guard let audioEngine = self.audioEngine else {
                 print("AudioEngine not initialized")

packages/expo-two-way-audio/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/expo-two-way-audio",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Native module for two way audio streaming",
   "keywords": [
     "ExpoTwoWayAudio",

packages/expo-two-way-audio/src/core.ts

@@ -17,6 +17,16 @@ export function toggleRecording(val: boolean): boolean {
   return ExpoTwoWayAudioModule.toggleRecording(val);
 }
 
+/** Capture speech without treating another app's playback focus as a microphone failure. */
+export function startDictation(): boolean {
+  // COMPAT(dictationCapture): added after v0.11.2, remove after 2027-01-16 once
+  // the native binary floor includes startDictation. Older OTA clients retain legacy capture.
+  if (typeof ExpoTwoWayAudioModule.startDictation !== "function") {
+    return ExpoTwoWayAudioModule.toggleRecording(true);
+  }
+  return ExpoTwoWayAudioModule.startDictation();
+}
+
 export function isRecording(): boolean {
   return ExpoTwoWayAudioModule.isRecording();
 }

packages/highlight/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "files": [
     "dist",
     "!dist/**/*.map",

packages/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo plugin SDK package",
   "files": [
     "dist",
@@ -70,8 +70,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.11.2",
-    "@getpaseo/protocol": "0.11.2",
+    "@getpaseo/client": "0.12.0-beta.1",
+    "@getpaseo/protocol": "0.12.0-beta.1",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.1.0",
@@ -81,8 +81,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@getpaseo/client": "0.11.2",
-    "@getpaseo/protocol": "0.11.2",
+    "@getpaseo/client": "0.12.0-beta.1",
+    "@getpaseo/protocol": "0.12.0-beta.1",
     "react": "~19.1.0",
     "react-native": ">=0.81.5",
     "zod": "^4.4.3"

packages/protocol/codegen/README.md

@@ -1,7 +1,7 @@
 # Protocol Validator Codegen
 
-This directory is build-time only. `ws-outbound.compile.ts` is the zod-aot discovery entry for the inbound WebSocket validator.
+This directory is build-time only. The generator writes `generated/ws-outbound.compile.ts`, the zod-aot discovery entry for the inbound WebSocket validators: one for the envelope and one per session message type.
 
-The generated runtime file is written to `../src/generated/validation/ws-outbound.aot.ts` and is not committed. The protocol package owns every generation trigger through its npm lifecycle scripts.
+The discovery entry and the generated runtime files under `../src/generated/validation/` are not committed. The protocol package owns every generation trigger through its npm lifecycle scripts.
 
 `zod-aot` is exact-pinned, and the protocol generator applies the small compiler patches it requires before generation. Treat changes to those patches like compiler changes: regenerate, inspect the output, and run the protocol validation regression tests before shipping.

packages/protocol/codegen/ws-outbound.compile.ts

@@ -1,4 +0,0 @@
-import { compile } from "zod-aot";
-import { WSOutboundMessageSchema as SourceWSOutboundMessageSchema } from "../src/messages.js";
-
-export const WSOutboundMessageSchema = compile(SourceWSOutboundMessageSchema);

packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",

packages/protocol/scripts/generate-validation-aot.mjs

@@ -4,8 +4,12 @@ import { dirname, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const source = resolve(packageRoot, "codegen/ws-outbound.compile.ts");
-const runtimeSchemaMetadata = resolve(packageRoot, "src/validation/ws-outbound-schema-metadata.ts");
+const envelopeSource = resolve(packageRoot, "src/validation/ws-outbound-envelope.ts");
+const source = resolve(packageRoot, "codegen/generated/ws-outbound.compile.ts");
+const runtimeSchemaMetadata = resolve(
+  packageRoot,
+  "src/generated/validation/ws-outbound-schema-metadata.ts",
+);
 const output = resolve(packageRoot, "src/generated/validation/ws-outbound.aot.ts");
 
 const require = createRequire(import.meta.url);
@@ -72,16 +76,69 @@ await Promise.all([
   ensureZodAotDiscriminatedUnionOutputPatch(),
 ]);
 
-const [{ discoverSchemas }, { compileSchemas }, { generateCompiledFileContent }] =
-  await Promise.all([
-    import(pathToFileURL(resolve(zodAotRoot, "dist/discovery.js")).href),
-    import(pathToFileURL(resolve(zodAotRoot, "dist/core/pipeline.js")).href),
-    import(pathToFileURL(resolve(zodAotRoot, "dist/cli/emitter.js")).href),
-  ]);
+const [
+  { loadSourceFile },
+  { discoverSchemas },
+  { compileSchemas },
+  { generateCompiledFileContent },
+] = await Promise.all([
+  import(pathToFileURL(resolve(zodAotRoot, "dist/loader.js")).href),
+  import(pathToFileURL(resolve(zodAotRoot, "dist/discovery.js")).href),
+  import(pathToFileURL(resolve(zodAotRoot, "dist/core/pipeline.js")).href),
+  import(pathToFileURL(resolve(zodAotRoot, "dist/cli/emitter.js")).href),
+]);
+
+// One compiled validator per session message plus a tag-only envelope. zod-aot emits one function
+// per compiled schema, so this keeps every generated function small enough for V8 to optimize cheaply.
+const { sessionOutboundMessageOptions } = await loadSourceFile(envelopeSource, { cacheBust: true });
+const sessionTags = sessionOutboundMessageOptions.map((option) => option.shape.type.value);
+function sessionExport(index) {
+  return `SessionOutboundMessage${index}`;
+}
+const envelopeImport = relative(dirname(source), envelopeSource)
+  .replace(/\.ts$/, ".js")
+  .split(sep)
+  .join("/");
+const metadataImport = relative(dirname(runtimeSchemaMetadata), envelopeSource)
+  .replace(/\.ts$/, ".js")
+  .split(sep)
+  .join("/");
+
+await mkdir(dirname(source), { recursive: true });
+await writeFile(
+  source,
+  [
+    "// AUTO-GENERATED by generate-validation-aot.mjs — DO NOT EDIT",
+    'import { compile } from "zod-aot";',
+    `import { WSOutboundEnvelopeSchema, sessionOutboundMessageOptions } from "${envelopeImport}";`,
+    "export const WSOutboundEnvelope = compile(WSOutboundEnvelopeSchema);",
+    ...sessionTags.map(
+      (_, index) =>
+        `export const ${sessionExport(index)} = compile(sessionOutboundMessageOptions[${index}]);`,
+    ),
+    "",
+  ].join("\n"),
+);
+await mkdir(dirname(runtimeSchemaMetadata), { recursive: true });
+await writeFile(
+  runtimeSchemaMetadata,
+  [
+    "// AUTO-GENERATED by generate-validation-aot.mjs — DO NOT EDIT",
+    `import { WSOutboundEnvelopeSchema, sessionOutboundMessageOptions } from "${metadataImport}";`,
+    "export const WSOutboundEnvelope = { schema: WSOutboundEnvelopeSchema };",
+    ...sessionTags.map(
+      (_, index) =>
+        `export const ${sessionExport(index)} = { schema: sessionOutboundMessageOptions[${index}] };`,
+    ),
+    "",
+  ].join("\n"),
+);
 
 const schemas = await discoverSchemas(source, { cacheBust: true });
-if (schemas.length === 0) {
-  throw new Error(`No zod-aot compile() exports found in ${relative(packageRoot, source)}`);
+if (schemas.length !== sessionTags.length + 1) {
+  throw new Error(
+    `Expected ${sessionTags.length + 1} zod-aot compile() exports in ${relative(packageRoot, source)}, found ${schemas.length}`,
+  );
 }
 
 const compiled = compileSchemas(schemas, { mode: "inline" });
@@ -95,12 +152,16 @@ const content = generateCompiledFileContent(compiled, runtimeImportPath, {
   "// AUTO-GENERATED by zod-aot — DO NOT EDIT",
   "// @ts-nocheck\n// AUTO-GENERATED by zod-aot — DO NOT EDIT",
 );
+const sessionMessageValidators = [
+  "export const SessionOutboundMessageValidators = {",
+  ...sessionTags.map((tag, index) => `  ${JSON.stringify(tag)}: ${sessionExport(index)},`),
+  "};",
+  "",
+].join("\n");
 
 await mkdir(dirname(output), { recursive: true });
-await writeFile(output, content);
+await writeFile(output, `${content}\n${sessionMessageValidators}`);
 
 console.info(
-  `generated ${relative(packageRoot, output)} from ${relative(packageRoot, source)} (${schemas
-    .map((schema) => schema.exportName)
-    .join(", ")})`,
+  `generated ${relative(packageRoot, output)}: envelope + ${sessionTags.length} session message validators`,
 );

packages/protocol/src/generated/validation/README.md

@@ -1,6 +1,6 @@
 # Generated protocol validators
 
-`ws-outbound.aot.ts` is generated by zod-aot from `packages/protocol/codegen/ws-outbound.compile.ts`.
+`ws-outbound.aot.ts` is generated by zod-aot from `packages/protocol/codegen/generated/ws-outbound.compile.ts`, which the generator writes along with `ws-outbound-schema-metadata.ts`.
 
 Run:
 

packages/protocol/src/validation/ws-outbound-envelope.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import {
+  SessionOutboundMessageSchema,
+  WSHelloRejectedMessageSchema,
+  WSPongMessageSchema,
+} from "../messages.js";
+
+export const sessionOutboundMessageOptions = SessionOutboundMessageSchema.options;
+
+const [firstSessionTag, ...otherSessionTags] = sessionOutboundMessageOptions.map((option) =>
+  z.object({ type: option.shape.type }),
+);
+
+// WSOutboundMessageSchema with every session message reduced to its tag. It reports the same
+// envelope and discriminator issues, while each session message gets its own generated validator:
+// one function for the whole protocol is large enough that V8's Maglev tier spends hundreds of MB
+// and seconds compiling it.
+export const WSOutboundEnvelopeSchema = z.discriminatedUnion("type", [
+  WSPongMessageSchema,
+  z.object({
+    type: z.literal("session"),
+    message: z.discriminatedUnion("type", [firstSessionTag, ...otherSessionTags]),
+  }),
+  WSHelloRejectedMessageSchema,
+]);

packages/protocol/src/validation/ws-outbound-schema-metadata.ts

@@ -1,3 +0,0 @@
-import { WSOutboundMessageSchema as SourceWSOutboundMessageSchema } from "../messages.js";
-
-export const WSOutboundMessageSchema = { schema: SourceWSOutboundMessageSchema };

packages/protocol/src/validation/ws-outbound.ts

@@ -1,19 +1,54 @@
+import { ZodRealError } from "zod";
 import type { z } from "zod";
-import { WSOutboundMessageSchema } from "../generated/validation/ws-outbound.aot.js";
-import type { WSOutboundMessage } from "../messages.js";
+import {
+  SessionOutboundMessageValidators,
+  WSOutboundEnvelope,
+} from "../generated/validation/ws-outbound.aot.js";
+import type { SessionOutboundMessage, WSOutboundMessage } from "../messages.js";
 
-type WSOutboundValidationResult =
-  | { success: true; data: WSOutboundMessage }
-  | { success: false; error: z.ZodError };
+type ValidationResult<T> = { success: true; data: T } | { success: false; error: z.ZodError };
 
-interface WSOutboundGeneratedValidator {
-  safeParse(input: unknown): WSOutboundValidationResult;
+interface GeneratedValidator<T> {
+  safeParse(input: unknown): ValidationResult<T>;
 }
 
-// zod-aot emits runtime JavaScript from WSOutboundMessageSchema but not its TypeScript surface.
+// zod-aot emits runtime JavaScript from the envelope and message schemas but not its TypeScript surface.
 // Protocol regression tests cover the patched compiler cases behind this boundary.
-const wsOutboundValidator = WSOutboundMessageSchema as WSOutboundGeneratedValidator;
+const envelopeValidator = WSOutboundEnvelope as GeneratedValidator<WSOutboundMessage>;
+const sessionMessageValidators = SessionOutboundMessageValidators as Record<
+  SessionOutboundMessage["type"],
+  GeneratedValidator<SessionOutboundMessage>
+>;
 
-export function validateWSOutboundMessage(input: unknown): WSOutboundValidationResult {
-  return wsOutboundValidator.safeParse(input);
+// The message validator reports paths relative to the message, nested issues included.
+function underMessage(issue: z.core.$ZodIssue): z.core.$ZodIssue {
+  const path = ["message", ...issue.path];
+  switch (issue.code) {
+    case "invalid_union":
+      return issue.inclusive === false
+        ? { ...issue, path }
+        : { ...issue, path, errors: issue.errors.map((branch) => branch.map(underMessage)) };
+    case "invalid_key":
+    case "invalid_element":
+      return { ...issue, path, issues: issue.issues.map(underMessage) };
+    default:
+      return { ...issue, path };
+  }
+}
+
+export function validateWSOutboundMessage(input: unknown): ValidationResult<WSOutboundMessage> {
+  const envelope = envelopeValidator.safeParse(input);
+  if (!envelope.success || envelope.data.type !== "session") {
+    return envelope;
+  }
+  const message = envelope.data.message;
+  const result = sessionMessageValidators[message.type].safeParse(message);
+  if (!result.success) {
+    return { success: false, error: new ZodRealError(result.error.issues.map(underMessage)) };
+  }
+  // Message validators return a new object when they apply defaults.
+  if (result.data === message) {
+    return envelope;
+  }
+  return { success: true, data: { ...envelope.data, message: result.data } };
 }

packages/protocol/tests/validation/ws-outbound.test.ts

@@ -3,8 +3,10 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
+import type { z } from "zod";
 import { describe, expect, it } from "vitest";
-import { WSOutboundMessageSchema as GeneratedWSOutboundMessageSchema } from "../../src/generated/validation/ws-outbound.aot.js";
+import { WSOutboundMessageSchema } from "../../src/messages.js";
+import { validateWSOutboundMessage } from "../../src/validation/ws-outbound.js";
 
 interface GeneratedSchema {
   safeParse(input: unknown): { success: boolean; data?: unknown };
@@ -132,10 +134,8 @@ const SourceSchema = z.object({
   });
 
   it("accepts a minimal valid envelope and rejects a corrupted envelope", () => {
-    expect(GeneratedWSOutboundMessageSchema.safeParse({ type: "pong" }).success).toBe(true);
-    expect(GeneratedWSOutboundMessageSchema.safeParse({ type: "not_a_message" }).success).toBe(
-      false,
-    );
+    expect(validateWSOutboundMessage({ type: "pong" }).success).toBe(true);
+    expect(validateWSOutboundMessage({ type: "not_a_message" }).success).toBe(false);
   });
 
   it("accepts project config responses with and without setup commit status", () => {
@@ -158,11 +158,10 @@ const SourceSchema = z.object({
       },
     });
 
-    expect(GeneratedWSOutboundMessageSchema.safeParse(envelope(payload)).success).toBe(true);
+    expect(validateWSOutboundMessage(envelope(payload)).success).toBe(true);
     expect(
-      GeneratedWSOutboundMessageSchema.safeParse(
-        envelope({ ...payload, hasUncommittedWorktreeSetupChanges: true }),
-      ).success,
+      validateWSOutboundMessage(envelope({ ...payload, hasUncommittedWorktreeSetupChanges: true }))
+        .success,
     ).toBe(true);
   });
 
@@ -196,7 +195,7 @@ const SourceSchema = z.object({
       },
     };
 
-    expect(GeneratedWSOutboundMessageSchema.safeParse(envelope)).toEqual({
+    expect(validateWSOutboundMessage(envelope)).toEqual({
       success: true,
       data: envelope,
     });
@@ -255,7 +254,7 @@ const SourceSchema = z.object({
   ])("preserves workspaceId in a $name", ({ message }) => {
     const envelope = { type: "session", message };
 
-    expect(GeneratedWSOutboundMessageSchema.safeParse(envelope)).toEqual({
+    expect(validateWSOutboundMessage(envelope)).toEqual({
       success: true,
       data: envelope,
     });
@@ -263,11 +262,11 @@ const SourceSchema = z.object({
 
   it("emits runtime imports with .js extensions", async () => {
     const generated = await readFile(generatedWSOutboundPath, "utf8");
-    expect(generated).toContain('from "../../validation/ws-outbound-schema-metadata.js"');
+    expect(generated).toContain('from "./ws-outbound-schema-metadata.js"');
   });
 
   it("accepts a forge.search.response envelope", () => {
-    const result = GeneratedWSOutboundMessageSchema.safeParse({
+    const result = validateWSOutboundMessage({
       type: "session",
       message: {
         type: "forge.search.response",
@@ -293,7 +292,7 @@ const SourceSchema = z.object({
   });
 
   it("accepts a legacy github_search_response envelope", () => {
-    const result = GeneratedWSOutboundMessageSchema.safeParse({
+    const result = validateWSOutboundMessage({
       type: "session",
       message: {
         type: "github_search_response",
@@ -319,4 +318,86 @@ const SourceSchema = z.object({
     });
     expect(result.success).toBe(true);
   });
+
+  it("keeps each generated validator function small", async () => {
+    // A single function for the whole protocol made V8's Maglev tier spend ~800 MB and seconds compiling it.
+    const generated = await readFile(generatedWSOutboundPath, "utf8");
+    const starts = [...generated.matchAll(/function safeParse_\w+\(/g)].map((match) => match.index);
+    const sizes = starts.map((start, index) => (starts[index + 1] ?? generated.length) - start);
+
+    expect(Math.max(...sizes)).toBeLessThan(1_000_000);
+    expect(sizes.length).toBeGreaterThan(1);
+  });
+
+  it("keeps nested union issue paths rooted at the envelope", () => {
+    // Generated validators root branch issues at the input; runtime Zod reports them relative to the union.
+    const envelope = {
+      type: "session",
+      message: {
+        type: "read_project_config_response",
+        payload: { repoRoot: "/repo", ok: true, config: {}, revision: { mtimeMs: 1, size: 1 } },
+      },
+    };
+    const paths = (issues: z.core.$ZodIssue[]): PropertyKey[][] =>
+      issues.flatMap((issue) => [
+        issue.path,
+        ...(issue.code === "invalid_union" ? paths(issue.errors.flat()) : []),
+      ]);
+
+    const result = validateWSOutboundMessage(envelope);
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(paths(result.error.issues)).toEqual([
+      ["message", "payload"],
+      ["message", "payload", "requestId"],
+      ["message", "payload", "requestId"],
+      ["message", "payload", "ok"],
+      ["message", "payload", "error"],
+    ]);
+  });
+
+  it("applies defaults from the matching session message schema", () => {
+    const envelope = {
+      type: "session",
+      message: {
+        type: "agent_update",
+        payload: {
+          kind: "upsert",
+          agent: {
+            id: "agent-1",
+            provider: "claude",
+            cwd: "/repo",
+            model: "model",
+            createdAt: "2026-01-01T00:00:00.000Z",
+            updatedAt: "2026-01-01T00:00:00.000Z",
+            lastUserMessageAt: "2026-01-01T00:00:00.000Z",
+            status: "initializing",
+            capabilities: {
+              supportsStreaming: false,
+              supportsSessionPersistence: false,
+              supportsDynamicModes: false,
+              supportsMcpServers: false,
+              supportsReasoningStream: false,
+              supportsToolInvocations: false,
+            },
+            currentModeId: "default",
+            availableModes: [],
+            pendingPermissions: [],
+            persistence: { provider: "claude", sessionId: "session-1" },
+            title: "Agent",
+          },
+        },
+      },
+    };
+
+    const result = validateWSOutboundMessage(envelope);
+    const expected = WSOutboundMessageSchema.safeParse(envelope);
+
+    expect(expected.success).toBe(true);
+    expect(result).toEqual(expected);
+    expect(result.success && result.data).toMatchObject({
+      message: { payload: { agent: { capabilities: { supportsRewindConversation: false } } } },
+    });
+  });
 });

packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo relay for bridging daemon and client connections",
   "files": [
     "dist",

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "description": "Paseo backend server",
   "files": [
     "dist/server",
@@ -107,11 +107,11 @@
     "@agentclientprotocol/sdk": "^0.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.3.246",
     "@anthropic-ai/sdk": "^0.104.2",
-    "@getpaseo/client": "0.11.2",
-    "@getpaseo/highlight": "0.11.2",
-    "@getpaseo/plugin": "0.11.2",
-    "@getpaseo/protocol": "0.11.2",
-    "@getpaseo/relay": "0.11.2",
+    "@getpaseo/client": "0.12.0-beta.1",
+    "@getpaseo/highlight": "0.12.0-beta.1",
+    "@getpaseo/plugin": "0.12.0-beta.1",
+    "@getpaseo/protocol": "0.12.0-beta.1",
+    "@getpaseo/relay": "0.12.0-beta.1",
     "@isaacs/ttlcache": "^2.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@opencode-ai/sdk": "1.14.46",

packages/server/src/server/agent/agent-loading.ts

@@ -12,6 +12,13 @@ import {
   toAgentPersistenceHandle,
 } from "../persistence-hooks.js";
 
+export class AgentNotFoundError extends Error {
+  constructor(agentId: string) {
+    super(`Agent not found: ${agentId}`);
+    this.name = "AgentNotFoundError";
+  }
+}
+
 interface PendingAgentInitialization {
   promise: Promise<ManagedAgent>;
   options: { broadcastTimeline: boolean };
@@ -94,7 +101,7 @@ export async function ensureAgentLoaded(
   const initPromise = (async () => {
     const record = await deps.agentStorage.get(agentId);
     if (!record) {
-      throw new Error(`Agent not found: ${agentId}`);
+      throw new AgentNotFoundError(agentId);
     }
 
     const validProviders = deps.validProviders ?? deps.agentManager.getRegisteredProviderIds();

packages/server/src/server/agent/agent-manager.test.ts

@@ -10929,6 +10929,41 @@ test("authoritative timeline records a daemon-handled submitted prompt before it
   }
 });
 
+test("tryRunOutOfBand gives providers the command another agent sent, not its envelope", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-agent-out-of-band-"));
+  const seenPrompts: AgentPromptInput[] = [];
+
+  class SlashCommandSession extends TestAgentSession {
+    override tryHandleOutOfBand(prompt: AgentPromptInput) {
+      seenPrompts.push(prompt);
+      return prompt === "/handled" ? { run: async () => {} } : null;
+    }
+  }
+  const client = new (class extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig) {
+      return new SlashCommandSession(config);
+    }
+  })();
+  const manager = new AgentManager({ clients: { codex: client }, logger });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+
+  try {
+    const fromAgent = prepareAgentMessage("/handled", { kind: "agent-message", agentId: "sender" });
+    expect(manager.tryRunOutOfBand(agent.id, fromAgent.prompt)).toBe(true);
+    expect(seenPrompts).toEqual(["/handled"]);
+
+    // A human who pastes an envelope gets it quoted, and it stays a plain prompt.
+    const pasted = prepareAgentMessage(String(fromAgent.prompt));
+    expect(manager.tryRunOutOfBand(agent.id, pasted.prompt)).toBe(false);
+    expect(seenPrompts.at(-1)).toBe(pasted.prompt);
+  } finally {
+    await manager.closeAgent(agent.id);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("replaceAgentRun succeeds when foreground turn terminal event is never delivered", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-stale-fg-"));
   const storagePath = join(workdir, "agents");

packages/server/src/server/agent/agent-manager.ts

@@ -79,7 +79,7 @@ import {
   type PendingForegroundRun,
 } from "./agent-run-state.js";
 import { invokeRewindCapability, type RewindMode } from "./rewind/rewind.js";
-import { projectAgentMessage } from "./agent-messages/index.js";
+import { parseAgentMessage, projectAgentMessage } from "./agent-messages/index.js";
 import { isStaleProviderSessionError } from "./stale-provider-session-error.js";
 import { stripInternalPaseoMcpServer, withRuntimePaseoMcpServer } from "./runtime-mcp-config.js";
 import { resolveCreateAgentTitles } from "./create-agent-title.js";
@@ -2459,7 +2459,12 @@ export class AgentManager {
    */
   tryRunOutOfBand(agentId: string, prompt: AgentPromptInput, options?: AgentRunOptions): boolean {
     const agent = this.requireSessionAgent(agentId);
-    const handler = agent.session.tryHandleOutOfBand?.(prompt);
+    // Providers parse slash commands from the raw text, so a command another agent sent
+    // must reach them without its sender envelope.
+    const agentMessage = typeof prompt === "string" ? parseAgentMessage(prompt) : null;
+    const handler = agent.session.tryHandleOutOfBand?.(
+      agentMessage?.source ? agentMessage.text : prompt,
+    );
     if (!handler) {
       return false;
     }

packages/server/src/server/agent/mcp-server.test.ts

@@ -5,7 +5,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it, vi } from "vitest";
 import { realpathSync } from "node:fs";
-import { access, mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { access, mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, resolve as resolvePath } from "node:path";
 import { tmpdir } from "node:os";
 import { z } from "zod";
@@ -15,6 +15,8 @@ import { createAgentMcpServer as createAgentMcpServerWithDependencies } from "./
 import { AgentManager, type ManagedAgent } from "./agent-manager.js";
 import { AgentStorage, type StoredAgentRecord } from "./agent-storage.js";
 import { createTestAgentClients } from "../test-utils/fake-agent-client.js";
+import { OmpAgentClient } from "./providers/omp/agent.js";
+import { FakeOmp } from "./providers/omp/test-utils/fake-omp.js";
 import type {
   AgentClient,
   AgentMode,
@@ -841,6 +843,49 @@ function createAgentMcpServer(options: Parameters<typeof createAgentMcpServerWit
   });
 }
 
+describe("bundled Paseo skill", () => {
+  it("documents only advertised create_workspace input names", async () => {
+    const server = await createAgentMcpServer({
+      agentManager: new BoundaryAgentManagerFake() as AgentManager,
+      agentStorage: new BoundaryAgentStorageFake() as AgentStorage,
+      providerSnapshotManager:
+        new BoundaryProviderSnapshotManagerFake() as unknown as ProviderSnapshotManager,
+      logger: createTestLogger(),
+    });
+    const client = await connectInMemoryMcpClient(server);
+
+    try {
+      const skill = await readFile(
+        new URL("../../../../../skills/paseo/SKILL.md", import.meta.url),
+        "utf8",
+      );
+      const paragraph = skill.split("\n").find((line) => line.startsWith("**`create_workspace`**"));
+      expect(paragraph).toBeTypeOf("string");
+      // The final sentence describes output, rather than tool inputs.
+      const inputGuidance = paragraph!.split("Returns ")[0]!;
+      const documentedInputs = [...inputGuidance.matchAll(/`([a-zA-Z][a-zA-Z0-9]*)`/g)].map(
+        (match) => match[1]!,
+      );
+      expect(documentedInputs.length).toBeGreaterThan(0);
+      const { tools } = await client.listTools();
+      const tool = tools.find((entry) => entry.name === "create_workspace")!;
+      const properties = tool.inputSchema.properties!;
+      const advertisedNamesAndValues = new Set([
+        ...Object.keys(properties),
+        ...Object.values(properties).flatMap((property) =>
+          typeof property === "object" && property !== null && Array.isArray(property.enum)
+            ? property.enum
+            : [],
+        ),
+      ]);
+      expect(documentedInputs.filter((name) => !advertisedNamesAndValues.has(name))).toEqual([]);
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+});
+
 describe("browser MCP tools", () => {
   const logger = createTestLogger();
 
@@ -3856,8 +3901,7 @@ class HeldTurnAgentSession implements AgentSession {
   }
 
   tryHandleOutOfBand(prompt: AgentPromptInput) {
-    const text = typeof prompt === "string" ? (parseAgentMessage(prompt)?.text ?? prompt) : null;
-    return text === "/side-command" ? { run: async () => {} } : null;
+    return prompt === "/side-command" ? { run: async () => {} } : null;
   }
 
   async startTurn(prompt: AgentPromptInput): Promise<{ turnId: string }> {
@@ -4557,6 +4601,180 @@ describe("send_agent_prompt MCP tool", () => {
   });
 });
 
+describe("send_agent_prompt MCP tool to an OMP child", () => {
+  const logger = createTestLogger();
+  const existingCwd = process.cwd();
+
+  async function setupOmpChild() {
+    const workdir = await mkdtemp(join(tmpdir(), "mcp-omp-child-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const parentClient = new HeldTurnAgentClient("claude", false);
+    const omp = new FakeOmp();
+    const agentManager = new AgentManager({
+      clients: {
+        claude: parentClient,
+        omp: new OmpAgentClient({
+          logger,
+          runtime: omp,
+          noTurnScheduler: { waitForSettle: async () => {} },
+          runtimeSettings: { command: { mode: "replace", argv: [process.execPath] } },
+        }),
+      },
+      registry: storage,
+      logger,
+    });
+    const parent = await agentManager.createAgent(
+      { provider: "claude", cwd: existingCwd },
+      undefined,
+      { workspaceId: "wks_parent" },
+    );
+    const child = await agentManager.createAgent(
+      { provider: "omp", cwd: existingCwd, title: "OMP child" },
+      undefined,
+      { workspaceId: "wks_parent" },
+    );
+    const server = await createAgentMcpServer({
+      agentManager,
+      agentStorage: storage,
+      callerAgentId: parent.id,
+      providerSnapshotManager: createOpenCodeManager().manager,
+      logger,
+    });
+    return {
+      agentManager,
+      storage,
+      workdir,
+      parentClient,
+      ompSession: omp.latestSession(),
+      childId: child.id,
+      tool: registeredTool(server, "send_agent_prompt"),
+    };
+  }
+
+  async function expectOneFinishNotification(
+    agentManager: AgentManager,
+    parentClient: HeldTurnAgentClient,
+    childId: string,
+  ) {
+    await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("idle"));
+    await vi.waitFor(() => {
+      expect(parentClient.sessions[0]!.prompts).toHaveLength(1);
+      expect(parentClient.sessions[0]!.prompts[0]).toContain(
+        `Agent ${childId} (OMP child) finished.`,
+      );
+    });
+  }
+
+  it.each([
+    { command: "follow-up", streamingBehavior: "followUp" },
+    { command: "steer", streamingBehavior: "steer" },
+  ] as const)(
+    "delivers /$command into a turn OMP started on its own, without aborting it",
+    async ({ command, streamingBehavior }) => {
+      const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+        await setupOmpChild();
+      try {
+        ompSession.beginTurn();
+        ompSession.streamAssistantText("background job finished, working on it");
+        await vi.waitFor(() => {
+          expect(agentManager.getAgent(childId)?.activeTurnId).toMatch(/^autonomous-/);
+        });
+
+        const response = await invokeToolWithParsedInput(tool, {
+          agentId: childId,
+          prompt: `/${command} then summarize the logs`,
+        });
+
+        expect(response.structuredContent).toMatchObject({
+          success: true,
+          disposition: "out_of_band",
+          status: "running",
+        });
+        await vi.waitFor(() => {
+          expect(ompSession.prompts).toEqual([
+            { message: "then summarize the logs", imageCount: 0, streamingBehavior },
+          ]);
+        });
+        expect(ompSession.abortRequested).toBe(false);
+        expect(agentManager.getAgent(childId)?.lifecycle).toBe("running");
+
+        ompSession.finishTurn();
+        await expectOneFinishNotification(agentManager, parentClient, childId);
+      } finally {
+        await removeAgentStateDir(agentManager, storage, workdir);
+      }
+    },
+  );
+
+  it.each(["before ack", "after ack"])(
+    "reports an idle follow-up rejected %s and notifies its parent",
+    async (order) => {
+      const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+        await setupOmpChild();
+      try {
+        ompSession.promptAck = { requestId: "follow-up-rejected" };
+        const rejection = {
+          type: "prompt_result",
+          id: "follow-up-rejected",
+          agentInvoked: false,
+          status: "error",
+          sessionSettled: true,
+          error: { message: "Provider rejected the follow-up", retryable: false },
+        } as const;
+        const promptStarted = ompSession.nextPrompt();
+        const response = invokeToolWithParsedInput(tool, {
+          agentId: childId,
+          prompt: "/follow-up check the build",
+        });
+        await promptStarted;
+        if (order === "before ack") ompSession.emit(rejection);
+        await response;
+        if (order === "after ack") ompSession.emit(rejection);
+        await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("error"));
+        expect(agentManager.getAgent(childId)?.lastError).toContain(
+          "Provider rejected the follow-up",
+        );
+        await vi.waitFor(() => expect(parentClient.sessions[0]!.prompts).toHaveLength(1));
+        expect(parentClient.sessions[0]!.prompts[0]).toContain(
+          `Agent ${childId} (OMP child) errored.`,
+        );
+      } finally {
+        await removeAgentStateDir(agentManager, storage, workdir);
+      }
+    },
+  );
+
+  it("lets an idle child start a run with the follow-up", async () => {
+    const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+      await setupOmpChild();
+    try {
+      const response = await invokeToolWithParsedInput(tool, {
+        agentId: childId,
+        prompt: "/follow-up check the build",
+      });
+
+      expect(response.structuredContent).toMatchObject({
+        success: true,
+        disposition: "out_of_band",
+        status: "running",
+      });
+      await vi.waitFor(() => {
+        expect(ompSession.prompts).toEqual([
+          { message: "check the build", imageCount: 0, streamingBehavior: "followUp" },
+        ]);
+      });
+
+      ompSession.beginTurn();
+      ompSession.streamAssistantText("Build is green");
+      await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("running"));
+      ompSession.finishTurn();
+      await expectOneFinishNotification(agentManager, parentClient, childId);
+    } finally {
+      await removeAgentStateDir(agentManager, storage, workdir);
+    }
+  });
+});
+
 describe("update_agent MCP tool", () => {
   const logger = createTestLogger();
 

packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
-import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import type { AgentSession, AgentStreamEvent } from "../../agent-sdk-types.js";
 import type { AgentTimelineRow } from "../../agent-manager.js";
 import { projectTimelineRows } from "../../timeline-projection.js";
 import { ClaudeAgentClient } from "./agent.js";
@@ -105,6 +105,39 @@ async function collectUntilTerminal(
   return events;
 }
 
+async function collectTimelineAcrossTurns(
+  session: AgentSession,
+  prompt: string,
+  turnCount: number,
+): Promise<AgentTimelineRow[]> {
+  const rows: AgentTimelineRow[] = [];
+  let currentTurnId: string | undefined;
+  let completedTurns = 0;
+  let unsubscribe = () => {};
+  const turnsCompleted = new Promise<void>((resolve) => {
+    unsubscribe = session.subscribe((event) => {
+      if (event.type === "turn_started") currentTurnId = event.turnId;
+      if (event.type === "timeline") {
+        rows.push({
+          seq: rows.length + 1,
+          timestamp: new Date(Date.UTC(2026, 9, 4, 0, 0, rows.length)).toISOString(),
+          item: event.item,
+          ...(currentTurnId ? { turnId: currentTurnId } : {}),
+        });
+      }
+      if (event.type === "turn_completed" && ++completedTurns === turnCount) resolve();
+    });
+  });
+  try {
+    await session.startTurn(prompt);
+    await turnsCompleted;
+    return rows;
+  } finally {
+    unsubscribe();
+    await session.close();
+  }
+}
+
 describe("background Claude subagents", () => {
   afterEach(() => {
     queryFactory.mockReset();
@@ -431,6 +464,124 @@ describe("background Claude subagents", () => {
         type: "sub_agent",
         subAgentType: "general-purpose",
         description: "Count files here",
+        log: "[Bash] ls -1",
+      },
+    });
+  });
+
+  test("keeps one logged Task card when the child streams on after the parent's turn ends", async () => {
+    // A child can stream across the main session's turn boundary. Claude opens the next
+    // main-session turn with system/init; bare child frames do not open a turn.
+    queryFactory.mockImplementation(() =>
+      buildQueryMock([
+        { type: "system", subtype: "init", session_id: "bg-session", permissionMode: "default" },
+        {
+          type: "assistant",
+          message: {
+            model: "claude-haiku-4-5",
+            content: [
+              {
+                type: "tool_use",
+                id: "toolu_background",
+                name: "Agent",
+                input: {
+                  subagent_type: "general-purpose",
+                  description: "Count files here",
+                  prompt: "Run ls and reply with the number of entries.",
+                  run_in_background: true,
+                },
+              },
+            ],
+          },
+        },
+        {
+          type: "system",
+          subtype: "task_started",
+          task_id: "bg-task",
+          tool_use_id: "toolu_background",
+          task_type: "local_agent",
+          subagent_type: "general-purpose",
+          description: "Count files here",
+          prompt: "Run ls and reply with the number of entries.",
+        },
+        {
+          type: "user",
+          message: {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "toolu_background",
+                content: "Async agent launched successfully.",
+              },
+            ],
+          },
+        },
+        {
+          type: "assistant",
+          parent_tool_use_id: "toolu_background",
+          message: {
+            model: "claude-haiku-4-5",
+            content: [
+              {
+                type: "tool_use",
+                id: "toolu_ls",
+                name: "Bash",
+                input: { command: "ls -1", description: "List files" },
+              },
+            ],
+          },
+        },
+        { type: "result", subtype: "success", usage: {}, total_cost_usd: 0 },
+        { type: "system", subtype: "init", session_id: "bg-session", permissionMode: "default" },
+        {
+          type: "user",
+          parent_tool_use_id: "toolu_background",
+          message: {
+            role: "user",
+            content: [{ type: "tool_result", tool_use_id: "toolu_ls", content: "a\nb\nc" }],
+          },
+        },
+        {
+          type: "assistant",
+          parent_tool_use_id: "toolu_background",
+          message: { model: "claude-haiku-4-5", content: [{ type: "text", text: "3" }] },
+        },
+        {
+          type: "system",
+          subtype: "task_updated",
+          task_id: "bg-task",
+          patch: { status: "completed" },
+        },
+        {
+          type: "system",
+          subtype: "task_notification",
+          task_id: "bg-task",
+          tool_use_id: "toolu_background",
+          status: "completed",
+        },
+        { type: "result", subtype: "success", usage: {}, total_cost_usd: 0 },
+      ]),
+    );
+    const session = await new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    }).createSession({ provider: "claude", cwd: process.cwd() });
+    const rows = await collectTimelineAcrossTurns(session, "delegate work", 2);
+
+    const cards = projectTimelineRows({ rows, mode: "projected" })
+      .map((entry) => entry.item)
+      .filter((item) => item.type === "tool_call" && item.callId === "toolu_background");
+
+    expect(cards).toHaveLength(1);
+    expect(cards[0]).toMatchObject({
+      status: "completed",
+      detail: {
+        type: "sub_agent",
+        subAgentType: "general-purpose",
+        description: "Count files here",
+        log: "[Bash] ls -1",
       },
     });
   });

packages/server/src/server/agent/providers/claude/agent.live-settings.test.ts

@@ -0,0 +1,157 @@
+import { expect, test } from "vitest";
+import type { Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import { ClaudeAgentClient } from "./agent.js";
+import type { ClaudeQueryInput } from "./query.js";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+// The injected SDK adapter consumes real session input and holds a command open
+// until the test releases it. Closing the query interrupts that command.
+class ForegroundQuery {
+  readonly work = deferred<void>();
+  readonly closed = deferred<void>();
+  private stopped = false;
+  private readonly output: AsyncGenerator<SDKMessage>;
+
+  constructor(input: ClaudeQueryInput) {
+    this.output = this.events(input);
+  }
+
+  private async *events(input: ClaudeQueryInput): AsyncGenerator<SDKMessage> {
+    if (typeof input.prompt === "string") throw new Error("Expected streaming input");
+    for await (const _prompt of input.prompt) {
+      yield {
+        type: "system",
+        subtype: "init",
+        session_id: "settings-session",
+        model: "claude-haiku-5-5",
+        permissionMode: "auto",
+      } as SDKMessage;
+      yield {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "tool_use", id: "tool_sleep", name: "Bash", input: { command: "sleep 20" } },
+          ],
+        },
+      } as SDKMessage;
+      await this.work.promise;
+      if (this.stopped) return;
+      yield { type: "assistant", message: { content: "DONE" } } as SDKMessage;
+      yield {
+        type: "result",
+        subtype: "success",
+        usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 },
+        total_cost_usd: 0,
+      } as SDKMessage;
+    }
+  }
+
+  next() {
+    return this.output.next();
+  }
+  return() {
+    this.close();
+    return this.output.return();
+  }
+  close() {
+    this.stopped = true;
+    this.closed.resolve();
+    this.work.resolve();
+  }
+  async interrupt() {
+    this.close();
+  }
+  async setPermissionMode() {}
+  async setModel() {}
+  async supportedCommands() {
+    return [];
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+test.each(["mode", "model", "commands"] as const)(
+  "a pending thinking change preserves the current turn during a %s request",
+  async (control) => {
+    const queries: ForegroundQuery[] = [];
+    const efforts: ClaudeQueryInput["options"]["effort"][] = [];
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      resolveBinary: async () => "/test/claude",
+      queryFactory: (input) => {
+        const query = new ForegroundQuery(input);
+        queries.push(query);
+        efforts.push(input.options.effort);
+        return query as unknown as Query;
+      },
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-haiku-5-5",
+      modeId: "auto",
+      thinkingOptionId: "low",
+    });
+    const running = deferred<void>();
+    let terminal = deferred<string>();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => {
+      events.push(event);
+      if (
+        event.type === "timeline" &&
+        event.item.type === "tool_call" &&
+        event.item.status === "running"
+      )
+        running.resolve();
+      if (
+        event.type === "turn_completed" ||
+        event.type === "turn_failed" ||
+        event.type === "turn_canceled"
+      )
+        terminal.resolve(event.type);
+    });
+    try {
+      await session.startTurn("Run the foreground command");
+      await running.promise;
+      expect(await session.setThinkingOption?.("medium")).toMatchObject({
+        message: "Thinking level applies next turn",
+      });
+      if (control === "mode") await session.setMode("acceptEdits");
+      else if (control === "model") await session.setModel("claude-sonnet-5-6");
+      else await session.listCommands();
+      queries[0].work.resolve();
+      expect(
+        await Promise.race([
+          terminal.promise,
+          queries[0].closed.promise.then(() => "query closed before turn finished"),
+        ]),
+      ).toBe("turn_completed");
+      expect(
+        events.some(
+          (event) =>
+            event.type === "timeline" &&
+            event.item.type === "assistant_message" &&
+            event.item.text === "DONE",
+        ),
+      ).toBe(true);
+
+      terminal = deferred<string>();
+      await session.startTurn("Run another command with the new thinking level");
+      queries[1].work.resolve();
+      expect(await terminal.promise).toBe("turn_completed");
+      expect(efforts).toEqual(["low", "medium"]);
+    } finally {
+      await session.close();
+    }
+  },
+);

packages/server/src/server/agent/providers/claude/agent.ts

@@ -2228,18 +2228,37 @@ class ClaudeAgentSession implements AgentSession {
     getToolInput: (toolUseId) => this.toolUseCache.get(toolUseId)?.input ?? null,
     readWorkflowResult: readClaudeWorkflowResultFile,
   });
+  /**
+   * Subagent tool calls Claude has already answered while the child still runs, with the input
+   * they were launched with and the turn that answered them. A background child is answered at
+   * launch and streams its frames afterwards.
+   */
+  private readonly settledSubagentToolCalls = new Map<
+    string,
+    {
+      item: Extract<AgentTimelineItem, { type: "tool_call" }>;
+      input: AgentMetadata | null;
+      turnId: string | null;
+    }
+  >();
   private readonly sidechainTracker = new ClaudeSidechainTracker({
-    getToolInput: (toolUseId) => this.toolUseCache.get(toolUseId)?.input ?? null,
+    getToolInput: (toolUseId) =>
+      this.toolUseCache.get(toolUseId)?.input ??
+      this.settledSubagentToolCallInCurrentTurn(toolUseId)?.input ??
+      null,
     // Releases that predate the task protocol announce nothing, so the tracker keeps deriving
     // identity and status from frames for them. Detecting the capability beats comparing version
     // strings: it reacts to what this session actually does.
     isDescriptorOwnedElsewhere: () => this.taskProtocolSource.isActive,
-    // The parent's tool call owns its card once its result arrives. A background child streams
-    // its frames after Claude has already answered the call, and re-emitting the card from them
-    // would replace the settled card with an unlabeled, running one.
+    // A background child streams its frames after Claude has already answered the call, so its
+    // card is rebuilt from the settled call: a running one would replace the settled, labeled card.
+    // A card belongs to the turn that answered the call, so frames from a later turn leave it be.
     needsSyntheticParentToolCard: (toolUseId) =>
-      this.toolUseCache.has(toolUseId) &&
+      (this.toolUseCache.has(toolUseId) ||
+        this.settledSubagentToolCallInCurrentTurn(toolUseId) !== undefined) &&
       this.taskProtocolSource.needsSyntheticParentToolCard(toolUseId),
+    getSettledParentToolCall: (toolUseId) =>
+      this.settledSubagentToolCallInCurrentTurn(toolUseId)?.item,
   });
   private persistedHistory: PersistedTimelineEntry[] = [];
   private persistedProviderSubagentEvents: Extract<
@@ -2591,13 +2610,13 @@ class ClaudeAgentSession implements AgentSession {
     const normalized = isPermissionMode(modeId) ? modeId : "default";
     assertClaudeModeCanRun(normalized, this.harnessEnvironment);
     const previousMode = this.currentMode;
-    const launchesQuery = !this.query || this.queryRestartNeeded;
+    const previousQuery = this.query;
     const activeQuery = await this.ensureQuery(normalized);
     try {
       await activeQuery.setPermissionMode(normalized);
     } catch (error) {
       // The query was launched in the rejected mode; relaunch in the current mode next time.
-      if (launchesQuery) this.queryRestartNeeded = true;
+      if (activeQuery !== previousQuery) this.queryRestartNeeded = true;
       throw error;
     }
     if (normalized === "plan") {
@@ -2876,6 +2895,7 @@ class ClaudeAgentSession implements AgentSession {
     this.cancelCurrentTurn = null;
     this.turnState = "idle";
     this.sidechainTracker.clear();
+    this.settledSubagentToolCalls.clear();
     this.taskProtocolSource.reset();
     this.input?.end();
     this.query?.close?.();
@@ -3294,7 +3314,9 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   private async ensureQuery(launchMode: PermissionMode = this.currentMode): Promise<Query> {
-    if (this.query && !this.queryRestartNeeded) {
+    // Controls use the running turn's query. Pending launch settings take effect
+    // after that turn finishes, when its active query handle has been cleared.
+    if (this.query && (!this.queryRestartNeeded || this.activeForegroundQuery === this.query)) {
       return this.query;
     }
 
@@ -4361,6 +4383,7 @@ class ClaudeAgentSession implements AgentSession {
     for (const event of foldSubagentObservations(subagentObservations)) {
       events.push({ type: "provider_subagent", provider: "claude", event });
     }
+    this.releaseFinishedSubagentToolCalls(subagentObservations);
     for (const observation of subagentObservations) {
       if (observation.kind !== "declared") continue;
       if (!this.taskProtocolSource.needsSyntheticParentToolCard(observation.id)) continue;
@@ -5548,28 +5571,22 @@ class ClaudeAgentSession implements AgentSession {
     const { images, text } = splitClaudeToolResultImages(block.content);
     const output = this.buildToolOutput(text, block, entry);
 
-    if (block.is_error) {
-      this.pushToolCall(
-        mapClaudeFailedToolCall({
+    const settledToolCall = block.is_error
+      ? mapClaudeFailedToolCall({
           name: toolName,
           callId,
           input: entry?.input ?? null,
           output: output ?? null,
           error: { ...block, content: text },
-        }),
-        items,
-      );
-    } else {
-      this.pushToolCall(
-        mapClaudeCompletedToolCall({
+        })
+      : mapClaudeCompletedToolCall({
           name: toolName,
           callId,
           input: entry?.input ?? null,
           output: output ?? null,
-        }),
-        items,
-      );
-    }
+        });
+    this.pushToolCall(settledToolCall, items);
+    this.rememberSettledSubagentToolCall(settledToolCall, entry);
 
     for (const image of images) {
       const imageItem = renderProviderImageOutputAsAssistantMarkdown(image, {
@@ -5585,6 +5602,34 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
+  private rememberSettledSubagentToolCall(
+    item: Extract<AgentTimelineItem, { type: "tool_call" }> | null,
+    entry: ToolUseCacheEntry | undefined,
+  ): void {
+    const subagentId = item ? this.taskProtocolSource.resolveSubagentId(item.callId) : undefined;
+    if (!item || !subagentId) return;
+    this.settledSubagentToolCalls.set(subagentId, {
+      item,
+      input: entry?.input ?? null,
+      turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null,
+    });
+  }
+
+  private settledSubagentToolCallInCurrentTurn(subagentId: string) {
+    const settled = this.settledSubagentToolCalls.get(subagentId);
+    const currentTurnId = this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null;
+    return settled && settled.turnId === currentTurnId ? settled : undefined;
+  }
+
+  /** A finished child streams no more frames, so its settled call has nothing left to update. */
+  private releaseFinishedSubagentToolCalls(observations: SubagentObservation[]): void {
+    for (const observation of observations) {
+      if (observation.kind === "status" && observation.status !== "running") {
+        this.settledSubagentToolCalls.delete(observation.id);
+      }
+    }
+  }
+
   private buildToolOutput(
     content: unknown,
     block: ClaudeContentChunk,

packages/server/src/server/agent/providers/claude/sidechain-tracker.ts

@@ -18,6 +18,8 @@ interface ClaudeContentChunk {
   [key: string]: unknown;
 }
 
+type ClaudeToolCallItem = Extract<AgentTimelineItem, { type: "tool_call" }>;
+
 interface SubAgentActionEntry {
   index: number;
   toolName: string;
@@ -64,6 +66,7 @@ export class ClaudeSidechainTracker {
   private readonly getToolInput: (toolUseId: string) => AgentMetadata | null | undefined;
   private readonly isDescriptorOwnedElsewhere: () => boolean;
   private readonly needsSyntheticParentToolCard: (toolUseId: string) => boolean;
+  private readonly getSettledParentToolCall: (toolUseId: string) => ClaudeToolCallItem | undefined;
 
   constructor(input: {
     getToolInput: (toolUseId: string) => AgentMetadata | null | undefined;
@@ -74,10 +77,17 @@ export class ClaudeSidechainTracker {
      */
     isDescriptorOwnedElsewhere?: () => boolean;
     needsSyntheticParentToolCard?: (toolUseId: string) => boolean;
+    /**
+     * The parent's tool call once Claude has answered it. A background child streams its frames
+     * after that answer, so its card keeps the settled status and output and gains the child's
+     * action log.
+     */
+    getSettledParentToolCall?: (toolUseId: string) => ClaudeToolCallItem | undefined;
   }) {
     this.getToolInput = input.getToolInput;
     this.isDescriptorOwnedElsewhere = input.isDescriptorOwnedElsewhere ?? (() => false);
     this.needsSyntheticParentToolCard = input.needsSyntheticParentToolCard ?? (() => true);
+    this.getSettledParentToolCall = input.getSettledParentToolCall ?? (() => undefined);
   }
 
   handleMessage(message: SDKMessage, parentToolUseId: string): AgentStreamEvent[] {
@@ -119,17 +129,19 @@ export class ClaudeSidechainTracker {
       return [];
     }
 
-    const toolCall = mapClaudeRunningToolCall({
-      name: "Task",
-      callId: parentToolUseId,
-      input: null,
-      output: null,
-    });
+    const toolCall =
+      this.getSettledParentToolCall(parentToolUseId) ??
+      mapClaudeRunningToolCall({
+        name: "Task",
+        callId: parentToolUseId,
+        input: null,
+        output: null,
+      });
     if (!toolCall) {
       return [];
     }
 
-    const detail: Extract<AgentTimelineItem, { type: "tool_call" }>["detail"] = {
+    const detail: ClaudeToolCallItem["detail"] = {
       type: "sub_agent",
       ...(state.subAgentType ? { subAgentType: state.subAgentType } : {}),
       ...(state.description ? { description: state.description } : {}),

packages/server/src/server/agent/providers/omp/agent.test.ts

@@ -39,6 +39,19 @@ const ABORTED_TERMINAL_RESPONSE: OmpAgentMessage = {
   errorMessage: "Interrupted by user",
 };
 
+test("an idle follow-up is submitted as a prompt so OMP can start a turn", async () => {
+  const runtime = new FakeOmp();
+  const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+  const session = await client.createSession({ provider: "omp", cwd: process.cwd() });
+  onTestFinished(() => session.close());
+  const handler = session.tryHandleOutOfBand?.("/follow-up check the build");
+  expect(handler).not.toBeNull();
+  await handler!.run({ emit: () => {} });
+  expect(runtime.latestSession().prompts).toEqual([
+    { message: "check the build", imageCount: 0, streamingBehavior: "followUp" },
+  ]);
+});
+
 test("OMP ready timeout defaults to 20 seconds and RPC timeout overrides both", () => {
   expect(resolveOmpProviderOptions({}).runtimeOptions).toMatchObject({
     readyTimeoutMs: 20_000,

packages/server/src/server/agent/providers/omp/agent.ts

@@ -705,6 +705,7 @@ export class OmpAgentSession implements AgentSession {
   private activeAssistantMessageId: string | null = null;
   private activeTurnTerminalAssistantMessage: OmpAgentMessage | null = null;
   private activeTurnStarted = false;
+  private outOfBandTurnStartAnnounced = false;
   private activeTurnHasUserMessage = false;
   private activeNoTurnPromptText: string | null = null;
   private readonly pendingNoTurnOutputs: Array<{ turnId: string; message: string }> = [];
@@ -849,6 +850,20 @@ export class OmpAgentSession implements AgentSession {
   }
 
   async startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<StartTurnResult> {
+    return this.startPrompt({ prompt, options });
+  }
+
+  private async startPrompt({
+    prompt,
+    options,
+    streamingBehavior,
+    announceTurn = false,
+  }: {
+    prompt: AgentPromptInput;
+    options?: AgentRunOptions;
+    streamingBehavior?: "steer" | "followUp";
+    announceTurn?: boolean;
+  }): Promise<StartTurnResult> {
     if (this.activeTurnId) {
       throw new Error("An OMP turn is already active");
     }
@@ -861,17 +876,26 @@ export class OmpAgentSession implements AgentSession {
     this.activeAssistantMessageId = null;
     this.activeTurnTerminalAssistantMessage = null;
     this.activeTurnStarted = false;
+    this.outOfBandTurnStartAnnounced = false;
     this.activeTurnHasUserMessage = false;
     this.activePromptRequestId = null;
     this.clearNoTurnBuffers();
     this.activeNoTurnPromptText = payload.text;
     this.usagePoller.startTurn();
+    if (announceTurn) {
+      this.outOfBandTurnStartAnnounced = true;
+      this.emit({ type: "turn_started", provider: this.provider, turnId });
+    }
 
     void (async () => {
       try {
         if (this.runtimeDead) await this.replaceRuntime(this.currentModeId ?? "full");
         if (this.closed) throw new Error("OMP session is closed");
-        const ack = await this.runtimeSession.prompt(payload.text, payload.images);
+        const ack = await this.runtimeSession.prompt({
+          message: payload.text,
+          images: payload.images,
+          streamingBehavior,
+        });
         this.activePromptRequestId = ack.requestId ?? null;
         const correlatedResult = ack.requestId
           ? this.pendingPromptResults.get(ack.requestId)
@@ -1191,6 +1215,7 @@ export class OmpAgentSession implements AgentSession {
     this.activeAssistantMessageId = null;
     this.activeTurnTerminalAssistantMessage = null;
     this.activeTurnStarted = false;
+    this.outOfBandTurnStartAnnounced = false;
     this.activeTurnHasUserMessage = false;
     this.pendingClientMessages.length = 0;
     this.clearNoTurnBuffers();
@@ -1235,12 +1260,13 @@ export class OmpAgentSession implements AgentSession {
       if (!message) {
         return null;
       }
+      const streamingBehavior = commandName === "steer" ? "steer" : "followUp";
       return {
         run: async () => {
-          if (commandName === "steer") {
-            this.runtimeSession.steer(message);
+          if (!this.activeTurnId && !this.activeTurnStarted) {
+            await this.startPrompt({ prompt: message, streamingBehavior, announceTurn: true });
           } else {
-            this.runtimeSession.followUp(message);
+            await this.runtimeSession.prompt({ message, streamingBehavior });
           }
         },
       };
@@ -1804,11 +1830,11 @@ export class OmpAgentSession implements AgentSession {
       case "turn_start":
         this.activeTurnStarted = true;
         this.clearNoTurnBuffers();
-        this.emit({
-          type: "turn_started",
-          provider: this.provider,
-          turnId,
-        });
+        if (this.outOfBandTurnStartAnnounced) {
+          this.outOfBandTurnStartAnnounced = false;
+        } else {
+          this.emit({ type: "turn_started", provider: this.provider, turnId });
+        }
         return;
       case "message_start":
         this.handleMessageStart(event);

packages/server/src/server/agent/providers/omp/cli-runtime.test.ts

@@ -143,6 +143,26 @@ describe("OMP CLI runtime", () => {
     await expect(result).rejects.toThrow("rejected");
     await session.close();
   });
+  test("sends the prompt streamingBehavior only when one is given", async () => {
+    const child = createOmpChild();
+    const session = await createRuntime(child, []).startSession({ cwd: "/workspace/project" });
+
+    for (const streamingBehavior of ["followUp", undefined] as const) {
+      const pending = capturePendingCommand(child, "prompt");
+      const result = session.prompt({ message: "after this, update the docs", streamingBehavior });
+      const command = await pending;
+      expect(withoutRequestId(command)).toEqual({
+        type: "prompt",
+        message: "after this, update the docs",
+        ...(streamingBehavior ? { streamingBehavior } : {}),
+      });
+      child.stdout.write(
+        `${JSON.stringify({ id: command.id, type: "response", command: "prompt", success: true })}\n`,
+      );
+      await result;
+    }
+    await session.close();
+  });
   test("uses the configured RPC timeout and attributes the pending phase", async () => {
     vi.useFakeTimers();
     const child = createOmpChild();
@@ -438,7 +458,7 @@ describe("OMP CLI runtime", () => {
     replyToCommands(child, () => undefined);
     const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
 
-    await expect(session.prompt("hello")).resolves.toEqual({ requestId: "req_1" });
+    await expect(session.prompt({ message: "hello" })).resolves.toEqual({ requestId: "req_1" });
   });
 
   test("reports OMP 18.3's late prompt rejection as a failed prompt result", async () => {
@@ -455,7 +475,7 @@ describe("OMP CLI runtime", () => {
     const events: unknown[] = [];
     session.onEvent((event) => events.push(event));
 
-    await expect(session.prompt("hello")).resolves.toEqual({ requestId: "req_1" });
+    await expect(session.prompt({ message: "hello" })).resolves.toEqual({ requestId: "req_1" });
 
     expect(events).toContainEqual({
       type: "prompt_result",

packages/server/src/server/agent/providers/omp/cli-runtime.ts

@@ -15,6 +15,7 @@ import {
   type OmpRuntime,
   type OmpRuntimeLaunch,
   type OmpRuntimeSession,
+  type OmpPromptInput,
   type OmpStartSessionInput,
 } from "./runtime.js";
 import {
@@ -142,14 +143,12 @@ class OmpCliRuntimeSession implements OmpRuntimeSession {
     };
   }
 
-  async prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck> {
+  async prompt({ message, images, streamingBehavior }: OmpPromptInput): Promise<OmpPromptAck> {
     const { id: requestId, promise } = this.process.startRequest({
       type: "prompt",
       message,
       ...(images?.length ? { images } : {}),
+      ...(streamingBehavior ? { streamingBehavior: streamingBehavior } : {}),
     });
     const ack = OmpPromptAckSchema.parse(await promise) ?? {};
     return { requestId, ...ack };
@@ -282,13 +281,6 @@ class OmpCliRuntimeSession implements OmpRuntimeSession {
     await this.request({ type: "steer", message, ...(images?.length ? { images } : {}) });
   }
 
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void {
-    this.process.send({ type: "follow_up", message, ...(images?.length ? { images } : {}) });
-  }
-
   async handoff(customInstructions?: string): Promise<void> {
     await this.request({
       type: "handoff",

packages/server/src/server/agent/providers/omp/rpc-types.ts

@@ -535,6 +535,7 @@ export const OmpRpcCommandSchema = z.discriminatedUnion("type", [
     type: z.literal("prompt"),
     message: z.string(),
     images: z.array(OmpImageContentSchema).optional(),
+    streamingBehavior: z.enum(["steer", "followUp"]).optional(),
   }),
   z.object({
     ...OmpCommandBase,

packages/server/src/server/agent/providers/omp/runtime.ts

@@ -42,13 +42,18 @@ export interface OmpStartSessionInput {
   extraArgs?: string[];
 }
 
+export interface OmpPromptInput {
+  message: string;
+  images?: Array<{ type: "image"; data: string; mimeType: string }>;
+  streamingBehavior?: "steer" | "followUp";
+}
+
 export interface OmpRuntimeSession {
   readonly environment: Record<string, string>;
   onEvent(callback: (event: OmpRuntimeEvent) => void): () => void;
-  prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck>;
+  // With streamingBehavior, a busy OMP queues the message instead of rejecting it, and an
+  // idle OMP starts a run with it.
+  prompt(input: OmpPromptInput): Promise<OmpPromptAck>;
   compact(customInstructions?: string): Promise<void>;
   setAutoCompaction(enabled: boolean): Promise<void>;
   abort(): Promise<void>;
@@ -71,10 +76,6 @@ export interface OmpRuntimeSession {
     message: string,
     images?: Array<{ type: "image"; data: string; mimeType: string }>,
   ): Promise<void>;
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void;
   handoff(customInstructions?: string): Promise<void>;
   respondToExtensionUiRequest(
     id: string,

packages/server/src/server/agent/providers/omp/test-utils/fake-omp.ts

@@ -2,6 +2,7 @@ import type {
   OmpRuntime,
   OmpRuntimeLaunch,
   OmpRuntimeSession,
+  OmpPromptInput,
   OmpStartSessionInput,
 } from "../runtime.js";
 import type {
@@ -133,7 +134,11 @@ export class FakeOmpSession implements OmpRuntimeSession {
   readonly environment: Record<string, string>;
   fastModeResult = { enabled: false, active: false };
   readonly setFastModeRequests: boolean[] = [];
-  readonly prompts: Array<{ message: string; imageCount: number }> = [];
+  readonly prompts: Array<{
+    message: string;
+    imageCount: number;
+    streamingBehavior?: "steer" | "followUp";
+  }> = [];
   readonly compactRequests: Array<{ customInstructions?: string }> = [];
   readonly setAutoCompactionRequests: boolean[] = [];
   readonly subagentSubscriptionRequests: FakeOmpSubagentSubscriptionLevel[] = [];
@@ -143,7 +148,6 @@ export class FakeOmpSession implements OmpRuntimeSession {
   readonly handoffRequests: Array<{ customInstructions?: string }> = [];
   readonly steerRequests: Array<{ message: string; imageCount: number }> = [];
   steerError: Error | null = null;
-  readonly followUpRequests: Array<{ message: string; imageCount: number }> = [];
   readonly hostToolSetRequests: OmpRpcHostToolDefinition[][] = [];
   readonly hostToolResults: OmpRpcHostToolResult[] = [];
   readonly hostToolUpdates: OmpRpcHostToolUpdate[] = [];
@@ -216,14 +220,19 @@ export class FakeOmpSession implements OmpRuntimeSession {
     };
   }
 
-  async prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck> {
-    if (this.state.isStreaming || this.state.isCompacting) {
+  async prompt({ message, images, streamingBehavior }: OmpPromptInput): Promise<OmpPromptAck> {
+    const busy = this.state.isStreaming || this.state.isCompacting;
+    if (busy && !streamingBehavior) {
       throw new Error("Agent is already processing");
     }
-    this.prompts.push({ message, imageCount: images?.length ?? 0 });
+    this.prompts.push({
+      message,
+      imageCount: images?.length ?? 0,
+      ...(streamingBehavior ? { streamingBehavior: streamingBehavior } : {}),
+    });
+    if (busy) {
+      return {};
+    }
     this.promptWaiters.shift()?.();
     const heldPrompt = this.nextHeldPrompt;
     if (heldPrompt) {
@@ -412,13 +421,6 @@ export class FakeOmpSession implements OmpRuntimeSession {
     if (this.steerError) throw this.steerError;
   }
 
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void {
-    this.followUpRequests.push({ message, imageCount: images?.length ?? 0 });
-  }
-
   sendHostToolResult(result: OmpRpcHostToolResult): void {
     this.hostToolResults.push(result);
     this.hostToolResultWaiters.shift()?.(result);

packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts

@@ -0,0 +1,202 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import { createPaseoToolCatalog } from "../../tools/paseo-tools.js";
+import { AgentManager } from "../../agent-manager.js";
+import { AgentStorage } from "../../agent-storage.js";
+import { ProviderSnapshotManager } from "../../provider-snapshot-manager.js";
+import { OpenCodeBridge } from "./bridge.js";
+import { ScheduleService } from "../../../schedule/service.js";
+import { createWorkspaceScriptsService } from "../../../session/workspace-scripts/workspace-scripts-service.js";
+import {
+  FileBackedProjectRegistry,
+  FileBackedWorkspaceRegistry,
+} from "../../../workspace-registry.js";
+import { createServiceProxySubsystem } from "../../../service-proxy.js";
+import { WorkspaceScriptRuntimeStore } from "../../../workspace-script-runtime-store.js";
+import { createTerminalManager } from "../../../../terminal/terminal-manager.js";
+
+test("bridge preserves tool failure messages and classifies invalid requests as client errors", async () => {
+  const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-7045-"));
+  const logger = createTestLogger();
+  const providerSnapshotManager = new ProviderSnapshotManager({ logger });
+  const agentManager = new AgentManager({ logger });
+  const agentStorage = new AgentStorage(paseoHome, logger);
+  const unused = async (): Promise<never> => {
+    throw new Error("Unexpected workspace or agent creation");
+  };
+  const scheduleService = new ScheduleService({
+    paseoHome,
+    logger,
+    agentManager,
+    agentStorage,
+    createAgent: unused,
+    createDirectoryWorkspace: unused,
+    createPaseoWorktreeWorkspace: unused,
+    archiveWorkspace: unused,
+    runner: async () => ({ agentId: null, output: "done" }),
+  });
+  const workspaceScripts = createWorkspaceScriptsService({
+    serviceProxy: createServiceProxySubsystem({ logger }),
+    scriptRuntimeStore: new WorkspaceScriptRuntimeStore(),
+    terminalManager: createTerminalManager(),
+    workspaceRegistry: new FileBackedWorkspaceRegistry(
+      path.join(paseoHome, "workspaces.json"),
+      logger,
+    ),
+    projectRegistry: new FileBackedProjectRegistry(path.join(paseoHome, "projects.json"), logger),
+    workspaceGitService: {
+      peekSnapshot: () => {
+        throw new Error("Unexpected git lookup");
+      },
+    },
+    getDaemonTcpPort: null,
+    getDaemonTcpHost: null,
+    serviceProxyPublicBaseUrl: null,
+    resolveScriptHealth: null,
+    logger,
+    emit: () => {},
+    publishStatusUpdate: () => {},
+    spawnWorkspaceScript: unused,
+    assertAutomationAllowed: unused,
+  });
+  const catalog = createPaseoToolCatalog({
+    workspaceScripts,
+    agentManager,
+    agentStorage,
+    scheduleService,
+    providerSnapshotManager,
+    logger,
+  });
+  const bridge = new OpenCodeBridge({ paseoHome, logger });
+  try {
+    await bridge.start();
+    bridge.setManifestCatalog(catalog);
+    bridge.bindSession({ sessionId: "diagnosis", env: {}, tools: catalog });
+    const config = JSON.parse(bridge.decorateServerEnv({}).OPENCODE_CONFIG_CONTENT);
+    const { baseUrl, token } = config.plugin[0][1];
+    const completed = await scheduleService.create({
+      prompt: "Run once",
+      name: "Daily check",
+      cadence: { type: "cron", expression: "0 0 * * *" },
+      target: { type: "new-agent", config: { provider: "codex", cwd: paseoHome } },
+      maxRuns: 1,
+      runOnCreate: true,
+    });
+    await scheduleService.tick();
+    expect((await scheduleService.inspect(completed.id)).status).toBe("completed");
+    const manifest = await fetch(`${baseUrl}/_internal/opencode/tools`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const { tools } = await manifest.json();
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "create_agent").inputSchema.properties,
+    ).not.toHaveProperty("background");
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "update_schedule").inputSchema
+        .properties,
+    ).not.toHaveProperty("every");
+    await writeFile(
+      path.join(paseoHome, "schedules", "broken.json"),
+      JSON.stringify({ id: "broken", prompt: 17 }),
+    );
+    const observed = [];
+    for (const [tool, body, expected] of [
+      [
+        "create_agent",
+        JSON.stringify({ title: "Probe", provider: "opencode", initialPrompt: "Reply OK" }),
+        400,
+      ],
+      ["create_agent", "{", 400],
+      ["nonexistent_tool", "{}", 404],
+      ["inspect_schedule", JSON.stringify({ id: "missing" }), 400],
+      ...["pause_schedule", "resume_schedule", "run_schedule_once"].map(
+        (action) => [action, JSON.stringify({ id: completed.id }), 400] as const,
+      ),
+      [
+        "create_schedule",
+        JSON.stringify({ prompt: "Probe", provider: "codex", cron: "not-a-cron" }),
+        400,
+      ],
+      [
+        "create_schedule",
+        JSON.stringify({
+          prompt: "Probe",
+          provider: "codex",
+          cron: "0 0 * * *",
+          timezone: "Mars/Phobos",
+        }),
+        400,
+      ],
+      ["update_schedule", JSON.stringify({ id: completed.id, name: "" }), 200],
+      ["update_schedule", JSON.stringify({ id: completed.id, cron: "0 0 30 2 *" }), 400],
+      ["update_schedule", JSON.stringify({ id: completed.id, expiresIn: "not-a-duration" }), 400],
+      ["send_agent_prompt", JSON.stringify({ agentId: "missing", prompt: "Hello" }), 400],
+      ["inspect_schedule", JSON.stringify({ id: "broken" }), 500],
+      ["list_workspace_scripts", JSON.stringify({ workspaceId: "wks_typo" }), 500],
+      [
+        "start_workspace_script",
+        JSON.stringify({ workspaceId: "wks_typo", scriptName: "web" }),
+        500,
+      ],
+    ] as const) {
+      const response = await fetch(
+        `${baseUrl}/_internal/opencode/sessions/diagnosis/tools/${tool}`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+          body,
+        },
+      );
+      observed.push({
+        tool,
+        body,
+        expected,
+        status: response.status,
+        payload: await response.json(),
+      });
+    }
+
+    for (const result of observed) expect.soft(result.status, result.body).toBe(result.expected);
+    expect((await scheduleService.inspect(completed.id)).name).toBeNull();
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "update_schedule").inputSchema.properties
+        .name,
+    ).not.toHaveProperty("minLength");
+    for (const result of observed.slice(14)) {
+      expect.soft(result.payload).toEqual({ error: "Workspace not found: wks_typo" });
+    }
+    expect.soft(observed[12].payload).toEqual({ error: "Agent not found: missing" });
+    expect.soft(observed[13].payload).toEqual({ error: expect.stringContaining('"prompt"') });
+    expect.soft(observed[13].payload).not.toHaveProperty("issues");
+    expect(observed[3].payload).toEqual({ error: "Schedule not found: missing" });
+    for (const result of observed.slice(4, 7))
+      expect(result.payload).toEqual({ error: `Schedule ${completed.id} is already completed` });
+    for (const [index, field] of [
+      [7, "cron"],
+      [8, "timezone"],
+      [10, "cron"],
+      [11, "expiresIn"],
+    ] as const) {
+      expect(observed[index].payload).toMatchObject({
+        error: "Invalid tool input",
+        issues: expect.arrayContaining([expect.objectContaining({ path: [field] })]),
+      });
+    }
+    expect(observed[0].payload).toMatchObject({
+      error: "Invalid tool input",
+      issues: expect.arrayContaining([
+        expect.objectContaining({
+          path: ["provider"],
+          message: expect.stringContaining("provider/model"),
+        }),
+      ]),
+    });
+  } finally {
+    await bridge.close();
+    await providerSnapshotManager.shutdown();
+    await rm(paseoHome, { recursive: true, force: true });
+  }
+});

packages/server/src/server/agent/providers/opencode/bridge-plugin.mjs

@@ -13,8 +13,11 @@ export default async function paseoPlugin(input, options) {
     });
     const payload = await response.json().catch(() => ({}));
     if (!response.ok) {
-      const error = new Error(payload.error ?? `Paseo OpenCode bridge failed: ${response.status}`);
+      const detail = formatErrorDetail(payload.issues ?? payload.details);
+      const message = payload.error ?? `Paseo OpenCode bridge failed: ${response.status}`;
+      const error = new Error(detail ? `${message}: ${detail}` : message);
       error.status = response.status;
+      if (detail) error.details = detail;
       throw error;
     }
     return payload;
@@ -79,6 +82,17 @@ export default async function paseoPlugin(input, options) {
   };
 }
 
+function formatErrorDetail(details) {
+  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
+  return details
+    .map((issue) => {
+      const path =
+        Array.isArray(issue?.path) && issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue?.message ?? "Invalid value"}`;
+    })
+    .join("; ");
+}
+
 function logPluginError(stage, context, error) {
   console.error(`[paseo-opencode-plugin] ${stage} failed`, {
     ...context,

packages/server/src/server/agent/providers/opencode/bridge.test.ts

@@ -9,6 +9,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
 import type { PaseoToolCatalog } from "../../tools/types.js";
+import { PaseoToolInputError } from "../../tools/types.js";
 import { createPaseoToolCatalog } from "../../tools/paseo-tools.js";
 import { AgentManager } from "../../agent-manager.js";
 import { AgentStorage } from "../../agent-storage.js";
@@ -36,8 +37,12 @@ function createCatalog(): PaseoToolCatalog {
     description: "Returns the supplied value.",
     inputSchema: { value: z.string() },
     async handler(input: unknown) {
-      const parsed = z.object({ value: z.string() }).parse(input);
-      return { content: [{ type: "text", text: parsed.value }] };
+      const parsed = z
+        .object({ value: z.string().min(2, "value must be at least 2 characters") })
+        .strict()
+        .safeParse(input);
+      if (!parsed.success) throw new PaseoToolInputError(parsed.error.message, parsed.error.issues);
+      return { content: [{ type: "text", text: parsed.data.value }] };
     },
   };
   const tools = new Map([[tool.name, tool]]);
@@ -193,6 +198,13 @@ describe("OpenCodeBridge", () => {
       expect(asked).toEqual([
         { permission: "paseo_echo_context", patterns: ["*"], always: ["*"], metadata: {} },
       ]);
+      asked.length = 0;
+      await expect(
+        hooks.tool.paseo_echo_context.execute(
+          { value: "x" },
+          { sessionID: "ses_one", ask: async () => undefined },
+        ),
+      ).rejects.toThrow("value: value must be at least 2 characters");
 
       executedInputs.length = 0;
       await expect(
@@ -357,12 +369,17 @@ describe("OpenCodeBridge", () => {
             body: JSON.stringify(input),
           },
         );
-        expect(response.status).toBe(500);
+        expect(response.status).toBe(400);
         const payload = await response.json();
-        expect(payload.error).toContain("provider must be provider/model");
+        expect(payload).toMatchObject({ error: "Invalid tool input", issues: expect.any(Array) });
         await expect(
           tools.get("paseo_create_agent")!.execute(input, { sessionID: "caller" }),
-        ).rejects.toMatchObject({ message: payload.error, status: 500 });
+        ).rejects.toMatchObject({
+          status: 400,
+          message: expect.stringContaining(
+            "Invalid tool input: provider: provider must be provider/model, for example codex/gpt-5.4",
+          ),
+        });
       } finally {
         await dispose();
       }
@@ -550,6 +567,104 @@ describe("OpenCodeBridge", () => {
     }
   });
 
+  test("returns actionable 4xx responses for invalid bridge requests", async () => {
+    const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-opencode-bridge-errors-"));
+    temporaryDirectories.push(paseoHome);
+    const bridge = new OpenCodeBridge({ paseoHome, logger: createTestLogger() });
+    await bridge.start();
+    const catalog = createCatalog();
+    bridge.bindSession({ sessionId: "ses_errors", env: {}, tools: catalog });
+    const expectedErrorCatalog: PaseoToolCatalog = {
+      tools: new Map([
+        [
+          "expected_error",
+          {
+            name: "expected_error",
+            description: "Throws an expected tool error.",
+            inputSchema: {},
+            async handler() {
+              throw new PaseoToolInputError("Agent not found: missing-agent");
+            },
+          },
+        ],
+        [
+          "internal_error",
+          {
+            name: "internal_error",
+            description: "Throws an internal error.",
+            inputSchema: {},
+            async handler() {
+              throw new Error("Provider unavailable");
+            },
+          },
+        ],
+      ]),
+      getTool(name) {
+        return this.tools.get(name);
+      },
+      async executeTool(name, input, context) {
+        const tool = this.tools.get(name);
+        if (!tool) throw new Error(`Unknown tool: ${name}`);
+        return tool.handler(input, context ?? {});
+      },
+    };
+    bridge.bindSession({ sessionId: "ses_expected_error", env: {}, tools: expectedErrorCatalog });
+
+    try {
+      const plugin = readPluginOptions(bridge.decorateServerEnv({}));
+      const headers = {
+        Authorization: `Bearer ${plugin.token}`,
+        "Content-Type": "application/json",
+      };
+      const invalidInput = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/echo_context`,
+        { method: "POST", headers, body: JSON.stringify({ value: "ok", extra: true }) },
+      );
+      expect(invalidInput.status).toBe(400);
+      expect(await invalidInput.json()).toEqual({
+        error: "Invalid tool input",
+        issues: [
+          {
+            code: "unrecognized_keys",
+            keys: ["extra"],
+            path: [],
+            message: 'Unrecognized key: "extra"',
+          },
+        ],
+      });
+
+      const unknownTool = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/missing`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(unknownTool.status).toBe(404);
+      expect(await unknownTool.json()).toEqual({ error: "Paseo tool not found: missing" });
+
+      const malformedBody = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/echo_context`,
+        { method: "POST", headers, body: "{" },
+      );
+      expect(malformedBody.status).toBe(400);
+      expect(await malformedBody.json()).toEqual({ error: "Malformed JSON request body" });
+
+      const expectedError = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_expected_error/tools/expected_error`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(expectedError.status).toBe(400);
+      expect(await expectedError.json()).toEqual({ error: "Agent not found: missing-agent" });
+
+      const internalError = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_expected_error/tools/internal_error`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(internalError.status).toBe(500);
+      expect(await internalError.json()).toEqual({ error: "Provider unavailable" });
+    } finally {
+      await bridge.close();
+    }
+  });
+
   test("preserves user OpenCode config while installing one content-addressed plugin", async () => {
     const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-opencode-bridge-config-"));
     temporaryDirectories.push(paseoHome);

packages/server/src/server/agent/providers/opencode/bridge.ts

@@ -11,11 +11,22 @@ import {
   addModelVisibleStructuredContent,
   serializePaseoToolInputParameters,
 } from "../../tools/paseo-tool-serialization.js";
-import type { PaseoToolCatalog } from "../../tools/types.js";
+import { PaseoToolInputError, type PaseoToolCatalog } from "../../tools/types.js";
 
 const INTERNAL_PREFIX = "/_internal/opencode";
 const MAX_REQUEST_BYTES = 1024 * 1024;
 
+class OpenCodeBridgeClientError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "OpenCodeBridgeClientError";
+  }
+}
+
 interface OpenCodeBridgeOptions {
   paseoHome: string;
   logger: Logger;
@@ -187,10 +198,26 @@ export class OpenCodeBridge {
       sendJson(response, 404, { error: "Not found" });
     } catch (error) {
       this.logger.warn({ err: error }, "OpenCode bridge request failed");
+      const failure = error instanceof Error ? error : new Error(String(error));
       if (!response.headersSent) {
-        sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        if (error instanceof OpenCodeBridgeClientError) {
+          sendJson(response, error.status, {
+            error: error.message,
+            ...(error.details === undefined ? {} : { details: error.details }),
+          });
+        } else if (error instanceof PaseoToolInputError) {
+          sendJson(
+            response,
+            error.status,
+            error.issues
+              ? { error: "Invalid tool input", issues: error.issues }
+              : { error: error.message },
+          );
+        } else {
+          sendJson(response, 500, { error: failure.message });
+        }
       } else {
-        response.destroy(error instanceof Error ? error : new Error(String(error)));
+        response.destroy(failure);
       }
     }
   }
@@ -224,6 +251,9 @@ export class OpenCodeBridge {
       sendJson(input.response, 403, { error: "Paseo tools are disabled for this session" });
       return;
     }
+    if (!binding.tools.getTool(input.toolName)) {
+      throw new OpenCodeBridgeClientError(404, `Paseo tool not found: ${input.toolName}`);
+    }
     const body = await readJsonBody(input.request);
     const controller = new AbortController();
     input.request.once("aborted", () =>
@@ -349,11 +379,17 @@ async function readJsonBody(request: IncomingMessage): Promise<unknown> {
   for await (const chunk of request) {
     const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
     size += buffer.byteLength;
-    if (size > MAX_REQUEST_BYTES) throw new Error("OpenCode bridge request body is too large");
+    if (size > MAX_REQUEST_BYTES) {
+      throw new OpenCodeBridgeClientError(413, "OpenCode bridge request body is too large");
+    }
     chunks.push(buffer);
   }
   if (chunks.length === 0) return {};
-  return JSON.parse(Buffer.concat(chunks).toString("utf8")) as unknown;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8")) as unknown;
+  } catch {
+    throw new OpenCodeBridgeClientError(400, "Malformed JSON request body");
+  }
 }
 
 function sendJson(response: ServerResponse, status: number, body: unknown): void {

packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs

@@ -15,12 +15,14 @@ export default {
       if (allowMissing && response.status === 404) return null;
       if (!response.ok) {
         const payload = await response.json().catch(() => null);
+        const detail = formatErrorDetail(payload?.issues ?? payload?.details);
         const message =
           typeof payload?.error === "string" && payload.error
             ? payload.error
             : `Paseo tool bridge returned HTTP ${response.status}`;
-        const error = new Error(message);
+        const error = new Error(detail ? `${message}: ${detail}` : message);
         error.status = response.status;
+        if (detail) error.details = detail;
         throw error;
       }
       return response.json();
@@ -78,6 +80,17 @@ export default {
   },
 };
 
+function formatErrorDetail(details) {
+  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
+  return details
+    .map((issue) => {
+      const path =
+        Array.isArray(issue?.path) && issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue?.message ?? "Invalid value"}`;
+    })
+    .join("; ");
+}
+
 // OpenCode tool content is text or a file; MCP images arrive as base64 data.
 function toOpenCodeContent(part) {
   if (part.type === "image") {

packages/server/src/server/agent/tools/paseo-tools.ts

@@ -25,7 +25,7 @@ import {
 import { curateAgentActivity } from "../activity-curator.js";
 import { selectItemsByProjectedLimit } from "../timeline-projection.js";
 import type { AgentStorage } from "../agent-storage.js";
-import { ensureAgentLoaded } from "../agent-loading.js";
+import { AgentNotFoundError, ensureAgentLoaded } from "../agent-loading.js";
 import { isStoredAgentProviderAvailable } from "../../persistence-hooks.js";
 import {
   archiveByScope,
@@ -40,7 +40,12 @@ import { everyMsToFiveFieldCron } from "@getpaseo/protocol/schedule/cadence";
 import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../../path-utils.js";
 import type { TerminalManager } from "../../../terminal/terminal-manager.js";
 import type { CreatePaseoWorktreeWorkflowFn } from "../../worktree-session.js";
-import type { ScheduleService } from "../../schedule/service.js";
+import { computeNextRunAt, validateScheduleCadence } from "../../schedule/cron.js";
+import {
+  ScheduleNotFoundError,
+  ScheduleStateConflictError,
+  type ScheduleService,
+} from "../../schedule/service.js";
 import {
   ScheduleRunSchema,
   ScheduleSummarySchema,
@@ -91,12 +96,13 @@ import {
 } from "../../worktree/commands.js";
 import { registerBrowserTools } from "../../browser-tools/tools.js";
 import type { BrowserToolsBroker } from "../../browser-tools/broker.js";
-import type {
-  PaseoToolCatalog,
-  PaseoToolConfig,
-  PaseoToolDefinition,
-  PaseoToolExecutionContext,
-  PaseoToolResult,
+import {
+  PaseoToolInputError,
+  type PaseoToolCatalog,
+  type PaseoToolConfig,
+  type PaseoToolDefinition,
+  type PaseoToolExecutionContext,
+  type PaseoToolResult,
 } from "./types.js";
 import type { ProviderPaseoToolsPolicy } from "@getpaseo/protocol/provider-config";
 import { isPaseoToolEnabled } from "../paseo-tool-policy.js";
@@ -229,7 +235,7 @@ function assertOptionsAbsent(
   message: string,
 ): void {
   if (options.some(([, value]) => value !== undefined)) {
-    throw new Error(message);
+    throw new PaseoToolInputError(message);
   }
 }
 
@@ -265,7 +271,7 @@ function resolveWorkspaceWorktreeTarget(input: WorkspaceWorktreeOptions): Worksp
       };
     case "checkout-branch":
       if (!input.branch) {
-        throw new Error("branch is required for checkout-branch mode");
+        throw new PaseoToolInputError("branch is required for checkout-branch mode");
       }
       assertOptionsAbsent(
         [
@@ -279,7 +285,7 @@ function resolveWorkspaceWorktreeTarget(input: WorkspaceWorktreeOptions): Worksp
       return { action: "checkout", refName: input.branch };
     case "checkout-pr":
       if (input.prNumber === undefined) {
-        throw new Error("prNumber is required for checkout-pr mode");
+        throw new PaseoToolInputError("prNumber is required for checkout-pr mode");
       }
       assertOptionsAbsent(
         [
@@ -355,7 +361,7 @@ function resolveScheduleProviderAndModel(params: {
   const provider = providerInput.slice(0, slashIndex).trim();
   const model = providerInput.slice(slashIndex + 1).trim();
   if (!provider || !model) {
-    throw new Error("provider must be <provider> or <provider>/<model>");
+    throw new PaseoToolInputError("provider must be <provider> or <provider>/<model>");
   }
 
   return {
@@ -372,7 +378,7 @@ function resolveScheduleUpdateProviderAndModel(params: {
   const modelInput = typeof params.model === "string" ? params.model.trim() : params.model;
 
   if (params.model !== undefined && modelInput === "") {
-    throw new Error("model cannot be empty");
+    throw new PaseoToolInputError("model cannot be empty");
   }
 
   if (!providerInput) {
@@ -390,13 +396,13 @@ function resolveScheduleUpdateProviderAndModel(params: {
   const provider = providerInput.slice(0, slashIndex).trim();
   const modelFromProvider = providerInput.slice(slashIndex + 1).trim();
   if (!provider || !modelFromProvider) {
-    throw new Error("provider must be <provider> or <provider>/<model>");
+    throw new PaseoToolInputError("provider must be <provider> or <provider>/<model>");
   }
   if (params.model === null) {
-    throw new Error("provider specifies a model but model is null");
+    throw new PaseoToolInputError("provider specifies a model but model is null");
   }
   if (typeof modelInput === "string" && modelInput !== modelFromProvider) {
-    throw new Error("Conflicting model values provided");
+    throw new PaseoToolInputError("Conflicting model values provided");
   }
 
   return {
@@ -438,26 +444,82 @@ function normalizeScheduleTimeZoneArg(value: string | undefined): string | undef
   return normalizeScheduleCadenceArg(value);
 }
 
+function addScheduleCadenceIssue(
+  input: { cron?: string; timezone?: string },
+  context: z.RefinementCtx,
+): void {
+  const expression = input.cron?.trim();
+  if (!expression) {
+    return;
+  }
+  const cadence: ScheduleCadence = {
+    type: "cron",
+    expression,
+    ...(input.timezone !== undefined ? { timezone: input.timezone.trim() } : {}),
+  };
+  try {
+    validateScheduleCadence(cadence);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.addIssue({
+      code: "custom",
+      path: [message.startsWith("Invalid cron time zone:") ? "timezone" : "cron"],
+      message,
+    });
+    return;
+  }
+  try {
+    computeNextRunAt(cadence, new Date());
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      path: ["cron"],
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function parseToolArguments<T>(schema: z.ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new PaseoToolInputError(result.error.message, result.error.issues);
+  }
+  return result.data;
+}
+
+function addScheduleDurationIssue(value: string, context: z.RefinementCtx): void {
+  try {
+    parseDurationString(value);
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+const scheduleDurationInputSchema = z.string().superRefine(addScheduleDurationIssue);
+
 function resolveScheduleUpdateCadence(input: ScheduleUpdateToolInput): ScheduleCadence | undefined {
   const every = normalizeScheduleCadenceArg(input.every);
   const cron = normalizeScheduleCadenceArg(input.cron);
   const timeZone = normalizeScheduleTimeZoneArg(input.timezone);
 
   if (every !== undefined && cron !== undefined) {
-    throw new Error("Specify at most one of every or cron");
+    throw new PaseoToolInputError("Specify at most one of every or cron");
   }
   if (timeZone !== undefined && cron === undefined) {
-    throw new Error("timezone can only be used with cron");
+    throw new PaseoToolInputError("timezone can only be used with cron");
   }
   if (every !== undefined) {
     // COMPAT(scheduleEveryInput): accept the old hidden field and canonicalize it before write.
     // Added in v0.2.0; remove after 2027-01-17.
-    const everyMs = parseDurationString(every);
+    const everyMs = parseDurationString(parseToolArguments(scheduleDurationInputSchema, every));
     const expression = everyMsToFiveFieldCron(everyMs);
     if (expression) {
       return { type: "cron", expression };
     }
-    throw new Error(`${every} cannot be represented faithfully by five-field cron`);
+    throw new PaseoToolInputError(`${every} cannot be represented faithfully by five-field cron`);
   }
   if (cron !== undefined) {
     return {
@@ -471,7 +533,7 @@ function resolveScheduleUpdateCadence(input: ScheduleUpdateToolInput): ScheduleC
 
 function resolveScheduleUpdateExpiresAt(input: ScheduleUpdateToolInput): string | null | undefined {
   if (input.expiresIn !== undefined && input.clearExpires) {
-    throw new Error("Specify at most one of expiresIn or clearExpires");
+    throw new PaseoToolInputError("Specify at most one of expiresIn or clearExpires");
   }
   if (input.expiresIn !== undefined) {
     return new Date(Date.now() + parseDurationString(input.expiresIn)).toISOString();
@@ -593,7 +655,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       typeof (inputSchema as { safeParseAsync?: unknown }).safeParseAsync === "function"
         ? (inputSchema as z.ZodType)
         : z.object(inputSchema as z.ZodRawShape).passthrough();
-    return schema.parseAsync(input);
+    const result = await schema.safeParseAsync(input);
+    if (!result.success) {
+      throw new PaseoToolInputError(result.error.message, result.error.issues);
+    }
+    return result.data;
   };
 
   const tools = new Map<string, PaseoToolDefinition>();
@@ -627,7 +693,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     ): Promise<PaseoToolResult> {
       const tool = tools.get(name);
       if (!tool) {
-        throw new Error(`Paseo tool not found: ${name}`);
+        throw new PaseoToolInputError(`Paseo tool not found: ${name}`);
       }
       return tool.handler(await parseToolInput(tool, input), context);
     },
@@ -639,7 +705,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
   }): ScheduleCadence => {
     const expression = input.cron?.trim() ?? "";
     if (!expression) {
-      throw new Error("cron is required");
+      throw new PaseoToolInputError("cron is required");
     }
     const timezone = normalizeScheduleTimeZoneArg(input.timezone);
     return {
@@ -661,7 +727,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
     const parentAgent = agentManager.getAgent(callerAgentId);
     if (!parentAgent) {
-      throw new Error(`Parent agent ${callerAgentId} not found`);
+      throw new PaseoToolInputError(`Parent agent ${callerAgentId} not found`);
     }
     return parentAgent;
   };
@@ -690,9 +756,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     const trimmedCwd = requestedCwd?.trim();
     if (!trimmedCwd) {
       if (opts?.required) {
-        throw new Error("cwd is required");
+        throw new PaseoToolInputError("cwd is required");
       }
-      throw new Error("cwd is required outside an agent-scoped session");
+      throw new PaseoToolInputError("cwd is required outside an agent-scoped session");
     }
 
     return expandUserPath(trimmedCwd);
@@ -707,11 +773,12 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
 
     if (!options.ensureWorkspaceForCreate) {
-      throw new Error(
-        callerAgentId
-          ? `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`
-          : "workspaceId is required outside an agent-scoped session",
-      );
+      if (callerAgentId) {
+        throw new Error(
+          `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`,
+        );
+      }
+      throw new PaseoToolInputError("workspaceId is required outside an agent-scoped session");
     }
 
     return options.ensureWorkspaceForCreate(resolvedCwd);
@@ -726,11 +793,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (callerAgentId) {
       const callerAgent = resolveCallerAgent();
       if (!callerAgent?.workspaceId) {
-        throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+        throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
       }
       return callerAgent.workspaceId;
     }
-    throw new Error("workspaceId is required outside an agent-scoped session");
+    throw new PaseoToolInputError("workspaceId is required outside an agent-scoped session");
   }
 
   const buildCallerAgentScheduleConfigExtras = (
@@ -800,7 +867,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
 
     if (!params?.provider?.trim()) {
-      throw new Error("provider is required when target is new-agent");
+      throw new PaseoToolInputError("provider is required when target is new-agent");
     }
 
     const resolvedProviderModel = resolveScheduleProviderAndModel({
@@ -822,22 +889,41 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (!scheduleService) {
       throw new Error("Schedule service is not configured");
     }
-    const schedule = await scheduleService.inspect(id);
+    let schedule: Awaited<ReturnType<ScheduleService["inspect"]>>;
+    try {
+      schedule = await scheduleService.inspect(id);
+    } catch (error) {
+      if (error instanceof ScheduleNotFoundError) {
+        throw new PaseoToolInputError(error.message);
+      }
+      throw error;
+    }
     if (schedule.target.type !== type) {
-      throw new Error(
+      throw new PaseoToolInputError(
         type === "agent" ? `Heartbeat not found: ${id}` : `Schedule not found: ${id}`,
       );
     }
     return schedule;
   }
 
+  async function runScheduleAction<T>(action: () => Promise<T>): Promise<T> {
+    try {
+      return await action();
+    } catch (error) {
+      if (error instanceof ScheduleStateConflictError) {
+        throw new PaseoToolInputError(error.message);
+      }
+      throw error;
+    }
+  }
+
   async function requireCallerHeartbeat(id: string) {
     if (!callerAgentId) {
-      throw new Error("Heartbeat operations require an agent-scoped session");
+      throw new PaseoToolInputError("Heartbeat operations require an agent-scoped session");
     }
     const schedule = await requireScheduleTarget(id, "agent");
     if (schedule.target.type !== "agent" || schedule.target.agentId !== callerAgentId) {
-      throw new Error(`Heartbeat ${id} does not belong to caller ${callerAgentId}`);
+      throw new PaseoToolInputError(`Heartbeat ${id} does not belong to caller ${callerAgentId}`);
     }
     return schedule;
   }
@@ -847,6 +933,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     })
     .refine(
       (value) => {
+        if (!value.includes("/")) {
+          return true;
+        }
         try {
           resolveRequiredProviderModel(value);
           return true;
@@ -1184,11 +1273,13 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       },
       async (args, context) => {
         if (!callerAgentId) {
-          throw new Error("speak is only available to agent-scoped tool sessions");
+          throw new PaseoToolInputError("speak is only available to agent-scoped tool sessions");
         }
         const handler = resolveSpeakHandler?.(callerAgentId) ?? null;
         if (!handler) {
-          throw new Error(`No speak handler registered for your session '${callerAgentId}'`);
+          throw new PaseoToolInputError(
+            `No speak handler registered for your session '${callerAgentId}'`,
+          );
         }
         await handler({
           text: args.text,
@@ -1289,7 +1380,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       if (isolation === "local") {
         const cwd = resolveScopedCwd(path, { required: true });
         if (!(await isExistingDirectory(cwd))) {
-          throw new Error(`Directory not found: ${cwd}`);
+          throw new PaseoToolInputError(`Directory not found: ${cwd}`);
         }
         assertOptionsAbsent(
           [
@@ -1534,7 +1625,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       if (hasLegacyCreateAgentPlacement(args)) {
         // COMPAT(nestedCreateAgentPlacement): accept the old relationship/workspace shape without
         // advertising it to models. Added in v0.2.0; remove after 2027-01-17.
-        const parsed = legacyAgentToAgentCreateAgentArgsSchema.parse(args);
+        const parsed = parseToolArguments(legacyAgentToAgentCreateAgentArgsSchema, args);
         const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsed.workspace, {
           prompt: parsed.initialPrompt,
         });
@@ -1547,7 +1638,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
           worktree,
         };
       }
-      const parsed = agentToAgentCreateAgentArgsSchema.parse(args);
+      const parsed = parseToolArguments(agentToAgentCreateAgentArgsSchema, args);
       const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(parsed.workspaceId, {
         prompt: parsed.initialPrompt,
       });
@@ -1563,13 +1654,15 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (hasLegacyCreateAgentPlacement(args)) {
       // COMPAT(nestedCreateAgentPlacement): see the agent-scoped branch above.
       const parsedArgs = normalizeTopLevelCreateAgentArgs(
-        legacyTopLevelCreateAgentArgsSchema.parse(args),
+        parseToolArguments(legacyTopLevelCreateAgentArgsSchema, args),
       );
       if (parsedArgs.relationship?.kind === "subagent") {
-        throw new Error("relationship subagent requires an agent-scoped tool session");
+        throw new PaseoToolInputError(
+          "relationship subagent requires an agent-scoped tool session",
+        );
       }
       if (!parsedArgs.workspace) {
-        throw new Error("Legacy create_agent placement could not be resolved");
+        throw new PaseoToolInputError("Legacy create_agent placement could not be resolved");
       }
       const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(
         parsedArgs.workspace,
@@ -1584,7 +1677,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         worktree,
       };
     }
-    const parsedArgs = canonicalTopLevelCreateAgentArgsSchema.parse(args);
+    const parsedArgs = parseToolArguments(canonicalTopLevelCreateAgentArgsSchema, args);
     const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(
       parsedArgs.workspaceId,
       { prompt: parsedArgs.initialPrompt },
@@ -1644,7 +1737,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
     const caller = resolveCallerAgent();
     if (!caller?.workspaceId) {
-      throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+      throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
     }
     return { cwd: undefined, workspaceId: caller.workspaceId };
   }
@@ -1672,18 +1765,18 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     };
 
     if (canonicalCandidate.relationship && canonicalCandidate.workspace) {
-      return legacyTopLevelCreateAgentArgsSchema.parse({
+      return parseToolArguments(legacyTopLevelCreateAgentArgsSchema, {
         ...canonicalCandidate,
         ...(Object.keys(settings).length > 0 ? { settings } : {}),
       });
     }
 
     if (canonicalCandidate.relationship || canonicalCandidate.workspace) {
-      throw new Error("relationship and workspace must be provided together");
+      throw new PaseoToolInputError("relationship and workspace must be provided together");
     }
 
     if (!cwd?.trim()) {
-      throw new Error("cwd is required for legacy top-level create_agent calls");
+      throw new PaseoToolInputError("cwd is required for legacy top-level create_agent calls");
     }
 
     const legacyWorktreeTarget = resolveLegacyCreateAgentWorktreeTarget({
@@ -1710,7 +1803,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
           },
         };
 
-    return legacyTopLevelCreateAgentArgsSchema.parse({
+    return parseToolArguments(legacyTopLevelCreateAgentArgsSchema, {
       ...canonicalCandidate,
       relationship: { kind: "detached" },
       workspace,
@@ -1763,11 +1856,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
   }> {
     if (workspace.kind === "current") {
       if (!callerAgentId) {
-        throw new Error("workspace current requires an agent-scoped tool session");
+        throw new PaseoToolInputError("workspace current requires an agent-scoped tool session");
       }
       const callerAgent = resolveCallerAgent();
       if (!callerAgent?.workspaceId) {
-        throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+        throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
       }
       return {
         cwd: workspace.cwd,
@@ -1784,14 +1877,16 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         (candidate) => candidate.workspaceId === workspace.workspaceId,
       );
       if (!existingWorkspace) {
-        throw new Error(`Workspace ${workspace.workspaceId} not found`);
+        throw new PaseoToolInputError(`Workspace ${workspace.workspaceId} not found`);
       }
       const cwd = workspace.cwd
         ? resolveScopedCwd(workspace.cwd, { required: true })
         : existingWorkspace.cwd;
       const lockedCwd = callerContext?.lockedCwd?.trim();
       if (lockedCwd && !isSameOrDescendantPath(expandUserPath(lockedCwd), cwd)) {
-        throw new Error(`Workspace ${workspace.workspaceId} is outside the allowed cwd`);
+        throw new PaseoToolInputError(
+          `Workspace ${workspace.workspaceId} is outside the allowed cwd`,
+        );
       }
       return {
         cwd,
@@ -1893,6 +1988,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         logger: childLogger,
       }).catch((error) => {
         stopNotification?.();
+        if (error instanceof AgentNotFoundError) {
+          throw new PaseoToolInputError(error.message);
+        }
         throw error;
       });
 
@@ -1956,7 +2054,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const record = await agentStorage.get(agentId);
       if (!record || record.internal) {
-        throw new Error(`Agent ${agentId} not found`);
+        throw new PaseoToolInputError(`Agent ${agentId} not found`);
       }
 
       const structuredSnapshot = buildStoredAgentPayload(
@@ -2194,10 +2292,10 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       const workspaceId = resolveWorkspaceIdForRename(requestedWorkspaceId);
       const existing = await options.workspaceRegistry.get(workspaceId);
       if (!existing) {
-        throw new Error(`Workspace ${workspaceId} not found`);
+        throw new PaseoToolInputError(`Workspace ${workspaceId} not found`);
       }
       if (existing.archivedAt) {
-        throw new Error(`Workspace ${workspaceId} is archived`);
+        throw new PaseoToolInputError(`Workspace ${workspaceId} is archived`);
       }
 
       await options.workspaceRegistry.upsert({
@@ -2401,7 +2499,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const terminal = terminalManager.getTerminal(terminalId);
       if (!terminal) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       terminal.kill();
@@ -2437,7 +2535,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       if (!terminalManager.getTerminal(terminalId)) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       const capture = await terminalManager.captureTerminal(terminalId, {
@@ -2478,7 +2576,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const terminal = terminalManager.getTerminal(terminalId);
       if (!terminal) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       terminal.send({
@@ -2498,24 +2596,26 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     {
       title: "Create schedule",
       description: "Create a recurring schedule that starts a new agent on a cron cadence.",
-      inputSchema: {
-        prompt: z.string().trim().min(1, "prompt is required"),
-        cron: z.string().trim().min(1, "cron is required"),
-        timezone: z
-          .string()
-          .trim()
-          .min(1)
-          .optional()
-          .describe("IANA time zone for the cron cadence. For example: America/New_York."),
-        name: z.string().optional(),
-        provider: (callerAgentId ? AgentProviderEnum.optional() : AgentProviderEnum).describe(
-          "Provider, or provider/model (for example: codex or codex/gpt-5.4). Defaults to the caller's provider in an agent-scoped session.",
-        ),
-        cwd: z.string().optional(),
-        isolation: z.enum(["local", "worktree"]).optional(),
-        maxRuns: z.number().int().positive().optional(),
-        expiresIn: z.string().optional(),
-      },
+      inputSchema: z
+        .object({
+          prompt: z.string().trim().min(1, "prompt is required"),
+          cron: z.string().trim().min(1, "cron is required"),
+          timezone: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+          name: z.string().optional(),
+          provider: (callerAgentId ? AgentProviderEnum.optional() : AgentProviderEnum).describe(
+            "Provider, or provider/model (for example: codex or codex/gpt-5.4). Defaults to the caller's provider in an agent-scoped session.",
+          ),
+          cwd: z.string().optional(),
+          isolation: z.enum(["local", "worktree"]).optional(),
+          maxRuns: z.number().int().positive().optional(),
+          expiresIn: scheduleDurationInputSchema.optional(),
+        })
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: ScheduleSummarySchema.shape,
     },
     async ({ prompt, cron, timezone, name, provider, cwd, isolation, maxRuns, expiresIn }) => {
@@ -2548,19 +2648,21 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     {
       title: "Create heartbeat",
       description: "Create a recurring heartbeat that sends you a prompt on a cron cadence.",
-      inputSchema: {
-        prompt: z.string().trim().min(1, "prompt is required"),
-        cron: z.string().trim().min(1, "cron is required"),
-        timezone: z
-          .string()
-          .trim()
-          .min(1)
-          .optional()
-          .describe("IANA time zone for the cron cadence. For example: America/New_York."),
-        name: z.string().optional(),
-        maxRuns: z.number().int().positive().optional(),
-        expiresIn: z.string().optional(),
-      },
+      inputSchema: z
+        .object({
+          prompt: z.string().trim().min(1, "prompt is required"),
+          cron: z.string().trim().min(1, "cron is required"),
+          timezone: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+          name: z.string().optional(),
+          maxRuns: z.number().int().positive().optional(),
+          expiresIn: scheduleDurationInputSchema.optional(),
+        })
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: ScheduleSummarySchema.shape,
     },
     async ({ prompt, cron, timezone, name, maxRuns, expiresIn }) => {
@@ -2568,7 +2670,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         throw new Error("Schedule service is not configured");
       }
       if (!callerAgentId) {
-        throw new Error("create_heartbeat requires an agent-scoped session");
+        throw new PaseoToolInputError("create_heartbeat requires an agent-scoped session");
       }
       resolveCallerAgent();
 
@@ -2679,7 +2781,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       await requireScheduleTarget(id, "new-agent");
-      await scheduleService.pause(id);
+      await runScheduleAction(() => scheduleService.pause(id));
       return {
         content: [],
         structuredContent: ensureValidJson({ success: true }),
@@ -2705,7 +2807,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       await requireScheduleTarget(id, "new-agent");
-      await scheduleService.resume(id);
+      await runScheduleAction(() => scheduleService.resume(id));
       return {
         content: [],
         structuredContent: ensureValidJson({ success: true }),
@@ -2787,13 +2889,13 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
             .optional()
             .describe("New mode for new-agent target (null to clear)."),
           cwd: z.string().trim().min(1).optional().describe("New cwd for new-agent target."),
-          expiresIn: z
-            .string()
+          expiresIn: scheduleDurationInputSchema
             .optional()
             .describe("New relative expiry duration (for example: 1h, 2d)."),
           clearExpires: z.boolean().optional().describe("Clear any schedule expiry."),
         })
-        .passthrough(),
+        .passthrough()
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: StoredScheduleSchema.shape,
     },
     async (input) => {
@@ -2850,7 +2952,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         throw new Error("Schedule service is not configured");
       }
       await requireScheduleTarget(id, "new-agent");
-      const schedule = await scheduleService.runOnce(id);
+      const schedule = await runScheduleAction(() => scheduleService.runOnce(id));
       return {
         content: [],
         structuredContent: ensureValidJson(schedule),
@@ -2963,10 +3065,10 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       });
       const summary = toProviderSummary(entry);
       if (!entry.enabled) {
-        throw new Error(`Provider '${providerId}' is disabled`);
+        throw new PaseoToolInputError(`Provider '${providerId}' is disabled`);
       }
       if (entry.status !== "ready") {
-        throw new Error(entry.error ?? `Provider '${providerId}' is unavailable`);
+        throw new PaseoToolInputError(entry.error ?? `Provider '${providerId}' is unavailable`);
       }
       const selectedModel = settings?.model ?? resolvedProviderModel.model;
       const features = await agentManager.listDraftFeatures({

packages/server/src/server/agent/tools/types.ts

@@ -1,6 +1,18 @@
 import type { z } from "zod";
 import type { ProviderPaseoToolsPolicy } from "@getpaseo/protocol/provider-config";
 
+export class PaseoToolInputError extends Error {
+  readonly status = 400;
+
+  constructor(
+    message: string,
+    readonly issues?: z.ZodError["issues"],
+  ) {
+    super(message);
+    this.name = "PaseoToolInputError";
+  }
+}
+
 export interface PaseoToolExecutionContext {
   signal?: AbortSignal;
   sendUpdate?: (update: PaseoToolResult) => void;

packages/server/src/server/daemon-e2e/claude-settings-mid-turn.real.e2e.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import pino from "pino";
+import { ClaudeAgentClient } from "../agent/providers/claude/agent.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+import { DaemonClient } from "../test-utils/daemon-client.js";
+
+test("changing thinking then mode preserves a foreground Claude command", async () => {
+  const logger = pino({ level: "silent" });
+  const cwd = await mkdtemp(path.join(tmpdir(), "claude-settings-mid-turn-"));
+  const daemon = await createTestPaseoDaemon({
+    logger,
+    agentClients: { claude: new ClaudeAgentClient({ logger }) },
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const agent = await client.createAgent({
+      provider: "claude",
+      model: "claude-haiku-5-5",
+      modeId: "auto",
+      thinkingOptionId: "low",
+      cwd,
+    });
+    await client.subscribeAgentTimeline(agent.id, () => {}).ready;
+    await client.sendMessage(
+      agent.id,
+      "Run exactly these three Bash commands in the foreground, one per tool call, in order: python3 -c \"from pathlib import Path; import time; Path('started').write_text('started'); time.sleep(20); print(1)\", then the same with print(2), then print(3). Then reply DONE.",
+    );
+    // A tool-call row is emitted before Claude's permission check finishes.
+    // Wait for the command itself, so changing to acceptEdits cannot gate its start.
+    await expect.poll(() => existsSync(path.join(cwd, "started")), { timeout: 90_000 }).toBe(true);
+    const notice = await client.setAgentThinkingOption(agent.id, "medium");
+    expect(notice).toEqual({ type: "warning", message: "Thinking level applies next turn" });
+    await client.setAgentMode(agent.id, "acceptEdits");
+    await expect
+      .poll(
+        async () => {
+          const timeline = await client.fetchAgentTimeline(agent.id, { limit: 100 });
+          return timeline.entries.some(
+            ({ item }) =>
+              item.type === "tool_call" &&
+              item.detail.type === "shell" &&
+              item.detail.command.includes("print(1)") &&
+              item.status === "completed",
+          );
+        },
+        { timeout: 45_000, interval: 100 },
+      )
+      .toBe(true);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 180_000);

packages/server/src/server/daemon-e2e/omp.real.e2e.test.ts

@@ -5,6 +5,8 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 import pino from "pino";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { afterEach, beforeAll, describe, expect, test } from "vitest";
 
 import type { AgentTimelineItem } from "../agent/agent-sdk-types.js";
@@ -131,6 +133,14 @@ async function timeline(client: DaemonClient, agentId: string): Promise<AgentTim
   return result.entries.map((entry) => entry.item);
 }
 
+async function readAssistantText(harness: Harness, agentId: string): Promise<string> {
+  const items = await timeline(harness.client, agentId);
+  return items
+    .filter((item) => item.type === "assistant_message")
+    .map((item) => item.text)
+    .join("");
+}
+
 function compactionFiller(records = 1200): string {
   const teas = ["assam", "darjeeling", "sencha", "oolong"];
   return Array.from(
@@ -257,8 +267,80 @@ async function contextWindowUsedTokens(client: DaemonClient, agentId: string) {
 
 describe("daemon E2E (real OMP)", () => {
   test(
-    "a prompt OMP rejects before its agent runs fails the turn with OMP's error",
+    "an idle out-of-band follow-up starts a turn",
     async () => {
+      const harness = await createHarness();
+      try {
+        const agent = await createAgent(harness, "idle-follow-up");
+        await harness.client.sendMessage(agent.id, "/follow-up Reply exactly IDLE_FOLLOWUP_OK");
+        await expect
+          .poll(() => readAssistantText(harness, agent.id), { timeout: 30_000 })
+          .toContain("IDLE_FOLLOWUP_OK");
+        const finish = await harness.client.waitForFinish(agent.id, TIMEOUT_MS);
+        expect(finish.status).toBe("idle");
+      } finally {
+        await closeHarness(harness);
+      }
+    },
+    TIMEOUT_MS,
+  );
+
+  test(
+    "an agent-sent idle follow-up starts a turn and notifies its parent",
+    async () => {
+      const harness = await createHarness();
+      const mcp = new Client({ name: "idle-follow-up-test", version: "1.0.0" });
+      try {
+        const parent = await createAgent(harness, "follow-up-parent");
+        const child = await createAgent(harness, "follow-up-child");
+        await mcp.connect(
+          new StreamableHTTPClientTransport(
+            new URL(
+              `http://127.0.0.1:${harness.daemon.port}/mcp/agents?callerAgentId=${parent.id}`,
+            ),
+          ),
+        );
+        const response = await mcp.callTool({
+          name: "send_agent_prompt",
+          arguments: { agentId: child.id, prompt: "/follow-up Reply exactly MCP_IDLE_FOLLOWUP_OK" },
+        });
+        expect(response.isError).not.toBe(true);
+        expect(response.structuredContent).toMatchObject({
+          success: true,
+          disposition: "out_of_band",
+        });
+        await expect
+          .poll(() => readAssistantText(harness, child.id), { timeout: 30_000 })
+          .toContain("MCP_IDLE_FOLLOWUP_OK");
+        await expect
+          .poll(
+            async () => {
+              const items = await timeline(harness.client, parent.id);
+              let notifications = 0;
+              for (const item of items) {
+                if (
+                  item.type === "tool_call" &&
+                  item.agentMessage?.sender.id === child.id &&
+                  item.agentMessage.event === "finished"
+                )
+                  notifications++;
+              }
+              return notifications;
+            },
+            { timeout: 15_000 },
+          )
+          .toBe(1);
+      } finally {
+        await mcp.close();
+        await closeHarness(harness);
+      }
+    },
+    TIMEOUT_MS,
+  );
+
+  test.each(["Reply with ok.", "/follow-up Reply with ok."])(
+    "a rejected %s fails the turn with OMP's error",
+    async (prompt) => {
       const harness = await createHarness({ ompHome: createOfflineOmpHome() });
       try {
         const agent = await harness.client.createAgent({
@@ -268,7 +350,7 @@ describe("daemon E2E (real OMP)", () => {
           model: "anthropic/claude-haiku-4-5",
           modeId: "full",
         });
-        await harness.client.sendMessage(agent.id, "Reply with ok.");
+        await harness.client.sendMessage(agent.id, prompt);
         const finish = await harness.client.waitForFinish(agent.id, 60_000);
         expect(finish.status).toBe("error");
         expect(finish.error).toContain("No API key found for anthropic");

packages/server/src/server/schedule/service.ts

@@ -38,6 +38,20 @@ export class ScheduleTargetGoneError extends Error {
   }
 }
 
+export class ScheduleNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Schedule not found: ${id}`);
+    this.name = "ScheduleNotFoundError";
+  }
+}
+
+export class ScheduleStateConflictError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScheduleStateConflictError";
+  }
+}
+
 function advanceNextRunAtPast(
   cadence: StoredSchedule["cadence"],
   nextRunAt: Date,
@@ -158,7 +172,7 @@ function shouldCompleteSchedule(schedule: StoredSchedule, now: Date): boolean {
 
 function requireSchedule(schedule: StoredSchedule | null, id: string): StoredSchedule {
   if (!schedule) {
-    throw new Error(`Schedule not found: ${id}`);
+    throw new ScheduleNotFoundError(id);
   }
   return schedule;
 }
@@ -392,10 +406,7 @@ export class ScheduleService {
 
   async inspect(id: string): Promise<StoredSchedule> {
     const schedule = await this.store.get(id);
-    if (!schedule) {
-      throw new Error(`Schedule not found: ${id}`);
-    }
-    return schedule;
+    return requireSchedule(schedule, id);
   }
 
   async logs(id: string): Promise<ScheduleRun[]> {
@@ -406,7 +417,7 @@ export class ScheduleService {
   async pause(id: string): Promise<StoredSchedule> {
     const paused = await this.store.update(id, (schedule) => {
       if (schedule.status === "completed") {
-        throw new Error(`Schedule ${id} is already completed`);
+        throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
       }
       if (schedule.status === "paused") {
         return schedule;
@@ -426,7 +437,7 @@ export class ScheduleService {
   async resume(id: string): Promise<StoredSchedule> {
     const resumed = await this.store.update(id, (schedule) => {
       if (schedule.status === "completed") {
-        throw new Error(`Schedule ${id} is already completed`);
+        throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
       }
       if (schedule.status === "active") {
         return schedule;
@@ -546,10 +557,10 @@ export class ScheduleService {
   async runOnce(id: string): Promise<StoredSchedule> {
     const schedule = await this.inspect(id);
     if (schedule.status === "completed") {
-      throw new Error(`Schedule ${id} is already completed`);
+      throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
     }
     if (this.runningScheduleIds.has(id)) {
-      throw new Error(`Schedule ${id} is already running`);
+      throw new ScheduleStateConflictError(`Schedule ${id} is already running`);
     }
     await this.runSchedule(schedule, this.now(), { manual: true });
     return this.inspect(id);

packages/server/src/server/test-utils/question-response-daemon.ts

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import {
+  MockLoadTestAgentClient,
+  MockLoadTestAgentSession,
+} from "../agent/providers/mock-load-test-agent.js";
+import { createTestPaseoDaemon } from "./paseo-daemon.js";
+
+const firstResponse = Promise.withResolvers<void>();
+
+class RetryQuestionSession extends MockLoadTestAgentSession {
+  private attempts = 0;
+
+  override async respondToPermission(
+    requestId: string,
+    response: Parameters<MockLoadTestAgentSession["respondToPermission"]>[1],
+  ) {
+    this.attempts += 1;
+    process.send?.({ type: "attempt", requestId, response, sessionId: this.id });
+    if (this.attempts === 1) {
+      await firstResponse.promise;
+      throw new Error("Synthetic question response failure");
+    }
+    return super.respondToPermission(requestId, response);
+  }
+}
+
+class RetryQuestionClient extends MockLoadTestAgentClient {
+  override async createSession(config: Parameters<MockLoadTestAgentClient["createSession"]>[0]) {
+    const session = new RetryQuestionSession({ config, sessionId: randomUUID() });
+    session.subscribe((event) => {
+      if (event.type === "permission_resolved") {
+        process.send?.({
+          type: "resolved",
+          requestId: event.requestId,
+          response: event.resolution,
+          sessionId: session.id,
+          pendingRequestIds: session.getPendingPermissions().map((request) => request.id),
+        });
+      }
+    });
+    return session;
+  }
+}
+
+async function main(): Promise<void> {
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { mock: new RetryQuestionClient() },
+    isDev: true,
+    mcpEnabled: false,
+    corsAllowedOrigins: [`http://localhost:${process.env.E2E_METRO_PORT}`],
+  });
+  process.on("message", (message: unknown) => {
+    if (message === "release") firstResponse.resolve();
+  });
+  const shutdown = async () => {
+    firstResponse.resolve();
+    await daemon.close();
+    process.exit(0);
+  };
+  process.once("SIGINT", () => void shutdown());
+  process.once("SIGTERM", () => void shutdown());
+  process.once("disconnect", () => void shutdown());
+  process.send?.({ type: "ready", port: daemon.port, serverId: daemon.daemon.getServerId() });
+}
+
+void main().catch((error: unknown) => {
+  process.send?.({ type: "error", error: error instanceof Error ? error.message : String(error) });
+  process.exit(1);
+});

packages/website/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "private": true,
   "type": "module",
   "scripts": {

plugins/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.11.2",
+  "version": "0.12.0-beta.1",
   "private": true,
   "type": "module",
   "scripts": {

scripts/ci-workflow.test.mjs

@@ -37,7 +37,7 @@ function jobBlocks(source) {
   let currentJob;
 
   for (const line of source.split("\n")) {
-    const jobMatch = /^  ([a-z0-9-]+):\s*$/.exec(line);
+    const jobMatch = /^  ([a-z0-9_-]+):\s*$/.exec(line);
     if (jobMatch) {
       currentJob = jobMatch[1];
       jobs.set(currentJob, []);
@@ -303,3 +303,31 @@ test("desktop packaging smokes main pushes and only the pull requests that touch
     assert.match(source, new RegExp(`${action}@[0-9a-f]{40} # v\\d+\\.\\d+\\.\\d+`));
   }
 });
+
+test("stable iOS releases upload once and distribute to external testers before App Store review", () => {
+  const source = readFileSync(
+    new URL("packages/app/.eas/workflows/release-mobile.yml", repoRoot),
+    "utf8",
+  );
+  const jobs = jobBlocks(source);
+  const uploads = [...jobs.entries()].filter(
+    ([, lines]) =>
+      lines.some((line) => /^    type: (submit|testflight)$/.test(line)) &&
+      lines.some((line) => line.includes("needs.build_ios.outputs.build_id")),
+  );
+  assert.equal(uploads.length, 1, "the iOS binary must be uploaded exactly once");
+  const [distributionId, distributionLines] = uploads[0];
+  const distribution = distributionLines.join("\n");
+  assert.match(distribution, /^    type: testflight$/m);
+  assert.match(distribution, /external_groups:\s*\n\s+- Paseo Beta/);
+  assert.match(distribution, /^      submit_beta_review: true$/m);
+
+  const review = jobs.get("submit_ios_for_review").join("\n");
+  assert.match(review, new RegExp(`needs: \\[build_ios, ${distributionId}\\]`));
+  assert.match(review, /APP_VERSION="\$\{\{ needs\.build_ios\.outputs\.app_version \}\}"/);
+  assert.match(
+    review,
+    /APP_BUILD_VERSION="\$\{\{ needs\.build_ios\.outputs\.app_build_version \}\}"/,
+  );
+  assert.match(review, /bundle exec fastlane ios submit_review/);
+});

skills/paseo/SKILL.md

@@ -21,7 +21,7 @@ For a local daemon, `project create` defaults to the current directory and resol
 
 ## Workspaces
 
-**`create_workspace`** — create a workspace independently of any agent. Required: `isolation` (`local` or `worktree`). Worktree isolation supports `mode: "branch-off" | "checkout-branch" | "checkout-pr"`: use `branchName`/`baseBranch` for a new branch, `branch` for an existing branch, or `prNumber` plus optional `forge`/`projectPath` for a change request. `worktreeSlug` controls the managed path. Returns the workspace descriptor centered on `workspaceId`.
+**`create_workspace`** — create a workspace independently of any agent. Required: `isolation` (`local` or `worktree`). Worktree isolation supports `mode: "branch-off" | "checkout-branch" | "checkout-pr"`: use `branchName`/`baseBranch` for a new branch, `branch` for an existing branch, or `prNumber` plus optional `forge` for a change request. Use `path` for a local directory or source checkout and `projectId` for the owning project; when no path is supplied, a worktree may resolve its source from `projectId`. `worktreeSlug` controls the managed path. Returns the workspace descriptor centered on `workspaceId`.
 
 `background: true` hides a workspace from default lists and the sidebar while its contents remain durable and accessible; omit `background` to inherit your current workspace’s value (false without a caller), and override it only when the user explicitly asks.