claude-dev-env 8.82.0 → 8.83.0

package/bin/install.uninstall-transaction.test.mjs

@@ -76,6 +76,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
         CDE_INSTALL_SUBAGENT_MODELS: '0',
+        CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -313,6 +314,7 @@ test('uninstall fault after_git_config restores prior core.hooksPath', () => {
                 CDE_INSTALL_PSTACK: '0',
                 CDE_INSTALL_USAGE_WRAPUP: '0',
                 CDE_INSTALL_SUBAGENT_MODELS: '0',
+                CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/install.update-keeps-hooks.test.mjs

@@ -27,6 +27,7 @@ function installerEnvironment(homeDirectory) {
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
         CDE_INSTALL_SUBAGENT_MODELS: '0',
+        CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/commands/deepen.md

@@ -0,0 +1,19 @@
+---
+description: Deepen a task into the omitted expert job before work starts
+argument-hint: [task to deepen]
+---
+
+Deepen this task before any work starts: `$ARGUMENTS`
+
+When `$ARGUMENTS` is empty, ask the user to paste the task and stop.
+
+When `$ARGUMENTS` holds a task, answer four things the prompt left out:
+
+1. What a top person in that field would do that this prompt omitted.
+2. The raw source to start from.
+3. The methods and tools they would use.
+4. What besides the agent or Jon would show the result is right.
+
+Rewrite the task so it asks for exactly that job. Put `CDE_DEEPEN:v1` at the top of the rewrite. Then do only that job.
+
+Skip this command when the prompt already carries `CDE_DEEPEN:v1`.

package/hooks/features/lifecycle-cleanup.md

@@ -13,7 +13,7 @@ This family runs nested checkout hooks, refreshes a worktree base, and clears st
 
 ## When it fires
 
-- `lifecycle/nested_project_hooks.py` runs on `PreToolUse` matcher `*` at `120` seconds and `SessionStart` matcher empty at `1800` seconds in `hooks.json`.
+- `lifecycle/nested_project_hooks.py` runs on `PreToolUse` matcher `*` at `120` seconds, `UserPromptSubmit` matcher empty at `120` seconds, and `SessionStart` matcher empty at `1800` seconds in `hooks.json`.
 - `lifecycle/enter_worktree_origin_prefetch.py` runs on `PreToolUse`, matcher `EnterWorktree`, timeout `25` seconds in `hooks.json`.
 - `lifecycle/session_end_cleanup.py` runs on `SessionEnd`, matcher empty, timeout `3` seconds in `hooks.json`.
 - `session/plugin_data_dir_cleanup.py` and `session/session_env_cleanup.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.

package/hooks/features/session-context.md

@@ -9,6 +9,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/working_style_prompt.py` injects the session's working style at session start.
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
+- `session/deepen_first_prompt.py` rewrites a first interactive user task so the worker does the omitted expert job.
 - `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. A status or progress report prefers the status flowchart from `docs/templates/artifact-page/status-flowchart.html`, unless the person asks for another shape. One flow or one comparison is an inline SVG flowchart with minimal text. A multi-part plan or evidence is an html-plan page from `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
@@ -16,6 +17,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 
 - `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
 - `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, and `session/orchestrator_auto_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `session/deepen_first_prompt.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`.
 - `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
 - `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
 
@@ -30,6 +32,7 @@ Preconditions:
 - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
+- **First-task deepen.** Input is a first UserPromptSubmit task. Run `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_first_prompt.py -q`. The adjacent test observes a skip table and a rewrite that names the four omitted answers.
 - **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 

package/hooks/hooks.json

@@ -273,6 +273,16 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/deepen_first_prompt.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",
+            "timeout": 120
           }
         ]
       }

package/hooks/hooks_constants/deepen_first_prompt_constants.py

@@ -0,0 +1,119 @@
+"""Named values for first-task deepening."""
+
+from __future__ import annotations
+
+from hooks_constants.mod_handoff_constants import DEEPEN_FIRST_PROMPT_PLUGIN_NAME
+from hooks_constants.skill_loaded_reminder_constants import (
+    CLAUDE_SUBAGENT_PROMPT_PREFIX,
+    CODEX_SUBAGENT_PROMPT_PREFIX,
+)
+
+__all__ = [
+    "ADDITIONAL_CONTEXT_KEY",
+    "ALL_HELPER_REPORT_MARKERS",
+    "ALL_LOOP_PROMPT_PREFIXES",
+    "ALL_NONINTERACTIVE_ENV_TRUE_VALUES",
+    "ALL_SPAWN_REWRITE_PREFIXES",
+    "ALL_TRIVIAL_PROMPTS",
+    "CLAUDE_HOST_ENV_VAR",
+    "CLAUDE_HOST_TRUE_VALUE",
+    "DEEPEN_AGENT_MARKER",
+    "DEEPEN_COMMAND_ENV_VAR",
+    "DEEPEN_COMMAND_TIMEOUT_SECONDS",
+    "DEEPEN_FIRST_PROMPT_PLUGIN_NAME",
+    "DEEPEN_MARKER",
+    "DEEPEN_OUTPUT_ENV_VAR",
+    "DEEPEN_OUTPUT_JSON",
+    "DEEPEN_OUTPUT_REWRITE",
+    "DEEPEN_REWRITE_ENV_VAR",
+    "DEEPEN_SLASH_COMMAND",
+    "DEEPEN_TIMEOUT_SECONDS",
+    "DEEPEN_TURN_MARKER_SUFFIX",
+    "HOOK_EVENT_NAME_KEY",
+    "HOOK_SPECIFIC_OUTPUT_KEY",
+    "JSONL_ROLE_KEY",
+    "JSONL_TYPE_KEY",
+    "NONINTERACTIVE_CODEX_ENV_VAR",
+    "NONINTERACTIVE_PRINT_ENV_VAR",
+    "PROMPT_FIELD_NAME",
+    "SESSION_ID_FIELD_NAME",
+    "SKIP_DEEPEN_ENV_VAR",
+    "SKIP_DEEPEN_TRUE_VALUE",
+    "TRANSCRIPT_PATH_FIELD_NAME",
+    "USER_PROMPT_SUBMIT_EVENT_NAME",
+    "USER_ROLE_NAME",
+    "USER_TYPE_NAME",
+    "UTF8_ENCODING",
+]
+
+DEEPEN_MARKER: str = "CDE_DEEPEN:v1"
+DEEPEN_AGENT_MARKER: str = "CDE_DEEPEN_AGENT"
+DEEPEN_SLASH_COMMAND: str = "/deepen"
+DEEPEN_TURN_MARKER_SUFFIX: str = ".cde-deepen-turn1"
+DEEPEN_TIMEOUT_SECONDS: int = 10
+DEEPEN_COMMAND_TIMEOUT_MARGIN_SECONDS: int = 2
+DEEPEN_COMMAND_TIMEOUT_SECONDS: int = DEEPEN_TIMEOUT_SECONDS - DEEPEN_COMMAND_TIMEOUT_MARGIN_SECONDS
+USER_PROMPT_SUBMIT_EVENT_NAME: str = "UserPromptSubmit"
+PROMPT_FIELD_NAME: str = "prompt"
+TRANSCRIPT_PATH_FIELD_NAME: str = "transcript_path"
+SESSION_ID_FIELD_NAME: str = "session_id"
+HOOK_SPECIFIC_OUTPUT_KEY: str = "hookSpecificOutput"
+HOOK_EVENT_NAME_KEY: str = "hookEventName"
+ADDITIONAL_CONTEXT_KEY: str = "additionalContext"
+SKIP_DEEPEN_ENV_VAR: str = "CDE_SKIP_DEEPEN"
+SKIP_DEEPEN_TRUE_VALUE: str = "1"
+DEEPEN_REWRITE_ENV_VAR: str = "CDE_DEEPEN_REWRITE"
+DEEPEN_COMMAND_ENV_VAR: str = "CDE_DEEPEN_COMMAND"
+DEEPEN_OUTPUT_ENV_VAR: str = "CDE_DEEPEN_OUTPUT"
+DEEPEN_OUTPUT_REWRITE: str = "rewrite"
+DEEPEN_OUTPUT_JSON: str = "json"
+NONINTERACTIVE_PRINT_ENV_VAR: str = "CLAUDE_CODE_NONINTERACTIVE"
+NONINTERACTIVE_CODEX_ENV_VAR: str = "CODEX_EXEC"
+CLAUDE_HOST_ENV_VAR: str = "CLAUDECODE"
+CLAUDE_HOST_TRUE_VALUE: str = "1"
+ALL_NONINTERACTIVE_ENV_TRUE_VALUES: frozenset[str] = frozenset({"1", "true", "yes"})
+UTF8_ENCODING: str = "utf-8"
+JSONL_TYPE_KEY: str = "type"
+JSONL_ROLE_KEY: str = "role"
+USER_TYPE_NAME: str = "user"
+USER_ROLE_NAME: str = "user"
+
+ALL_TRIVIAL_PROMPTS: frozenset[str] = frozenset(
+    {
+        "yes",
+        "y",
+        "no",
+        "n",
+        "ok",
+        "okay",
+        "thanks",
+        "thank you",
+        "thx",
+        "status",
+        "hello",
+        "hi",
+        "hey",
+        "k",
+        "sure",
+        "continue",
+        "go",
+        "?",
+    }
+)
+
+ALL_LOOP_PROMPT_PREFIXES: tuple[str, ...] = (
+    "/loop",
+    "<scheduled-task",
+    "scheduled task firing",
+)
+
+ALL_HELPER_REPORT_MARKERS: tuple[str, ...] = (
+    "<task-notification",
+    "background subagent reporting",
+    "a message another session sends",
+)
+
+ALL_SPAWN_REWRITE_PREFIXES: tuple[str, ...] = (
+    CLAUDE_SUBAGENT_PROMPT_PREFIX,
+    CODEX_SUBAGENT_PROMPT_PREFIX,
+)

package/hooks/hooks_constants/mod_handoff_constants.py

@@ -14,6 +14,7 @@ __all__ = [
     "ENABLED_PLUGINS_SETTINGS_KEY",
     "PLUGIN_MARKETPLACE_SEPARATOR",
     "PROJECT_SETTINGS_DIRECTORY_NAME",
+    "DEEPEN_FIRST_PROMPT_PLUGIN_NAME",
     "SESSION_PROMPTS_PLUGIN_NAME",
     "SHELL_GUARDS_PLUGIN_NAME",
     "USER_SETTINGS_FILE_NAME",
@@ -23,6 +24,7 @@ ENABLED_PLUGINS_SETTINGS_KEY = "enabledPlugins"
 PLUGIN_MARKETPLACE_SEPARATOR = "@"
 SHELL_GUARDS_PLUGIN_NAME = "shell-guards"
 SESSION_PROMPTS_PLUGIN_NAME = "session-prompts"
+DEEPEN_FIRST_PROMPT_PLUGIN_NAME = "deepen-first-prompt"
 CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
 CLAUDE_PROJECT_DIR_ENV_VAR = "CLAUDE_PROJECT_DIR"
 DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"

package/hooks/hooks_constants/nested_project_hooks_constants.py

@@ -20,9 +20,11 @@ ALL_MATCH_EVERYTHING_MATCHERS: frozenset[str] = frozenset({"", "*"})
 HOOK_EVENT_NAME_KEY: str = "hook_event_name"
 PRE_TOOL_USE_EVENT: str = "PreToolUse"
 SESSION_START_EVENT: str = "SessionStart"
+USER_PROMPT_SUBMIT_EVENT: str = "UserPromptSubmit"
 ALL_MATCH_TARGET_KEYS_BY_EVENT: dict[str, str] = {
     PRE_TOOL_USE_EVENT: "tool_name",
     SESSION_START_EVENT: "source",
+    USER_PROMPT_SUBMIT_EVENT: "prompt",
 }
 
 ALL_SHELL_PROGRAM_NAMES: tuple[str, ...] = ("bash", "sh")

package/hooks/lifecycle/nested_project_hooks.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python3
-"""SessionStart and PreToolUse hook: run the hooks of checkouts nested one level down.
+"""SessionStart, UserPromptSubmit, and PreToolUse hook: run nested checkout hooks.
 
 Claude Code reads project hooks from ``<project>/.claude/settings.json`` of the
 directory a session starts in. A cloud session that holds several repository
 checkouts starts in their parent directory, which has no settings of its own,
-and ``--add-dir`` loads no hooks from the checkouts. Their start hooks and tool
-guards then never run. This hook runs them::
+and ``--add-dir`` loads no hooks from the checkouts. Their start hooks, first
+prompt deepeners, and tool guards then never run. This hook runs them::
 
     session directory (no .git, no .claude/settings.json)
     |-- checkout-a/.claude/settings.json   hooks run with CLAUDE_PROJECT_DIR=checkout-a
@@ -15,7 +15,7 @@ Each child hook receives the same stdin payload, runs inside its checkout, and
 keeps its own matcher and timeout. A child ``exit 2`` blocks the tool call and a
 child ``deny`` or ``ask`` decision passes through; a child ``allow`` is dropped,
 so no child widens permissions for the session. The ``additionalContext`` of
-every child, at SessionStart and at PreToolUse, joins into one
+every child, at SessionStart, UserPromptSubmit, and PreToolUse, joins into one
 ``additionalContext``.
 
 When the session directory is itself a checkout or holds its own settings,
@@ -342,13 +342,15 @@ def _non_empty_sections(all_sections: Iterable[str]) -> list[str]:
     return [each_section for each_section in all_sections if each_section]
 
 
-def session_start_verdict(
+def additional_context_verdict(
     all_results: list[subprocess.CompletedProcess[str]],
+    event_name: str,
 ) -> HookVerdict:
-    """Join nested SessionStart output into one additional-context block.
+    """Join nested hook output into one additional-context block.
 
     Args:
         all_results: The completed nested hooks, in run order.
+        event_name: The envelope event name Claude Code expects.
 
     Returns:
         A pass whose stdout carries every child's context, or an empty pass
@@ -364,13 +366,20 @@ def session_start_verdict(
         return HookVerdict(0, "", stderr_text)
     hook_output = {
         HOOK_SPECIFIC_OUTPUT_KEY: {
-            HOOK_EVENT_NAME_OUTPUT_KEY: SESSION_START_EVENT,
+            HOOK_EVENT_NAME_OUTPUT_KEY: event_name,
             ADDITIONAL_CONTEXT_KEY: CONTEXT_SECTION_SEPARATOR.join(all_context_sections),
         }
     }
     return HookVerdict(0, json.dumps(hook_output), stderr_text)
 
 
+def session_start_verdict(
+    all_results: list[subprocess.CompletedProcess[str]],
+) -> HookVerdict:
+    """Join nested SessionStart output into one additional-context block."""
+    return additional_context_verdict(all_results, SESSION_START_EVENT)
+
+
 def _completed_results(
     all_nested_hooks: list[NestedHook], payload_text: str
 ) -> list[subprocess.CompletedProcess[str]]:
@@ -402,7 +411,7 @@ def forward_nested_hooks(session_directory: Path, payload_text: str) -> HookVerd
     all_results = _completed_results(all_nested_hooks, payload_text)
     if event_name == PRE_TOOL_USE_EVENT:
         return pre_tool_use_verdict(all_results)
-    return session_start_verdict(all_results)
+    return additional_context_verdict(all_results, event_name)
 
 
 def main() -> None:

package/hooks/lifecycle/test_nested_project_hooks.py

@@ -62,6 +62,10 @@ def _session_start_payload() -> dict[str, object]:
     return {"hook_event_name": "SessionStart", "source": "startup"}
 
 
+def _user_prompt_submit_payload(prompt: str) -> dict[str, object]:
+    return {"hook_event_name": "UserPromptSubmit", "prompt": prompt}
+
+
 def test_should_run_a_child_session_start_hook_inside_that_child(
     tmp_path: pathlib.Path,
 ) -> None:
@@ -352,6 +356,52 @@ def test_should_let_the_call_through_when_a_child_hook_fails_to_start(
     assert completed_process.returncode == 0
 
 
+def test_should_carry_child_user_prompt_submit_output_as_additional_context(
+    tmp_path: pathlib.Path,
+) -> None:
+    context_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "CDE_DEEPEN:v1\nTreat the submitted prompt as this rewritten task.",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {
+            "UserPromptSubmit": [
+                _command_group("", f"echo '{json.dumps(context_output)}'")
+            ]
+        },
+    )
+
+    completed_process = _run_hook(
+        tmp_path, _user_prompt_submit_payload("Add dark mode to the settings page")
+    )
+
+    assert completed_process.returncode == 0
+    hook_output = json.loads(completed_process.stdout)
+    assert hook_output["hookSpecificOutput"]["hookEventName"] == "UserPromptSubmit"
+    assert "CDE_DEEPEN:v1" in hook_output["hookSpecificOutput"]["additionalContext"]
+
+
+def test_should_stay_quiet_on_an_event_it_does_not_forward(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"SessionStart": [_command_group("", "echo should not run")]},
+    )
+
+    completed_process = _run_hook(
+        tmp_path, {"hook_event_name": "SessionEnd", "prompt": "Add dark mode"}
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout.strip() == ""
+
+
 @pytest.mark.parametrize("unreadable_settings", ["{not json", "[]", '{"hooks": []}'])
 def test_should_skip_a_child_whose_settings_cannot_be_read(
     tmp_path: pathlib.Path, unreadable_settings: str