one-code-extension 0.4.0 → 0.5.0

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

@@ -9,28 +9,39 @@ wake-ups, and how the results of background work reach the model.
 ## The task list
 
 For multi-step work the model keeps a structured task list, using the
-`task_create`, `task_get`, `task_list`, and `task_update` tools. Each task
+`task_create`, `task_get`, `task_list`, and `task_update` tools. Frontier
+models and Sonnet 5 or later run without them, as in Claude Code, unless you
+set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` ([Providers and
+models](providers-and-models.md#prompting-adapts-to-the-model)). Each task
 has a subject, a description, a status (pending, in progress, or
 completed), an optional owner, and dependencies on other tasks.
 
 While the list has entries, a pinned widget below the transcript shows a
 summary line and up to 12 tasks: `✔` for completed, `◼` for in progress,
-`◻` for pending.
+`◻` for pending. Once every task is completed, the list clears itself about
+five seconds later and the widget goes away. A new task starts a fresh list,
+and its numbering carries on from the old one.
 
-| Command | What it does |
+| Key | What it does |
 |---|---|
-| `/tasks` | Prints the full list. |
-| `/tasks hide` | Hides the widget. |
-| `/tasks show` | Shows it again. |
+| **alt+t** (**ctrl+\\** on macOS) | Hides the widget down to one line, or shows it again. |
+
+`/tasks` isn't about this list. As in Claude Code, it opens the background
+tasks: see [Talk to an agent](subagents-and-workflows.md#talk-to-an-agent).
 
 The list is stored inside the session, so it survives a resume and follows
-the branch you're on in `/tree`. If the model hasn't touched the list for
+the branch you're on in `/tree`. A list that was already finished comes back
+empty. If the model hasn't touched the list for
 a while during a long task, it's reminded that the list exists.
 
 ## Background shells
 
 When the model runs a command with `run_in_background`, the command starts
-detached and the model gets a task id at once. Output spools to a log file
+detached and the model gets a task id at once. A background command has no
+time limit: it runs until it exits or is stopped, even if the model passed a
+`timeout`, so a dev server started this way keeps running. (In a `-p` or
+`--mode json` run, the command runs in the foreground instead and stops at
+its timeout; see [Non-interactive runs](#non-interactive-runs).) Output spools to a log file
 under the session directory. When the command finishes, the model is
 notified with the result, and it can read the output at any time with
 `task_output` or stop the command with `task_stop`.
@@ -52,6 +63,16 @@ The turn-duration line reports how many shells are still running when a
 turn ends. When a session ends, running shells are stopped and the next
 session is told which ones.
 
+Background work belongs to the session. While a shell, monitor, background
+agent, or scheduled job is active, a line under the prompt counts them and
+reminds you that `/clear` or quitting stops them. Before `/clear`, `/new`,
+`/resume`, or a fork stops anything, One Code lists what's running and asks
+first. **Cancel** is the default (Esc does the same), so you can let the work
+finish or stop it from `/tasks` before switching. Quitting can't be paused,
+so the line under the prompt is the only warning you get there. A process
+that a finished shell left behind, such as a dev server started with `&`,
+keeps running until you quit.
+
 ## Monitors
 
 The `monitor` tool watches a long-running command, or a WebSocket URL, and
@@ -62,28 +83,75 @@ 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`.
+persistent. The model can stop it with `task_stop`. The whole stream is
+also written to a log file under the session directory, like a background
+shell's. When `task_output` has more than it can show, it returns the most
+recent part and names that file.
 
 A monitor isn't auto-approved, because it runs a shell command; the
 permission gate treats it like `bash`.
 
 ## Scheduled wake-ups and loops
 
-`/loop` runs a task repeatedly. Two forms exist:
-
-- **Fixed interval.** `/loop 5m check whether the deploy finished` runs the
-  task every five minutes. Intervals accept `s`, `m`, and `h`, and are
-  clamped between one minute and one hour. The first run happens
-  immediately. A tick that arrives while the model is still busy is
-  skipped, not queued.
+The model can schedule prompts for itself within a session. Ask it to
+"check CI every 10 minutes" or "remind me at 2:30pm to look at the deploy",
+and it calls `cron_create` with a five-field cron expression in your local
+time. A recurring job fires on every match. A one-shot job fires once and
+deletes itself. `cron_list` shows the session's jobs, and `cron_delete`
+cancels one. A session holds up to 50 jobs.
+
+A scheduled prompt fires only while the model is idle. A job that comes due
+during a turn waits for the turn to end, then fires once, however many
+times it matched in the meantime. Like Claude Code, the scheduler spreads
+jobs out with a fixed per-job delay: a recurring job fires up to half its
+period late (at most 30 minutes), and a one-shot set for :00 or :30 fires
+up to 90 seconds early. A prompt that's a slash command, such as
+`/babysit-prs`, runs that skill when it fires. When it fires, the transcript shows a dim
+`Running scheduled task` line and the model gets the prompt as its next
+input. Recurring jobs expire after seven days: they fire one last time and
+are deleted. Nothing is written to disk, so jobs end with the session;
+`/clear` asks before cancelling them, then tells you which ones it cancelled.
+
+`/loop` runs a task repeatedly. It's Claude Code's `/loop` skill: One Code
+hands your input to the model, and the model sets up the loop itself.
+
+- **Fixed interval.** `/loop 5m check whether the deploy finished`, or
+  `/loop check the deploy every 20m`, makes the model convert the interval
+  to a cron expression, create a recurring job with `cron_create`, confirm
+  it with the job id, and run the task right away. An interval that
+  doesn't divide its unit evenly is rounded, and the model says what it
+  rounded to.
 - **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'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`
-ends it. Only one loop runs at a time, and loops end with the session.
+  choose when to check next. It runs the task, then calls
+  `schedule_wakeup` with a delay between one minute and one hour. When
+  the wake-up fires, the same `/loop` input runs again. If the model ends a
+  turn without scheduling the next one, One Code schedules a 20-minute
+  fallback once; if that turn also schedules nothing, the loop ends. A
+  self-paced loop also ends after seven days.
+- **No prompt.** A bare `/loop` runs an autonomous check that keeps your
+  current work moving (CI, review threads, unfinished steps), self-paced.
+  `/loop 30m` runs the same check on a cron. If `.claude/loop.md` exists in
+  the project (or `~/.claude/loop.md`), its tasks replace the autonomous
+  check, and the model sees the file again whenever you edit it.
+
+When a self-paced tick finds nothing to do (the model reports `noop: true`),
+the next wake-up line counts the streak, for example `Resuming /loop wakeup
+(2:04pm) · 2 no-op ticks since 2:02pm`, and those quiet ticks leave the
+model's context, replaced by one line saying the loop is healthy. The ticks
+stay visible above in the terminal.
+
+A background subagent can schedule its own jobs with the same tools. It sees
+and cancels only its own, a job it made fires into that agent while it is
+still running, and the job is dropped once the agent has ended. The main
+session's `cron_list` shows every job. A subagent that runs until its task is
+done, such as one another subagent starts or any subagent in a `-p` run, can't
+schedule a job: nothing would be left to receive it, so its `cron_create`
+returns an error.
+
+To stop a loop, ask the model to stop it, as in Claude Code. It cancels the
+job with `cron_delete`, or ends a self-paced loop with `schedule_wakeup`.
+Several loops can run at once. Set `CLAUDE_CODE_LOOP_KEEPALIVE=0` to turn
+off the fallback wake-up.
 
 ## The background list
 
@@ -100,8 +168,12 @@ Background work reports back through notifications:
   batch of tool calls, or starts a new turn if the model is idle.
 - Notifications that arrive within a quarter of a second of each other are
   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.
+- After you interrupt a turn, or a turn ends on a provider error,
+  notifications are held instead of starting a turn on their own. The held
+  notifications ride your next prompt as one message, or go to the next turn
+  that starts some other way, such as a skill you type. A monitor keeps a
+  single batch while it waits. Scheduled prompts from `/loop` and
+  `cron_create` are not held: they keep firing on schedule.
 - Each notification is framed as an automated event, so the model doesn't
   mistake it for something you said or approved.
 
@@ -110,4 +182,7 @@ 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` don't fire.
+directly. A shell command run this way stops at its `timeout`, or after two
+minutes when the model gives none, and its result says why it stopped. `/loop`, `schedule_wakeup`, and scheduled prompts don't fire;
+`cron_create` still creates the job, and its result says the job can never
+fire.

package/docs/guide/terminal-interface.md

@@ -42,13 +42,22 @@ the result on an indented `⎿` line. Thinking is collapsed behind
 Set `CC_NO_INPUT_MARKER=1` or `CC_NO_ASSISTANT_MARKER=1` to remove either
 marker.
 
+When you type a slash command that takes an argument followed by a space, a
+dim placeholder after the cursor shows what goes there, as in Claude Code:
+`/loop ` shows `[interval] [prompt]`, and `/add-dir ` shows `<path>`. It
+disappears once you start typing the argument. Skills and custom commands
+get theirs from an `argument-hint` line in their frontmatter. A custom
+command that lists `arguments` instead shows the names you haven't typed
+yet, one space at a time.
+
 ## The working indicator
 
 While the model works, a spinner shows a random verb, the elapsed time, and
 the tokens streamed so far, for example `✳ Cogitating… (12s · ↓ 843 tokens)`.
 The clock runs from the start of the turn until it settles, through retries.
 
-After the turn, a dim `✻ Cooked for 5m 12s` line reports the total time.
+After the turn, a dim `✻ Cooked for 5m 12s · done 2:33 PM` line reports the
+total time and when the turn finished.
 Set `CC_TURN_DURATION=0` to turn it off.
 
 ## The status line
@@ -56,7 +65,9 @@ Set `CC_TURN_DURATION=0` to turn it off.
 The footer replaces pi's status line with One Code's own:
 
 - **Left:** the working directory, the git branch, and the open pull
-  request number for that branch when the GitHub CLI is installed.
+  request number for that branch when the GitHub CLI is installed. The pull
+  request is checked again every minute while you're using the session, so
+  one merged or closed mid-session drops off, and a new one appears.
 - **Right:** context usage as `used/window (percent)`, the session cost,
   the cache-hit rate of the latest turn, the model, and the reasoning
   effort. When ultracode is armed, the effort reads `✦ ultracode`.
@@ -78,13 +89,14 @@ 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
   subagent rows. Otherwise the first **↓** lands on the first subagent.
-- In the subagent rows, **↑** and **↓** select, **Enter** opens the
-  selected agent's live transcript, **x** stops it, **ctrl+x** then
-  **ctrl+k** stops every agent, and **Esc** leaves the panel. Typing any
-  other key returns to the editor.
-- Inside a transcript, **↑** and **↓** scroll, **PgUp** and **PgDn** page,
-  **Tab** switches to the next agent, **←** returns to the row list, and
-  **Enter** closes the view.
+- In the subagent rows, **↑** and **↓** select, **Enter** views the
+  selected agent (or `main`), **x** stops it, **ctrl+x** then **ctrl+k**
+  stops every agent, and **Esc** hands focus back to the editor. Typing
+  any other key does the same, with the key included.
+- While you view an agent, the editor talks to it: the border shows which
+  agent, and what you send goes to that agent instead of the main
+  conversation. **PgUp** and **PgDn** scroll its transcript, and **Esc** in
+  an empty editor takes you back to `main`.
 
 The panel's own footer names the keys that apply at each stage. Mouse-wheel
 scrolling deliberately isn't enabled in the transcript view, because
@@ -130,7 +142,7 @@ and [Plan mode](permissions-modes-and-auto-mode.md#plan-mode).
 | `/mcp` | The MCP server manager. | **↑↓** navigate, **Enter** open a server or run an action, a digit picks a numbered action, **Esc** back or close. |
 | `/doctor report` | The setup report. | **↑↓** or **j**/**k** scroll, **Space**/**b** page, **g**/**G** top and end, **f** run the checkup, **Esc** or **q** close. |
 | `/memory` | The instruction and memory file picker. | **↑↓** move, **Enter** open, **Esc** close. |
-| `/effort` | The reasoning-effort slider. | **←→** or **h**/**l** adjust, **Enter** confirm, **Esc** cancel. |
+| `/effort` | The reasoning-effort slider. | **←→** or **h**/**l** adjust, **Enter** confirm, **s** this session only, **Esc** cancel. |
 
 **ctrl+c** closes any panel.
 
@@ -140,8 +152,8 @@ them for its own scrollback; use the keys the panel's footer names.
 ## Full-screen mode
 
 The bundled app runs in pi's full-screen mode, on the terminal's alternate
-screen, and restores your terminal when you exit. On a plain pi
-installation full-screen mode is opt-in; see
+screen, and restores your terminal when you exit. pi 1.0 and later start
+in full-screen mode too; on an older pi it's opt-in. See
 [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
 
 ## Themes

package/docs/guide/tools.md

@@ -46,7 +46,9 @@ reported as deleted or moved.
 
 ## Shell
 
-`bash` runs a shell command. Its `run_in_background` option starts the
+`bash` runs a shell command. A command in the foreground stops after its
+`timeout` (in milliseconds, at most 600000), or after two minutes when the
+model gives none, as in Claude Code. Its `run_in_background` option starts the
 command detached and returns a task id; output spools to a log file under
 the session directory, and completion is reported to the model as a
 notification. A background shell shows up in the shells section of the
@@ -88,7 +90,7 @@ the model to a better route:
 |---|---|
 | `Agent` | Starts a subagent with its own context window. Runs in the background and returns a task id; the result arrives as a notification. Supports forking the current conversation and isolating the agent in a git worktree. |
 | `SendMessage` | Sends a message to an agent that was started earlier: a running one receives it live, a finished one is resumed from its saved session. Deferred. |
-| `list_agents` | Lists the agents started in this session and their status. Deferred. |
+| `list_agents` | Lists the agents started in this session and their status. |
 | `workflow` | Runs a JavaScript script that coordinates many agents. This is the `ultracode` mechanism. |
 
 See [Subagents and workflows](subagents-and-workflows.md).
@@ -101,6 +103,39 @@ See [Subagents and workflows](subagents-and-workflows.md).
 | `ask_user_question` | Asks you up to four structured questions in a tabbed dialog. See [The terminal interface](terminal-interface.md#the-question-dialog). |
 | `skill` | Runs a skill by name. See [Skills](skills-plugins-and-mcp.md#skills). |
 
+## Artifacts
+
+`artifact` saves a self-contained HTML page the model wrote (a report, a
+dashboard, a visual explainer, a small tool) and opens it in your default
+browser. Claude Code publishes these pages to claude.ai; One Code keeps them
+on your machine under `~/.onecode/artifacts/`, so nothing is uploaded.
+Before writing a page, the model loads the bundled `artifact-design` skill,
+which holds the page rules: a real title, light and dark themes, and a
+layout that works at phone width.
+
+The page opens under a slim bar. The home icon goes to the gallery, and
+**Download** saves the page as an HTML file. The title opens a menu with the
+version and update time, Download HTML, Copy file path, Reload, the page
+without the bar, the list of versions, and All artifacts. Claude Code's
+Share and Chat buttons are left out, since there is no server behind a local
+artifact.
+
+When the model publishes the same file again with changed contents, the
+artifact is updated in place as a new version, and every earlier version is
+kept. Publishing unchanged contents keeps the current version. Pick an earlier
+version from the title menu to view or download it. The browser tab does not
+reload by itself, so refresh it to see the update.
+
+`~/.onecode/artifacts/index.html` is a gallery of every artifact, newest
+first, with links to each earlier version and a Download button. Run `/artifacts` to pick one and open it, save a copy to
+`~/Downloads`, show its path, or delete it. To stop the browser opening on
+each new artifact, set `artifacts.autoOpen` to `false` (see
+[Settings reference](configuration.md#settings-reference)). Over SSH, or on
+a machine with no display, the model gives you the file path instead.
+
+Publishing passes through the permission gate like any other tool, and in
+plan mode it is refused. Deleting always asks you first. Deferred.
+
 ## Tasks and background work
 
 | Tool | What it does |
@@ -108,7 +143,8 @@ See [Subagents and workflows](subagents-and-workflows.md).
 | `task_create`, `task_get`, `task_list`, `task_update` | Maintain the structured task list shown in the pinned widget. Deferred. |
 | `monitor` | Watches a long-running command or a WebSocket and reports each output line as an event. Deferred. |
 | `task_output`, `task_stop` | Read the output of a background task or stop it. Deferred. |
-| `schedule_wakeup` | Schedules a prompt for later; the mechanism behind self-paced `/loop`. Deferred. |
+| `schedule_wakeup` | Schedules the next iteration of a self-paced `/loop`. The pending wake-up shows in `cron_list`. |
+| `cron_create`, `cron_list`, `cron_delete` | Schedule a prompt on a cron expression within the session, list the jobs, or cancel one. A fixed-interval `/loop` uses them. Deferred. |
 
 See [Tasks and background work](tasks-and-background-work.md).
 
@@ -150,8 +186,11 @@ 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` and
-`powershell` with `run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
-`schedule_wakeup` and `/loop` never fire in these modes.
+`powershell` with `run_in_background`, `Agent`, `monitor`, and `workflow`.
+A shell command run this way holds the run like a foreground command, so it
+stops at the same timeout, two minutes unless the model gives another, and
+the result says so. Timers such as
+`schedule_wakeup`, `cron_create`, 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
@@ -177,6 +216,7 @@ matchers, and mapped to One Code's names. Case is ignored.
 | `Read`, `Write`, `Edit` | `read`, `write`, `edit` |
 | `Grep`, `Glob`, `LS` | `grep`, `find`, `ls` |
 | `NotebookEdit` | `notebook_edit` |
+| `Artifact` | `artifact` |
 | `WebFetch`, `WebSearch` | `web_fetch`, `web_search` |
 | `Task`, `Agent` | `Agent` |
 | `SendMessage` | `SendMessage` |
@@ -190,6 +230,7 @@ matchers, and mapped to One Code's names. Case is ignored.
 | `TaskOutput`, `TaskStop` | `task_output`, `task_stop` |
 | `Monitor` | `monitor` |
 | `ScheduleWakeup` | `schedule_wakeup` |
+| `CronCreate`, `CronList`, `CronDelete` | `cron_create`, `cron_list`, `cron_delete` |
 | `EnterWorktree`, `ExitWorktree` | `enter_worktree`, `exit_worktree` |
 | `LSP` | `lsp_diagnostics` |
 | `ListMcpResourcesTool`, `ReadMcpResourceTool`, `ReadMcpResourceDirTool` | `list_mcp_resources`, `read_mcp_resource`, `read_mcp_resource_dir` |

package/docs/guide/troubleshooting.md

@@ -38,7 +38,8 @@ pins pi itself.
 
 **`Failed to load extension` on startup.** The extension package and the
 pi it runs on are out of step. On the bundled app, reinstall it. On your own
-pi, run `pi update --extensions`.
+pi, run `pi update npm:one-code-extension`, and update pi itself with
+`pi update` if it's older than 0.84.3.
 
 **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
@@ -87,10 +88,10 @@ 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 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.
+**The classifier approves or blocks something it shouldn't.** A cheap-tier
+classifier is a measurably weaker boundary than a workhorse- or
+frontier-tier one. Choose a stronger classifier with `/auto-mode model`, or
+a stronger main model.
 
 ## Models and providers
 
@@ -107,7 +108,8 @@ session is worth reporting.
 **A side call failed on a Gemini or OpenAI model with a message about
 reasoning or temperature.** Some models reject an option others accept.
 One Code avoids these options in its side calls; if you still see this,
-choose a different classifier or reader model and report the model.
+report the model and error. The reader model is selected automatically;
+`/auto-mode model` chooses the classifier.
 
 ## Web search
 
@@ -157,9 +159,11 @@ with the session. The new session lists what was stopped.
 **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` 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.
+**The `/effort` level reset after a restart.** `/effort` saves `low`,
+`medium`, `high` and `xhigh` for the model you're on, so a level set on a
+different model, a `max` or `ultracode` level, or one picked with **s**
+(this session only) doesn't come back. Set it again on this model, or pass
+`--thinking <level>` at launch.
 
 ## Interface
 

package/docs/guide/windows.md

@@ -59,7 +59,13 @@ 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`.
+`Set-Location` into the worktree, the way bash commands get a `cd`. The
+same git guard applies too: git that would reach your main checkout or
+another worktree (through `Set-Location`, `git -C`, `--git-dir`, or a
+`GIT_DIR` variable) is refused, and so is git inside a script block, a
+call operator or a nested shell, where the guard can't tell which
+repository it would touch. Plain `git` statements in the worktree run as
+usual.
 
 ## Permission rules
 
@@ -88,35 +94,52 @@ counterparts. Hook matchers accept `PowerShell`, `Bash|PowerShell`, and
 
 ## 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.
+One Code judges a PowerShell command the way PowerShell itself reads it. It
+keeps one PowerShell process running in the background and asks PowerShell's
+own parser what the command does: which commands it runs, how each argument
+binds to a parameter, and what every alias really points to on your machine.
+That process is the same PowerShell the tool runs, so the check and the
+command can't disagree about quotes, backticks, or a stray `–` dash. If the
+parser can't answer (it's still starting, it crashed, or your machine runs
+PowerShell in Constrained Language Mode), nothing gets a shortcut and the
+command takes the ordinary route.
+
+Read-only commands run without a prompt or a classifier call. These are
+Claude Code's read-only cmdlets, `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`, `Write-Output` and `Write-Host`, plus the pipeline cmdlets
+they're usually piped through: `Select-Object`, `Sort-Object`,
+`Measure-Object`, `Group-Object`, `ConvertFrom-Json`, `Out-String`,
+`Out-Null` and the `Format-*` family. `Where-Object` and `ForEach-Object`
+count too when their script block only reads `$_` and compares, like
+`Where-Object { $_.Length -gt 1kb }`. Each cmdlet is checked parameter by
+parameter, so `Get-Content -Wait` or `Get-ChildItem -FollowSymlink` doesn't
+qualify. Every path has to land inside the project or one of the harness's
+own session directories (auto-memory, the scratchpad, persisted tool output,
+this project's transcripts), judged where it resolves, so a symlink out of
+the project counts as outside. A UNC path, `~`, a registry or environment
+drive, a provider path, or `..` always takes the ordinary route. So does a
+cmdlet that takes paths from the pipeline, like `Get-Content list.txt |
+Get-Item`, because it reads whatever the list names.
+
+On a frontier or workhorse model in auto or acceptEdits mode, Claude Code's
+acceptEdits cmdlets skip the classifier too: `Set-Content`, `Add-Content`,
+`Remove-Item` and `Clear-Content` on paths inside the working directories.
+The same limits as the bash file commands apply. A wildcard target, a path
+outside, a credential or protected file, or removing the project root or a
+`.git` goes to the classifier. So does a recursive `Remove-Item` over a
+folder with a link inside, because Windows PowerShell 5.1 follows it.
+`New-Item`, `Copy-Item` and `Move-Item` are always classified, as Claude Code
+always asks about them. On cheaper models every write is classified.
+
+Everything else goes to the auto-mode classifier. 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 commands and refuses the rest, as it does for
+bash.
 
 ## Hooks
 
@@ -172,13 +195,22 @@ is the same.
 - 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.
+- 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 shortcut for most of PowerShell's native commands (`git`, `npm`, `rg`):
+  they always go to the classifier in auto mode, where the bash tool
+  fast-paths the read-only ones. Windows' own `findstr` and `where.exe` are
+  the exceptions: a read-only use inside the project runs without the
+  classifier, and plan mode allows it.
 - 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.