gdhanush27 · gdhanush27 · May 12, 2026 · May 12, 2026
@@ -2,7 +2,7 @@
 
 AI coding assistant with persistent memory, powered by GitHub Copilot.
 
-![Version](https://img.shields.io/badge/version-0.2-informational)
+![Version](https://img.shields.io/badge/version-0.3-informational)
 [![CI](https://github.com/gdhanush27/co-claw/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gdhanush27/co-claw/actions/workflows/ci.yml)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.93%2B-blue?logo=visual-studio-code)
 ![Copilot Required](https://img.shields.io/badge/Copilot-Required-orange?logo=github)

@@ -94,6 +94,8 @@ Runs your task through the multi-agent orchestrator. A Planner produces a JSON D
 
 Live progress is shown in the **Agents** sidebar (the CoClaw activity bar icon). Tune fan-out width with `CoClaw.agents.maxParallelCoders` (ceiling) and `CoClaw.agents.minParallelCoders` (floor — pads small tasks with generic lanes), and switch modes with `CoClaw.agents.mode` (`off`, `slash`, `always`).
 
+Every `/agents` run also ends with an automatic **final reviewer** task (tagged `[final review]` in the plan) that depends on every coder and tester sibling, reads their shared-memory output, and produces a single consolidated review with an `APPROVED` / `CHANGES_REQUESTED` verdict. This is controlled by `CoClaw.agents.finalReviewer` (default `auto` — skipped when the planner already produced a covering reviewer; set to `always` to force one on every run, or `off` to disable). The final reviewer uses the **hard** tier, so it picks up whatever model you've assigned to `CoClaw.models.hard`.
+
 ## Command Palette Commands
 
 Open the Command Palette with `Ctrl+Shift+P` and type the command name.

@@ -54,6 +54,26 @@ All CoClaw settings are under the `CoClaw.*` namespace. Open them quickly with *
 - **Default:** `""` (empty — uses global preference)
 - **Description:** Override the Copilot model family at the workspace level. When set, this workspace uses the specified model regardless of the global selection. Leave empty to use the globally selected model.
 
+### `CoClaw.models.light`
+
+- **Type:** string
+- **Default:** `""` (empty — uses default model)
+- **Description:** Model family to use for light-difficulty tasks (e.g. `gpt-4o-mini`). Light tasks are simple, fast operations such as formatting or renaming. Leave empty to fall back to the general model selection.
+
+### `CoClaw.models.medium`
+
+- **Type:** string
+- **Default:** `""` (empty — uses default model)
+- **Description:** Model family to use for medium-difficulty tasks (e.g. `gpt-4o`). Medium tasks are standard implementation or review work. Leave empty to fall back to the general model selection.
+
+### `CoClaw.models.hard`
+
+- **Type:** string
+- **Default:** `""` (empty — uses default model)
+- **Description:** Model family to use for hard-difficulty tasks (e.g. `claude-3.5-sonnet`). Hard tasks involve complex architecture, multi-file refactoring, or deep reasoning. Leave empty to fall back to the general model selection.
+
+> **Tip:** rather than editing the three `CoClaw.models.*` keys by hand, run **CoClaw: Select Tier Models (Light / Medium / Hard)** from the Command Palette, or send `/models` to the Telegram bot. Both surfaces write to the same settings.
+
 ## Heartbeat Settings (`/open` mode)
 
 ### `CoClaw.heartbeat.enabled`
@@ -159,6 +179,19 @@ All CoClaw settings are under the `CoClaw.*` namespace. Open them quickly with *
 - **Default:** `false`
 - **Description:** When `true`, every `/agents` run skips the per-task character cap entirely — equivalent to passing `--full` on every prompt. This overrides `CoClaw.agents.summaryMaxChars`. Useful when you regularly need long, untrimmed summaries; otherwise leave it off and pass `--full` ad-hoc.
 
+### `CoClaw.agents.finalReviewer`
+
+- **Type:** string enum — `"auto"` / `"always"` / `"off"`
+- **Default:** `"auto"`
+- **Description:** Controls whether the orchestrator appends a **final reviewer** task at the end of every `/agents` run. The final reviewer is a `reviewer`-role agent that depends on every coder and tester task in the plan, reads their shared-memory output, inspects the actual files that changed, and ends its report with a single verdict line: `APPROVED` or `CHANGES_REQUESTED: <reason>`.
+- **Modes:**
+    - `auto` *(default)* — inject a final reviewer **only if** the plan does not already contain a reviewer whose dependency graph transitively covers every coder + tester task. If the planner already produced a "review everything" task, no duplicate is added.
+    - `always` — append a final reviewer on every run, even if other reviewers already exist. Use this if you want a guaranteed, holistic final pass on top of any mid-DAG reviews.
+    - `off` — never inject. The plan's reviewers (if any) are used as-is.
+- **Difficulty tier:** the auto-injected final reviewer is tagged with `difficulty: "hard"`, so it picks up whatever Copilot model you've assigned to the **hard** tier via `CoClaw.models.hard` (or the matching VS Code Settings dropdown / the `/model tier hard <family>` chat command). Pair `always` with a strong model on the hard tier (e.g. Claude Sonnet) for the best results.
+- **What it produces:** the chat plan tags this task as `[final review]`, and the run summary contains the consolidated report — one short paragraph describing what was built, issues grouped by severity (Critical / Major / Minor / Nit) with concrete fixes, and the verdict line.
+- **Why it exists:** with parallel coder fan-out, no single coder sees the whole change set. A final reviewer is the only agent guaranteed to look across every sibling at once.
+
 #### Precedence
 
 The runtime cap is resolved in this order (first match wins):

@@ -45,3 +45,75 @@ When set, this workspace-level preference overrides the global selection for tha
 The model's `maxInputTokens` determines how much memory context CoClaw can inject. With a larger context window model, more memories are included in each prompt. The token budget is controlled by `CoClaw.memory.tokenBudgetPercent` (default: 20%).
 
 **Example:** With a 128K-token model and 20% budget, up to ~25,600 tokens of memory are injected.
+
+## Tier-Based Model Selection
+
+CoClaw supports assigning different Copilot models to different task difficulty tiers: **light**, **medium**, and **hard**. This is most useful for multi-agent orchestration (`/agents`): the Planner tags each sub-task with a difficulty, and the Orchestrator routes that sub-task to the model you configured for that tier.
+
+| Tier   | Intended workload                                                                |
+|--------|----------------------------------------------------------------------------------|
+| light  | Trivial / formulaic work — typos, renames, version bumps, one-line patches.     |
+| medium | Typical implementation, review, and test work. The default when unsure.          |
+| hard   | Multi-file refactors, architectural design, security-sensitive logic.            |
+
+### Pick models via VS Code Quick Pick
+
+1. Press `Ctrl+Shift+P`.
+2. Run **CoClaw: Select Tier Models (Light / Medium / Hard)**.
+3. Pick the tier you want to configure.
+4. Pick a Copilot model family from the list — or pick **Clear override** to reset that tier back to the default model.
+
+Repeat for the other tiers as needed. Selections persist as VS Code settings (`CoClaw.models.light` / `.medium` / `.hard`), so they roam with Settings Sync.
+
+### Pick models from Telegram
+
+There are two equivalent flows:
+
+- Send `/models` (alias `/m`) to jump straight into the **Model Tiers** panel.
+- Or send `/settings` (alias `/s`) and tap the **Model Tiers** group.
+
+For each tier, the bot renders one inline button per available Copilot model family — tap to assign. Tap **🗑 Clear (use default)** to drop the override.
+
+### Pick models from chat with `/model`
+
+The `/model` chat command lets you inspect and change models without leaving the conversation.
+
+| Command | Effect |
+|---|---|
+| `/model` | Show the active model, all tier overrides, and one-click "Pick…" buttons. |
+| `/model list` | List every Copilot model family currently available to you (live). |
+| `/model gpt-4o-mini` | Switch the **general** model directly. Fuzzy match — `/model claude` will list every Claude family as buttons if more than one matches. |
+| `/model tier hard` | Open the Quick Pick for the **hard** tier (skips the "which tier?" step). |
+| `/model tier hard claude-opus-4` | Set the **hard** tier model directly. |
+| `/model clear` | Drop the general model preference (revert to first available). |
+| `/model clear hard` | Drop the **hard** tier override (revert to general default). |
+| `/model help` | Print the table above. |
+
+The status bar and the next `/agents` run pick up the change immediately — no reload needed.
+
+### Pick models from VS Code Settings GUI
+
+1. Open Settings (`Ctrl+,`).
+2. Search for `CoClaw.models`.
+3. Each of the three tier settings (`light`, `medium`, `hard`) plus the top-level `CoClaw.model.family` now renders as a **dropdown** of known Copilot model families, with friendly labels like "GPT-5", "Claude Opus 4", and "Gemini 2.5 Pro".
+4. Pick `(default — use top-level model)` on a tier to clear its override.
+
+> **Note:** the dropdown ships with a curated list of stable Copilot model family identifiers. If Copilot ever exposes a new family that isn't in the dropdown yet, use **CoClaw: Select Tier Models** from the Command Palette (or `/models` in Telegram) — both surfaces pull the **live** list from Copilot at the moment you open them, so they always reflect what's actually available to you right now.
+
+If you'd rather edit `settings.json` directly:
+
+| Setting | Example value |
+|---|---|
+| `CoClaw.models.light` | `gpt-4o-mini` |
+| `CoClaw.models.medium` | `gpt-4o` |
+| `CoClaw.models.hard` | `claude-3.5-sonnet` |
+
+Leave any tier empty to fall back to the general `CoClaw.model.family` selection (or the first available model).
+
+### How It Works End-to-End
+
+1. The Planner agent emits a `"difficulty"` field on each sub-task in its JSON DAG (`"light"`, `"medium"`, or `"hard"`).
+2. The Orchestrator calls `ModelManager.getModelForTier(difficulty ?? "medium")` immediately before invoking each sub-task agent.
+3. If no tier-specific override is configured — or the configured family isn't currently available — the call falls back to the general active model. A one-shot warning is logged to the **CoClaw** output channel whenever a configured family resolves to nothing, so silent fallback can't slip past you.
+4. Dynamic tasks spawned via `CoClaw_spawn_agent` can also pass an explicit `"difficulty"`; without it they default to medium.
+5. When the Coder fan-out splits a single task into parallel units, each child inherits the parent's difficulty.
@@ -91,7 +91,7 @@ In `/open` mode the assistant adopts a configurable tone. Switch via `/settings`
 
 ## Settings Panel
 
-Send `/settings` (or `/s`) to open an interactive panel with inline buttons. Settings are grouped into Agents, Memory, Heartbeat, Telegram, and Model. Each entry supports the right input style:
+Send `/settings` (or `/s`) to open an interactive panel with inline buttons. Settings are grouped into Agents, Memory, Heartbeat, Telegram, Model, and Model Tiers. Send `/models` (or `/m`) to jump straight into the **Model Tiers** group. Each entry supports the right input style:
 
 - **Booleans** — on/off toggle
 - **Enums** — one button per allowed value