@qwen-code/qwen-code 0.14.0-preview.2 → 0.14.0-preview.4

package/bundled/loop/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: loop
+description: Create a recurring loop that runs a prompt on a schedule. Usage - /loop 5m check the build, /loop check the PR every 30m, /loop run tests (defaults to 10m). /loop list to show jobs, /loop clear to cancel all.
+allowedTools:
+  - cron_create
+  - cron_list
+  - cron_delete
+---
+
+# /loop — schedule a recurring prompt
+
+## Subcommands
+
+If the input (after stripping the `/loop` prefix) is exactly one of these keywords, run the subcommand instead of scheduling:
+
+- **`list`** — call CronList and display the results. Done.
+- **`clear`** — call CronList, then call CronDelete for every job returned. Confirm how many were cancelled. Done.
+
+Otherwise, parse the input below into `[interval] <prompt…>` and schedule it with CronCreate.
+
+## Parsing (in priority order)
+
+1. **Leading token**: if the first whitespace-delimited token matches `^\d+[smhd]$` (e.g. `5m`, `2h`), that's the interval; the rest is the prompt.
+2. **Trailing "every" clause**: otherwise, if the input ends with `every <N><unit>` or `every <N> <unit-word>` (e.g. `every 20m`, `every 5 minutes`, `every 2 hours`), extract that as the interval and strip it from the prompt. Only match when what follows "every" is a time expression — `check every PR` has no interval.
+3. **Default**: otherwise, interval is `10m` and the entire input is the prompt.
+
+If the resulting prompt is empty, show usage `/loop [interval] <prompt>` and stop — do not call CronCreate.
+
+Examples:
+
+- `5m /babysit-prs` → interval `5m`, prompt `/babysit-prs` (rule 1)
+- `check the deploy every 20m` → interval `20m`, prompt `check the deploy` (rule 2)
+- `run tests every 5 minutes` → interval `5m`, prompt `run tests` (rule 2)
+- `check the deploy` → interval `10m`, prompt `check the deploy` (rule 3)
+- `check every PR` → interval `10m`, prompt `check every PR` (rule 3 — "every" not followed by time)
+- `5m` → empty prompt → show usage
+
+## Interval → cron
+
+Supported suffixes: `s` (seconds, rounded up to nearest minute, min 1), `m` (minutes), `h` (hours), `d` (days). Convert:
+
+| Interval pattern  | Cron expression        | Notes                                     |
+| ----------------- | ---------------------- | ----------------------------------------- |
+| `Nm` where N ≤ 59 | `*/N * * * *`          | every N minutes                           |
+| `Nm` where N ≥ 60 | `0 */H * * *`          | round to hours (H = N/60, must divide 24) |
+| `Nh` where N ≤ 23 | `0 */N * * *`          | every N hours                             |
+| `Nd`              | `0 0 */N * *`          | every N days at midnight local            |
+| `Ns`              | treat as `ceil(N/60)m` | cron minimum granularity is 1 minute      |
+
+**If the interval doesn't cleanly divide its unit** (e.g. `7m` → `*/7 * * * *` gives uneven gaps at :56→:00; `90m` → 1.5h which cron can't express), pick the nearest clean interval and tell the user what you rounded to before scheduling.
+
+## Action
+
+1. Call CronCreate with:
+   - `cron`: the expression from the table above
+   - `prompt`: the parsed prompt from above, verbatim (slash commands are passed through unchanged)
+   - `recurring`: `true`
+2. Briefly confirm: what's scheduled, the cron expression, the human-readable cadence, that recurring tasks auto-expire after 3 days, and that they can cancel sooner with CronDelete (include the job ID).
+3. **Then immediately execute the parsed prompt now** — don't wait for the first cron fire. If it's a slash command, invoke it via the Skill tool; otherwise act on it directly.
+
+## Input

package/bundled/qc-helper/docs/extension/extension-releasing.md

@@ -1,11 +1,12 @@
 # Extension Releasing
 
-There are two primary ways of releasing extensions to users:
+There are three primary ways of releasing extensions to users:
 
 - [Git repository](#releasing-through-a-git-repository)
 - [Github Releases](#releasing-through-github-releases)
+- [npm Registry](#releasing-through-npm-registry)
 
-Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files.
+Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files. npm registry releases are ideal for teams that already use npm for package distribution, especially with private registries.
 
 ## Releasing through a git repository
 
@@ -119,3 +120,85 @@ jobs:
             release/linux.arm64.my-tool.tar.gz
             release/win32.arm64.my-tool.zip
 ```
+
+## Releasing through npm registry
+
+You can publish Qwen Code extensions as scoped npm packages (e.g. `@your-org/my-extension`). This is a good fit when:
+
+- Your team already uses npm for package distribution
+- You need private registry support with existing auth infrastructure
+- You want version resolution and access control handled by npm
+
+### Package requirements
+
+Your npm package must include a `qwen-extension.json` file at the package root. This is the same config file used by all Qwen Code extensions — the npm tarball is simply another delivery mechanism.
+
+A minimal package structure looks like:
+
+```
+my-extension/
+├── package.json
+├── qwen-extension.json
+├── QWEN.md              # optional context file
+├── commands/             # optional custom commands
+├── skills/               # optional custom skills
+└── agents/               # optional custom subagents
+```
+
+Make sure `qwen-extension.json` is included in your published package (i.e. not excluded by `.npmignore` or the `files` field in `package.json`).
+
+### Publishing
+
+Use standard npm publishing tools:
+
+```bash
+# Publish to the default registry
+npm publish
+
+# Publish to a private/custom registry
+npm publish --registry https://your-registry.com
+```
+
+### Installation
+
+Users install your extension using the scoped package name:
+
+```bash
+# Install latest version
+qwen extensions install @your-org/my-extension
+
+# Install a specific version
+qwen extensions install @your-org/my-extension@1.2.0
+
+# Install from a custom registry
+qwen extensions install @your-org/my-extension --registry https://your-registry.com
+```
+
+### Update behavior
+
+- Extensions installed without a version pin (e.g. `@scope/pkg`) track the `latest` dist-tag.
+- Extensions installed with a dist-tag (e.g. `@scope/pkg@beta`) track that specific tag.
+- Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date and will not prompt for updates.
+
+### Authentication for private registries
+
+Qwen Code reads npm auth credentials automatically:
+
+1. **`NPM_TOKEN` environment variable** — highest priority
+2. **`.npmrc` file** — supports both host-level and path-scoped `_authToken` entries (e.g. `//your-registry.com/:_authToken=TOKEN` or `//pkgs.dev.azure.com/org/_packaging/feed/npm/registry/:_authToken=TOKEN`)
+
+`.npmrc` files are read from the current directory and the user's home directory.
+
+### Managing release channels
+
+You can use npm dist-tags to manage release channels:
+
+```bash
+# Publish a beta release
+npm publish --tag beta
+
+# Users install beta channel
+qwen extensions install @your-org/my-extension@beta
+```
+
+This works similarly to git branch-based release channels but uses npm's native dist-tag mechanism.

package/bundled/qc-helper/docs/extension/introduction.md

@@ -12,11 +12,11 @@ We offer a suite of extension management tools using both `qwen extensions` CLI
 
 You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
 
-| Command                               | Description                                                       |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `/extensions` or `/extensions manage` | Manage all installed extensions                                   |
-| `/extensions install <source>`        | Install an extension from a git URL, local path, or marketplace   |
-| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser |
+| Command                               | Description                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| `/extensions` or `/extensions manage` | Manage all installed extensions                                              |
+| `/extensions install <source>`        | Install an extension from a git URL, local path, npm package, or marketplace |
+| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser            |
 
 ### CLI Extension Management
 
@@ -89,6 +89,34 @@ Gemini extensions are automatically converted to Qwen Code format during install
 - TOML command files are automatically migrated to Markdown format
 - MCP servers, context files, and settings are preserved
 
+#### From npm Registry
+
+Qwen Code supports installing extensions from npm registries using scoped package names. This is ideal for teams with private registries that already have auth, versioning, and publishing infrastructure in place.
+
+```bash
+# Install the latest version
+qwen extensions install @scope/my-extension
+
+# Install a specific version
+qwen extensions install @scope/my-extension@1.2.0
+
+# Install from a custom registry
+qwen extensions install @scope/my-extension --registry https://your-registry.com
+```
+
+Only scoped packages (`@scope/package-name`) are supported to avoid ambiguity with the `owner/repo` GitHub shorthand format.
+
+**Registry resolution** follows this priority:
+
+1. `--registry` CLI flag (explicit override)
+2. Scoped registry from `.npmrc` (e.g. `@scope:registry=https://...`)
+3. Default registry from `.npmrc`
+4. Fallback: `https://registry.npmjs.org/`
+
+**Authentication** is handled automatically via the `NPM_TOKEN` environment variable or registry-specific `_authToken` entries in your `.npmrc` file.
+
+> **Note:** npm extensions must include a `qwen-extension.json` file at the package root, following the same format as any other Qwen Code extension. See [Extension Releasing](./extension-releasing.md#releasing-through-npm-registry) for packaging details.
+
 #### From Git Repository
 
 ```bash
@@ -127,7 +155,7 @@ This is useful if you have an extension disabled at the top-level and only enabl
 
 ### Updating an extension
 
-For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
+For extensions installed from a local path, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
 
 You can update all extensions with:
 

package/bundled/qc-helper/docs/features/_meta.ts

@@ -15,4 +15,5 @@ export default {
   language: 'i18n',
   channels: 'Channels',
   hooks: 'Hooks',
+  'scheduled-tasks': 'Scheduled Tasks',
 };

package/bundled/qc-helper/docs/features/hooks.md

@@ -4,13 +4,18 @@
 
 Qwen Code hooks provide a powerful mechanism for extending and customizing the behavior of the Qwen Code application. Hooks allow users to execute custom scripts or programs at specific points in the application lifecycle, such as before tool execution, after tool execution, at session start/end, and during other key events.
 
-> **⚠️ EXPERIMENTAL FEATURE**
->
-> Hooks are currently in an experimental stage. To enable hooks, start Qwen Code with the `--experimental-hooks` flag:
->
-> ```bash
-> qwen --experimental-hooks
-> ```
+Hooks are enabled by default. You can temporarily disable all hooks by setting `disableAllHooks` to `true` in your settings file (at the top level, alongside `hooks`):
+
+```json
+{
+  "disableAllHooks": true,
+  "hooks": {
+    "PreToolUse": [...]
+  }
+}
+```
+
+This disables all hooks without deleting their configurations.
 
 ## What are Hooks?
 

package/bundled/qc-helper/docs/features/scheduled-tasks.md

@@ -0,0 +1,139 @@
+# Run Prompts on a Schedule
+
+> Use `/loop` and the cron scheduling tools to run prompts repeatedly, poll for status, or set one-time reminders within a Qwen Code session.
+
+Scheduled tasks let Qwen Code re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
+
+Tasks are session-scoped: they live in the current Qwen Code process and are gone when you exit. Nothing is written to disk.
+
+> **Note:** Scheduled tasks are an experimental feature. Enable them with `experimental.cron: true` in your [settings](../configuration/settings.md), or set `QWEN_CODE_ENABLE_CRON=1` in your environment.
+
+## Schedule a recurring prompt with /loop
+
+The `/loop` [bundled skill](skills.md) is the quickest way to schedule a recurring prompt. Pass an optional interval and a prompt, and Qwen Code sets up a cron job that fires in the background while the session stays open.
+
+```text
+/loop 5m check if the deployment finished and tell me what happened
+```
+
+Qwen Code parses the interval, converts it to a cron expression, schedules the job, and confirms the cadence and job ID. It then immediately executes the prompt once — you don't have to wait for the first cron fire.
+
+### Interval syntax
+
+Intervals are optional. You can lead with them, trail with them, or leave them out entirely.
+
+| Form                    | Example                               | Parsed interval              |
+| :---------------------- | :------------------------------------ | :--------------------------- |
+| Leading token           | `/loop 30m check the build`           | every 30 minutes             |
+| Trailing `every` clause | `/loop check the build every 2 hours` | every 2 hours                |
+| No interval             | `/loop check the build`               | defaults to every 10 minutes |
+
+Supported units are `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. Seconds are rounded up to the nearest minute since cron has one-minute granularity. Intervals that don't divide evenly into their unit, such as `7m` or `90m`, are rounded to the nearest clean interval and Qwen Code tells you what it picked.
+
+### Loop over another command
+
+The scheduled prompt can itself be a command or skill invocation. This is useful for re-running a workflow you've already packaged.
+
+```text
+/loop 20m /review-pr 1234
+```
+
+Each time the job fires, Qwen Code runs `/review-pr 1234` as if you had typed it.
+
+### Manage loops
+
+`/loop` also supports two subcommands for managing existing jobs:
+
+```text
+/loop list
+```
+
+Lists all scheduled jobs with their IDs and cron expressions.
+
+```text
+/loop clear
+```
+
+Cancels all scheduled jobs at once.
+
+## Set a one-time reminder
+
+For one-shot reminders, describe what you want in natural language instead of using `/loop`. Qwen Code schedules a single-fire task that deletes itself after running.
+
+```text
+remind me at 3pm to push the release branch
+```
+
+```text
+in 45 minutes, check whether the integration tests passed
+```
+
+Qwen Code pins the fire time to a specific minute and hour using a cron expression and confirms when it will fire.
+
+## Manage scheduled tasks
+
+Ask Qwen Code in natural language to list or cancel tasks, or reference the underlying tools directly.
+
+```text
+what scheduled tasks do I have?
+```
+
+```text
+cancel the deploy check job
+```
+
+Under the hood, Qwen Code uses these tools:
+
+| Tool         | Purpose                                                                                                         |
+| :----------- | :-------------------------------------------------------------------------------------------------------------- |
+| `CronCreate` | Schedule a new task. Accepts a 5-field cron expression, the prompt to run, and whether it recurs or fires once. |
+| `CronList`   | List all scheduled tasks with their IDs, schedules, and prompts.                                                |
+| `CronDelete` | Cancel a task by ID.                                                                                            |
+
+Each scheduled task has an 8-character ID you can pass to `CronDelete`. A session can hold up to 50 scheduled tasks at once.
+
+## How scheduled tasks run
+
+The scheduler checks every second for due tasks and enqueues them when the session is idle. A scheduled prompt fires between your turns, not while Qwen Code is mid-response. If Qwen Code is busy when a task comes due, the prompt waits until the current turn ends.
+
+All times are interpreted in your local timezone. A cron expression like `0 9 * * *` means 9am wherever you're running Qwen Code, not UTC.
+
+### Jitter
+
+To avoid every session hitting the API at the same wall-clock moment, the scheduler adds a small deterministic offset to fire times:
+
+- **Recurring tasks** fire up to 10% of their period late, capped at 15 minutes. An hourly job might fire anywhere from `:00` to `:06`.
+- **One-shot tasks** scheduled for the top or bottom of the hour (minute `:00` or `:30`) fire up to 90 seconds early.
+
+The offset is derived from the task ID, so the same task always gets the same offset. If exact timing matters, pick a minute that is not `:00` or `:30`, for example `3 9 * * *` instead of `0 9 * * *`, and the one-shot jitter will not apply.
+
+### Three-day expiry
+
+Recurring tasks automatically expire 3 days after creation. The task fires one final time, then deletes itself. This bounds how long a forgotten loop can run. If you need a recurring task to last longer, cancel and recreate it before it expires.
+
+One-shot tasks do not expire on a timer — they simply delete themselves after firing once.
+
+## Cron expression reference
+
+`CronCreate` accepts standard 5-field cron expressions: `minute hour day-of-month month day-of-week`. All fields support wildcards (`*`), single values (`5`), steps (`*/15`), ranges (`1-5`), and comma-separated lists (`1,15,30`).
+
+| Example        | Meaning                      |
+| :------------- | :--------------------------- |
+| `*/5 * * * *`  | Every 5 minutes              |
+| `0 * * * *`    | Every hour on the hour       |
+| `7 * * * *`    | Every hour at 7 minutes past |
+| `0 9 * * *`    | Every day at 9am local       |
+| `0 9 * * 1-5`  | Weekdays at 9am local        |
+| `30 14 15 3 *` | March 15 at 2:30pm local     |
+
+Day-of-week uses `0` or `7` for Sunday through `6` for Saturday. When both day-of-month and day-of-week are constrained (neither is `*`), a date matches if either field matches — this follows standard vixie-cron semantics.
+
+Extended syntax like `L`, `W`, `?`, and name aliases such as `MON` or `JAN` is not supported.
+
+## Limitations
+
+Session-scoped scheduling has inherent constraints:
+
+- Tasks only fire while Qwen Code is running and idle. Closing the terminal or letting the session exit cancels everything.
+- No catch-up for missed fires. If a task's scheduled time passes while Qwen Code is busy on a long-running request, it fires once when Qwen Code becomes idle, not once per missed interval.
+- No persistence across restarts. Restarting Qwen Code clears all session-scoped tasks.

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -98,6 +98,7 @@ Subagents are configured using Markdown files with YAML frontmatter. This format
 ---
 name: agent-name
 description: Brief description of when and how to use this agent
+model: inherit # Optional: inherit or model-id
 tools:
 	- tool1
 	- tool2
@@ -106,9 +107,17 @@ tools:
 
 System prompt content goes here.
 Multiple paragraphs are supported.
-You can use ${variable} templating for dynamic content.
 ```
 
+#### Model Selection
+
+Use the optional `model` frontmatter field to control which model a subagent uses:
+
+- `inherit`: Use the same model as the main conversation
+- Omit the field: Same as `inherit`
+- `glm-5`: Use that model ID with the main conversation's auth type
+- `openai:gpt-4o`: Use a different provider (resolves credentials from env vars)
+
 #### Example Usage
 
 ```
@@ -117,12 +126,7 @@ name: project-documenter
 description: Creates project documentation and README files
 ---
 
-You are a documentation specialist for the ${project_name} project.
-
-Your task: ${task_description}
-
-Working directory: ${current_directory}
-Generated on: ${timestamp}
+You are a documentation specialist.
 
 Focus on creating clear, comprehensive documentation that helps both
 new contributors and end users understand the project.
@@ -213,7 +217,7 @@ tools:
   - web_search
 ---
 
-You are a technical documentation specialist for ${project_name}.
+You are a technical documentation specialist.
 
 Your role is to create clear, comprehensive documentation that serves both
 developers and end users. Focus on:

package/bundled/review/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: review
-description: Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with `/review`, `/review <pr-number>`, or `/review <file-path>`.
+description: Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with `/review`, `/review <pr-number>`, `/review <file-path>`, or `/review <pr-number> --comment` to post inline comments on the PR.
 allowedTools:
   - task
   - run_shell_command
   - grep_search
   - read_file
+  - write_file
   - glob
 ---
 
@@ -15,7 +16,11 @@ You are an expert code reviewer. Your job is to review code changes and provide
 
 ## Step 1: Determine what to review
 
-Your goal here is to understand the scope of changes so you can dispatch agents effectively in Step 2. Based on the arguments provided:
+Your goal here is to understand the scope of changes so you can dispatch agents effectively in Step 2.
+
+First, parse the `--comment` flag: split the arguments by whitespace, and if any token is exactly `--comment` (not a substring match — ignore tokens like `--commentary`), set the comment flag and remove that token from the argument list. If `--comment` is set but the review target is not a PR, warn the user: "Warning: `--comment` flag is ignored because the review target is not a PR." and continue without it.
+
+Based on the remaining arguments:
 
 - **No arguments**: Review local uncommitted changes
   - Run `git diff` and `git diff --staged` to get all changes
@@ -36,6 +41,20 @@ Launch **four parallel review agents** to analyze the changes from different ang
 
 **IMPORTANT**: Do NOT paste the full diff into each agent's prompt — this duplicates it 4x. Instead, give each agent the command to obtain the diff, a concise summary of what the changes are about, and its review focus. Each agent can read files and search the codebase on its own.
 
+Apply the **Exclusion Criteria** (defined at the end of this document) — do NOT flag anything that matches those criteria.
+
+Each agent must return findings in this structured format (one per issue):
+
+```
+- **File:** <file path>:<line number or range>
+- **Issue:** <clear description of the problem>
+- **Impact:** <why it matters>
+- **Suggested fix:** <concrete code suggestion when possible, or "N/A">
+- **Severity:** Critical | Suggestion | Nice to have
+```
+
+If an agent finds no issues in its dimension, it should explicitly return "No issues found."
+
 ### Agent 1: Correctness & Security
 
 Focus areas:
@@ -80,15 +99,42 @@ Focus areas:
 - Unexpected side effects or hidden coupling
 - Anything else that looks off — trust your instincts
 
-## Step 3: Restore environment and present findings
+## Step 2.5: Deduplicate and verify
+
+### Deduplication
+
+Before verification, merge findings that refer to the same issue (same file, same line range, same root cause) even if reported by different agents. Keep the most detailed description and note which agents flagged it.
+
+### Independent verification
+
+For each **unique** finding, launch an **independent verification agent**. Run verification agents in parallel, but if there are more than 10 unique findings, batch them in groups of 10 to avoid resource exhaustion.
+
+Each verification agent receives:
 
-If you checked out a PR branch in Step 1, restore the original state first: check out the original branch, `git stash pop` if changes were stashed, and remove the temp file.
+- The finding description (what's wrong, file, line)
+- The command to obtain the diff (as determined in Step 1)
+- Access to read files and search the codebase
 
-Then combine results from all four agents into a single, well-organized review. Use this format:
+Each verification agent must **independently** (without seeing other agents' findings):
+
+1. Read the actual code at the referenced file and line
+2. Check surrounding context — callers, type definitions, tests, related modules
+3. Verify the issue is not a false positive — reject if it matches any item in the **Exclusion Criteria**
+4. Return a verdict:
+   - **confirmed** — with severity: Critical, Suggestion, or Nice to have
+   - **rejected** — with a one-line reason why it's not a real issue
+
+**When uncertain, lean toward rejecting.** The goal is high signal, low noise — it's better to miss a minor suggestion than to report a false positive.
+
+**After all verification agents complete:** remove all rejected findings. Only confirmed findings proceed to Step 3.
+
+## Step 3: Present findings
+
+Present the confirmed findings from Step 2.5 as a single, well-organized review. Use this format:
 
 ### Summary
 
-A 1-2 sentence overview of the changes and overall assessment.
+A 1-2 sentence overview of the changes and overall assessment. Include verification stats: "X findings reported, Y confirmed after independent verification."
 
 ### Findings
 
@@ -113,6 +159,98 @@ One of:
 - **Request changes** — Has critical issues that need fixing
 - **Comment** — Has suggestions but no blockers
 
+## Step 4: Post PR inline comments (only if `--comment` flag was set)
+
+Skip this step if `--comment` was not specified or the review target is not a PR.
+
+First, get the repository owner/repo and the PR's HEAD commit SHA:
+
+```bash
+gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
+gh pr view {pr_number} --json headRefOid --jq '.headRefOid'
+```
+
+**Important:** Use `gh pr view --json headRefOid` instead of `git rev-parse HEAD` — the local branch may be behind the remote, and the GitHub API requires the exact remote HEAD SHA. If either command fails, inform the user and skip Step 4.
+
+Then, for each confirmed finding, post an **inline comment** on the specific file and line using `gh api`:
+
+**Shell safety:** Review content may contain double quotes, `$VAR`, backticks, or other shell-sensitive characters. Do NOT interpolate review text directly into shell arguments. Instead, use a **two-step process**: write the body to a temp file using the `write_file` tool (which bypasses shell interpretation entirely), then reference the file with `-F body=@file` in the shell command.
+
+```
+# Step A: Use write_file tool to create /tmp/pr-comment.txt with content:
+**[{severity}]** {issue description}
+
+{suggested fix}
+```
+
+```bash
+# Step B: Post single-line comment referencing the file:
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
+  -F body=@/tmp/pr-comment.txt \
+  -f commit_id="{commit_sha}" \
+  -f path="{file_path}" \
+  -F line={line_number} \
+  -f side="RIGHT"
+
+# For multi-line findings (e.g., line range 42-50), add start_line and start_side:
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
+  -F body=@/tmp/pr-comment.txt \
+  -f commit_id="{commit_sha}" \
+  -f path="{file_path}" \
+  -F start_line={start_line} \
+  -F line={end_line} \
+  -f start_side="RIGHT" \
+  -f side="RIGHT"
+```
+
+Repeat Steps A-B for each finding, overwriting the temp file each time. Clean up the temp file in Step 5.
+
+If posting an inline comment fails (e.g., line not part of the diff, auth error), include the finding in the overall review summary comment instead.
+
+**Important rules:**
+
+- Only post **ONE comment per unique issue** — do not duplicate across lines
+- Keep each comment concise and actionable
+- Include the severity tag (Critical/Suggestion/Nice to have) at the start of each comment
+- Include the suggested fix in the comment body when available
+
+After posting all inline comments, use `write_file` to create `/tmp/pr-review-summary.txt` with the summary text, then submit the review using the action that matches the verdict from Step 3:
+
+```bash
+# Submit review with the matching action:
+# If verdict is "Approve":
+gh pr review {pr_number} --approve --body-file /tmp/pr-review-summary.txt
+
+# If verdict is "Request changes":
+gh pr review {pr_number} --request-changes --body-file /tmp/pr-review-summary.txt
+
+# If verdict is "Comment":
+gh pr review {pr_number} --comment --body-file /tmp/pr-review-summary.txt
+```
+
+If there are **no confirmed findings**:
+
+```bash
+gh pr review {pr_number} --approve --body "No issues found. LGTM! ✅"
+```
+
+## Step 5: Restore environment
+
+If you checked out a PR branch in Step 1, restore the original state now: check out the original branch, `git stash pop` if changes were stashed, and remove all temp files (`/tmp/pr-review-context.md`, `/tmp/pr-comment.txt`, `/tmp/pr-review-summary.txt`).
+
+This step runs **after** Step 4 to ensure the PR branch is still checked out when posting inline comments (Step 4 needs the correct commit SHA from the PR branch).
+
+## Exclusion Criteria
+
+These criteria apply to both Step 2 (review agents) and Step 2.5 (verification agents). Do NOT flag or confirm any finding that matches:
+
+- Pre-existing issues in unchanged code (focus on the diff only)
+- Style, formatting, or naming that matches surrounding codebase conventions
+- Pedantic nitpicks that a senior engineer would not flag
+- Issues that a linter or type checker would catch automatically
+- Subjective "consider doing X" suggestions that aren't real problems
+- If you're unsure whether something is a problem, do NOT report it
+
 ## Guidelines
 
 - Be specific and actionable. Avoid vague feedback like "could be improved."