claude-dev-env 8.82.1 → 8.83.1

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/hooks_constants/pull_request_proof_constants.py

@@ -24,6 +24,44 @@ MISSING_PROOF_REASON = (
     " prove the change, leave the pull request unopened and tell the user what you could"
     " not run. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
+INLINE_COMMAND_PATTERN = r"(?<!`)`([^`\n]+)`(?!`)"
+CODE_FENCE_MARKER = "```"
+FENCED_COMMAND_PROMPT = "$ "
+UNITTEST_MODULE_NAME = "unittest"
+PATH_WITH_LINE_PATTERN = r"^\S+:\d+(?:[-:]\d+)?$"
+SINGLE_FILE_NAME_PATTERN = r"^\S*[/\\]\S*$|^[\w.-]+\.[A-Za-z0-9]+$"
+ALL_PASSTHROUGH_PROGRAM_NAMES = frozenset({"tee", "tail", "head", "grep", "cat"})
+ALL_TEST_RUNNER_COMMAND_PREFIXES = frozenset(
+    {
+        ("jest",),
+        ("vitest",),
+        ("mocha",),
+        ("npm", "test"),
+        ("npm", "t"),
+        ("npm", "run", "test"),
+        ("yarn", "test"),
+        ("yarn", "run", "test"),
+        ("pnpm", "test"),
+        ("pnpm", "run", "test"),
+        ("bun", "test"),
+        ("npx", "jest"),
+        ("npx", "vitest"),
+        ("npx", "mocha"),
+        ("go", "test"),
+        ("cargo", "test"),
+        ("deno", "test"),
+        ("dotnet", "test"),
+        ("unittest",),
+    }
+)
+UNIT_TESTS_GUIDE_LINE = "Unit tests are welcome as extra evidence. The live run is the proof."
+TEST_ONLY_PROOF_REASON = (
+    "Every command under this pull request's 'Proof in practice' heading runs a test"
+    " suite. The proof rule says: \"" + UNIT_TESTS_GUIDE_LINE + "\" Run the changed thing"
+    " the way its user runs it, once without the change and once with it. List each"
+    " command in backticks and quote the output lines that show the difference. Keep the"
+    " test run in the section as extra evidence. Read " + PROOF_GUIDE_PATH + " for the full rule."
+)
 EXISTING_WORK_HEADING_PATTERN = r"^(#{1,6})[ \t]+existing work[ \t]*#*[ \t]*$"
 EXISTING_WORK_GUIDE_PATH = "~/.claude/docs/rule-guides/explore-thoroughly.md"
 MISSING_EXISTING_WORK_REASON = (

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -12,6 +12,10 @@ CARD_TEXT_SEPARATOR = "\n"
 ALL_DECISION_CARD_PROSE_KEYS = ("question", "context")
 DECISION_CARD_OPTIONS_KEY = "options"
 ALL_DECISION_OPTION_PROSE_KEYS = ("label", "consequence")
+DECISION_CARD_CONTEXT_KEY = "context"
+MAXIMUM_CARD_CONTEXT_SENTENCE_COUNT = 2
+ALL_DECISION_CARD_LENGTH_KEYS = ("question", "context", "reason")
+ALL_DECISION_OPTION_LENGTH_KEYS = ("consequence",)
 QUESTION_CARD_TOOL_NAME = "AskUserQuestion"
 QUESTION_CARD_QUESTIONS_KEY = "questions"
 ALL_QUESTION_CARD_PROSE_KEYS = ("question", "header")
@@ -41,6 +45,16 @@ WORD_SEPARATOR = " "
 SENTENCE_PREVIEW_SUFFIX = "..."
 RETRY_INSTRUCTION = " Cut the text and resend the call."
 TOO_MANY_SENTENCES_MESSAGE = "Reply too long: {sentence_count} sentences, limit {sentence_limit}."
+CARD_CONTEXT_TOO_LONG_MESSAGE = (
+    "Card context too long: {sentence_count} sentences, limit {sentence_limit}."
+)
+CARD_CONTEXT_LIST_MESSAGE = "Card context holds a list of items, and a card cannot format a list."
+CARD_LIST_ITEM_PATTERN = re.compile(r"^[ \t]*(?:[-*+]|\d+[.)])[ \t]+\S", re.MULTILINE)
+CARD_FORMAT_FLOW_INSTRUCTION = (
+    " For a list or several items, publish an Artifact page with a tap button per item"
+    " and a Send button, with the capability that republishes its state so the watching"
+    " session wakes. Then send a short reply that links the page."
+)
 UNLINKED_PULL_REQUEST_MESSAGE = 'Pull request "{reference}" has no link. Write it as [PR N](https://github.com/<owner>/<repo>/pull/N).'
 MID_SENTENCE_COLON_MESSAGE = (
     "A colon joins two clauses on one line. Write two sentences, or end the line with the colon"

package/hooks/hooks_constants/test_reply_length_gate_constants.py

@@ -51,3 +51,11 @@ def test_colon_pattern_matches_a_colon_with_prose_after_it_on_the_line() -> None
     assert constants.MID_SENTENCE_COLON_PATTERN.search("matters: one message")
     assert constants.MID_SENTENCE_COLON_PATTERN.search("at 9:47") is None
     assert constants.MID_SENTENCE_COLON_PATTERN.search("items:\n- one") is None
+
+
+def test_gate_caps_card_context_at_two_sentences_and_checks_card_length_fields() -> None:
+    assert (
+        constants.MAXIMUM_CARD_CONTEXT_SENTENCE_COUNT,
+        constants.ALL_DECISION_CARD_LENGTH_KEYS,
+        constants.ALL_DECISION_OPTION_LENGTH_KEYS,
+    ) == (2, ("question", "context", "reason"), ("consequence",))

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