@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/__tests__/files.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Pins the reader contract and the path discipline: lexical containment of
+ * listed and declared paths, the sorted in-memory reader, the index's
+ * directory queries, BOM stripping, and the two-sided document cap (the
+ * declared size before a read, the returned length after, so a reader that
+ * under-declares cannot smuggle bytes past the cap).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  decodeUtf8,
+  inMemoryPluginFiles,
+  isContainedPath,
+  PLUGIN_DOCUMENT_LIMITS,
+  PluginFileIndex,
+  type PluginFiles,
+  resolveDeclaredPath,
+} from "../files.js";
+import { readPluginPackage } from "../read-plugin-package.js";
+import { openPlugin } from "../testing.js";
+import { kindsOf, read } from "../__test-utils__/read.js";
+
+describe("isContainedPath", () => {
+  it("accepts plugin-relative POSIX paths", () => {
+    expect(isContainedPath("plugin.json")).toBe(true);
+    expect(isContainedPath("skills/a/SKILL.md")).toBe(true);
+    expect(isContainedPath(".cursor-plugin/plugin.json")).toBe(true);
+  });
+
+  it("refuses absolute, parent, dot, empty-segment and backslash paths", () => {
+    for (const path of ["", "/etc/passwd", "../x", "a/../b", "a/./b", "a//b", "a\\b", "a/"]) {
+      expect(isContainedPath(path), path).toBe(false);
+    }
+  });
+});
+
+describe("resolveDeclaredPath", () => {
+  it("normalises ./-prefixed directories and files, and the root spellings", () => {
+    expect(resolveDeclaredPath("./skills/")).toEqual({ ok: true, path: "skills" });
+    expect(resolveDeclaredPath("./agents/reviewer.md")).toEqual({ ok: true, path: "agents/reviewer.md" });
+    expect(resolveDeclaredPath(".")).toEqual({ ok: true, path: "" });
+    expect(resolveDeclaredPath("./")).toEqual({ ok: true, path: "" });
+  });
+
+  it("refuses a bare, an escaping and a glob path, each with its own kind", () => {
+    expect(resolveDeclaredPath("skills/")).toEqual({ ok: false, kind: "path-not-relative" });
+    expect(resolveDeclaredPath("./../other")).toEqual({ ok: false, kind: "path-escapes-root" });
+    expect(resolveDeclaredPath("./skills/**/*.md")).toEqual({ ok: false, kind: "path-glob-unsupported" });
+  });
+});
+
+describe("inMemoryPluginFiles and PluginFileIndex", () => {
+  const files = inMemoryPluginFiles(
+    new Map<string, string>([
+      ["skills/b/SKILL.md", "b"],
+      ["skills/a/SKILL.md", "a"],
+      ["skills/a/scripts/run.sh", "run"],
+      ["plugin.json", "{}"],
+      ["agents/x.md", "x"],
+    ]),
+  );
+  const index = new PluginFileIndex(files);
+
+  it("lists entries sorted by path with their byte sizes", () => {
+    expect(files.entries.map((e) => e.path)).toEqual([
+      "agents/x.md",
+      "plugin.json",
+      "skills/a/SKILL.md",
+      "skills/a/scripts/run.sh",
+      "skills/b/SKILL.md",
+    ]);
+    expect(files.entries.find((e) => e.path === "skills/a/scripts/run.sh")?.size).toBe(3);
+  });
+
+  it("answers directory queries from the sorted list", () => {
+    expect(index.childDirectories("")).toEqual(["agents", "skills"]);
+    expect(index.childDirectories("skills")).toEqual(["a", "b"]);
+    expect(index.childFiles("")).toEqual(["plugin.json"]);
+    expect(index.filesUnder("skills/a")).toEqual(["skills/a/SKILL.md", "skills/a/scripts/run.sh"]);
+    expect(index.isDirectory("skills/a/scripts")).toBe(true);
+    expect(index.isDirectory("nope")).toBe(false);
+  });
+
+  it("throws on a read of an unlisted path (a reader contract violation, not plugin content)", () => {
+    expect(() => files.read("missing")).toThrow(/not listed/);
+  });
+});
+
+describe("decodeUtf8", () => {
+  it("strips a leading byte-order mark and nothing else", () => {
+    expect(decodeUtf8(new Uint8Array([0xef, 0xbb, 0xbf, 0x7b, 0x7d]))).toBe("{}");
+    expect(decodeUtf8(new TextEncoder().encode("a\ufeffb"))).toBe("a\ufeffb");
+  });
+});
+
+describe("document caps", () => {
+  it("refuses a manifest over its declared-size cap before reading it", () => {
+    const huge = `{"name":"x","pad":"${"a".repeat(PLUGIN_DOCUMENT_LIMITS.manifest)}"}`;
+    const files = openPlugin({ files: { "plugin.json": huge } });
+    const outcome = read(files);
+    expect(kindsOf(outcome).errors).toEqual(["document-too-large", "manifest-name-missing"]);
+  });
+
+  it("refuses a document whose reader returned more bytes than it declared", () => {
+    const manifest = JSON.stringify({ $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", name: "x" });
+    const lying: PluginFiles = {
+      entries: [{ path: "plugin.json", size: 1 }],
+      read: () => new TextEncoder().encode(manifest.padEnd(PLUGIN_DOCUMENT_LIMITS.manifest + 1, " ")),
+    };
+    const outcome = readPluginPackage(lying);
+    expect(kindsOf(outcome).errors).toEqual(["document-too-large", "manifest-name-missing"]);
+  });
+
+  it("refuses a listed path outside the root", () => {
+    const files = openPlugin({ files: { "../escape.txt": "x" } });
+    expect(kindsOf(read(files)).errors).toEqual(["path-uncontained"]);
+  });
+});

package/src/__tests__/fixtures/cursor-plugins/NOTICE

@@ -0,0 +1,22 @@
+Vendored test fixtures from the Cursor plugins repository.
+
+Source:  https://github.com/cursor/plugins
+Commit:  c1c0a32
+License: each plugin directory carries its own LICENSE file (MIT License,
+         Copyright Cursor), vendored beside it unchanged.
+
+Directories and their paths in the source repository:
+
+  thermos/     <- thermos/
+  advisor/     <- advisor/
+  github/      <- third_party/github/
+  xero/        <- third_party/xero/
+  playwright/  <- third_party/playwright/
+  salesforce/  <- third_party/salesforce/
+
+Every text file is a byte-for-byte copy of the source at that commit. The
+image files (assets/*.png, assets/*.svg) are zero-byte placeholders of the
+same name: the reader never opens them (a logo is an ignored component), and
+the tests pin only that they are listed and never read. Nothing under this
+directory is formatted, linted or edited; a change here is a re-vendoring at
+a new commit and updates this notice.

package/src/__tests__/fixtures/cursor-plugins/advisor/.cursor-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "advisor",
+  "displayName": "Advisor",
+  "version": "1.0.0",
+  "description": "Consult a stronger model at key checkpoints: before major decisions, when stuck on an error, and before declaring a task done. The advisor gets a full briefing plus the conversation transcript, returns guidance, and the main model keeps doing the work.",
+  "author": {
+    "name": "Cursor",
+    "email": "plugins@cursor.com"
+  },
+  "homepage": "https://github.com/cursor/plugins/tree/main/advisor",
+  "repository": "https://github.com/cursor/plugins",
+  "license": "MIT",
+  "logo": "assets/avatar.png",
+  "keywords": [
+    "advisor",
+    "second-opinion",
+    "grok",
+    "multi-model",
+    "subagents",
+    "review",
+    "quality"
+  ],
+  "category": "developer-tools",
+  "tags": [
+    "agents",
+    "quality",
+    "review",
+    "automation"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "hooks": "./hooks/hooks.json"
+}

package/src/__tests__/fixtures/cursor-plugins/advisor/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0
+
+- Initial Advisor plugin release.
+- Skill: `advisor` (`/advisor [model|off|status|ask ...|nudge on|off]`), usable as a Custom Mode.
+- Agent: `advisor-subagent`, a read-only subagent pinned to Grok 4.6 at xhigh effort by default (any model via `/advisor <model>`) that returns a verdict and guidance.
+- Hooks: track edits since the last consult, log each consult to `.cursor/advisor/log.md`, and nudge a pre-completion consult at the end of a turn.

package/src/__tests__/fixtures/cursor-plugins/advisor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/__tests__/fixtures/cursor-plugins/advisor/README.md

@@ -0,0 +1,87 @@
+# Advisor
+
+Advisor gives Cursor's agent a stronger second model to consult at key points: before a major decision, when it is stuck on an error, and before it declares a task done. The main model keeps doing the work; the advisor reads a full briefing (and the conversation transcript when available), thinks hard, and returns a verdict with concrete guidance. You get higher quality on complex tasks while paying for the strong model only where it matters.
+
+The default advisor is the latest Grok (Grok 4.6) at its highest reasoning effort. Because the advisor is a subagent with its own model, it does not have to be the model you are chatting with: any model available to subagents works, so a second opinion can come from a different model family.
+
+## Installation
+
+```bash
+/add-plugin advisor
+```
+
+## Quick start
+
+```text
+/advisor                     turn on with the default advisor (Grok 4.6, xhigh effort)
+/advisor composer-2.5        turn on with a different model (any subagent model slug)
+/advisor ask is this migration safe to run twice?
+/advisor status
+/advisor off
+```
+
+Then work as usual. When the agent hits a checkpoint it consults the advisor and reports back in a line or two:
+
+```text
+Advisor (cursor-grok-4.6-xhigh): proceed with changes. The retry wrapper hides the real
+failure; the 401 comes from a stale token cache. Dropped the retry, fixed the cache key.
+```
+
+To keep the skill in context for a whole session, invoke `/advisor` with Option+Enter (macOS) or Alt+Enter (Windows/Linux) to run it as a Custom Mode. The state file works either way.
+
+## How it works
+
+```mermaid
+flowchart LR
+  U[User] -->|/advisor| M[Main model]
+  M -->|writes| S[.cursor/advisor/state.json]
+  M -->|briefing + transcript path| A[advisor-subagent<br/>strong model, read-only]
+  A -->|verdict + guidance| M
+  H[hooks] -->|track edits, log consults,<br/>nudge before done| M
+```
+
+- **Skill `advisor`** implements the `/advisor` command and the checkpoint protocol: when to consult, how to write the briefing, how to act on the verdict, and how to report it. See [skills/advisor/SKILL.md](skills/advisor/SKILL.md) and the [briefing template](skills/advisor/references/briefing-template.md).
+- **Agent `advisor-subagent`** is a read-only subagent pinned to a strong model (`grok-4.6[effort=xhigh]` by default, overridden per session by `/advisor <model>`). It verifies the briefing against the repository, reads the transcript when a path is available, and answers with `Verdict / Why / Recommendations / Risks / Answers / Confidence`.
+- **Hooks** keep the mode honest without adding chatter: `afterFileEdit` records that files changed since the last consult, `subagentStop` counts each consult and appends the advice to `.cursor/advisor/log.md`, and `stop` posts a one-line `[Advisor]` follow-up when a turn ends with unreviewed edits so the pre-completion consult is not skipped. The nudge fires at most once per batch of edits, stays quiet when the agent ended its turn with a question for you, and can be disabled with `/advisor nudge off`.
+
+## Checkpoints
+
+| Checkpoint | Trigger |
+| --- | --- |
+| Major decision | Choosing between approaches; migrations, deletions, public API or config changes, dependency swaps, auth or payment code; requests ambiguous enough to change the work. |
+| Stuck | Same error or failing test after two real attempts; unexplained behavior; about to add a workaround (retry loop, `sleep`, broad `try/except`, skipped test, disabled check). |
+| Before declaring done | Any task that changed logic or touched more than a couple of files. Trivial edits are skipped and said so. |
+| On request | `/advisor ask ...`, or asking what the advisor thinks. |
+
+The skill caps this at roughly four consults per task and never consults for routine steps or things the agent can verify itself.
+
+## Models
+
+The default is the latest Grok model at its highest reasoning effort (currently `cursor-grok-4.6-xhigh`). `/advisor <model>` accepts any model slug available to subagents; a family name such as `grok fast` or `composer` resolves to that family's latest model at its highest reasoning tier. If Cursor rejects a slug, the skill picks the closest valid one from the error, saves it, and tells you. Team model restrictions and plan limits apply to the advisor like any subagent.
+
+## State
+
+Everything lives in `.cursor/advisor/` at the project root and is safe to delete at any time:
+
+| File | Purpose |
+| --- | --- |
+| `state.json` | Mode, model, nudge setting, consult count, bound conversation, transcript path. |
+| `log.md` | Every completed consult with its verdict, for later review. |
+| `pending` | Marker: files changed since the last consult. |
+| `last-response.txt` | Tail of the latest reply, used to avoid nudging over a question to you. |
+
+Add `.cursor/advisor/` to your `.gitignore` if you do not want it in the repository; the skill never stages it.
+
+## Cost
+
+Each consult is one call to the advisor model with a briefing of a few thousand tokens plus whatever the advisor chooses to read. Selective use is the point: a typical feature takes one to three consults. The default advisor, Grok 4.6, draws from the Cursor Models usage pool, so it is the cheapest of the strong options; switch models when you want a different family's perspective.
+
+## Limitations
+
+- State is per project, bound to the conversation that enabled it. Running `/advisor` in a second conversation on the same project re-binds the mode there (model and nudge settings carry over; the consult history and advisor context start fresh). Use `/advisor status` to look without re-binding.
+- The transcript path is recorded by hooks, so the advisor only reads the full transcript when hooks run and transcripts are enabled. It always receives the briefing.
+- The end-of-turn nudge relies on the plugin's hooks; where hooks do not run, the skill still performs the pre-completion consult on its own.
+
+## License
+
+MIT

package/src/__tests__/fixtures/cursor-plugins/advisor/agents/advisor-subagent.md

@@ -0,0 +1,48 @@
+---
+name: advisor-subagent
+description: Stronger-model advisor for the Advisor plugin. Consulted by the main agent at key checkpoints (before a major decision, when stuck on an error, before declaring a task done) with a briefing and, when available, the conversation transcript. Read-only. Returns a verdict and concrete guidance, not edits.
+model: grok-4.6[effort=xhigh]
+readonly: true
+---
+
+# Advisor
+
+You are the senior engineer a working agent consults at key points. Your prompt is a briefing: the user's request, what has happened so far, verbatim evidence, the current state, and specific questions. It may also name a transcript file. The parent does the work; you supply judgment.
+
+## Method
+
+1. Read the whole briefing before forming a view. Separate evidence (tool output, diffs) from the parent's interpretation of it.
+2. Verify what matters. You can read the repository and run read-only commands (`git diff`, `git log`, `grep`, viewing files). Open the files the briefing names and read the actual diff rather than the description of it. For a "stuck" checkpoint, read the failing code path yourself before proposing a cause.
+3. If a transcript path is given and the file exists, use it to recover what the briefing left out: the user's exact words, earlier decisions, tool results that were summarized away. Check the file size first. For a large transcript, read the most recent portion and search for the user's messages instead of reading everything.
+4. Look for what the parent most likely missed: an assumption it never tested, a simpler approach, a hidden coupling, a production failure mode, part of the request that quietly dropped out of scope, verification that was claimed but not actually run.
+5. Decide. Prefer one clear recommendation over a menu. If two options are genuinely close, say so and give the tie-breaker.
+
+## Response
+
+The parent has to act on this, not read an essay. Stay under about 400 words unless the situation truly needs more.
+
+```text
+Verdict: proceed | proceed with changes | stop
+Why: <two or three sentences>
+
+Recommendations:
+1. <specific action, with file:line or the exact command where relevant>
+2. ...
+
+Risks / verify before done:
+- <what could still be wrong, and how to check it>
+
+Answers:
+<numbered, matching the briefing's questions>
+
+Confidence: high | medium | low — <what would change your mind>
+```
+
+## Rules
+
+- Do not edit files, run state-changing commands, or do the task yourself. You advise.
+- Be direct. Disagree when the evidence warrants it, including with the parent's stated leaning. Do not pad agreement with caveats.
+- Say what you verified and what you infer. Never present a guess about the codebase as fact.
+- If the briefing lacks something you need, ask for exactly that in a short numbered list and still give your best provisional read. One round only.
+- Do not spawn subagents.
+- When resumed, treat the new message as the next checkpoint of the same task. Reuse what you already know and do not re-verify what has not changed.

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/capture-response.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# afterAgentResponse hook for Advisor.
+# Keeps the tail of the latest assistant message so the stop hook can tell
+# whether the agent ended its turn with a question for the user.
+#
+# Input:  { "text": "<assistant response text>", ...common }
+# Output: none
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+HOOK_INPUT=$(cat)
+
+advisor_require_enabled
+advisor_bind_conversation "$HOOK_INPUT" || exit 0
+
+jq -r '.text // empty' <<< "$HOOK_INPUT" | tail -c 400 > "$LAST_RESPONSE_FILE"
+exit 0

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterFileEdit": [
+      {
+        "command": "bash \"${CURSOR_PLUGIN_ROOT}/hooks/mark-pending.sh\""
+      }
+    ],
+    "afterAgentResponse": [
+      {
+        "command": "bash \"${CURSOR_PLUGIN_ROOT}/hooks/capture-response.sh\""
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": "bash \"${CURSOR_PLUGIN_ROOT}/hooks/record-consult.sh\"",
+        "matcher": "^advisor-subagent$"
+      }
+    ],
+    "stop": [
+      {
+        "command": "bash \"${CURSOR_PLUGIN_ROOT}/hooks/stop-hook.sh\"",
+        "loop_limit": 3
+      }
+    ]
+  }
+}

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/lib.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Shared helpers for the Advisor hooks. Source this file; do not run it.
+#
+# State lives in $CURSOR_PROJECT_DIR/.cursor/advisor/:
+#   state.json          written by the advisor skill, kept current here
+#   pending             marker: files were edited since the last consult
+#   last-response.txt   tail of the latest assistant message
+#   log.md              one entry per completed consult
+
+ADVISOR_DIR="${CURSOR_PROJECT_DIR:-.}/.cursor/advisor"
+STATE_FILE="$ADVISOR_DIR/state.json"
+PENDING_FILE="$ADVISOR_DIR/pending"
+LAST_RESPONSE_FILE="$ADVISOR_DIR/last-response.txt"
+LOG_FILE="$ADVISOR_DIR/log.md"
+
+# Exit quietly unless advisor mode is on and jq is available.
+advisor_require_enabled() {
+  command -v jq >/dev/null 2>&1 || exit 0
+  [[ -f "$STATE_FILE" ]] || exit 0
+  [[ "$(jq -r '.enabled // false' "$STATE_FILE" 2>/dev/null)" == "true" ]] || exit 0
+}
+
+# Atomically apply a jq filter to state.json.
+# Usage: advisor_state_update '<filter>' [jq args...]
+advisor_state_update() {
+  local filter="$1"
+  shift
+  local tmp="${STATE_FILE}.tmp.$$"
+  if jq "$@" "$filter" "$STATE_FILE" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$STATE_FILE"
+  else
+    rm -f "$tmp"
+  fi
+}
+
+# Bind the state to the first conversation that touches it and keep transcript_path
+# current. Returns 1 when the hook input belongs to a different conversation, so
+# callers can stay out of conversations that did not enable the advisor.
+# A fresh bind also drops per-conversation markers so a re-bind cannot inherit
+# the previous conversation's pending edits.
+advisor_bind_conversation() {
+  local input="$1"
+  local conv bound transcript current
+  conv=$(jq -r '.conversation_id // empty' <<< "$input")
+  bound=$(jq -r '.conversation_id // empty' "$STATE_FILE")
+  if [[ -n "$conv" ]]; then
+    if [[ -z "$bound" ]]; then
+      advisor_state_update '.conversation_id = $conv' --arg conv "$conv"
+      rm -f "$PENDING_FILE" "$LAST_RESPONSE_FILE"
+    elif [[ "$bound" != "$conv" ]]; then
+      return 1
+    fi
+  fi
+  transcript=$(jq -r '.transcript_path // empty' <<< "$input")
+  current=$(jq -r '.transcript_path // empty' "$STATE_FILE")
+  if [[ -n "$transcript" && "$transcript" != "$current" ]]; then
+    advisor_state_update '.transcript_path = $path' --arg path "$transcript"
+  fi
+  return 0
+}

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/mark-pending.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# afterFileEdit hook for Advisor.
+# Remembers that files changed since the last advisor consult, so the stop hook
+# can ask for a pre-completion review if the turn ends without one.
+#
+# Input:  { "file_path": "<absolute path>", "edits": [...], ...common }
+# Output: none
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+HOOK_INPUT=$(cat)
+
+advisor_require_enabled
+advisor_bind_conversation "$HOOK_INPUT" || exit 0
+
+FILE_PATH=$(jq -r '.file_path // empty' <<< "$HOOK_INPUT")
+
+# The plugin's own state is not work product.
+case "$FILE_PATH" in
+  */.cursor/advisor/*) exit 0 ;;
+esac
+
+touch "$PENDING_FILE"
+exit 0

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/record-consult.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# subagentStop hook for Advisor (matcher: the `advisor-subagent` subagent).
+# Counts the consult, clears the pending-edits marker, and appends the advice
+# to .cursor/advisor/log.md so the user can review it later.
+#
+# Input:  { "subagent_type": "advisor-subagent", "status": "completed"|"error"|"aborted",
+#           "description": "...", "summary": "...", ...common }
+# Output: none
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+HOOK_INPUT=$(cat)
+
+advisor_require_enabled
+advisor_bind_conversation "$HOOK_INPUT" || exit 0
+
+SUBAGENT_TYPE=$(jq -r '.subagent_type // empty' <<< "$HOOK_INPUT")
+STATUS=$(jq -r '.status // empty' <<< "$HOOK_INPUT")
+if [[ "$SUBAGENT_TYPE" != "advisor-subagent" || "$STATUS" != "completed" ]]; then
+  exit 0
+fi
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+advisor_state_update '.consults = ((.consults // 0) + 1) | .last_consult_at = $now' --arg now "$NOW"
+rm -f "$PENDING_FILE"
+
+DESCRIPTION=$(jq -r '.description // "Advisor consult"' <<< "$HOOK_INPUT")
+SUMMARY=$(jq -r '.summary // empty' <<< "$HOOK_INPUT" | head -c 6000)
+{
+  printf '## %s — %s\n\n' "$NOW" "$DESCRIPTION"
+  if [[ -n "$SUMMARY" ]]; then
+    printf '%s\n\n' "$SUMMARY"
+  else
+    printf '_No summary captured._\n\n'
+  fi
+} >> "$LOG_FILE"
+
+exit 0

package/src/__tests__/fixtures/cursor-plugins/advisor/hooks/stop-hook.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# stop hook for Advisor.
+# If files changed since the last advisor consult and the turn ended without one,
+# ask the agent (once per batch of edits) to run the pre-completion consult.
+#
+# Input:  { "status": "completed"|"aborted"|"error", "loop_count": N, ...common }
+# Output: { "followup_message": "<text>" } to continue, or exit 0 with no output
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+HOOK_INPUT=$(cat)
+
+advisor_require_enabled
+advisor_bind_conversation "$HOOK_INPUT" || exit 0
+
+STATUS=$(jq -r '.status // empty' <<< "$HOOK_INPUT")
+if [[ "$STATUS" != "completed" ]]; then
+  exit 0
+fi
+
+NUDGE=$(jq -r 'if .nudge == false then "false" else "true" end' "$STATE_FILE")
+if [[ "$NUDGE" != "true" ]]; then
+  exit 0
+fi
+
+if [[ ! -f "$PENDING_FILE" ]]; then
+  exit 0
+fi
+
+# The agent stopped to ask the user something. Stay quiet and leave the marker
+# armed so the reminder fires after the user answers and the work resumes.
+if [[ -f "$LAST_RESPONSE_FILE" ]]; then
+  LAST_CHAR=$(tr -d '[:space:]' < "$LAST_RESPONSE_FILE" | tail -c 1)
+  if [[ "$LAST_CHAR" == "?" ]]; then
+    exit 0
+  fi
+fi
+
+rm -f "$PENDING_FILE"
+
+MODEL=$(jq -r '.model // "the configured advisor model"' "$STATE_FILE")
+MESSAGE="[Advisor] Files changed since the last advisor consult and the turn ended without one. If this work is done, or you were about to declare it done, run the pre-completion consult now per the advisor skill: build the briefing, spawn the \`advisor-subagent\` subagent (model: $MODEL), act on the verdict, and report it in one line. If the change was trivial, or you are waiting on the user, say so in one line and stop."
+
+jq -n --arg msg "$MESSAGE" '{"followup_message": $msg}'
+exit 0