agent-policy-kit 0.4.0 → 0.5.0

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.0 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.0 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.0 --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.0 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.0 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.0 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.0 agent-policy uninstall --json
    ```
 
 2. Review the plan.

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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.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.0 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.0 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,11 @@ 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.
+- 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).
+
 ## 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.0 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.0` 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,7 @@ 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.
+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 +114,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.0 agent-policy setup \
   --roles 'reviewer,explorer' \
   --max-concurrent 3 \
   --chatgpt 'reviewer=gpt-6.1-sol:high,explorer=gpt-6-luna:high' \
@@ -125,15 +125,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.0 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 +159,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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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.0 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,21 @@ 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.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,17 @@ 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.
+
 ## 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 +188,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`

package/docs/reference/model-catalog.md

@@ -1,12 +1,12 @@
 # Model catalog
 
-This document describes `models/catalog.json`, the model catalog of release 0.4.0. It explains the fields, lists the models and effort levels for each AI assistant, and records defaults, lifecycle dates and access requirements. It is for everyone who chooses a model in Custom or wants to know which values a release accepts.
+This document describes `models/catalog.json`, the model catalog of release 0.5.0. It explains the fields, lists the models and effort levels for each AI assistant, and records defaults, lifecycle dates and access requirements. It is for everyone who chooses a model in Custom or wants to know which values a release accepts.
 
 ## What the catalog is
 
 The model catalog is a dated snapshot of the native subagent selectors that each AI assistant accepts. A selector is the value that a native role setting takes: a model ID, an alias or a tier. The catalog ships inside the package. One package version has one catalog, as with presets (see [Presets](presets.md)).
 
-- The snapshot date is `reviewedAt`: 2026-11-01 UTC. The review checked the installed native clients and the current vendor documentation. No vendor released or retired a subagent model between the previous check on 2026-10-30 and this one.
+- The snapshot date is `reviewedAt`: 2026-11-02 UTC. On that date the lifecycle of the Claude 4.5 models was checked again. See [Lifecycle](#lifecycle). The full review of 2026-11-01 checked the installed native clients and the current vendor documentation. No vendor released or retired a subagent model between the previous check on 2026-10-30 and this one.
 - The configurator page and the preferences validation use the same data. For the validation rules, see [Preferences](../guide/preferences.md).
 - APK never fetches a catalog at run time. Normal agent work never reads the catalog.
 - The catalog is not a live inventory and not a list of what one account can use. Account access and custom deployment IDs vary.
@@ -48,7 +48,7 @@ Some entries have optional fields:
 | `delegationModes` | Execution modes such as `ultra`. These are not effort levels. |
 | `nativeSource` | A second source for the native behavior. |
 | `effortResolution` | How an alias or `inherit` resolves effort. |
-| `lifecycle` | Status (`active`, `deprecated` or `retired`), a retirement date or earliest retirement date, the scope and the source. |
+| `lifecycle` | Status (`active`, `deprecated` or `retired`), a retirement date (`retirementDate`) or earliest retirement date (`earliestRetirement`), the scope and the source. Optional: the deprecation date (`deprecationDate`), the recommended replacement ID (`replacement`), a `note`, and `partners`, a list of partner platforms that set their own schedule. Each partner entry has `platform`, `source` and, where announced, the partner's own `status`, `earliestRetirement` or `endOfLife`, or a `note`. |
 | `upstreamModelId`, `thinkingRequired`, `planRequirement` | Kimi: the upstream model, whether thinking must be on, and the plan that the model needs. |
 | `documented` | `false` when the native client accepts a selector that the vendor documentation does not list. |
 
@@ -98,7 +98,7 @@ The inventory has 14 versioned IDs, 4 family aliases and `inherit`. The review c
 | `claude-opus-4-6` | Opus 4.6 | low, medium, high, max | high |
 | `claude-sonnet-4-6` | Sonnet 4.6 | low, medium, high, max | high |
 | `claude-opus-4-5-20251101` | Opus 4.5 | none | not documented |
-| `claude-sonnet-4-5-20250929` | Sonnet 4.5 (deprecated) | none | not documented |
+| `claude-sonnet-4-5-20250929` | Sonnet 4.5 (retires 2026-11-30) | none | not documented |
 | `claude-haiku-4-5-20251001` | Haiku 4.5 | none | not documented |
 | `fable` | Fable (alias) | low, medium, high, xhigh, max | high |
 | `opus` | Opus (alias) | low, medium, high, xhigh, max | not documented |
@@ -148,25 +148,41 @@ The native role field takes a tier, not a model ID. The review checked the Antig
 
 The inventory has 4 model IDs from the documented xAI model list. The review checked Grok Build 1.0.70.
 
-| ID | Label | Native efforts | API efforts |
+The client `efforts` list is `low`, `medium`, `high`, `xhigh` and `max`: the values that Grok Build 1.0.70 accepts in the `effort` field of an agent file. A custom model ID can request these levels. Grok Build drops an agent with any other value.
+
+| ID | Label | Native efforts | Native default |
 |---|---|---|---|
-| `grok-4.7` | Grok 4.7 | none | low, medium, high (default), xhigh |
-| `grok-4.6` | Grok 4.6 | none | not recorded |
-| `grok-4.5` | Grok 4.5 | none | not recorded |
-| `grok-build-0.1` | Grok Build 0.1 | none | not recorded |
+| `grok-4.7` | Grok 4.7 | low, medium, high, xhigh | high |
+| `grok-4.6` | Grok 4.6 | not verified, none offered | not documented |
+| `grok-4.5` | Grok 4.5 | not verified, none offered | not documented |
+| `grok-build-0.1` | Grok Build 0.1 | none | none |
 
-The Grok 4.7 levels are API capabilities. APK writes only a model for each Grok role, so the catalog has no native efforts for Grok. For how Grok Build resolves subagent effort, see [Roles](roles.md#how-effort-applies).
+- The Grok 4.7 levels and default come from the Grok Build model list (`supports_reasoning_effort`, `reasoning_efforts`) of 1.0.70. They are the same as the API levels in `apiEfforts`. `max` is not listed for Grok 4.7, so APK does not write it for that model.
+- Grok Build 0.1 has no effort setting. Grok Build ignores an effort for a model without effort support.
+- The levels of Grok 4.6 and 4.5 were not verified, so the catalog offers no effort for them.
+- For where APK writes the effort and how Grok Build applies it, see [Roles](roles.md#how-effort-applies).
 
 ## Lifecycle
 
 | Model | Status | Date | Scope |
 |---|---|---|---|
 | GPT-5.5 | retired | 2026-10-14 | Codex with ChatGPT sign-in. API-key sign-in keeps access. |
-| Sonnet 4.5 | deprecated | retirement 2026-11-30 | Anthropic-operated platforms. Partner schedules differ. |
-| Opus 4.5 | active | earliest retirement 2026-11-24 | Anthropic model lifecycle |
-| Haiku 4.5 | active | earliest retirement 2026-10-15 | Anthropic model lifecycle |
+| Sonnet 4.5 | deprecated since 2026-09-30 | retirement 2026-11-30 | Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. Replacement: `claude-sonnet-5-5`. |
+| Opus 4.5 | active (legacy) | earliest retirement 2026-11-24 | Anthropic-operated platforms and Microsoft Foundry. No deprecation notice. |
+| Haiku 4.5 | active (legacy) | earliest retirement 2026-10-15 | Anthropic-operated platforms and Microsoft Foundry. No deprecation notice. |
+
+Partner platforms set their own schedules:
+
+| Model | Amazon Bedrock | Google Cloud (Google managed) |
+|---|---|---|
+| Sonnet 4.5 | Legacy. End of life 2027-04-08. | No retirement date announced. The earliest retirement date, 2026-09-29, passed. |
+| Opus 4.5 | Not on the legacy list | Earliest retirement 2026-11-24 |
+| Haiku 4.5 | Not on the legacy list | Earliest retirement 2026-12-07 |
 
-The earliest retirement date of Haiku 4.5, 2026-10-15, passed without an announced deprecation. This was the state on the review date, 2026-11-01.
+- This is the state on 2026-11-02. Sonnet 4.5 still works for organizations that already have access, so the catalog records it as deprecated, not retired. The Anthropic Models API describes a deprecated model as closed to new adopters, so a new account can already fail with it.
+- The page offers Sonnet 4.5 with the label "Sonnet 4.5 (retires 2026-11-30)". After that date, a role that names `claude-sonnet-4-5-20250929` fails on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. Choose Sonnet 5.5 instead.
+- Anthropic gives at least 60 days' notice before it retires a model. Opus 4.5 and Haiku 4.5 had no deprecation notice, so their earliest retirement dates are floors, not scheduled dates. The date for Haiku 4.5, 2026-10-15, passed without an announcement.
+- The Claude Code aliases `sonnet`, `haiku` and `default` can resolve to these 4.5 models on some providers. See [AI assistants](assistants.md#claude-model-aliases-on-other-providers).
 
 A release does not keep a retired model available. See [Updates and removal](../guide/updates-and-removal.md).
 
@@ -186,7 +202,7 @@ A catalog entry does not grant access. The account plan and the provider decide
 Each entry has a `source` URL in `models/catalog.json`. The main sources are:
 
 - ChatGPT: [OpenAI models](https://learn.chatgpt.com/docs/models) and the Codex CLI 0.166.0 bundled and server catalogs.
-- Claude: [Claude Code model configuration](https://code.claude.com/docs/en/model-config) and [model lifecycle](https://platform.claude.com/docs/en/about-claude/model-deprecations).
+- Claude: [Claude Code model configuration](https://code.claude.com/docs/en/model-config), [model lifecycle](https://platform.claude.com/docs/en/about-claude/model-deprecations), [Bedrock legacy models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle-legacy.html) and [Google partner model deprecations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/partner-models).
 - Kimi: [Kimi Code models](https://www.kimi.com/code/docs/en/kimi-code/models) and [membership](https://www.kimi.com/code/docs/en/kimi-code/membership.html).
 - Gemini: [Antigravity subagents](https://antigravity.google/docs/subagents?tab=cli) and the CLI 1.4.12 parser.
 - Grok: [xAI models](https://docs.x.ai/developers/models) and [Grok Build subagents](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md).