agent-policy-kit 0.4.0 → 0.5.1

package/AGENT_INSTALL.md

@@ -20,7 +20,7 @@ Obey these rules in every step:
 In the steps below, `agent-policy` means the pinned command for the requested release:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy
 ```
 
 ## Step 1: Select the release
@@ -30,7 +30,7 @@ The package version is the configuration release. Use the version that the owner
 1. Read the release notes:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy release --json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy release --json
    ```
 
 2. Read the entry for this version in [CHANGELOG.md](CHANGELOG.md): what changed, why, and the migration limits.
@@ -41,7 +41,7 @@ The package version is the configuration release. Use the version that the owner
 For several commands, you can install the package into a temporary or user-owned prefix:
 
 ```sh
-npm install --prefix PREFIX agent-policy-kit@0.4.0 --ignore-scripts --no-audit --no-fund
+npm install --prefix PREFIX agent-policy-kit@0.5.1 --ignore-scripts --no-audit --no-fund
 ```
 
 Then run `PREFIX/node_modules/.bin/agent-policy`. If the owner gives you a verified local `.tgz` file of a version that is not on npm, install that file in the same way. You need no sudo, no fixed prefix and no shell profile change.
@@ -51,7 +51,7 @@ More: [updates and removal](docs/guide/updates-and-removal.md), [presets](docs/r
 ## Step 2: Detect
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy detect --json
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy detect --json
 ```
 
 1. Read the status of each assistant: `detected`, `not_found`, `invalid` or `timeout`.
@@ -112,7 +112,7 @@ APK updates owned files in a transaction for each client, without a removal gap.
 1. Run `doctor`:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy doctor --json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy doctor --json
    ```
 
    Each client reports its saved release, source and preset from its receipt, independent of the version that runs `doctor`. `verified` means that the owned files match the receipt.
@@ -120,7 +120,7 @@ APK updates owned files in a transaction for each client, without a removal gap.
 2. Run `show` to read the current user-level subagent settings, including manual edits:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy show --json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy show --json
    ```
 
    `show` does not resolve project, managed or session settings. It exits with code 3 when a client needs attention, and it keeps the results of the other clients.
@@ -134,7 +134,7 @@ A verified configuration does not prove that a model runs. After verification, y
 1. Plan the removal:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall --json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall --json
    ```
 
 2. Review the plan.

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 Each npm version is one configuration release: its presets, native role definitions, instructions and configuration page. Published versions are not rewritten. Applying another release is explicit; package installation alone changes no settings.
 
+## 0.5.1 — 2026-11-01
+
+### Why this release
+
+The Grok Reviewer and Code explorer roles were not read-only (#30). Releases 0.4.0 and 0.5.0 wrote `permission_mode: plan` in their role files. Grok Build reads the fields of an agent file in camelCase, so it ignored this key without a warning, and the prompt was the only restriction. A role file template reaches your setup only through a new release.
+
+### Who should update
+
+- Anyone who uses Grok Build with APK and wants the Reviewer and the Code explorer to be read-only.
+- Other assistants get no configuration change. Their role files, presets and the model catalog are the same as in 0.5.0.
+
+### Migration and rollback
+
+Assistant IDs, preset ids, share-link format v2 and receipt format v4 are unchanged. `doctor` and `show` of 0.5.1 read installations and receipts from 0.4.0 and 0.5.0. Setup with 0.5.1 and `--release`, `--preset`, `--config` or explicit tool arguments replaces their Grok role files in place. A setup without these options reports `unchanged` and keeps the old role files. Setup with 0.5.0 or 0.4.0 moves Grok back in place and writes `permission_mode: plan` again. `uninstall` of 0.5.1 removes a 0.4.0, 0.5.0 or 0.5.1 installation. This was checked for Grok with the published 0.4.0 and 0.5.0 packages in isolated homes and with `grok inspect --json` of Grok Build 1.0.70. The [migration boundaries](docs/guide/updates-and-removal.md#migration-boundaries) of earlier releases still apply.
+
+### What changed
+
+- Grok: the Reviewer and the Code explorer role files have `capabilityMode: read-only` instead of `permission_mode: plan` (#30). When Grok Build starts a subagent of this type, it removes the built-in tools that edit, write, delete or move files and the shell tool. A capability mode requested at spawn cannot widen it. Tools from MCP servers stay, and image or video tools can stay when they are enabled. See [Grok read-only roles](docs/reference/assistants.md#grok-read-only-roles).
+- Grok: APK does not write `permissionMode: plan`. Grok Build reads this field, but at spawn it uses only `bypassPermissions`.
+- `show` reports `UNSUPPORTED_ROLE_CAPABILITY` for a Grok agent file whose `capabilityMode` Grok Build does not accept. Grok Build drops such an agent without a warning.
+- Not checked: a live Grok model task with a read-only role.
+- Configuration page: when you edit Kimi, Gemini or Grok alone, a short note above the model table tells how that assistant applies effort. Kimi shares one effort among the roles that use the same model alias. Gemini has native tiers only and no effort per role. Grok applies an effort only for models that support it, and a role without one runs at its model default. The **All** view shows no note. The unused note text in the page source is removed (#21).
+
+## 0.5.0 — 2026-11-01
+
+### Why this release
+
+Three follow-ups from the 2026-11-01 model review needed released configuration changes. Primary Anthropic data showed that Sonnet 5.5 at medium is too weak for the Standard Coder (#29). Grok Build turned out to accept a reasoning effort per role, and APK described its Grok effort behavior wrongly (#27). Claude 4.5 models approach retirement, and the `sonnet` alias still points at Sonnet 4.5 on some providers (#28). The release also makes undo visible, so people can apply a setup without fear, and keeps the share link short until a setup is complete.
+
+### Who should update
+
+- Anyone who uses the Standard preset with Claude.
+- Anyone who uses Grok Build and wants a different effort per role.
+- Everyone else can update for the clearer undo guidance and the corrected Grok and Claude information. Light and Top-tier values do not change.
+
+### Migration and rollback
+
+Assistant IDs, preset ids, share-link format v2 and receipt format v4 are unchanged. Setup with 0.5.0 replaces a 0.4.0 installation in place, and setup with 0.4.0 moves back in place, for ChatGPT, Claude, Gemini and Grok. A Grok role effort written by 0.5.0 is removed when 0.4.0 writes its role files. Kimi was not checked with a provisioned model pool. The Claude boundary to 0.3.0 and earlier from 0.4.0 still applies to receipts from 0.5.0: see the [migration boundaries](docs/guide/updates-and-removal.md#migration-boundaries).
+
+### Presets and model catalog
+
+- **Standard, Claude:** the Coder uses Sonnet 5.5 at high instead of medium (#29). Anthropic's per-effort data puts Sonnet 5.5 at medium 8.6 to 14.2 points below high on Terminal-Bench 4.0, FrontierCode and CursorBench, and Opus 5.5 at medium costs more per solved task on every measurement. Claude subagents without a named role in Standard also move from medium to high, so they use more of the plan. Reviewer and Test writer keep Sonnet 5.5 at high.
+- **Grok:** Grok 4.7 lists the native levels low, medium, high and xhigh, with high as its default. Grok 4.6, Grok 4.5 and Grok Build 0.1 offer no effort. Grok presets keep the native default, and there is still no Grok top choice (#27).
+- **Claude lifecycle:** Sonnet 4.5 is labelled "Sonnet 4.5 (retires 2026-11-30)" and records its deprecation date, its replacement and the partner schedules: Bedrock Legacy with end of life 2027-04-08, and no date on Google managed. Opus 4.5 and Haiku 4.5 stay active as legacy models without a deprecation notice (#28). The catalog review date is 2026-11-02.
+
+Configuration checks are not model-quality evaluations.
+
+### What changed
+
+- Grok: each role can pin a reasoning effort. Setup writes `effort: <level>` in `~/.grok/agents/apk-<role>.md`; a role without an effort gets no line. `--grok` accepts `role=model:effort` and `role=model:native`; `role=model` still means the native default and produces the same files as before. The configurator offers effort buttons for Grok 4.7 and custom model IDs, share links keep a Grok effort, and `agent-policy show` reports the effort of each Grok agent.
+- Fixed: APK no longer says that Grok subagents use the main session effort. APK pins each role's model, so a role without an effort runs at that model's default (Grok 4.7: high). The setup warning `grok-per-role-effort-unsupported` is replaced by `grok-effort-model-dependent`.
+- The README and step 4 of the configurator show how to undo a setup: the uninstall command pinned to the release, with a copy button. Removal restores the settings you had before APK and keeps your unrelated edits.
+- The configurator puts a `#setup=` share link in the address only when steps 1–3 are complete. Opening the page, Reset form, or a change that leaves a step incomplete removes the link. Existing links, including links to unfinished forms, still open as before.
+- Docs: the AI assistants reference shows which 4.5 models the Claude `sonnet`, `haiku` and `default` aliases resolve to on Bedrock, Google Agent Platform, Microsoft Foundry and Claude Platform on AWS, and tells Foundry users to pin a newer Sonnet before 2026-11-30. The model review cites primary sources for the Opus 5.5 and Sonnet 5.5 equal-effort numbers and records the Standard Claude Coder decision.
+- Docs: Grok Build ignores the `permission_mode` field that APK writes for read-only roles, so the Grok Reviewer and Code explorer are not read-only yet (#30).
+
 ## 0.4.0 — 2026-11-01
 
 ### Why this release

package/README.md

@@ -17,12 +17,22 @@ Created and maintained by [Mykola Maksymenko](https://www.linkedin.com/in/nick-m
 
 [Getting started](docs/guide/getting-started.md) shows the full path, from the configurator to removal.
 
+## Undo
+
+One command removes the APK settings. It restores the settings that you had before APK and keeps your unrelated edits:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall --apply
+```
+
+To preview the removal first, run the command without `--apply`. Removal uses the receipts in `~/.agent-policy-kit`, so keep that folder. [Updates and removal](docs/guide/updates-and-removal.md#remove-apk) gives the details and the exceptions.
+
 ## Good to know
 
 - Your main agent and its model do not change. The main agent still decides when to delegate.
 - APK configures the coding agent of each assistant: Codex in ChatGPT, Claude Code in Claude, Kimi Code, Antigravity for Gemini, and Grok Build. Plain chats do not change. [Assistants](docs/reference/assistants.md) lists the details, also for the desktop apps.
 - APK adds no proxy and no background process. You can delete the npm package after setup.
-- `npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy show` reads your current settings. Use `uninstall --apply` instead of `show` to remove the APK settings and keep yours.
+- `npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy show` reads your current settings.
 - Apart from the npm download, APK makes no network requests. [Privacy](docs/guide/privacy.md) tells what it reads and writes.
 
 ## Documentation

package/docs/design/2026-11-01-grok-build-support.md

@@ -25,6 +25,12 @@ Many programmers use Grok Build next to Codex, Claude Code, Kimi Code and Antigr
 - Explicit command: `--grok`, `--grok-max-concurrent`, `--avoid-grok`, following the existing per-tool pattern.
 - Ownership, drift refusal, receipts and uninstall follow the existing adapters; TOML edits are surgical, like Codex.
 
+## Later corrections
+
+- 0.5.0: Grok Build 1.0.70 does read a per-role effort from the `effort` field of an agent file, and a model pinned in `[subagents.models]` runs at that model's default effort, not at the main session's effort (#27). APK now writes `effort` when a role pins one. See the AI assistants reference.
+- 0.5.0: Grok Build reads agent fields in camelCase, so it ignores `permission_mode: plan`. The Reviewer and Code explorer roles are therefore not read-only in Grok (#30).
+- 0.5.1: APK writes `capabilityMode: read-only` for the Reviewer and the Code explorer instead of `permission_mode: plan` (#30). Grok Build applies this field when it starts the subagent and removes the built-in tools that edit, write, delete or move files and the shell tool. `permissionMode: plan` has no effect at spawn, so APK does not write it. The bundled read-only agents mentioned above use the same ignored snake_case key. See the AI assistants reference.
+
 ## Out of scope
 
 Personas, roles TOML, plugin agents, project-level `.grok/` files, live model execution and any change to the main session's model or effort.

package/docs/guide/commands.md

@@ -9,10 +9,10 @@ APK needs Node.js 22.13 or later in the 22 line, or Node.js 24 or later.
 Run a pinned release with `npx`:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy <command> [options]
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy <command> [options]
 ```
 
-- `--package agent-policy-kit@0.4.0` selects the configuration release. The package version is the release version.
+- `--package agent-policy-kit@0.5.1` selects the configuration release. The package version is the release version.
 - `--ignore-scripts` prevents npm install scripts.
 - `--yes` lets npx download the package without a prompt.
 
@@ -99,7 +99,7 @@ agent-policy setup \
   --claude 'reviewer=claude-sonnet-5-5:high,explorer=claude-haiku-5-5:native' \
   --claude-max-concurrent 2 \
   --gemini 'reviewer=pro,explorer=flash' \
-  --grok 'reviewer=grok-4.7,explorer=grok-4.7'
+  --grok 'reviewer=grok-4.7:xhigh,explorer=grok-4.7'
 ```
 
 | Option | Value | Rules |
@@ -108,7 +108,7 @@ agent-policy setup \
 | `--max-concurrent` | A whole number from 1 to 32 | Required. The shared parallel limit. |
 | `--chatgpt`, `--claude`, `--kimi` | `ROLE=MODEL:EFFORT,...` | One entry for each role in `--roles`, exactly once. |
 | `--gemini` | `ROLE=TIER,...` | `TIER` is `pro`, `flash`, `flash_lite` or `inherit`. No effort. |
-| `--grok` | `ROLE=MODEL,...` | No effort. A model that ends with `:` and an effort word is refused. |
+| `--grok` | `ROLE=MODEL,...`, `ROLE=MODEL:EFFORT,...` or a mix | `ROLE=MODEL` sets no effort, the same as `:native`. APK reads a trailing `:` and an effort word or `native` as the effort. For a model ID that itself ends like that, add `:native`. |
 | `--TOOL-max-concurrent` | A whole number from 1 to 32 | Optional. Replaces `--max-concurrent` for one assistant. Needs the `--TOOL` option. |
 | `--avoid-TOOL` | Comma-separated model IDs | Optional. At most 32 models. Routing guidance only. Needs the `--TOOL` option. |
 

package/docs/guide/configurator.md

@@ -1,6 +1,6 @@
 # Configurator
 
-This document describes the configurator page: its four steps, the work modes, the top models switch, the per-assistant limits and the share links. It is for people who use the page to make a setup command. For a first setup from start to end, see [Getting started](getting-started.md).
+This document describes the configurator page: its four steps, the work modes, the top models switch, the per-assistant limits, the undo command and the share links. It is for people who use the page to make a setup command. For a first setup from start to end, see [Getting started](getting-started.md).
 
 ## Open the page
 
@@ -76,7 +76,9 @@ The **Models & effort** table shows one row for each selected role. It is visibl
 
 Any change to a model or effort sets the assistant to **Custom**. Selecting **Custom** without a change does not change any value. A model ID can have 1 to 128 ASCII characters and no spaces.
 
-For Kimi, roles that use the same model alias share one effort. A change to one of these roles changes all of them. For Grok, the page has no effort buttons. Grok subagents use the main session effort. The [assistants reference](../reference/assistants.md) explains these limits.
+When you edit Kimi, Gemini or Grok, a short note above the table tells how that assistant applies effort. Screen readers read the note with the model and effort controls of each role. The **All** view shows no note, because it has no model table.
+
+For Kimi, roles that use the same model alias share one effort. A change to one of these roles changes all of them. For Grok, the page offers the effort levels of the model: low, medium, high and xhigh for Grok 4.7, and none for Grok 4.6, Grok 4.5 and Grok Build 0.1. A custom Grok model ID offers every level that Grok Build accepts. Grok Build applies an effort only when the model supports effort. A Grok role without an effort runs at the default effort of its model. The [assistants reference](../reference/assistants.md) explains these limits.
 
 ### Use the top models switch
 
@@ -114,7 +116,7 @@ The command always lists every selected assistant and role with its model and ef
 A generated command has this form:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup \
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup \
   --roles 'reviewer,explorer' \
   --max-concurrent 3 \
   --chatgpt 'reviewer=gpt-6.1-sol:high,explorer=gpt-6-luna:high' \
@@ -125,15 +127,33 @@ npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup \
 - The package version is the release of the page.
 - `--roles` lists the selected role IDs.
 - `--max-concurrent` is the shared limit. If the limits of the assistants differ, the assistants with a different limit also get `--TOOL-max-concurrent`.
-- Each assistant gets one argument with `role=model:effort` entries. Gemini and Grok entries have no effort.
+- Each assistant gets one argument with `role=model:effort` entries. Gemini entries have no effort. A Grok entry has an effort only when one is set, so a Grok role without an effort stays `role=model`.
 - `--avoid-TOOL` appears only when the list of models to avoid is not empty. A model that you select is removed from that list.
 - `--apply` is always the last line.
 
 The [Commands](commands.md#explicit-tool-arguments) reference describes this syntax. To preview without writes, delete the `--apply` line and the ` \` at the end of the line before it.
 
+### Undo the setup
+
+Under step 4, the box **You can undo the setup** shows the command that removes the APK settings. The command is pinned to the release of the page, for example:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall --apply
+```
+
+The removal restores the settings that you had before APK and keeps your unrelated edits. It uses the receipts that setup saves in the state directory, `~/.agent-policy-kit` by default. Keep this directory.
+
+1. Click **Copy** next to the command. If the clipboard is not available, the page selects the command. Copy it with your keyboard.
+2. To preview the removal, run the command without `--apply`.
+3. Run the command with `--apply` to remove the APK settings.
+
+To remove the APK settings of one assistant only, add `--client ID`, for example `--client claude`.
+
+The box is always visible. It does not depend on the form. [Updates and removal](updates-and-removal.md#remove-apk) gives the full procedure and the known exceptions.
+
 ## Reset the form
 
-Click **Reset form** under step 4. The page selects all six roles again and clears the assistants, the modes and the copy status. The address then holds only the six roles, as on a page that you open for the first time. Reset does not change files on your computer.
+Click **Reset form** under step 4. The page selects all six roles again and clears the assistants, the modes and the copy status. It also removes the setup link from the address. Reset does not change files on your computer. To remove the APK settings, use the [undo command](#undo-the-setup).
 
 ## Check current settings
 
@@ -141,15 +161,22 @@ At the bottom of the page, **Check current settings** has a **Copy** button. It
 
 ## Share a setup
 
-The page saves the form in the address. Each change replaces the part after `#setup=`.
+The page saves a complete form in the address, in the part after `#setup=`. The form is complete when steps 1, 2 and 3 show their green checks.
+
+- When you open the page without a setup link, the address has no `#setup=` part.
+- When steps 1, 2 and 3 are complete, the page writes the form into the address. Each later change replaces the part after `#setup=`.
+- When a change makes step 1, 2 or 3 incomplete, the page removes the `#setup=` part. For example, this occurs when you remove the last assistant.
+- **Reset form** removes the `#setup=` part.
+
+To share a setup:
 
-1. Complete the form, or a part of it.
+1. Complete steps 1, 2 and 3.
 2. Copy the page address from the browser.
 3. Send the address to the other person.
 
 The link contains the roles, the assistant order, the mode of each assistant, the model and effort choices, each limit and the assistant that you edit. It does not contain the copy status. The link stays in the browser. The page needs no database to open it.
 
-When someone opens the link, the page restores the form, including unfinished choices. The command is still blocked until all values are valid.
+When someone opens the link, the page restores the form, including unfinished choices. The command is still blocked until all values are valid. For a link to an unfinished form, the address keeps the link until the form changes.
 
 - A link contains its release version. A link from another release opens only on the page of that release. The hosted page sends such a link to the page of its release, if that page is hosted. Otherwise, the page shows an error.
 - If a link is not valid, the page shows an error. Click **Reset form** to start again.

package/docs/guide/getting-started.md

@@ -40,6 +40,8 @@ Make sure that you have:
 10. Run the full command, with `--apply`.
 11. Open a new session in each configured assistant. A session that was open before setup can keep the old settings.
 
+You can undo the setup later. Step 4 of the page shows the `uninstall` command for its release. The removal restores the settings that you had before APK and keeps your unrelated edits. See [Remove APK settings after other changes](#remove-apk-settings-after-other-changes).
+
 For each control on the page, see [Configurator](configurator.md).
 
 ## Check the result
@@ -47,13 +49,13 @@ For each control on the page, see [Configurator](configurator.md).
 1. Run `doctor` to verify the configuration that APK owns:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy doctor
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy doctor
    ```
 
 2. Run `show` to read the subagent settings that your assistants use now, including settings that you made yourself:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy show
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy show
    ```
 
 A verified configuration does not prove that a provider runs a specific model. For all command options, see [Commands](commands.md).
@@ -89,7 +91,7 @@ Each assistant gets its own native role files and instructions. No central servi
 Run setup with the release input mode:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --release
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --release
 ```
 
 This previews the Standard mode. Add `--preset fast` for Light or `--preset quality` for Top-tier. Add `--apply` to write the files. For details, see [Commands](commands.md#release-presets---release-and---preset).

package/docs/guide/preferences.md

@@ -18,7 +18,7 @@ Preferences apply only when the main agent decides to delegate. They do not turn
 1. Create a file with the Standard preset of the release:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy init --policy ./preferences.json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy init --policy ./preferences.json
    ```
 
 2. Edit the file. Use the rules below.
@@ -96,7 +96,7 @@ This example configures three roles in Claude Code and Antigravity. The Claude R
 APK refuses preferences that break one of these rules:
 
 - `selectedRoles`, if present, is not empty, has no duplicates and contains only `worker`, `reviewer`, `explorer`, `tester`, `writer` and `routine`.
-- The effort is `null` or a native level of the assistant. Gemini and Grok accept only `null`. The [model catalog reference](../reference/model-catalog.md) lists the levels of each assistant.
+- The effort is `null` or a native level of the assistant. Gemini accepts only `null`. Grok accepts the levels that Grok Build reads from an agent file, limited by the catalog for a known model: Grok 4.7 accepts `low` to `xhigh`, and the other Grok models only `null`. The [model catalog reference](../reference/model-catalog.md) lists the levels of each assistant.
 - If the model is in the release catalog, the effort is a level of that model. A model that is not in the catalog can use any native level of the assistant. The assistant must still support it.
 - A Gemini model is a native tier: `pro`, `flash`, `flash_lite` or `inherit`.
 - A Kimi model is not `primary`.
@@ -112,7 +112,7 @@ Some conditions can only be checked against the native files, for example missin
 APK has no separate validation command. A preview checks the file and writes nothing:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --policy ./preferences.json
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --policy ./preferences.json
 ```
 
 If the file is not valid, the command fails with `INVALID_POLICY`. The file must be a regular file of at most 64 KiB, not a symbolic link.
@@ -126,13 +126,13 @@ Use one of these methods.
 1. Preview the setup:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --policy ./preferences.json
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --policy ./preferences.json
    ```
 
 2. Apply it:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --policy ./preferences.json --apply
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --policy ./preferences.json --apply
    ```
 
 `--policy` is conservative. If APK already has a setup with other values, it stops with `INSTALLATION_CONFLICT` or `POLICY_CONFLICT`.
@@ -150,7 +150,7 @@ To replace saved values with the values of a file, send the file as `--config`:
 2. Preview the setup with the encoded value:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --config ENCODED_VALUE
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --config ENCODED_VALUE
    ```
 
 3. Run the same command with `--apply`.

package/docs/guide/updates-and-removal.md

@@ -21,7 +21,7 @@ Installing or updating the npm package does not change your native files. Only `
 2. Show the release and its notes with the `release` command:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy release
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy release
    ```
 
 3. Check the installed versions of your assistants and the models that your account can use.
@@ -37,7 +37,7 @@ A release that is not published yet has the heading `VERSION — Unreleased` in
 1. Preview the setup with the release that you want:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup --release
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy setup --release
    ```
 
 2. To select another preset, add `--preset fast` (Light) or `--preset quality` (Top-tier). The default is `balanced` (Standard).
@@ -76,16 +76,16 @@ These boundaries are known:
 
 | Assistant | Change | Setup without removal | Remove with |
 |---|---|---|---|
-| Claude | From 0.4.0 to 0.3.0 or earlier | `INVALID_RECEIPT` | 0.4.0 |
+| Claude | From 0.4.0 or later to 0.3.0 or earlier | `INVALID_RECEIPT` | The installed release, 0.4.0 or later |
 | ChatGPT and Gemini | From 0.2.0 or earlier to 0.3.0 or later | `OWNERSHIP_CONFLICT` | The release that created the settings, for example 0.2.0 |
 | ChatGPT and Gemini | From 0.3.0 or later to 0.2.0 or earlier | `OWNERSHIP_CONFLICT` | The release that created the settings, for example 0.4.0 |
 
-**Claude, 0.4.0 to an older release.** A 0.4.0 Claude receipt owns `CLAUDE_CODE_SUBAGENT_EFFORT` when the effort of the default subagent role is pinned. Every preset pins it. Releases 0.3.0 and earlier do not know this setting, so they refuse the receipt. To move Claude back to 0.3.0:
+**Claude, 0.4.0 or later to 0.3.0 or earlier.** A Claude receipt from 0.4.0 or later owns `CLAUDE_CODE_SUBAGENT_EFFORT` when the effort of the default subagent role is pinned. Every preset pins it. Releases 0.3.0 and earlier do not know this setting, so they refuse the receipt. To move Claude back to 0.3.0:
 
-1. Remove the Claude settings with 0.4.0:
+1. Remove the Claude settings with the installed release (0.4.0 or later), for example:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall --client claude --apply
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall --client claude --apply
    ```
 
 2. Set up Claude with 0.3.0.
@@ -124,14 +124,14 @@ APK has no background updater and requests no live model catalog. Your configure
 1. Preview the removal:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall
    ```
 
 2. Read the preview.
 3. Remove the configuration:
 
    ```sh
-   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall --apply
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.1 agent-policy uninstall --apply
    ```
 
 4. Run `show` to check the current settings.
@@ -143,7 +143,7 @@ Uninstall uses the receipts in the state directory. It needs no assistant execut
 You do not need the release that you used for setup. Any release that can read the receipt can remove it. There are two known exceptions:
 
 - Releases 0.3.0 and later do not read the ChatGPT and Gemini receipts of 0.2.0 and earlier. Remove these settings with the release that created them.
-- Releases 0.3.0 and earlier cannot read a 0.4.0 Claude receipt that owns `CLAUDE_CODE_SUBAGENT_EFFORT`. Remove these settings with 0.4.0.
+- Releases 0.3.0 and earlier cannot read a Claude receipt from 0.4.0 or later that owns `CLAUDE_CODE_SUBAGENT_EFFORT`. Remove these settings with 0.4.0 or a later release.
 
 See [Migration boundaries](#migration-boundaries) and the [ownership reference](../reference/ownership.md#receipt-formats).
 

package/docs/maintainers/verification.md

@@ -14,6 +14,36 @@ A configuration check does not prove native loading. Native loading does not pro
 
 Each record names the platform and the date. Browser evidence, temporary homes, raw configuration fixtures and logs stay outside Git and npm.
 
+## 0.5.1
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 387/387. New tests cover the Grok read-only role files, 0.4.0 and 0.5.0 Grok installs that verify, update in place and uninstall, the `show` capability warning, and the assistant notes on the page |
+| Hosted CI | PASS on main 6691f94: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41381777278)) |
+| Published 0.5.0 to 0.5.1 | PASS in isolated homes with the npm 0.5.0 package and the 0.5.1 tarball, Standard preset. ChatGPT, Claude, Gemini and Grok upgrade to 0.5.1 and move back to 0.5.0 in place. The Grok `apk-reviewer.md` has `capabilityMode: read-only` with 0.5.1 and `permission_mode: plan` again after the move back. Kimi NOT CHECKED with a provisioned model pool: both versions return a prerequisite in an empty home |
+| Grok read-only roles | PASS by source reading and a non-live `grok inspect --json` of Grok Build 1.0.70 with an isolated profile: `capabilityMode` is parsed (an invalid value drops the agent) and `read-only` is listed. A live model task with a read-only role is NOT CHECKED |
+| Browser | PASS in a local Chromium preview: the Kimi, Gemini and Grok notes in their details views, none for ChatGPT and the All view (#33) |
+| Native ChatGPT, Claude, Kimi, Gemini and Grok loading and provider execution | NOT CHECKED for 0.5.1. No live model tasks were used as configuration proof |
+| npm packaging | PASS: `npm pack --dry-run` lists 50 files. No private evidence or configuration |
+| Model catalog | Unchanged from 0.5.0 |
+
+## 0.5.0
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 381/381. New tests cover the Grok role effort (frontmatter, explicit `role=model:effort`, share links, `show`, a rebuilt 0.4.0 install), the Standard Claude Coder at high and its default subagent effort, the Claude 4.5 lifecycle data, the undo box and the share-address rule |
+| Hosted CI | PASS on main 19844f5: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41377664489)) |
+| Published 0.4.0 to 0.5.0 | PASS in isolated homes with the npm 0.4.0 package and the 0.5.0 tarball, Standard preset. ChatGPT, Claude, Gemini and Grok upgrade to 0.5.0 and move back to 0.4.0 in place. Kimi NOT CHECKED with a provisioned model pool: both versions return a prerequisite in an empty home |
+| Grok role effort | PASS: an explicit `worker=grok-4.7:xhigh` writes `effort: xhigh` in `apk-worker.md`; moving back to 0.4.0 removes the line. A non-live `grok inspect --json` with an isolated profile lists the generated agents. That the effort reaches a model request is NOT CHECKED with a live task |
+| Browser | PASS in a local Chromium preview: no share fragment on first load or with steps 1–2 only, a fragment after a mode is chosen, none after Reset form; Standard Claude Coder at Sonnet 5.5 high; Grok 4.7 effort buttons; the undo box with the 0.5.0 uninstall command and its copy button |
+| Native ChatGPT, Claude, Kimi, Gemini and Grok loading and provider execution | NOT CHECKED for 0.5.0. No live model tasks were used as configuration proof |
+| npm packaging | PASS: `npm pack --dry-run` lists 50 files. No private evidence or configuration |
+| Model catalog | Reviewed on 2026-11-02; see the [model review](../research/2026-11-01-model-review.md). Configuration tests do not establish account access or model quality |
+
 ## 0.4.0
 
 macOS arm64, 2026-11-01.

package/docs/reference/assistants.md

@@ -74,7 +74,7 @@ APK writes settings through native features. It does not run during agent work a
 | Claude | Native setting. It applies to ordinary Agent-tool spawns, with documented exceptions. | Role file | Role file | Session, project and managed settings, environment overrides and some spawn paths can override user settings. |
 | Kimi | Guidance only. No native cap is set. | Guidance only. The parent selects the pool alias when it spawns. | Per alias, not per role | Native Kimi rules |
 | Gemini | Guidance only. There is no universal native cap. | Native tier per role | None | Native Antigravity rules |
-| Grok | Native setting | `config.toml` per role | None. Subagents use the main session effort. | Project settings, explicit spawn settings and higher-priority instructions follow Grok Build rules. |
+| Grok | Native setting | `config.toml` per role | Role file. It applies only when the model supports effort. A role without an effort runs at the default effort of its model. | Project settings, explicit spawn settings, Grok roles with the same name and higher-priority instructions follow Grok Build rules. |
 
 Each assistant adds warning codes to the setup result. The codes tell the person or agent which limits apply:
 
@@ -84,7 +84,7 @@ Each assistant adds warning codes to the setup result. The codes tell the person
 | Claude | `claude-native-precedence-limits` |
 | Kimi | `kimi-concurrency-guidance-only`, `kimi-model-pool-routing-guidance` |
 | Gemini | `gemini-concurrency-guidance-only`, `gemini-per-role-effort-unsupported` |
-| Grok | `grok-per-role-effort-unsupported`, `grok-native-precedence-limits` |
+| Grok | `grok-effort-model-dependent`, `grok-native-precedence-limits`. Installs made by 0.4.0 keep the older code `grok-per-role-effort-unsupported` in their receipt; setup shows it with the same corrected note. |
 
 Other limits apply to all assistants:
 
@@ -111,6 +111,24 @@ These rules apply to all assistants except Gemini:
 - If `env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is `1`, setup returns `claude-force-model-conflict`. That setting forces one model for all subagents, so the role models cannot apply. Change the native setting first.
 - Claude Code 2.1.316 or later reads `CLAUDE_CODE_SUBAGENT_EFFORT`. Earlier versions ignore it.
 
+#### Claude model aliases on other providers
+
+APK writes a Claude alias such as `sonnet` or `haiku` as it is. Claude Code resolves the alias for each provider. The presets use versioned IDs, not aliases. A role that you set to an alias in Custom can resolve to an older model outside the Anthropic API. On 2026-11-02, the Claude Code documentation gave these resolutions:
+
+| Provider | `sonnet` | `haiku` |
+|---|---|---|
+| Anthropic API | Sonnet 5.5 | Haiku 5.5 |
+| Claude Platform on AWS | Sonnet 4.6 | Haiku 4.5 |
+| Amazon Bedrock, Google Cloud's Agent Platform | Sonnet 4.5 | Haiku 4.5 |
+| Microsoft Foundry | Sonnet 4.5 | Haiku 4.5 |
+
+- On Microsoft Foundry, the `default` model setting is also Sonnet 4.5.
+- Sonnet 4.5 is deprecated. On Bedrock and Agent Platform it stays available until the partner's own date: Bedrock lists it as Legacy with end of life on 2027-04-08, and Google announces no date. See [Model catalog](model-catalog.md#lifecycle).
+- Haiku 4.5 is active (legacy) and has no deprecation notice.
+- **Foundry risk after 2026-11-30:** Foundry follows the Claude API lifecycle, so Sonnet 4.5 retires there on 2026-11-30. Unless Claude Code changes its Foundry defaults, `sonnet` and `default` then name a retired model. Bedrock and Agent Platform show a notice and fall back to an earlier version of an unavailable alias default. Foundry has no such startup check, so Foundry users see errors instead.
+- On Foundry, pin a newer Sonnet before 2026-11-30: set `ANTHROPIC_DEFAULT_SONNET_MODEL` to a Sonnet 5.x or Sonnet 4.6 deployment, or choose a full model ID for each role and for the main model.
+- Claude Code warns when a requested model has a scheduled retirement date. The check also covers a `model` in subagent frontmatter, so it covers APK role files.
+
 ### Kimi (Kimi Code)
 
 Kimi needs provisioned model entries. APK never creates aliases, providers or credentials.
@@ -132,6 +150,36 @@ Kimi sets effort for each alias, not for each role. The effort rules and their r
 - Existing `[subagents]` or `[subagents.models]` values that are not tables, or a `max_concurrent` that is not a positive whole number, stop setup with `UNSUPPORTED_CONFIG`.
 - Grok Build reads `~/.claude/CLAUDE.md` by default. If Claude is also configured, Grok Build can therefore also read the Claude instruction block. APK does not change that behavior.
 
+#### Grok role effort
+
+Issue #27 tested whether a named agent such as `apk-reviewer` can have its own effort. It can. The result comes from the Grok Build source and from a check with Grok Build 1.0.70:
+
+- APK writes a role effort as `effort: <level>` in the frontmatter of `~/.grok/agents/apk-<role>.md`. A role with the native default gets no `effort` line.
+- Grok Build 1.0.70 accepts `low`, `medium`, `high`, `xhigh` and `max` in this field. For any other value, Grok Build drops the whole agent without a warning. `grok inspect --json` with an isolated `GROK_HOME` confirmed both cases. APK writes only the levels that the [model catalog](model-catalog.md#grok-grok-build) lists for a known model.
+- Grok Build applies the effort only when the model supports effort. Grok 4.7 lists `low`, `medium`, `high` and `xhigh`, with `high` as its default. Grok Build 0.1 has no effort setting, so Grok Build ignores an effort for it.
+- A role without an effort runs at the default effort of its model, not at the main session effort. The reason: APK pins the model of each role in `[subagents.models]`, and Grok Build gives a pinned model the default effort from its model list. For Grok 4.7 the default is `high`. Exceptions: the `--effort` option of Grok Build applies to all models, and `[models].default_reasoning_effort` applies to the default model.
+- Grok Build uses this order: a spawn override from the harness, then a Grok role with the same name as the agent (`[subagents.roles.apk-<role>]` or `~/.grok/roles/apk-<role>.toml`), then the agent frontmatter, then the default of the model. The parent model cannot select an effort when it spawns a subagent. APK writes no Grok roles.
+- Not checked: a live model task. Grok Build has no command that shows the resolved subagent effort without a model run. The source is a public sync from 2026-09-29, and the error and log text of these code paths occurs in the 1.0.70 program.
+
+#### Grok read-only roles
+
+Issue #30 tested which field makes the Reviewer and the Code explorer read-only in Grok Build. The result comes from the Grok Build source and from a check with Grok Build 1.0.70:
+
+- Grok Build reads the fields of an agent file in camelCase. It ignores a snake_case key such as `permission_mode` without a warning. Releases 0.4.0 and 0.5.0 wrote `permission_mode: plan`, so their Grok Reviewer and Code explorer had only the prompt as a restriction.
+- Since 0.5.1, APK writes `capabilityMode: read-only` in `~/.grok/agents/apk-reviewer.md` and `~/.grok/agents/apk-explorer.md`.
+- When Grok Build starts a subagent of this type, it removes every built-in tool whose kind is not allowed in read-only mode: the tools that edit, write, delete or move files, the shell tool, the image and video tools, and messages to other active agents. The tools that read, list and search files, the LSP, web search and web fetch, the plan tools and skills stay. Because no edit tool stays, Grok Build also does not add its separate file write tool.
+- The agent file sets an upper limit. A capability mode that the parent or a Grok role requests at spawn cannot widen it: read-only combined with any other mode gives read-only.
+- Grok Build accepts `read-only`, `read-write`, `execute` and `all`, and some spellings of them such as `readOnly`. For any other value, Grok Build drops the whole agent without a warning. `grok inspect --json` with an isolated `GROK_HOME` confirmed both cases. `agent-policy show` reports `UNSUPPORTED_ROLE_CAPABILITY` for such an agent file.
+- `permissionMode: plan` does not make a subagent read-only. Grok Build reads the field, but at spawn it uses only `bypassPermissions`. APK therefore does not write `permissionMode`.
+
+These limits apply:
+
+- Tools from MCP servers have no tool kind, so read-only mode keeps them. An MCP tool that changes files or other systems stays available to the role.
+- If image or video generation is enabled in Grok Build, the source adds these tools to the subagent after the filter. A read-only role can then still generate images or videos.
+- By default a subagent cannot start its own subagents. If you raise the Grok Build subagent depth, it is not checked whether a subagent that a read-only role starts is also read-only.
+- Installs made by 0.4.0 or 0.5.0 keep `permission_mode: plan` until a setup replaces the role files. Use 0.5.1 or later with `--release`, `--preset`, `--config` or explicit tool arguments. A setup without these options reports `unchanged` and keeps the old files.
+- Not checked: a live model task. The spawn path runs only when a model starts a subagent. The source is a public sync from 2026-09-29, and the log text of the capability filter occurs in the 1.0.70 program.
+
 ## Desktop apps
 
 Some desktop apps include their own copy of a CLI and do not put it on `PATH`. On macOS, detection also checks these copies, after `PATH` and the conventional locations:
@@ -159,7 +207,7 @@ These desktop features are not configured:
 ## Sources
 
 - [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
-- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents)
+- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [Claude Code model configuration](https://code.claude.com/docs/en/model-config) and [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
 - [Kimi configuration files](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/configuration/config-files.md) and [Kimi agent definitions](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/customization/agents.md)
 - [Antigravity subagents](https://antigravity.google/docs/subagents?tab=cli)
 - [Grok Build subagents](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md), observed with Grok Build 1.0.70 and an isolated `GROK_HOME`