docs: full restricted-session policy for run-interactive-session adb-shell (KOB-54475, 1.10.1)

[TranKienCuong]

Problem

The run-interactive-session adb-shell guidance historically taught quoting the remote command so metacharacters run on-device:

kobiton device adb-shell "dumpsys window | grep mCurrentFocus"

On public cloud and trial devices the shell is restricted, and that form is rejected outright — the pipe and the quotes themselves are forbidden characters — with the rejection arriving on stdout at exit 0. An agent following the docs composes commands that can never work there, and can't tell the refusal from a result. 1.10.0 added basic restricted-shell notes (bare-command + local-filter); this PR replaces them with the complete policy.

Fixes #108. Covers the documentation half of #107 and the command-table half of #109 (the CLI --help and website halves are tracked separately).

Changes

• New "Restricted sessions" policy block in the adb-shell section: the forbidden-character set, command whitelist by category, file-path allowlist, the single permitted settings key, the four rejection message shapes with the exit-0 gotcha (incl. the settings-specific message — verified live on restricted test-env devices 2026-08-13 by the KOB-54475 contract spec), and a pointer to kobiton device adb-shell --help as the always-current authority.
• Quoting rules split by scope: the quoted form is scoped to unrestricted (dedicated) devices; restricted sessions get the working idiom — run the bare whitelisted command, redirect locally into the session artifact dir, filter locally.
• Command table gains a Restricted column covering every row: local-compose alternatives for the quoted-pipe rows, settings system rows marked rejected with the allowed secure enabled_accessibility_services row added, path-allowlist notes on cat/ls, the input text single-token limit, wm size → wd get window/rect, a new screencap row, and de-quoted logcat. 1.10.0's rows (Open-a-URL Android/iOS, iOS device log pointer) are preserved and annotated.
• device forward documented as a foreground command that holds the local port until killed (here and in references/response-shapes.md).
• references/response-shapes.md: the three rejection strings added to the existing exit-code gotcha so agents string-match refusals before trusting empty output.
• AGENTS.md carries the same facts for non-Claude hosts; .codex/ mirror regenerated via pnpm run build:codex.

Version 1.10.1 (docs-only release). pnpm run validate and all 193 tests green.

Rebase note

Rebased onto main after #114 (pinned CLI download). Two parts of the original branch were dropped as superseded:

• the bundled-binary refresh — the CLI is no longer committed to the repo; the pinned build the installer downloads is built from the same source and already carries the file-transfer status fix this branch originally bundled;
• the 1.9.1 version bump — renumbered to 1.10.1 on top of 1.10.0.

Release coordination

Hold until the deviceConnect sanitizer expansion reaches prod. Cleared 2026-08-13: all four expanded whitelist entries (cat /proc/version, screencap, input, the settings secure enabled_accessibility_services key) verified working on a prod restricted public device, with the quoted-pipe rejection and the settings-specific rejection message matching these docs verbatim. Prod deviceConnect carries the expanded policy; the docs are releasable as-is.

🤖 Generated with Claude Code