one-code-extension 0.3.1 → 0.4.1

package/docs/guide/installation.md

@@ -8,14 +8,17 @@ fits how you already work.
 | You | Install | What you get |
 |---|---|---|
 | New to this, or you want the simplest setup | `npm install -g @one-ai/one-code` | The bundled app: its own `onecode` command, a pinned version of the pi coding agent inside it, and its state kept in `~/.onecode`. It coexists with any `pi` you already have. |
+| On Windows without Node.js | `powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 \| iex"` | The bundled app, with Node.js fetched for you when the machine has none. See [Install on Windows](#install-on-windows). |
 | Already running [pi](https://github.com/earendil-works/pi) | `pi install npm:one-code-extension` | The extensions only. They run on your existing pi. One Code's own state still goes to `~/.onecode`; pi's own files stay under your pi agent directory (`~/.pi/agent`). |
 
 ## Requirements
 
 - Node.js 22.19 or later. The app refuses to start on older versions,
   because pi crashes at import time there.
-- macOS or Linux. Windows Subsystem for Linux (WSL) works the same way.
-  Native Windows is untested and unsupported.
+- macOS, Linux, or Windows. Windows Subsystem for Linux (WSL) works like
+  Linux. On native Windows, One Code takes Claude Code's shape: Git for
+  Windows is recommended but optional, and PowerShell is the primary shell
+  tool. See [Windows](windows.md) for what is verified and what isn't.
 - `git`. Optional: `rg` (ripgrep) for faster search, the GitHub CLI for the
   pull-request marker in the footer, and a language server for your
   language (see
@@ -38,6 +41,46 @@ The first run also seeds pi's settings under `~/.onecode/agent/` with the
 `onecode` theme, quiet startup, and full-screen mode. It never overrides a
 value you change later.
 
+## Install on Windows
+
+Open Windows Terminal or PowerShell and run:
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
+```
+
+The script looks for Node.js 22.19 or later on your PATH. When there is
+none, it downloads the current Node LTS for your CPU from nodejs.org as a
+zip, checks it against nodejs.org's published checksums, unpacks it under
+`%LOCALAPPDATA%\onecode\node`, and adds that folder to your user PATH.
+Nothing is installed system-wide and no Windows installer runs. It then
+runs `npm install -g @one-ai/one-code` and makes sure the `onecode` command
+is on your PATH. Open a new terminal afterwards so it sees the PATH change.
+
+The script also tells you when `git` is missing. One Code runs without it,
+but Git for Windows gives you the branch in the footer, `/init`, worktrees,
+and a bash tool for the model next to PowerShell. Install it with
+`winget install --id Git.Git -e`, or set `ONECODE_INSTALL_GIT=1` before
+running the script to have it do that for you.
+
+If you already have Node.js 22.19 or later, the plain npm command works the
+same on Windows as anywhere else:
+
+```powershell
+npm install -g @one-ai/one-code
+```
+
+The script's knobs are environment variables, because a piped script
+cannot take parameters: `ONECODE_INSTALL_NODE=1` downloads the standalone
+Node even when one exists, `ONECODE_NODE_VERSION` pins the version it
+downloads, and `ONECODE_NO_PATH_UPDATE=1` leaves your PATH alone and prints
+what to add. Read the script before running it if you like; it is the
+`install.ps1` at the root of the repository.
+
+Windows Subsystem for Linux (WSL) is Linux: use the npm or Homebrew route
+inside the distribution. For what works on native Windows, see
+[Windows](windows.md).
+
 ## Install with Homebrew
 
 Homebrew installs Node for you, so this route has no separate Node step:
@@ -59,7 +102,7 @@ pi install npm:one-code-extension
 ```
 
 Use `pi` in place of `onecode` for every command in this guide. The
-extension is tested against pi 0.83 through 0.85 and warns at startup when
+extension is tested against pi 0.83 through 0.86 and warns at startup when
 your pi is outside that range. Full-screen mode is opt-in on your own pi;
 see [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
 
@@ -102,7 +145,10 @@ npm install -g @one-ai/one-code      # npm installs
 brew upgrade onecode                 # Homebrew installs
 ```
 
-Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check; `--offline` skips it too.
+A Homebrew install sees the notice a day after the npm release, because
+Homebrew refuses packages younger than that and `brew upgrade` would find
+nothing sooner. Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check;
+`--offline` skips it too.
 On your own pi, update with `pi update --extensions`.
 
 Both packages are released together with the same version number.
@@ -114,8 +160,10 @@ npm uninstall -g @one-ai/one-code    # or: brew uninstall onecode
 rm -rf ~/.onecode                    # One Code's state, including pi's under the app
 ```
 
-On your own pi, run `pi remove one-code-extension` (or remove the package
-entry from pi's settings). Removing `~/.onecode` deletes One Code's
+If the Windows script fetched Node.js for you, delete `%LOCALAPPDATA%\onecode`
+too and remove that folder from your user PATH. On your own pi, run
+`pi remove one-code-extension` (or remove the package entry from pi's
+settings). Removing `~/.onecode` deletes One Code's
 settings, approvals, plan files, and, under the bundled app, pi's sessions
 and credentials. Memory files stay in `~/.claude/projects/`, because they
 are shared with Claude Code.

package/docs/guide/permissions-modes-and-auto-mode.md

@@ -83,6 +83,18 @@ contains command substitution (`$(…)` or backticks), `eval`, `exec`, a pipe
 into an interpreter, or a base64 decode is never covered by a prefix or
 wildcard `allow` rule.
 
+### PowerShell rule patterns
+
+`PowerShell(...)` rules have the same shape and follow Claude Code's
+PowerShell matching: aliases are canonicalized on both sides
+(`PowerShell(Remove-Item:*)` catches `rm`, `del`, and `ri`), cmdlet names
+are case-insensitive, a line is split on `|`, `;`, `&&`, `||`, and newlines
+outside quotes and here-strings, an `allow` rule must cover every statement,
+and a `deny` or `ask` rule fires on any statement. A `$(…)` subexpression, a
+backtick escape, a script block, the `&`/`.` call operators,
+`Invoke-Expression`, or an encoded command keeps a wildcard `allow` from
+applying. Details in [Windows](windows.md#permission-rules).
+
 ### Add a rule during a session
 
 To add an allow rule for the current repository, run:
@@ -120,10 +132,10 @@ stops risky ones, so you're not prompted for every step.
 The current badge appears in the banner and is announced when the mode
 changes.
 
-### Cycle modes with ctrl+q
+### Cycle modes with ctrl+q (alt+m on Windows and WSL)
 
-Press **ctrl+q** to cycle through manual, accept edits, plan, and auto.
-Two modes join the cycle only under certain conditions:
+Press **ctrl+q** to cycle through manual, accept edits, plan, and auto. On
+Windows and WSL the key is **alt+m**. Two modes join the cycle only under certain conditions:
 
 - **Auto** appears only when a model that can run the classifier is
   available. With no provider connected, the cycle skips it.
@@ -134,8 +146,9 @@ flag or a settings file.
 
 Claude Code cycles modes with shift+tab. One Code can't use that key
 because pi reserves it for the reasoning-effort dial. On Windows and WSL,
-pi's own default keybindings also use ctrl+q to queue a follow-up message.
-If the two conflict there, change pi's binding in its keybindings file.
+pi's own default keybindings use ctrl+q to queue a follow-up message, so
+One Code cycles modes with alt+m there instead. The footer badge and the
+startup hints name whichever key applies on your machine.
 
 ### Choose the starting mode
 
@@ -216,7 +229,10 @@ Reads and edits are confined to the working directory by default:
   mode, and is denied in don't-ask mode.
 - Accept-edits mode approves edits only inside the working directory.
 - The harness's own session directories count as inside: the auto-memory
-  folder, the session scratchpad, persisted tool output, and the plan file.
+  folder, the session scratchpad, persisted tool output, the plan file, and
+  this project's own session transcripts (with auto mode's decision log next
+  to them), which is what `/doctor` reads. Other projects' transcripts are
+  outside, as they are for Claude Code.
 
 Paths are compared after resolving symlinks, so a symlink inside the project
 that points outside it counts as outside.
@@ -287,7 +303,7 @@ code. Only read-only tools and edits to one plan file are available.
   `plan` agent, and then write the plan.
 - You can read and edit the plan file yourself while the model works.
 
-Enter plan mode by cycling to it with **ctrl+q**, by starting with
+Enter plan mode by cycling to it with **ctrl+q** (**alt+m** on Windows and WSL), by starting with
 `--permission-mode plan`, or by asking the model to plan first (it can call
 `enter_plan_mode` itself).
 

package/docs/guide/reference.md

@@ -49,7 +49,7 @@ that explains it.
 | `/loop status`, `/loop stop` | Report or end the loop. | |
 | `/tools-deferred` | List deferred tools and whether each is loaded. | [Tools](tools.md#eager-and-deferred-tools) |
 | `/init` | Have the model write a `CLAUDE.md` for the project. | [CLAUDE.md](bring-your-claude-code-setup.md#project-instructions-claudemd) |
-| `/clear` | Start a new session (pi's `/new`). | [Sessions](sessions-and-context.md#start-over) |
+| `/clear` | Start a new session (pi's `/new`); the model is told. | [Sessions](sessions-and-context.md#start-over) |
 | `/exit` | Quit (pi's `/quit`). | |
 
 ### pi commands
@@ -85,7 +85,7 @@ These come from pi and are available in every One Code session.
 
 | Shortcut | What it does |
 |---|---|
-| **ctrl+q** | Cycle the permission mode: manual, accept edits, plan, auto. |
+| **ctrl+q** (**alt+m** on Windows and WSL) | Cycle the permission mode: manual, accept edits, plan, auto. |
 | **↓** (empty editor) | Focus the panel below the editor: background shells, then subagents, then workflows. |
 | **ctrl+x** then **ctrl+k** | Stop every running agent (in the subagent panel). |
 | **x** | Stop the selected agent, shell, or workflow (in a panel). |
@@ -175,6 +175,7 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `CC_FOOTER=0` | Keep pi's footer instead of One Code's status line. |
 | `CC_TURN_DURATION=0` | Remove the post-turn timing line. |
 | `CC_RECAP=0` | Turn off the "while you were away" recap. |
+| `CC_SESSION_TITLE=0` | Turn off the automatic session title. |
 | `CC_RECAP_IDLE_MS` | Idle time before a recap, in milliseconds (default 300000). |
 | `CC_COMPACTION=0` | Use pi's compaction summary instead of Claude Code's. |
 | `CC_CLEAR_THINKING=0`, `=1` | Force the thinking-preservation request off or on for Anthropic models. Default: on for `api.anthropic.com` only. |
@@ -194,6 +195,8 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `PI_CACHE_RETENTION` | pi's prompt-cache lifetime. One Code sets `long` for interactive sessions unless you set it yourself. |
 | `PI_OFFLINE=1` | Same as `--offline`. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from. |
+| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | `1` turns the `powershell` tool on (the default on Windows), `0` turns it off. Off Windows it needs a `pwsh` on PATH. See [Windows](windows.md). |
+| `CLAUDE_CODE_GIT_BASH_PATH` | The bash that drives the `bash` tool, hooks, and background shells. Also read from the `env` block of `~/.claude/settings.json`; a non-bash binary is ignored with a warning. |
 | `CLAUDE_CODE_SUBAGENT_MODEL` | Default subagent model on a Claude session. |
 | `EDITOR`, `VISUAL` | Editor used by `/memory` (and pi's **ctrl+g**). |
 | `SHELL` | Shell used for commands (default `/bin/sh`). |

package/docs/guide/sessions-and-context.md

@@ -184,6 +184,24 @@ Not restored:
 `/new`. Running background tasks are stopped and listed. The permission
 mode you chose carries over.
 
+### What the model learns about your commands
+
+As in Claude Code, a slash command you run is recorded for the model: the
+next message you send carries a short note that the command ran, wrapped in a
+caveat telling the model not to act on it. `/clear` opens the new session
+with that note, and a model switch records "Set model to …" the way Claude
+Code does. Commands that One Code cannot observe (pi's own `/compact`,
+`/settings`, `/name`) leave no note.
+
+### The session title
+
+After your first real message, One Code names the session the way Claude
+Code does: a cheap model on your provider turns the message into a short
+title (Claude Code's own naming prompt), which shows in the terminal tab as
+`One Code - <title> - <folder>` and in the session picker. A name you set
+with `/name` is never overwritten. The call's cost is included in the
+footer's total. Set `CC_SESSION_TITLE=0` to turn it off.
+
 ## Turn timing
 
 After each turn, a dim line such as `✻ Cooked for 5m 12s` reports how long

package/docs/guide/terminal-interface.md

@@ -16,7 +16,7 @@ hint line lists the keys worth knowing:
 |---|---|
 | `/hotkeys` | pi's full key list. |
 | `shift+tab` | Cycle reasoning effort. |
-| `ctrl+q` | Cycle the permission mode. |
+| `ctrl+q` (`alt+m` on Windows and WSL) | Cycle the permission mode. |
 | `ctrl+t` | Show or hide thinking blocks. |
 | `ctrl+o` | Expand a collapsed tool output. |
 | `/` | List commands. |

package/docs/guide/tools.md

@@ -53,6 +53,15 @@ notification. A background shell shows up in the shells section of the
 panel below the editor. See
 [Tasks and background work](tasks-and-background-work.md).
 
+`powershell` is Claude Code's PowerShell tool: on by default on Windows,
+where it becomes the primary shell and `bash` (Git Bash) stays alongside
+when Git for Windows is installed; off elsewhere unless
+`CLAUDE_CODE_USE_POWERSHELL_TOOL=1` and a `pwsh` is on your PATH. It has the
+same `run_in_background`, the same background panel, and its description is
+Claude Code's own, with the edition section (PowerShell 7 or Windows
+PowerShell 5.1) picked from the executable found. Permission rules use
+Claude Code's `PowerShell(...)` form. See [Windows](windows.md).
+
 Some command shapes are refused before they run, with a message that steers
 the model to a better route:
 
@@ -140,10 +149,22 @@ and the model is steered to `tool_search`.
 
 In `-p` and `--mode json` runs the process exits when the turn settles, so
 nothing can run in the background. Tools that would detach work run to
-completion instead and return the output in their result: `bash` with
-`run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
+completion instead and return the output in their result: `bash` and
+`powershell` with `run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
 `schedule_wakeup` and `/loop` never fire in these modes.
 
+Give a scripted run its own deadline. One Code has no idle timeout on a
+provider response, so a stream that stalls mid-reply keeps the process
+waiting indefinitely. Wrap the call in your script:
+
+```bash
+timeout 180 onecode --mode json -p "…" </dev/null
+```
+
+The `</dev/null` matters too: in `-p` mode piped standard input is read as
+part of the prompt, so a run inside a shell script that reads its own body
+from stdin would hand the rest of the script to the model.
+
 ## Claude Code tool names
 
 Claude Code's tool names are accepted in permission rules and hook
@@ -152,6 +173,7 @@ matchers, and mapped to One Code's names. Case is ignored.
 | Claude Code | One Code |
 |---|---|
 | `Bash` | `bash` |
+| `PowerShell` | `powershell` |
 | `Read`, `Write`, `Edit` | `read`, `write`, `edit` |
 | `Grep`, `Glob`, `LS` | `grep`, `find`, `ls` |
 | `NotebookEdit` | `notebook_edit` |

package/docs/guide/troubleshooting.md

@@ -46,12 +46,12 @@ on first run, so there's nothing to ask.
 
 ## Permissions
 
-**Auto mode is missing from the ctrl+q cycle.** Auto mode needs a model to
+**Auto mode is missing from the mode cycle.** Auto mode needs a model to
 run its classifier. Connect a provider.
 
-**ctrl+q does something else.** On Windows and WSL, pi's default
-keybindings also bind ctrl+q, to queue a follow-up message. Rebind one of
-them in pi's keybindings file.
+**ctrl+q queues a follow-up instead of changing the mode.** On Windows and
+WSL that is pi's own binding for ctrl+q. The mode key there is alt+m; the
+footer badge names it.
 
 **Everything prompts, even in auto mode.** Auto mode pauses after several
 blocked actions in a row and prompts you once; approving resumes it. Also
@@ -171,6 +171,16 @@ for its scrollback. Use the keys the panel's footer names (**Space** and
 `CC_FOOTER=0`, or the other toggles listed in
 [Environment variables](reference.md#environment-variables).
 
+**On Windows the model has no shell tool, or the wrong one.** With Git for
+Windows installed you get `bash` plus `powershell`; without it, `powershell`
+alone. Set `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` to hide the PowerShell tool
+or `=1` to force it on (it also works on macOS and Linux with a `pwsh` on
+PATH). A startup warning names a `CLAUDE_CODE_GIT_BASH_PATH` that was
+ignored and why. If you report a Windows problem, include the shells on your
+PATH (`where bash`, `where pwsh`, `where powershell`), the value of those two
+variables, and whether the command came through `bash` or `powershell`.
+See [Windows](windows.md).
+
 ## Getting help
 
 Report problems at the project's GitHub repository. Include the output of

package/docs/guide/windows.md

@@ -0,0 +1,189 @@
+# Windows
+
+[← One Code user guide](README.md)
+
+One Code on native Windows works the way Claude Code does today: Git for
+Windows is optional, PowerShell is the primary shell tool when it is
+enabled, and the Windows-specific pieces of your Claude Code configuration
+keep working. This page says what that means in practice and what has and
+hasn't been verified.
+
+## Install
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
+```
+
+This fetches Node.js when the machine has none and installs the app; with
+Node.js 22.19 or later already present, `npm install -g @one-ai/one-code`
+does the same. Details, and the script's knobs, are in
+[Install on Windows](installation.md#install-on-windows). Git for Windows is
+optional; the section below says what it adds.
+
+## Two shell tools
+
+| Tool | When it is active | What runs it |
+|---|---|---|
+| `powershell` | On by default on Windows. Off elsewhere unless `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. | `pwsh.exe`, else `powershell.exe`, from your PATH. On macOS and Linux, a `pwsh` on PATH. |
+| `bash` | Whenever a bash exists. | Git Bash (`Program Files\Git\bin\bash.exe`, then `bash.exe` on PATH), or the bash named by `CLAUDE_CODE_GIT_BASH_PATH`. |
+
+When both are active, PowerShell is the primary shell: the system prompt says
+so and the model reaches for it first, with bash alongside for POSIX scripts.
+`CLAUDE_CODE_USE_POWERSHELL_TOOL=0` turns the PowerShell tool off and makes
+bash primary again, which is the shape Claude Code had before 2.1.126.
+
+A Windows machine with neither Git for Windows nor PowerShell has no shell
+tool. One Code says so at startup, in Claude Code's words, and the fix is to
+install one of them.
+
+`CLAUDE_CODE_GIT_BASH_PATH` is read from your environment or from the `env`
+block of `~/.claude/settings.json`. A value that isn't a `bash` or `sh`
+binary is ignored with a warning, as Claude Code does since 2.1.219.
+
+## The PowerShell tool
+
+The tool the model sees is Claude Code's PowerShell tool: same parameters
+(`command`, `timeout` in milliseconds, `description`, `run_in_background`)
+and Claude Code's own description text, including the edition section. One
+Code picks that section from the executable it found: PowerShell 7 guidance
+for `pwsh`, Windows PowerShell 5.1 guidance for `powershell.exe`. Under the
+hood it is pi's `powershell` tool, run with `-NoProfile -NonInteractive
+-ExecutionPolicy Bypass -Command`, output forced to UTF-8.
+
+`run_in_background` works like bash's: a task id comes back at once, output
+spools to the session directory, completion arrives as a notification, and
+the shell shows up in the panel below the editor. A foreground command that
+starts with `Start-Sleep` is refused with a pointer to background runs and
+the monitor tool, and `Read-Host`, `Get-Credential`, `Out-GridView`, `pause`
+and interactive git are refused because the shell has no console to prompt
+on.
+
+Inside a worktree session, every PowerShell command is prefixed with a
+`Set-Location` into the worktree, the way bash commands get a `cd`.
+
+## Permission rules
+
+`PowerShell(...)` rules use the same shape as `Bash(...)` rules and follow
+Claude Code's PowerShell matching:
+
+- Aliases are canonicalized on both sides, so `PowerShell(Remove-Item:*)`
+  catches `rm -Recurse build`, `del x`, and `ri y`, and
+  `PowerShell(Get-ChildItem:*)` allows `ls` and `dir`. Cmdlet names are
+  case-insensitive.
+- A command line is split on `|`, `;`, `&&`, `||`, and newlines, outside
+  quotes and here-strings. An `allow` rule has to cover every statement; a
+  `deny` or `ask` rule fires on any statement, including inside a nested
+  `pwsh -Command '…'`.
+- A line with a `$(…)` subexpression, a backtick escape, a script block, the
+  `&` or `.` call operators, `Invoke-Expression`, or an encoded command is
+  never covered by a wildcard or prefix allow rule. An exact rule for the
+  literal line still is.
+- Unbalanced quoting is a parse failure: no allow rule applies and you are
+  asked.
+
+Blanket rules (`PowerShell`, `PowerShell(*)`, `PowerShell(iex *)`,
+`PowerShell(Start-Process *)`) are suspended in auto mode like their bash
+counterparts. Hook matchers accept `PowerShell`, `Bash|PowerShell`, and
+`Bash,PowerShell`.
+
+## Auto mode and plan mode
+
+Claude Code's read-only cmdlets run without a prompt or a classifier call:
+`Get-ChildItem`, `Get-Content`, `Get-Item`, `Test-Path`, `Resolve-Path`,
+`Select-String`, `Get-Location`, `Get-Process`, `Get-Service`,
+`Get-FileHash`, `Get-Acl`, `Format-Hex`, `findstr`, `where.exe`, plus
+`Write-Output` and `Write-Host`. One Code adds the pure pipeline cmdlets
+those are usually piped through, `Select-Object`, `Sort-Object`,
+`Measure-Object`, `Group-Object`, `ConvertFrom-Json`, `Out-String` and the
+`Format-*` family, so `Select-String … | Measure-Object` counts as read-only
+too; `Where-Object` and `ForEach-Object` do not, because they take script
+blocks. The check is textual and strict: no
+redirection, no variables, no script blocks, and every path inside the
+project or one of the harness's own session directories (auto-memory, the
+scratchpad, persisted tool output, this project's transcripts). A relative
+path is inside by construction; an absolute or drive-lettered path is
+resolved and checked, so `Select-String -Path C:\src\app\notes.md` runs
+unprompted while `Get-Content C:\Users\you\.ssh\id_rsa` does not. A UNC
+path, `~`, a registry or environment drive, or `..` always takes the
+ordinary route.
+
+Everything else goes to the auto-mode classifier. One Code has no PowerShell
+command parser yet, so unlike bash there is no deterministic shortcut for
+in-project deletes: a `Remove-Item` inside the repository is classified, not
+auto-approved. The safety floor still applies. Any PowerShell line that
+names a permission settings file (`.claude/settings.json`,
+`~/.onecode/settings.json`, `.claude.json`, managed settings) stops for you,
+whether it reads or writes.
+
+Plan mode allows the read-only cmdlets above and refuses the rest, as it
+does for bash.
+
+## Hooks
+
+Hooks run in bash where one exists and in PowerShell on a Windows machine
+without Git for Windows. A hook can pick its interpreter with Claude Code's
+`shell` field: `"shell": "powershell"` or `"shell": "bash"`. Timeouts kill
+the whole process tree through `taskkill /T` on Windows. See
+[Hooks](hooks.md#which-shell-runs-a-hook).
+
+## Keys
+
+pi binds a few of its own shortcuts differently on Windows and WSL, where
+alt+enter and ctrl+shift+letter do not reach the terminal reliably: queue a
+follow-up is ctrl+q instead of alt+enter, fork is ctrl+f, paste is alt+v,
+model selection is alt+p. Because ctrl+q is taken there, One Code cycles
+permission modes with **alt+m** on Windows and WSL (ctrl+q everywhere
+else). The footer badge, the startup hints, and `/doctor` name the key that
+applies on your machine. Everything else in the [terminal reference](reference.md)
+is the same.
+
+## Paths and state
+
+- One Code's state lives in `%USERPROFILE%\.onecode`; Claude Code's
+  configuration is read from `%USERPROFILE%\.claude` (or
+  `CLAUDE_CONFIG_DIR`).
+- The scratchpad directory is under `%TEMP%`.
+- The `Shell:` line in the system prompt is the basename of `SHELL`, else
+  `COMSPEC`, with `.exe` stripped, the value Claude Code prints.
+- Language servers installed with npm are `.cmd` shims on Windows
+  (`typescript-language-server.cmd`). One Code finds them on `PATH` and
+  starts them through `cmd.exe`, so a plugin's `.lsp.json` can name the
+  command the way it does elsewhere.
+- Auto mode's shell pre-gate and the worktree guards understand Git Bash's
+  path spellings inside a command line: `/c/Users/…` is `C:\Users\…`, and
+  `/tmp/…` is your temp directory, which Git for Windows mounts there. A
+  path rule with a wildcard is spelled with forward slashes
+  (`Read(C:/notes/**)` or `Read(//c/notes/**)`), because a backslash before
+  `*` is the escape character.
+
+## What is verified
+
+- The unit suite, including live PowerShell runs, passes on the
+  `windows-latest`, `macos-latest`, and `ubuntu-latest` GitHub runners.
+- A real model drives both shell tools on the `windows-latest` runner: the
+  bash tool under Git Bash and the PowerShell tool under PowerShell 7, each
+  running a command whose output has to come back in the tool result. This
+  runs as its own workflow whenever the shell-facing code changes.
+- Drive-letter, backslash, `C:/` and `~` paths in `Read(...)`/`Edit(...)`
+  rules, Windows PowerShell 5.1 (edition text, UTF-8 output, no `&&`),
+  stopping background PowerShell commands and timed-out hooks, and
+  npm-installed language servers all have Windows-only unit tests that run
+  on that runner.
+- The PowerShell tool has also been driven through a real model with a
+  `pwsh` on macOS, the same way Claude Code's own PowerShell tool was
+  captured for reference.
+- An interactive session on a real Windows machine (a Windows Server 2025
+  VM, the same kernel as the CI runner): the interface in Windows Terminal,
+  `alt+m` mode cycling, a permission prompt, plan mode, the PowerShell tool's
+  rendering, a background PowerShell shell with its panel and notification,
+  diagnostics through an npm-installed language server, and both `/doctor`
+  surfaces, with Git for Windows present and with PowerShell alone. Windows
+  10 and 11 desktops have not had the same pass; if you hit something there,
+  [Troubleshooting](troubleshooting.md) says what to collect.
+
+## Not provided
+
+- No PowerShell command parser or pre-gate beyond the read-only list.
+- No sandbox on Windows. Claude Code has none there either.
+- `defaultShell` for the user's own `!` prefix is pi's to handle; One Code
+  does not read it.

package/extensions/auto-mode/actions.ts

@@ -17,6 +17,8 @@
  * path auto mode exists to close.
  */
 
+import type { HandBackVerdict } from "../lib/notifications.ts";
+
 export const SUBAGENT_ACTIONS_CHANNEL = "one-code:subagent-actions";
 
 export interface ChildAction {
@@ -45,7 +47,7 @@ export interface SubagentActionsPayload {
 	 * synchronously when no review will run, so the emitter never waits for
 	 * nothing.
 	 */
-	onReview?: (flag: string | undefined) => void;
+	onReview?: (verdict: HandBackVerdict | undefined) => void;
 }
 
 /** Per-action and total caps: a long-running child must not blow up the prompt. */

package/extensions/auto-mode/paths.ts

@@ -15,9 +15,9 @@
  *    and every caller treats that as "not provably contained".
  */
 
-import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { lstatSync, readlinkSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { expandTilde } from "../lib/paths.ts";
+import { comparablePath, expandTilde, gitBashPathToNative, isPathAtOrUnder, tryRealpath } from "../lib/paths.ts";
 
 /**
  * Tools whose calls write to a path. Lives here — the lowest shared layer both
@@ -41,23 +41,8 @@ export function pathArgument(input: Record<string, unknown> | undefined): string
 	return typeof path === "string" ? path : undefined;
 }
 
-/** Case-folded on darwin/win32, where the filesystem is case-insensitive. */
-function normalize(target: string): string {
-	const normalized = resolve(target).replace(/\\/g, "/").replace(/\/+$/, "");
-	return process.platform === "linux" ? normalized : normalized.toLowerCase();
-}
-
-function tryRealpath(target: string): string | undefined {
-	try {
-		return realpathSync.native(target);
-	} catch {
-		try {
-			return realpathSync(target);
-		} catch {
-			return undefined;
-		}
-	}
-}
+/** The shared comparison form (lib/paths.ts): `/` separators, case-folded on darwin/win32. */
+const normalize = comparablePath;
 
 /**
  * Resolve a path for containment checks, following a symlink leaf that does not
@@ -99,11 +84,9 @@ export function resolveForContainment(target: string): string | undefined {
 	}
 }
 
-/** True only when `target` is provably at or under `base`. */
+/** True only when `target` is provably at or under `base` (lib/paths.ts `isPathAtOrUnder`, argument order kept for the callers here). */
 export function isWithin(base: string, target: string): boolean {
-	const normalizedBase = normalize(base);
-	const normalizedTarget = normalize(target);
-	return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
+	return isPathAtOrUnder(target, base);
 }
 
 /**
@@ -119,3 +102,18 @@ export function toAbsolute(cwd: string, token: string, home: string): string {
 	if (isAbsolute(token)) return resolve(token);
 	return resolve(cwd, token);
 }
+
+/**
+ * {@link toAbsolute} for a token taken from a bash command line. On Windows the
+ * bash tool runs Git Bash, whose absolute paths are MSYS spellings — `/c/proj/f`
+ * is `C:\proj\f`, `/tmp/f` sits under the user's temp dir — so the token is
+ * converted first (lib/paths.ts gitBashPathToNative). `path.resolve` alone reads
+ * `/c/proj/f` as `<cwd drive>:\c\proj\f`, which no gate recognises as the
+ * project: the error fell towards escalate/prompt, never towards allow, but every
+ * in-project write spelled that way went to the classifier. File-tool paths keep
+ * `toAbsolute`: pi's read/edit/write resolve them natively, and a gate must
+ * judge the path the tool acts on, not the one Git Bash would reach.
+ */
+export function toAbsoluteBash(cwd: string, token: string, home: string): string {
+	return toAbsolute(cwd, gitBashPathToNative(token), home);
+}