claude-dev-env 8.96.8 → 8.98.0

package/bin/install-pstack-plugin.mjs

@@ -318,6 +318,23 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
     return { host, executable, status: 'installed', warning: null };
 }
 
+/**
+ * Build the notice that tells the user to restart each session the install reached.
+ *
+ * A running Claude Code or Codex session keeps the plugin files it loaded at
+ * start, so a plugin installed or updated under it stays unavailable there
+ * until the session restarts.
+ *
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins the install wrote.
+ * @param {ReadonlyArray<string>} allInstalledHosts The hosts the install reached.
+ * @returns {string} The restart notice.
+ */
+export function restartNotice(allSpecs, allInstalledHosts) {
+    const pluginLabels = allSpecs.map(eachSpec => eachSpec.label).join(', ');
+    return `Restart each open ${allInstalledHosts.join(' and ')} session to load ${pluginLabels}. `
+        + 'A running session keeps the plugin version it loaded at start.';
+}
+
 /**
  * Install a set of plugins from one marketplace into each host's own home.
  *
@@ -334,7 +351,9 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
  * skipped. When a host cannot replace a plugin folder because something holds
  * it, the warning names each process that holds it, so the user knows what to
- * close before running the install again.
+ * close before running the install again. When any host installs, the step
+ * prints one restart notice, because an open session keeps the plugin
+ * version it loaded at start.
  *
  * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
@@ -342,8 +361,8 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
  * @param {string} [options.codexHome] The Codex home to install into.
  * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
- * @param {object} [dependencies] Seams for the command runner and the folder locker search.
- * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
+ * @param {object} [dependencies] Seams for the command runner, the folder locker search, and the line writer.
+ * @returns {{status: string, hosts: object[], warning: string|null, restartNotice: string|null}} The outcome per host.
  */
 export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
@@ -365,7 +384,15 @@ export function installMarketplacePlugins(allSpecs, options = {}, dependencies =
     const installedCount = hostOutcomes.filter(outcome => outcome.status === 'installed').length;
     const status = failedCount > 0 ? 'failed' : (installedCount > 0 ? 'installed' : 'skipped');
     const warnings = hostOutcomes.map(outcome => outcome.warning).filter(Boolean);
-    return { status, hosts: hostOutcomes, warning: warnings.join(' ') || null };
+    const allInstalledHosts = hostOutcomes
+        .filter(outcome => outcome.status === 'installed')
+        .map(outcome => outcome.host);
+    const notice = allInstalledHosts.length > 0 ? restartNotice(allSpecs, allInstalledHosts) : null;
+    if (notice) {
+        const writeLine = dependencies.writeLine ?? (line => console.log(line));
+        writeLine(notice);
+    }
+    return { status, hosts: hostOutcomes, warning: warnings.join(' ') || null, restartNotice: notice };
 }
 
 /**

package/bin/install-pstack-plugin.test.mjs

@@ -17,6 +17,7 @@ import {
     removeOrphanedPluginVersions,
     removeStaleMarketplaceClone,
     removeRetiredMarketplacePlugins,
+    restartNotice,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 
@@ -500,3 +501,25 @@ test('should delete a half-made marketplace clone before the shared marketplace
 test('should report no removal when no stale marketplace clone exists', () => {
     assert.equal(removeStaleMarketplaceClone(join(tmpdir(), 'cde-no-such-clone')), false);
 });
+
+test('an install prints one restart notice that names each plugin and host', () => {
+    const allLoggedLines = [];
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        ...recordingRunner(),
+        writeLine: line => allLoggedLines.push(line),
+    });
+    assert.deepEqual(allLoggedLines, [restartNotice([PSTACK_PLUGIN_SPEC], ['claude', 'codex'])]);
+    assert.equal(outcome.restartNotice, allLoggedLines[0]);
+    assert.match(allLoggedLines[0], /Restart each open claude and codex session to load Pstack\./);
+});
+
+test('a run that installs nothing prints no restart notice', () => {
+    const allLoggedLines = [];
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        ...recordingRunner(() => ({ status: null, error: Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' }) })),
+        writeLine: line => allLoggedLines.push(line),
+    });
+    assert.equal(outcome.status, 'skipped');
+    assert.deepEqual(allLoggedLines, []);
+    assert.equal(outcome.restartNotice, null);
+});

package/bin/install.prompt-context.test.mjs

@@ -35,11 +35,13 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
     mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
 
     const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
-    assert.equal(userPromptHooks.length, 4);
+    assert.equal(userPromptHooks.length, 6);
     assert.equal(userPromptHooks[0].command, userCommand);
     assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
     assert.match(userPromptHooks[2].command, /lifecycle\/nested_project_hooks\.py$/);
     assert.match(userPromptHooks[3].command, /blocking\/chat_reply_gate\.py$/);
+    assert.match(userPromptHooks[4].command, /session\/open_task_ask_recorder\.py$/);
+    assert.match(userPromptHooks[5].command, /session\/plugin_change_warning\.py$/);
     assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
 
     const firstMerge = JSON.stringify(settings);

package/bin/install.settings-defaults.test.mjs

@@ -268,7 +268,7 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
     }
 });
 
-test('package settings.json publishes the session agent, advisor model, auto-compact, auto mode and idle compaction defaults', () => {
+test('package settings.json publishes the session agent, advisor model, auto-compact, auto mode, idle compaction and Python UTF-8 defaults', () => {
     const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
     const settingsDefaults = settingsDefaultsFromPackageSettings(packageSettings);
     assert.deepEqual(
@@ -276,7 +276,7 @@ test('package settings.json publishes the session agent, advisor model, auto-com
         ['advisorModel', 'agent', 'autoCompactWindow', 'autoMode', 'env', 'modelSettings'],
     );
     assert.equal(settingsDefaults.autoCompactWindow, 350000);
-    assert.deepEqual(settingsDefaults.env, { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000' });
+    assert.deepEqual(settingsDefaults.env, { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000', PYTHONUTF8: '1' });
     assert.deepEqual(settingsDefaults.modelSettings, {
         'claude-haiku-5-5': { autoCompactWindow: 100000 },
         'claude-haiku-4-5': { autoCompactWindow: 100000 },
@@ -307,7 +307,7 @@ test('a missing default is added and a user-set value is kept', () => {
     assert.equal(userSettings.advisorModel, 'sonnet');
 });
 
-test('install adds the idle compaction variable to an env block and keeps a user value on rerun', () => {
+test('install adds the idle compaction and Python UTF-8 variables to an env block and keeps a user value on rerun', () => {
     const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
     try {
         const settingsPath = join(sandboxHome, '.claude', 'settings.json');
@@ -318,6 +318,7 @@ test('install adds the idle compaction variable to an env block and keeps a user
         assert.deepEqual(JSON.parse(readFileSync(settingsPath, 'utf8')).env, {
             EDITOR: 'vim',
             CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000',
+            PYTHONUTF8: '1',
         });
         const userChoice = JSON.parse(readFileSync(settingsPath, 'utf8'));
         userChoice.env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS = '300000';

package/docs/agents-guidance/asks.md

@@ -29,7 +29,12 @@ The installer registers `open_tasks_stop_gate.py` as a Stop hook for each host:
 - Codex: `$CODEX_HOME/hooks.json`. Codex turns the reason into a continuation prompt.
 - Cursor: a native `stop` entry in `~/.cursor/hooks.json`. The reason comes back as `followup_message`, the next user message. A stop with status `aborted` or `error` passes, so a turn the user cancels stays silent.
 
-The gate reads the task list from the task store, the transcript TaskCreate, TaskUpdate, and TodoWrite calls, or the Codex `update_plan` calls. It ends the hold when each open item is named on a `Blocked:` or `Open:` line of the closing reply.
+The gate merges the task store, the transcript TaskCreate, TaskUpdate, and TodoWrite calls, the Codex `update_plan` calls, and the Claude Code desktop `mcp__ccd_turn__update_plan` calls. Each new desktop plan list keeps the unfinished items of the list before it. In Claude Code, `open_task_ask_recorder.py` also records each prompt that asks for work as `#ask-N`. The gate ends the hold when each open item is named on a `Blocked:` or `Open:` line of the closing reply, and that line releases only the current stop.
+
+Close an item for good with one of these lines:
+
+- `Done: #ask-N` for a finished ask. A plan item closes only when the plan marks it completed.
+- `Dropped: <#ask-N or carried item> - "<the user's words>"` for an ask or carried plan item the user called off. The quote must come from a prompt the user sent after that ask or after the plan list that held the item.
 
 ## Cursor
 

package/hooks/blocking/open_tasks_stop_gate.py

@@ -1,20 +1,34 @@
 #!/usr/bin/env python3
 """Stop hook that keeps a session working while its task list has unreported open items.
 
-The session's task list comes from the first of these that exists::
+The session's open items merge these sources, one item per subject::
 
-    ~/.claude/tasks/<task list id>/*.json     (TaskCreate / TaskUpdate store)
-    transcript TaskCreate / TaskUpdate calls   (replayed in order)
-    transcript TodoWrite input.todos           (last call wins)
-    transcript Codex update_plan arguments     (last call wins)
+    ~/.claude/tasks/<task list id>/*.json        (TaskCreate / TaskUpdate store)
+    transcript TaskCreate / TaskUpdate calls      (replayed in order)
+    transcript TodoWrite input.todos              (last call wins)
+    transcript Codex update_plan arguments        (last call wins)
+    transcript mcp__ccd_turn__update_plan calls   (unfinished items carry into a replacing list)
+    ~/.claude/open-task-asks/<session id>.json    (each prompt that asks for work, as #ask-N)
 
-An item with status ``pending`` or ``in_progress`` is open. The turn may end
-only when the closing reply names every open item on a report line::
+An item with status ``pending`` or ``in_progress`` is open, and so is an ask
+until a reply closes it. The turn may end only when the closing reply names
+every open item on a report line::
 
     allow: Blocked: Rotate the deploy key - the owner must approve the org secret
     allow: - Open: #3 - waits on the release checks
+    allow: Open: #ask-2 - the export job runs next
     block: (reply never mentions "Rotate the deploy key")
 
+A report line releases only the current stop. Two lines in any assistant text
+of the session close an item for good::
+
+    Done: #ask-2                                    closes an ask; never a plan item
+    Dropped: #ask-1 - "skip the APK export"         closes an ask
+    Dropped: Submit both APKs - "skip the APK export"   closes a carried plan item
+
+A ``Dropped:`` quote must appear in a prompt the user sent after that ask, or
+after the last plan list that held the item.
+
 A block sends the open items back as the reason, so the model keeps working or
 reports them. Claude Code ends the turn after eight blocks in a row. Codex
 turns the reason into a continuation prompt. A Cursor payload (it carries
@@ -45,14 +59,19 @@ if blocking_directory not in sys.path:
 
 from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
-from open_tasks_transcript import TaskItem, parsed_object, replayed_transcript
+from open_task_asks import RecordedPrompt, claude_home, recorded_prompts
+from open_tasks_transcript import TaskItem, normalized_text, parsed_object, replayed_transcript
 from hooks_constants.open_tasks_stop_gate_constants import (
     ALLOW_EXIT_CODE,
+    ASK_CLOSE_SUFFIX,
+    ASK_ID_PREFIX,
+    ASK_LINE_TEMPLATE,
+    ASK_REFERENCE_PATTERN,
+    ASK_SUBJECT_CHARACTER_LIMIT,
+    ASK_SUBJECT_ELLIPSIS,
     BLOCK_DECISION,
     BLOCK_REASON_PREFIX,
     BLOCK_REASON_SUFFIX,
-    CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE,
-    CLAUDE_HOME_DIRECTORY_NAME,
     CURSOR_COMPLETED_STATUS,
     CURSOR_CONVERSATION_ID_KEY,
     CURSOR_FOLLOWUP_LIMIT,
@@ -60,10 +79,16 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     CURSOR_LOOP_COUNT_KEY,
     CURSOR_STATUS_KEY,
     DECISION_KEY,
+    DONE_LINE_PATTERN,
+    DONE_TEXT_GROUP_INDEX,
+    DROPPED_LINE_PATTERN,
+    DROPPED_QUOTE_GROUP_INDEX,
+    DROPPED_TARGET_GROUP_INDEX,
     HOOK_EVENT_NAME,
     INCOMPLETE_STATUSES,
     ITEM_LINE_TEMPLATE,
     LAST_ASSISTANT_MESSAGE_KEY,
+    PENDING_STATUS,
     REASON_KEY,
     REPORT_LINE_PATTERN,
     REPORTED_TEXT_GROUP_INDEX,
@@ -78,17 +103,9 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     TRANSCRIPT_PATH_KEY,
     UTF8_ENCODING,
     WORD_BOUNDARY_PATTERN,
-    WORD_SEPARATOR,
 )
 
 
-def _claude_home() -> Path:
-    configured_directory = os.environ.get(CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE)
-    if configured_directory:
-        return Path(configured_directory)
-    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME
-
-
 def _task_file_item(task_file: Path) -> TaskItem | None:
     try:
         task_text = task_file.read_text(encoding=UTF8_ENCODING)
@@ -109,25 +126,30 @@ def task_store_items(session_id: object) -> list[TaskItem] | None:
     task_list_id = os.environ.get(TASK_LIST_ID_ENVIRONMENT_VARIABLE) or session_id
     if not isinstance(task_list_id, str) or not task_list_id:
         return None
-    task_directory = _claude_home() / TASKS_DIRECTORY_NAME / task_list_id
+    task_directory = claude_home() / TASKS_DIRECTORY_NAME / task_list_id
     if not task_directory.is_dir():
         return None
     all_items = (_task_file_item(each_file) for each_file in sorted(task_directory.glob(TASK_FILE_GLOB)))
     return [each_item for each_item in all_items if each_item is not None]
 
 
-def _normalized(text: str) -> str:
-    return WORD_SEPARATOR.join(text.lower().split())
+def _line_matches(line_pattern: str, all_texts: list[str]) -> list[re.Match[str]]:
+    all_matches = (
+        re.match(line_pattern, each_line, re.IGNORECASE) for each_text in all_texts for each_line in each_text.splitlines()
+    )
+    return [each_match for each_match in all_matches if each_match]
 
 
 def _reported_texts(reply_text: str) -> list[str]:
-    all_matches = (re.match(REPORT_LINE_PATTERN, each_line, re.IGNORECASE) for each_line in reply_text.splitlines())
-    return [_normalized(each_match.group(REPORTED_TEXT_GROUP_INDEX)) for each_match in all_matches if each_match]
+    return [
+        normalized_text(each_match.group(REPORTED_TEXT_GROUP_INDEX))
+        for each_match in _line_matches(REPORT_LINE_PATTERN, [reply_text])
+    ]
 
 
 def is_reported(task_item: TaskItem, reply_text: str) -> bool:
     """Return True when a Blocked: or Open: line of the reply names the item."""
-    subject_text = _normalized(task_item.subject)
+    subject_text = normalized_text(task_item.subject)
     number_pattern = re.escape(TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=task_item.item_id)) + WORD_BOUNDARY_PATTERN
     return any(
         (subject_text and subject_text in each_text) or re.search(number_pattern, each_text)
@@ -135,14 +157,82 @@ def is_reported(task_item: TaskItem, reply_text: str) -> bool:
     )
 
 
+def _is_quoted_after(quote_text: str, all_later_prompts: list[RecordedPrompt]) -> bool:
+    normalized_quote = normalized_text(quote_text)
+    return bool(normalized_quote) and any(
+        normalized_quote in normalized_text(each_prompt.text) for each_prompt in all_later_prompts
+    )
+
+
+def _ask_subject(prompt_text: str) -> str:
+    first_line = prompt_text.strip().splitlines()[0]
+    if len(first_line) <= ASK_SUBJECT_CHARACTER_LIMIT:
+        return first_line
+    return first_line[:ASK_SUBJECT_CHARACTER_LIMIT] + ASK_SUBJECT_ELLIPSIS
+
+
+def open_ask_items(all_prompts: list[RecordedPrompt], all_closing_texts: list[str]) -> list[TaskItem]:
+    """Return each recorded ask that no ``Done:`` line and no quoted ``Dropped:`` line closes."""
+    all_done_ids = {
+        each_reference
+        for each_match in _line_matches(DONE_LINE_PATTERN, all_closing_texts)
+        for each_reference in re.findall(ASK_REFERENCE_PATTERN, each_match.group(DONE_TEXT_GROUP_INDEX))
+    }
+    all_drop_matches = _line_matches(DROPPED_LINE_PATTERN, all_closing_texts)
+    all_open_asks = []
+    for each_position, each_prompt in enumerate(all_prompts):
+        if not each_prompt.ask_id or each_prompt.ask_id in all_done_ids:
+            continue
+        is_dropped = any(
+            each_prompt.ask_id in re.findall(ASK_REFERENCE_PATTERN, each_match.group(DROPPED_TARGET_GROUP_INDEX))
+            and _is_quoted_after(each_match.group(DROPPED_QUOTE_GROUP_INDEX), all_prompts[each_position + 1 :])
+            for each_match in all_drop_matches
+        )
+        if not is_dropped:
+            all_open_asks.append(TaskItem(each_prompt.ask_id, _ask_subject(each_prompt.text), PENDING_STATUS))
+    return all_open_asks
+
+
+def is_dropped_carried_item(task_item: TaskItem, all_prompts: list[RecordedPrompt], all_closing_texts: list[str]) -> bool:
+    """Return True when a ``Dropped:`` line names the carried item and quotes a prompt sent after its list."""
+    listed_at = task_item.listed_at
+    subject_text = normalized_text(task_item.subject)
+    if not task_item.is_carried or listed_at is None or not subject_text:
+        return False
+    all_later_prompts = [each_prompt for each_prompt in all_prompts if each_prompt.recorded_at > listed_at]
+    return any(
+        subject_text in normalized_text(each_match.group(DROPPED_TARGET_GROUP_INDEX))
+        and _is_quoted_after(each_match.group(DROPPED_QUOTE_GROUP_INDEX), all_later_prompts)
+        for each_match in _line_matches(DROPPED_LINE_PATTERN, all_closing_texts)
+    )
+
+
+def deduplicated_by_subject(all_items: list[TaskItem]) -> list[TaskItem]:
+    """Keep the first item for each subject, so the task store wins over the transcript."""
+    item_by_key: dict[str, TaskItem] = {}
+    for each_item in all_items:
+        item_key = normalized_text(each_item.subject) or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=each_item.item_id)
+        item_by_key.setdefault(item_key, each_item)
+    return list(item_by_key.values())
+
+
 def unreported_open_items(all_hook_input_fields: dict[str, object]) -> list[TaskItem]:
-    """Return the open task items the closing reply does not report."""
+    """Return the open task items and asks the closing reply does not report."""
     replay = replayed_transcript(all_hook_input_fields.get(TRANSCRIPT_PATH_KEY))
-    all_items = task_store_items(all_hook_input_fields.get(SESSION_ID_KEY))
-    if all_items is None:
-        all_items = replay.items() or []
+    session_id = all_hook_input_fields.get(SESSION_ID_KEY)
     reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
     reply_text = reply_value if isinstance(reply_value, str) else replay.last_assistant_text
+    all_closing_texts = [*replay.all_assistant_texts, reply_text]
+    all_prompts = recorded_prompts(session_id)
+    all_replayed_items = [
+        each_item
+        for each_item in replay.items() or []
+        if not is_dropped_carried_item(each_item, all_prompts, all_closing_texts)
+    ]
+    all_items = [
+        *deduplicated_by_subject([*(task_store_items(session_id) or []), *all_replayed_items]),
+        *open_ask_items(all_prompts, all_closing_texts),
+    ]
     return [
         each_item
         for each_item in all_items
@@ -150,13 +240,17 @@ def unreported_open_items(all_hook_input_fields: dict[str, object]) -> list[Task
     ]
 
 
+def _item_line(task_item: TaskItem) -> str:
+    if task_item.item_id.startswith(ASK_ID_PREFIX):
+        return ASK_LINE_TEMPLATE.format(ask_id=task_item.item_id, subject=task_item.subject)
+    return ITEM_LINE_TEMPLATE.format(subject=task_item.subject or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=task_item.item_id))
+
+
 def block_reason_for(all_open_items: list[TaskItem]) -> str:
-    """Return the block reason that lists each open item."""
-    all_item_lines = (
-        ITEM_LINE_TEMPLATE.format(subject=each_item.subject or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=each_item.item_id))
-        for each_item in all_open_items
-    )
-    return BLOCK_REASON_PREFIX + "".join(all_item_lines) + BLOCK_REASON_SUFFIX
+    """Return the block reason that lists each open item, and how to close an ask when one is open."""
+    has_open_ask = any(each_item.item_id.startswith(ASK_ID_PREFIX) for each_item in all_open_items)
+    all_item_lines = "".join(_item_line(each_item) for each_item in all_open_items)
+    return BLOCK_REASON_PREFIX + all_item_lines + BLOCK_REASON_SUFFIX + (ASK_CLOSE_SUFFIX if has_open_ask else "")
 
 
 def block_output_for(all_hook_input_fields: dict[str, object], block_reason: str) -> dict[str, str]:

package/hooks/blocking/open_tasks_transcript.py

@@ -1,11 +1,21 @@
 #!/usr/bin/env python3
 """Rebuild a session task list and its last assistant text from a transcript.
 
-The open tasks Stop gate reads three transcript shapes, replayed in order::
+The open tasks Stop gate reads four transcript shapes, replayed in order::
 
     TaskCreate / TaskUpdate calls        (Claude Code)
     TodoWrite input.todos                (Claude Code and Cursor; ``merge`` updates by id)
     update_plan function_call arguments  (Codex rollout)
+    mcp__ccd_turn__update_plan input     (Claude Code desktop plan)
+
+A desktop plan call either lists items or moves the current list::
+
+    {"items": [...], "scope": "continuation"}   -> new list, unfinished old items carried after it
+    {"done": [2], "start": 3}                    -> 1-based positions in the tool's own items
+    {"advance": true}                            -> complete the in_progress item, start the next pending
+
+Only ``assistant`` records count for a desktop plan call, because Claude Code
+also copies each call into ``api-request-blob`` records.
 
 The Cursor CLI can also reach TodoWrite through ``CallDynamicTool``, with the
 TodoWrite input under ``arguments``; that call counts as the TodoWrite call.
@@ -16,6 +26,7 @@ from __future__ import annotations
 import json
 import re
 import sys
+from datetime import datetime
 from pathlib import Path
 from typing import NamedTuple
 
@@ -24,7 +35,15 @@ if hooks_root_directory not in sys.path:
     sys.path.insert(0, hooks_root_directory)
 
 from hooks_constants.open_tasks_stop_gate_constants import (
+    ASSISTANT_RECORD_TYPE,
     ASSISTANT_ROLE,
+    CCD_PLAN_ADVANCE_KEY,
+    CCD_PLAN_CONTENT_KEY,
+    CCD_PLAN_DONE_KEY,
+    CCD_PLAN_ITEM_ID_TEMPLATE,
+    CCD_PLAN_ITEMS_KEY,
+    CCD_PLAN_START_KEY,
+    CCD_PLAN_TOOL_NAME,
     CODEX_ARGUMENTS_KEY,
     CODEX_FUNCTION_CALL_TYPE,
     CODEX_PAYLOAD_KEY,
@@ -32,14 +51,18 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     CODEX_PLAN_TOOL_NAME,
     CODEX_RESPONSE_ITEM_TYPE,
     CODEX_STEP_KEY,
+    COMPLETED_STATUS,
     CONTENT_KEY,
     CREATED_TASK_ID_GROUP_INDEX,
     DYNAMIC_TOOL_ARGUMENTS_KEY,
     DYNAMIC_TOOL_CALL_NAME,
     DYNAMIC_TOOL_NAME_KEY,
     FIRST_ITEM_NUMBER,
+    INCOMPLETE_STATUSES,
+    IN_PROGRESS_STATUS,
     MESSAGE_KEY,
     PENDING_STATUS,
+    RECORD_TIMESTAMP_KEY,
     RECORD_TYPE_KEY,
     REPLY_TEXT_SEPARATOR,
     ROLE_KEY,
@@ -61,6 +84,8 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     TOOL_RESULT_BLOCK_TYPE,
     TOOL_USE_BLOCK_TYPE,
     TOOL_USE_ID_KEY,
+    UTC_OFFSET_TEXT,
+    UTC_SUFFIX,
     UTF8_ENCODING,
     WORD_SEPARATOR,
 )
@@ -73,11 +98,31 @@ class TaskItem(NamedTuple):
         item_id: The task number or position, as text.
         subject: The item's wording.
         status: The item's status, such as ``pending`` or ``completed``.
+        listed_at: For a desktop plan item, seconds since the epoch of the last list that held it.
+        is_carried: True for a desktop plan item a replacing list left out.
     """
 
     item_id: str
     subject: str
     status: str
+    listed_at: float | None = None
+    is_carried: bool = False
+
+
+def normalized_text(text: str) -> str:
+    """Return the text lowercased with each run of whitespace collapsed to one space."""
+    return WORD_SEPARATOR.join(text.lower().split())
+
+
+def record_epoch(all_record_fields: dict[str, object]) -> float | None:
+    """Return the record's ISO ``timestamp`` as seconds since the epoch, or None."""
+    timestamp_value = all_record_fields.get(RECORD_TIMESTAMP_KEY)
+    if not isinstance(timestamp_value, str):
+        return None
+    try:
+        return datetime.fromisoformat(timestamp_value.replace(UTC_SUFFIX, UTC_OFFSET_TEXT)).timestamp()
+    except ValueError:
+        return None
 
 
 def parsed_object(json_text: str) -> dict[str, object] | None:
@@ -171,6 +216,22 @@ def codex_plan_items(all_record_fields: dict[str, object]) -> list[TaskItem] | N
     return _numbered_items(all_plan_arguments.get(CODEX_PLAN_KEY), CODEX_STEP_KEY)
 
 
+def advanced_items(all_own_items: list[TaskItem]) -> list[TaskItem]:
+    """Complete the in_progress item and start the next pending one after it, as ``advance`` does."""
+    all_advanced_items = list(all_own_items)
+    search_start = 0
+    for each_position, each_item in enumerate(all_advanced_items):
+        if each_item.status == IN_PROGRESS_STATUS:
+            all_advanced_items[each_position] = each_item._replace(status=COMPLETED_STATUS)
+            search_start = each_position + 1
+            break
+    for each_position in range(search_start, len(all_advanced_items)):
+        if all_advanced_items[each_position].status == PENDING_STATUS:
+            all_advanced_items[each_position] = all_advanced_items[each_position]._replace(status=IN_PROGRESS_STATUS)
+            break
+    return all_advanced_items
+
+
 def unwrapped_tool_call(tool_name: str, all_input_fields: dict[str, object]) -> tuple[str, dict[str, object]]:
     """Return the inner tool name and arguments of a Cursor ``CallDynamicTool`` call, or the call itself.
 
@@ -191,7 +252,10 @@ class _TranscriptReplay:
         self.latest_items: list[TaskItem] | None = None
         self.created_by_id: dict[str, TaskItem] = {}
         self.subject_by_tool_use_id: dict[str, str] = {}
+        self.plan_items: list[TaskItem] | None = None
+        self.own_plan_count = 0
         self.last_assistant_text = ""
+        self.all_assistant_texts: list[str] = []
 
     def apply_record(self, all_record_fields: dict[str, object]) -> None:
         plan_items = codex_plan_items(all_record_fields)
@@ -199,10 +263,46 @@ class _TranscriptReplay:
             self.latest_items = plan_items
             return
         all_blocks = _content_blocks(all_record_fields)
+        is_assistant_record = all_record_fields.get(RECORD_TYPE_KEY) == ASSISTANT_RECORD_TYPE
         for each_block in all_blocks:
-            self.apply_block(each_block)
+            plan_input = each_block.get(TOOL_INPUT_KEY)
+            if is_assistant_record and each_block.get(TOOL_NAME_KEY) == CCD_PLAN_TOOL_NAME and isinstance(plan_input, dict):
+                self.apply_desktop_plan(plan_input, record_epoch(all_record_fields))
+            else:
+                self.apply_block(each_block)
         self.note_assistant_text(all_record_fields, all_blocks)
 
+    def apply_desktop_plan(self, all_plan_fields: dict[str, object], listed_at: float | None) -> None:
+        all_listed_entries = all_plan_fields.get(CCD_PLAN_ITEMS_KEY)
+        if isinstance(all_listed_entries, list):
+            self.replace_desktop_plan(all_listed_entries, listed_at)
+            return
+        all_own_items = (self.plan_items or [])[: self.own_plan_count]
+        all_done_positions = all_plan_fields.get(CCD_PLAN_DONE_KEY)
+        for each_position in all_done_positions if isinstance(all_done_positions, list) else []:
+            if isinstance(each_position, int) and FIRST_ITEM_NUMBER <= each_position <= len(all_own_items):
+                all_own_items[each_position - FIRST_ITEM_NUMBER] = all_own_items[each_position - FIRST_ITEM_NUMBER]._replace(status=COMPLETED_STATUS)
+        start_position = all_plan_fields.get(CCD_PLAN_START_KEY)
+        if isinstance(start_position, int) and FIRST_ITEM_NUMBER <= start_position <= len(all_own_items):
+            all_own_items[start_position - FIRST_ITEM_NUMBER] = all_own_items[start_position - FIRST_ITEM_NUMBER]._replace(status=IN_PROGRESS_STATUS)
+        if all_plan_fields.get(CCD_PLAN_ADVANCE_KEY) is True:
+            all_own_items = advanced_items(all_own_items)
+        self.plan_items = all_own_items + (self.plan_items or [])[self.own_plan_count :]
+
+    def replace_desktop_plan(self, all_listed_entries: list[object], listed_at: float | None) -> None:
+        all_own_items = [
+            each_item._replace(item_id=CCD_PLAN_ITEM_ID_TEMPLATE.format(position=each_item.item_id), listed_at=listed_at)
+            for each_item in _numbered_items(all_listed_entries, CCD_PLAN_CONTENT_KEY)
+        ]
+        all_listed_subjects = {normalized_text(each_item.subject) for each_item in all_own_items}
+        all_carried_items = [
+            each_item._replace(is_carried=True)
+            for each_item in self.plan_items or []
+            if each_item.status in INCOMPLETE_STATUSES and normalized_text(each_item.subject) not in all_listed_subjects
+        ]
+        self.plan_items = all_own_items + all_carried_items
+        self.own_plan_count = len(all_own_items)
+
     def note_assistant_text(self, all_record_fields: dict[str, object], all_blocks: list[dict[str, object]]) -> None:
         message_body = all_record_fields.get(MESSAGE_KEY)
         message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
@@ -213,6 +313,7 @@ class _TranscriptReplay:
         ).strip()
         if record_text:
             self.last_assistant_text = record_text
+            self.all_assistant_texts.append(record_text)
 
     def apply_block(self, all_block_fields: dict[str, object]) -> None:
         block_type = all_block_fields.get(RECORD_TYPE_KEY)
@@ -252,9 +353,15 @@ class _TranscriptReplay:
         self.created_by_id[created_id] = TaskItem(created_id, created_subject, PENDING_STATUS)
 
     def items(self) -> list[TaskItem] | None:
-        if self.created_by_id:
-            return list(self.created_by_id.values())
-        return self.latest_items
+        all_sources = [
+            list(self.created_by_id.values()) if self.created_by_id else None,
+            self.latest_items,
+            self.plan_items,
+        ]
+        all_present_sources = [each_source for each_source in all_sources if each_source is not None]
+        if not all_present_sources:
+            return None
+        return [each_item for each_source in all_present_sources for each_item in each_source]
 
 
 def replayed_transcript(transcript_path: object) -> _TranscriptReplay: