one-code-extension 0.3.0 → 0.4.0

package/docs/guide/skills-plugins-and-mcp.md

@@ -1,5 +1,7 @@
 # Skills, plugins, and MCP
 
+[← One Code user guide](README.md)
+
 One Code runs Agent Skills, Claude Code plugins, and MCP servers from your
 existing configuration. This page covers using each and the panels that
 manage them.
@@ -23,7 +25,7 @@ command, as in Claude Code: `/simplify`, `/code-review`, or any skill from
 arguments. Plugin skills keep their plugin prefix and are run as
 `/skill:<plugin>:<name>`. pi's `/skill:<name>` form works for every skill.
 
-A skill's slash command is not created when the name is already taken by a
+A skill's slash command isn't created when the name is already taken by a
 built-in command, a `.claude/commands/` template, or another skill.
 
 ### Manage skills
@@ -57,7 +59,7 @@ A skill of the same name in your own `.claude/skills/` takes precedence.
 ### Skills not bundled
 
 The bundle omits the Claude Code skills that depend on services One Code
-does not have:
+doesn't have:
 
 | Group | Skills omitted |
 |---|---|
@@ -113,7 +115,7 @@ servers, agents, and hooks load on the next session, and the panel says so
 when you close it.
 
 Marketplace sources are git repositories and local paths. Version pinning,
-npm or pip sources, and dependency resolution are not implemented.
+npm or pip sources, and dependency resolution aren't implemented.
 
 ## MCP servers
 
@@ -144,7 +146,7 @@ appears as disabled in `/mcp`; choosing Enable there approves it.
 Claude Code's `enabledMcpjsonServers`, `disabledMcpjsonServers`, and
 `enableAllProjectMcpServers` settings are honored from
 `~/.claude/settings.json`, and from `.claude/settings.local.json` when that
-file is not tracked by git. They are never honored from a checked-in
+file isn't tracked by git. They are never honored from a checked-in
 `.claude/settings.json`, which would let a repository approve its own
 servers.
 
@@ -154,7 +156,7 @@ stderr.
 ### Use MCP tools
 
 Each server's tools appear to the model as `mcp__<server>__<tool>` and load
-on demand, so a server with many tools does not bloat the prompt. Servers
+on demand, so a server with many tools doesn't bloat the prompt. Servers
 also expose resources, which the model can list and read.
 
 A permission rule naming `mcp__<server>` covers every tool of that server.

package/docs/guide/subagents-and-workflows.md

@@ -1,5 +1,7 @@
 # Subagents and workflows
 
+[← One Code user guide](README.md)
+
 One Code delegates work in two ways: subagents for tasks that deserve their
 own context window, and `ultracode` workflows for fanning a large job out
 across many agents at once.
@@ -33,7 +35,7 @@ the `explore` agent". What happens next:
 - **The run starts in the background.** The model receives a task id at
   once and keeps working. The subagent's report arrives as a notification
   when it finishes, mid-turn if the model is still busy, or as a new turn
-  if it is idle. In a `-p` or `--mode json` run, the subagent runs to
+  if it's idle. In a `-p` or `--mode json` run, the subagent runs to
   completion instead and the report is returned inline.
 - **You can keep talking to the model** while agents run.
 - **Subagents go through your permission gate.** A subagent's tool calls
@@ -47,14 +49,14 @@ the `explore` agent". What happens next:
 Two options change how a subagent runs:
 
 - **Fork.** A forked subagent inherits the whole conversation so far, for a
-  task that needs everything you have built up. Forks run on the main
+  task that needs everything you've built up. Forks run on the main
   model and can only be started from the main conversation. Depth is
   limited: the main conversation can start a subagent, and that subagent
   one more, but no further.
 - **Worktree isolation.** The subagent gets its own git worktree, branched
   from `HEAD`, so it can edit files without colliding with your working
   tree or other agents. A worktree the agent left unchanged is removed;
-  otherwise it is kept and its path reported.
+  otherwise it's kept and its path reported.
 
 ### Choose the subagent model
 
@@ -90,7 +92,7 @@ agent.
 ### Follow agents live
 
 While agents run, the panel below the editor shows a tree: `main` first,
-then each agent with its type, what it is doing right now ("Reading
+then each agent with its type, what it's doing right now ("Reading
 src/index.ts", "Running a command"), its elapsed time, and its token count.
 Nested agents appear under their parent. A finished agent stays for a few
 seconds.
@@ -125,23 +127,23 @@ JavaScript script that fans the work out across many agents in parallel,
 then runs it with the `workflow` tool.
 
 The keyword arms the turn it appears in. A message you queue while the
-model is still working does not arm the next turn. For a longer stretch of
+model is still working doesn't arm the next turn. For a longer stretch of
 this kind of work, turn the mode on with `/effort ultracode`: it sets the
 reasoning effort to `xhigh` and keeps workflow orchestration armed until
-you change the effort again. The footer shows `✦ ultracode` while it is
+you change the effort again. The footer shows `✦ ultracode` while it's
 armed.
 
 ### How a workflow runs
 
-- The script runs in a separate thread, so a runaway script cannot freeze
+- The script runs in a separate thread, so a runaway script can't freeze
   the interface. A script that stops making progress is stopped after a
   few seconds; a run is capped at 30 minutes.
 - The run goes to the background and the model gets a run id. Progress
   shows in a strip below the editor (**↓** to focus it, **Enter** to open,
   **x** to stop) and in `/workflows`.
 - Every completed agent call is journaled. Re-running a workflow with
-  `resumeFromRunId` replays the calls whose inputs did not change at no
-  cost and runs only what differs. A background run does not survive the
+  `resumeFromRunId` replays the calls whose inputs didn't change at no
+  cost and runs only what differs. A background run doesn't survive the
   end of a session, but its journal does.
 - A script can carry an output-token target. Once the target is reached,
   new and queued agent calls stop; agents already running finish and can
@@ -183,11 +185,11 @@ the current run's script there.
 `/effort` sets how much reasoning the model spends: `off`, `minimal`,
 `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode`. A bare `/effort`
 opens a slider (**←** and **→** or **h** and **l** move, **Enter** confirms).
-Levels the current model does not support are skipped. **shift+tab** cycles
+Levels the current model doesn't support are skipped. **shift+tab** cycles
 the plain levels; cycling away from `xhigh` while ultracode is armed turns
 ultracode off.
 
 Changing the effort re-caches the conversation, so the next request costs
-more than usual. `/effort` does not save the level across restarts; to
+more than usual. `/effort` doesn't save the level across restarts; to
 save one, open pi's `/thinking` picker and press **ctrl+s**, or pass
 `--thinking <level>` at launch.

package/docs/guide/tasks-and-background-work.md

@@ -1,5 +1,7 @@
 # Tasks and background work
 
+[← One Code user guide](README.md)
+
 One Code keeps long-running work out of the model's way. This page covers
 the structured task list, background shells, monitors, scheduled
 wake-ups, and how the results of background work reach the model.
@@ -22,8 +24,8 @@ summary line and up to 12 tasks: `✔` for completed, `◼` for in progress,
 | `/tasks show` | Shows it again. |
 
 The list is stored inside the session, so it survives a resume and follows
-the branch you are on in `/tree`. If the model has not touched the list for
-a while during a long task, it is reminded that the list exists.
+the branch you're on in `/tree`. If the model hasn't touched the list for
+a while during a long task, it's reminded that the list exists.
 
 ## Background shells
 
@@ -55,14 +57,14 @@ session is told which ones.
 The `monitor` tool watches a long-running command, or a WebSocket URL, and
 turns each line of output (or each message) into an event. Events are
 batched and delivered to the model as notifications: at most once a second
-while the model is idle, once every ten seconds while it is working, so a
-noisy process does not flood the conversation.
+while the model is idle, once every ten seconds while it's working, so a
+noisy process doesn't flood the conversation.
 
 A monitor runs until its command exits or its timeout passes (five minutes
 by default, one hour at most), or for the whole session when started as
 persistent. The model can stop it with `task_stop`.
 
-A monitor is not auto-approved, because it runs a shell command; the
+A monitor isn't auto-approved, because it runs a shell command; the
 permission gate treats it like `bash`.
 
 ## Scheduled wake-ups and loops
@@ -77,7 +79,7 @@ permission gate treats it like `bash`.
 - **Self-paced.** `/loop watch the CI run` with no interval lets the model
   choose when to check next. It uses the `schedule_wakeup` tool, which
   schedules one wake-up at a time between one minute and one hour ahead.
-  The model is told to pick a delay that matches what it is waiting for,
+  The model is told to pick a delay that matches what it's waiting for,
   and to stop the loop when the task is done.
 
 `/loop status` (or a bare `/loop`) reports the current loop. `/loop stop`
@@ -100,7 +102,7 @@ Background work reports back through notifications:
   merged into one message.
 - After you interrupt a turn, notifications are held and attached to your
   next prompt instead of starting a turn on their own.
-- Each notification is framed as an automated event, so the model does not
+- Each notification is framed as an automated event, so the model doesn't
   mistake it for something you said or approved.
 
 ## Non-interactive runs
@@ -108,4 +110,4 @@ Background work reports back through notifications:
 In `-p` and `--mode json` runs nothing can run in the background, because
 the process exits when the turn settles. Background shells, monitors,
 subagents, and workflows run to completion and return their output
-directly. `/loop` and `schedule_wakeup` do not fire.
+directly. `/loop` and `schedule_wakeup` don't fire.

package/docs/guide/terminal-interface.md

@@ -1,5 +1,7 @@
 # The terminal interface
 
+[← One Code user guide](README.md)
+
 This page describes what you see on screen and how to move around it: the
 banner, the status line, the working indicator, the panels below the
 editor, the dialogs, and the themes.
@@ -14,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. |
@@ -70,8 +72,8 @@ Set `CC_FOOTER=0` to keep pi's footer.
 ## The panel below the editor
 
 One panel below the editor holds the background-shell manager and the
-live subagent tree. It appears when there is something to show and hides
-when there is not.
+live subagent tree. It appears when there's something to show and hides
+when there isn't.
 
 - Press **↓** from an empty editor to focus it. If background shells exist,
   the first **↓** lands on the shells chip; a second **↓** moves to the
@@ -85,7 +87,7 @@ when there is not.
   **Enter** closes the view.
 
 The panel's own footer names the keys that apply at each stage. Mouse-wheel
-scrolling is deliberately not enabled in the transcript view, because
+scrolling deliberately isn't enabled in the transcript view, because
 turning on mouse reporting would take over the terminal's native scrolling
 and text selection for the whole session.
 
@@ -132,7 +134,7 @@ and [Plan mode](permissions-modes-and-auto-mode.md#plan-mode).
 
 **ctrl+c** closes any panel.
 
-PgUp and PgDn do not reach these panels in full-screen mode, because pi uses
+PgUp and PgDn don't reach these panels in full-screen mode, because pi uses
 them for its own scrollback; use the keys the panel's footer names.
 
 ## Full-screen mode

package/docs/guide/tools.md

@@ -1,6 +1,8 @@
 # Tools
 
-The model works by calling tools. You do not type tool names; you describe
+[← One Code user guide](README.md)
+
+The model works by calling tools. You don't type tool names; you describe
 the task and the model chooses. This page lists every tool One Code gives
 the model, what each does, what you see when it runs, and how Claude Code's
 tool names map onto them.
@@ -51,11 +53,20 @@ 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:
 
 - A foreground command that starts with `sleep`, or a polling loop that
-  sleeps, when the wait is not provably short. The model is told to use
+  sleeps, when the wait isn't provably short. The model is told to use
   `run_in_background` or `monitor` instead.
 - A command that would orphan a process (`nohup`, `setsid`, or a trailing
   `&` with no `wait`).
@@ -131,17 +142,29 @@ deferred until needed. `list_mcp_resources`, `read_mcp_resource`, and
 
 `tool_search` loads deferred tools. The model passes exact names
 (`select:monitor,task_output`), a required term (`+notebook`), or free
-keywords. If the model calls a tool it has not loaded yet, the call fails
+keywords. If the model calls a tool it hasn't loaded yet, the call fails
 and the model is steered to `tool_search`.
 
 ## Behavior in non-interactive runs
 
 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
@@ -150,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

@@ -1,5 +1,7 @@
 # Troubleshooting
 
+[← One Code user guide](README.md)
+
 Symptoms you might hit, what causes them, and what to do.
 
 ## Start with the doctor
@@ -38,18 +40,18 @@ pins pi itself.
 pi it runs on are out of step. On the bundled app, reinstall it. On your own
 pi, run `pi update --extensions`.
 
-**The stock pi first-run wizard did not appear.** The bundled app seeds
+**The stock pi first-run wizard didn't appear.** The bundled app seeds
 pi's settings with the One Code theme, quiet startup, and full-screen mode
-on first run, so there is nothing to ask.
+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
@@ -57,7 +59,7 @@ check `/permissions`: an `ask` rule prompts in every mode.
 
 **An allow rule I wrote has no effect in auto mode.** Broad execution rules
 (`Bash(*)`, wildcarded interpreters, delegation rules) are suspended in
-auto mode so they cannot bypass the classifier. Session grants from the
+auto mode so they can't bypass the classifier. Session grants from the
 approval prompt are also ignored there. Narrow the rule or switch to
 accept-edits or manual mode.
 
@@ -66,7 +68,7 @@ may not select auto or bypass mode. Set it in `~/.claude/settings.json`
 or pass `--permission-mode auto`.
 
 **`defaultMode` in `~/.onecode/settings.json` does nothing.** The
-permission loader does not read that key from One Code's file. Use a Claude
+permission loader doesn't read that key from One Code's file. Use a Claude
 Code settings file or the flag.
 
 **The model is denied a write to `.claude/settings.json`.** The auto-mode
@@ -80,12 +82,12 @@ allow rules, or use auto mode with a provider that can run the classifier.
 ## Auto-mode classifier
 
 **Actions are blocked with a message about the classifier being
-unavailable.** The classifier model could not be reached or returned
+unavailable.** The classifier model couldn't be reached or returned
 nothing usable; the gate fails closed. Check `/auto-mode config` for the
 model in use, and `/doctor report` for provider credentials. Set
 `CC_AUTO_MODE_DEBUG=1` to see each verdict on stderr.
 
-**The classifier approves or blocks something it should not.** Choose a
+**The classifier approves or blocks something it shouldn't.** Choose a
 stronger classifier with `/auto-mode model <provider/model-id>`. A
 Haiku-class classifier is a measurably weaker boundary than a Sonnet-class
 one.
@@ -122,7 +124,7 @@ to a rate-limited endpoint. Set `BRAVE_SEARCH_API_KEY` or
 `/doctor report` for install hints.
 
 **TypeScript diagnostics fail with a message about `lib/tsserver.js`.**
-TypeScript 7's native compiler does not ship that file, and
+TypeScript 7's native compiler doesn't ship that file, and
 `typescript-language-server` needs it. Install a TypeScript 5.x development
 dependency in the project.
 
@@ -139,7 +141,7 @@ Authenticate. Tokens are stored under `~/.onecode/mcp-auth/`.
 
 ## Hooks
 
-**A project's hooks do not run.** They need one-time approval at startup.
+**A project's hooks don't run.** They need one-time approval at startup.
 Restart the session and accept, or check
 `~/.onecode/hooks/project-approvals.json`.
 
@@ -152,10 +154,10 @@ Restart the session and accept, or check
 **My background shells are gone after `/clear`.** Background work ends
 with the session. The new session lists what was stopped.
 
-**A resumed session is in a different permission mode.** Modes are not
+**A resumed session is in a different permission mode.** Modes aren't
 saved with the session. Pass `--permission-mode` or set a default.
 
-**The `/effort` level reset after a restart.** `/effort` does not save the
+**The `/effort` level reset after a restart.** `/effort` doesn't save the
 level. Open pi's `/thinking` picker and press **ctrl+s** to save a startup
 default, or pass `--thinking <level>` at launch.
 
@@ -169,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,184 @@
+# 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 Windows desktop (Windows Terminal, permission
+  prompts, plan mode) has not been checked by hand yet. 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. */