claude-dev-env 8.68.4 → 8.69.1

package/.agents/skills/correction/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: correction
-description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake. Use when the user types /correction followed by what the agent got wrong.
-argument-hint: "<what the agent got wrong, in the user's words>"
+description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake, or land the fix in this session with the fix playbook. Use when the user types /correction followed by what the agent got wrong, or /correction fix to land the fix here.
+argument-hint: "[fix] <what the agent got wrong, in the user's words>"
 ---
 
 # /correction
 
-The user corrected an agent and wants the fix to stick. Write one brief they can paste into the place that turns corrections into lasting fixes.
+The user corrected an agent and wants the fix to stick. Write one brief that records the correction. By default the user pastes it into the place that turns corrections into lasting fixes. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself.
 
-`$ARGUMENTS` is the user's statement of the correction. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
+`$ARGUMENTS` is the user's statement of the correction, after a leading `fix` when one is present. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
 
-Print the brief as one fenced `text` block, and nothing after it:
+Print the brief as one fenced `text` block:
 
 ```text
-Correction: <$ARGUMENTS, word for word>
+Correction: <$ARGUMENTS word for word, minus a leading fix>
 Asked: <what the user asked for, quoted where a message carries it>
 Agent did: <what the agent did, with the reply, file, or command that shows it>
 Corrected to: <what the user wanted instead, or the fix already made>
@@ -22,4 +22,18 @@ Evidence: <file:line, log line, or quoted message that shows the miss>
 Repeat: <yes, with the earlier time it happened | no | unknown>
 ```
 
-Keep each field to one or two lines. Leave out the layer and the fix design; the intake decides those.
+Keep each field to one or two lines. Leave out the layer and the fix design; the intake or the fix playbook decides those.
+
+## Playbooks
+
+| Mode | What follows the brief |
+|---|---|
+| Hand off, the default | Nothing. The brief is the whole reply. |
+| `fix` | Read [`playbooks/fix.md`](playbooks/fix.md) right after the brief, and run its steps from step 2. |
+
+## Layout
+
+| File | What it holds |
+|---|---|
+| `SKILL.md` | The brief and the playbook index |
+| `playbooks/fix.md` | The steps that land one correction as a control and a pull request in this session |

package/.agents/skills/correction/playbooks/fix.md

@@ -0,0 +1,14 @@
+# Fix
+
+Use this playbook when this session lands the fix for the correction itself. One correction gets one control and one pull request.
+
+1. Write the brief from [`../SKILL.md`](../SKILL.md) first. It is the record every later step reads.
+2. When pstack is loaded, invoke `/pstack:poteto-mode`, then `/correct`. Point `/correct` at the brief's mistake alone, and skip its sweep of the whole repository.
+3. Read the correction instructions of the repository the mistake happened in. Open each `AGENTS.md` or `CLAUDE.md` index line that names corrections, and any intake note it points to. Where they name the target repository, the proof, or the run route, they win over this playbook.
+4. Search for an existing control: a rule, hook, lint, test, or skill that already names this mistake. A control that exists and still let the mistake through makes this a repeat.
+5. Choose the layer with [`correction-lens.md`](../../../../docs/rule-guides/correction-lens.md). When `Repeat` is `yes`, or step 4 found a control, go one layer above the one that failed.
+6. Land the control in the repository whose code, CI, or agents it guards, per the guide's "Where the control lands" section. When that repository is not in this session, add it. When it cannot be added, print the brief, name the missing repository, and stop.
+7. Prove the control. Show it fail on the mistake from the brief's `Evidence` line, then pass with the change, per [`falsify-before-green.md`](../../../../rules/falsify-before-green.md) and [`proof-before-pull-request.md`](../../../../rules/proof-before-pull-request.md). Without that proof, open no pull request.
+8. Open the pull request through `pr-lifecycle`. Put the brief, the layer, and both proof results in the body.
+
+**Reply:** the layer chosen, why each higher layer cannot hold the lesson, and the pull request link.

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -25,7 +25,9 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small
 **Prove the change where it runs before you open the pull request.** The body carries a
 "Proof in practice" section with each command you ran and its quoted output. A hook denies
 a new pull request without one. Read `~/.claude/docs/rule-guides/proof-before-pull-request.md`
-before you plan the proof run.
+before you plan the proof run. A `feat` pull request also needs an "Eval" section and a
+session that invoked `/claude-api build-eval`; read
+`~/.claude/docs/rule-guides/features-start-with-an-eval.md` before you build the feature.
 
 **Open every pull request ready for review.** Pass `--draft` only when the owner asks
 for a draft.

package/.agents/skills/second-account-workers/SKILL.md

@@ -3,7 +3,8 @@ name: second-account-workers
 description: >-
   Run local headless Claude workers through the account picker.
   Triggers: spawn a worker on the second account or another extra account, offload a worker,
-  use a named Claude profile, save main account usage.
+  use a named Claude profile, save main account usage, run a local orchestrator that spawns
+  and watches Claude workers.
 ---
 
 # Extra account workers
@@ -22,8 +23,9 @@ JSON list of profile names, with the first choice first. Names use letters,
 digits, hyphens, and underscores. The worker uses the existing second profile
 when the file is absent. When the file exists, its list sets the full order.
 Keep `main` and `wait` out of the list because they name picker decisions.
-The picker ranks main and every extra profile by room left and picks the one
-with the most.
+The picker keeps each account that has room and gives the job to the first one
+listed in `claude-account-order.json` in the main Claude home. Unlisted accounts
+follow, by most room left.
 For direct picker calls, `--second-config-dir` sets the first extra profile and
 each `--extra-config-dir` adds another in the order given.
 Picker JSON prints `config_dir` for the choice and meters under `main`, `second`,
@@ -47,6 +49,13 @@ worker_exit=$?
 cat "<report>"
 ```
 
+Add `--live-log "<events.jsonl>"` to watch the worker while it runs. The worker
+then writes one JSON event per line into that file as it happens. Every event
+carries the `session_id`, from the first startup hook line on. Each `assistant` line names the tool
+calls and text, and the last line is the `result` event. Read new lines with
+`tail -n 20 "<events.jsonl>"` and skip screenshots unless a check needs to see
+the screen.
+
 Read the JSON report and worker log after the process ends. The JSON fields are
 `account`, `reason`, `exit_code`, `duration_seconds`, `result`, and `is_error`.
 The runner writes one summary line with the selected account, exit code, and
@@ -83,3 +92,12 @@ Blocked: <open issue, or none>
 
 Keep the owned file list closed. Name the worktree path with `--cwd` and use a
 separate brief and report path for each worker.
+
+## Run a local orchestrator
+
+To save usage in a long session, start one local orchestrator worker and let it
+spawn the other workers. Give it its own brief that names each worker brief,
+worktree, report path and live log. It launches each worker with the command
+above in the background, reads the live logs to follow progress, and reads each
+report at the end. Each spawn goes through the picker, so every worker lands on
+the account with the most weekly room at its start.

package/docs/rule-guides/features-start-with-an-eval.md

@@ -0,0 +1,40 @@
+Back to the [rule entry](../../rules/features-start-with-an-eval.md).
+
+# Features start with an eval
+
+**When this applies:** A user asks for a new feature or a change in behavior, in any project.
+
+## What counts
+
+A feature is behavior a user or a caller can see that did not exist before, or that now works differently: a command, a flag, a page, an endpoint, a hook, a rule, a skill, a report, or an integration. A bug fix that restores intended behavior, a rename, a refactor, a docs edit, a question, a test run, and speed work that leaves the output the same are not features.
+
+An eval is three things for one feature: a set of input cases with their expected results, a runner that drives the feature through the entry point its users call, and a grader that scores each output. A test suite counts when it does all three for that feature.
+
+## Rule
+
+1. Make the Skill tool call with skill `claude-api` and args `build-eval` your first action on the ask. A user who types `/claude-api build-eval` has made the same call.
+2. Run the existing-work search from [`explore-thoroughly.md`](../../rules/explore-thoroughly.md) next. The guide's own first step also looks for cases, graders, and runners that exist.
+3. Follow the guide the skill loads. It asks the user to approve the inputs and the grading method, and to approve the cost before the first paid run. Ask through the session's question tool. Where the host says to keep working while a question waits, continue on the option you recommended and change course if the answer differs.
+4. Run the eval before the change to get a baseline, build the feature, and run it again.
+5. Give the pull request an "Eval" section. Name the cases and the grader, give the command that runs the eval in backticks, and quote the baseline and the result.
+
+## An existing feature with no eval
+
+When your work touches an existing feature, look for its eval. When it has none, start a separate session that builds it, and keep doing your own work while that session runs. Your own feature still starts with its own eval.
+
+- In a Claude project thread, call `send_message` with the coordinator's session id from `get_channel_session_id`, and ask it to start a thread for the eval. A thread session has no `start_thread_session`, so the coordinator starts that thread.
+- In a project's coordinator session, call `start_thread_session` with the brief.
+- In a command-line session, start a headless session through the account broker: `python ~/.claude/scripts/account_broker.py run --product claude --report <report.json> -- claude -p "<brief>" --model <model> --effort <level>`.
+
+The brief names the feature, its entry point, and the first step, the `claude-api` skill with args `build-eval`. An Agent-tool subagent is not a separate session. It shares your context window and ends with your turn.
+
+You own that session's result. Check its pull request, and link it from your own pull request's "Eval" section.
+
+## Enforcement
+
+`hooks/blocking/pull_request_proof.py` reads each new pull request before it opens, through `pr_lifecycle_skill_gate.py`. A new pull request is a `gh pr create` command, a GitHub MCP create call, or a GitHub MCP `run_workflow` dispatch whose inputs name a `head` branch and a `title`, because that workflow opens the pull request. A pull request whose title starts with `feat` (`feat:`, `feat(scope):`, `feat!:`) is denied when:
+
+- its body has no "Eval" heading, or the text under that heading names no command in backticks;
+- the session's transcript is readable and shows no `claude-api` Skill call with args `build-eval`, and no `/claude-api build-eval` command.
+
+The gate checks that the section and the call are there. Whether the eval measures the feature stays a judgment for the author and the reviewer. The order of the first action and the separate session for an existing feature are not checked by a hook, so the agent applies them.

package/hooks/blocking/followup_pr_dedupe.py

@@ -19,16 +19,20 @@ from hooks_constants.followup_pr_dedupe_constants import (
     ALL_BODY_FILE_OPTIONS,
     ALL_BODY_OPTIONS,
     ALL_REPOSITORY_OPTIONS,
+    ALL_TITLE_OPTIONS,
     CREATE_PULL_REQUEST_TOOL_SUFFIX,
     DUPLICATE_FOLLOWUP_REASON_TEMPLATE,
     FOLLOWUP_PARENT_PATTERN,
     ALL_GH_CREATE_WORDS,
     ALL_GIT_REMOTE_COMMAND_WORDS,
+    ALL_PULL_REQUEST_DISPATCH_INPUT_KEYS,
     GITHUB_API_ROOT,
     GITHUB_REMOTE_PATTERN,
     OPEN_PULL_REQUESTS_PATH_TEMPLATE,
     READ_TIMEOUT_SECONDS,
+    RUN_WORKFLOW_METHOD,
     STANDARD_INPUT_PATH,
+    WORKFLOW_DISPATCH_TOOL_SUFFIX,
 )
 from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
 from hooks_constants.pytest_invocation import unquoted_token
@@ -99,6 +103,18 @@ def body_from_arguments(all_arguments: list[str], working_directory: str) -> str
         return None
 
 
+def title_from_arguments(all_arguments: list[str]) -> str | None:
+    """Return the title a gh-style argument list passes, or None when it passes none.
+
+    ::
+
+        ["--title", "feat: x"] -> "feat: x"
+        ["-t=fix: y"]          -> "fix: y"
+        ["--fill"]             -> None
+    """
+    return _option_value(all_arguments, ALL_TITLE_OPTIONS)
+
+
 def _origin_repository(working_directory: str) -> tuple[str, str] | None:
     try:
         completed = subprocess.run(
@@ -146,19 +162,53 @@ def _shell_draft(command: str, working_directory: str) -> PullRequestDraft | Non
     return next((each_draft for each_draft in all_drafts if each_draft is not None), None)
 
 
-def pull_request_draft(all_payload_fields: Mapping[str, object]) -> PullRequestDraft | None:
-    """Return the pull request a PreToolUse payload is about to open, or None."""
+def _dispatch_fields(all_tool_input_fields: Mapping[str, object]) -> dict[str, object] | None:
+    all_inputs = all_tool_input_fields.get("inputs")
+    if all_tool_input_fields.get("method") != RUN_WORKFLOW_METHOD or not isinstance(all_inputs, dict):
+        return None
+    if not all(isinstance(all_inputs.get(each_key), str) for each_key in ALL_PULL_REQUEST_DISPATCH_INPUT_KEYS):
+        return None
+    return {**all_inputs, "owner": all_tool_input_fields.get("owner"), "repo": all_tool_input_fields.get("repo")}
+
+
+def create_tool_fields(all_payload_fields: Mapping[str, object]) -> Mapping[str, object] | None:
+    """Return the fields a GitHub MCP call that opens a pull request carries, or None.
+
+    ::
+
+        create_pull_request {owner, repo, title, body}       -> those fields
+        actions_run_trigger run_workflow, head and title in   -> the inputs, owner and repo
+        actions_run_trigger whose inputs name no head         -> None
+
+    A dispatch whose inputs name a head branch and a title runs a workflow
+    that opens the pull request, so it counts as a create call.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+
+    Returns:
+        The owner, repo, title, body and head keys the call names, or None.
+    """
     tool_name = all_payload_fields.get("tool_name")
     tool_input = all_payload_fields.get("tool_input")
     if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
         return None
     if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
-        owner, repo, body = (tool_input.get(each_key) for each_key in ("owner", "repo", "body"))
+        return tool_input
+    return _dispatch_fields(tool_input) if tool_name.endswith(WORKFLOW_DISPATCH_TOOL_SUFFIX) else None
+
+
+def pull_request_draft(all_payload_fields: Mapping[str, object]) -> PullRequestDraft | None:
+    """Return the pull request a PreToolUse payload is about to open, or None."""
+    create_fields = create_tool_fields(all_payload_fields)
+    if create_fields is not None:
+        owner, repo, body = (create_fields.get(each_key) for each_key in ("owner", "repo", "body"))
         if isinstance(owner, str) and isinstance(repo, str) and isinstance(body, str):
             return PullRequestDraft(owner, repo, body)
         return None
-    command = tool_input.get("command")
-    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+    tool_input = all_payload_fields.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
         return None
     working_directory = all_payload_fields.get("cwd")
     return _shell_draft(command, working_directory if isinstance(working_directory, str) else "")

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -6,6 +6,7 @@ import json
 import re
 import shlex
 import sys
+from collections.abc import Callable, Iterable
 from pathlib import Path
 
 hooks_directory = str(Path(__file__).resolve().parent.parent)
@@ -15,6 +16,7 @@ if hooks_directory not in sys.path:
 from hooks_constants.pr_lifecycle_skill_gate_constants import (
     AGENT_ID_FIELD,
     AGENT_ID_PATTERN,
+    ALL_BUILD_EVAL_SKILL_NAMES,
     ALL_API_ACTION_NAMES,
     ALL_COMMAND_PREFIX_WORDS,
     ALL_GITHUB_MCP_TOOL_SUFFIXES,
@@ -23,6 +25,8 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     ALL_SHELL_WRAPPER_EXECUTABLES,
     ALL_SLASH_COMMAND_MARKERS,
     ALL_TRANSCRIPT_PATH_FIELDS,
+    BUILD_EVAL_ARGUMENT_WORD,
+    BUILD_EVAL_COMMAND_MARKER,
     COMMAND_SEPARATORS,
     COMMAND_WHITESPACE,
     DENY_DECISION,
@@ -52,13 +56,19 @@ from hooks_constants.hook_specific_output_keys import (
 )
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
-from blocking.followup_pr_dedupe import duplicate_followup_reason
+from blocking.followup_pr_dedupe import create_tool_fields, duplicate_followup_reason
 from blocking.pull_request_proof import (
+    is_feature_pull_request,
+    missing_eval_section_reason,
     missing_existing_work_reason,
     missing_look_reason,
     missing_proof_reason,
 )
-from transcript_skill_scan import is_skill_loaded_after_last_compaction
+from hooks_constants.pull_request_proof_constants import MISSING_BUILD_EVAL_REASON
+from transcript_skill_scan import (
+    invokes_skill_with_argument,
+    is_skill_loaded_after_last_compaction,
+)
 
 
 def _command_segments(command: str) -> list[list[str]]:
@@ -169,7 +179,7 @@ def _is_governed_action(all_payload_fields: dict[str, object]) -> bool:
     tool_name = all_payload_fields.get("tool_name")
     if not isinstance(tool_name, str):
         return False
-    if tool_name.endswith(ALL_GITHUB_MCP_TOOL_SUFFIXES):
+    if tool_name.endswith(ALL_GITHUB_MCP_TOOL_SUFFIXES) or create_tool_fields(all_payload_fields) is not None:
         return True
     if tool_name not in SHELL_TOOL_NAMES:
         return False
@@ -177,16 +187,29 @@ def _is_governed_action(all_payload_fields: dict[str, object]) -> bool:
     return isinstance(tool_input, dict) and isinstance(tool_input.get("command"), str) and _matches_shell_command(tool_input["command"])
 
 
-def _transcript_load_status(path: str) -> bool | None:
+def _scanned_transcript(path: str, scan: Callable[[Iterable[str]], bool]) -> bool | None:
     try:
         with open(path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY) as transcript:
-            return is_skill_loaded_after_last_compaction(
-                transcript, (SKILL_NAME,), ALL_SLASH_COMMAND_MARKERS
-            )
+            return scan(transcript)
     except OSError:
         return None
 
 
+def _shows_skill_load(all_transcript_lines: Iterable[str]) -> bool:
+    return is_skill_loaded_after_last_compaction(
+        all_transcript_lines, (SKILL_NAME,), ALL_SLASH_COMMAND_MARKERS
+    )
+
+
+def _shows_build_eval(all_transcript_lines: Iterable[str]) -> bool:
+    return invokes_skill_with_argument(
+        all_transcript_lines,
+        ALL_BUILD_EVAL_SKILL_NAMES,
+        BUILD_EVAL_ARGUMENT_WORD,
+        BUILD_EVAL_COMMAND_MARKER,
+    )
+
+
 def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | None:
     session_path = all_payload_fields.get(SESSION_TRANSCRIPT_PATH_FIELD)
     agent_id = all_payload_fields.get(AGENT_ID_FIELD)
@@ -203,7 +226,17 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for an unloaded skill, a new pull request with no proof or existing-work section, or a second follow-up.
+    """Return a deny for the first rule a pull request action breaks, else None.
+
+    ::
+
+        pr-lifecycle skill not loaded                     -> DENY_REASON
+        new pull request with no proof section            -> MISSING_PROOF_REASON
+        new pull request with no existing-work section    -> MISSING_EXISTING_WORK_REASON
+        feature pull request with no eval section         -> MISSING_EVAL_SECTION_REASON
+        changed page whose proof shows no picture         -> MISSING_LOOK_REASON
+        feature pull request, no /claude-api build-eval   -> MISSING_BUILD_EVAL_REASON
+        second follow-up pull request for one parent      -> DUPLICATE_FOLLOWUP_REASON_TEMPLATE
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -218,23 +251,41 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     search_reason = missing_existing_work_reason(all_payload_fields)
     if search_reason is not None:
         return _deny(search_reason)
+    eval_reason = missing_eval_section_reason(all_payload_fields)
+    if eval_reason is not None:
+        return _deny(eval_reason)
     look_reason = missing_look_reason(all_payload_fields)
     if look_reason is not None:
         return _deny(look_reason)
+    if is_feature_pull_request(all_payload_fields) and _is_build_eval_missing(all_payload_fields):
+        return _deny(MISSING_BUILD_EVAL_REASON)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)
 
 
-def _is_skill_unloaded(all_payload_fields: dict[str, object]) -> bool:
+def _transcript_paths(all_payload_fields: dict[str, object]) -> list[str]:
     paths = [all_payload_fields.get(field) for field in ALL_TRANSCRIPT_PATH_FIELDS]
     paths.append(_subagent_transcript_path(all_payload_fields))
-    readable_paths = list(dict.fromkeys(path for path in paths if isinstance(path, str) and path))
+    return list(dict.fromkeys(path for path in paths if isinstance(path, str) and path))
+
+
+def _is_skill_unloaded(all_payload_fields: dict[str, object]) -> bool:
+    readable_paths = _transcript_paths(all_payload_fields)
     if not readable_paths:
         return False
-    statuses = [_transcript_load_status(path) for path in readable_paths]
+    statuses = [_scanned_transcript(path, _shows_skill_load) for path in readable_paths]
     return not any(status is None or status for status in statuses)
 
 
+def _is_build_eval_missing(all_payload_fields: dict[str, object]) -> bool:
+    all_statuses = [
+        _scanned_transcript(each_path, _shows_build_eval)
+        for each_path in _transcript_paths(all_payload_fields)
+    ]
+    all_read_statuses = [each_status for each_status in all_statuses if each_status is not None]
+    return bool(all_read_statuses) and not any(all_read_statuses)
+
+
 def _deny(reason: str) -> dict[str, object]:
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {

package/hooks/blocking/pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section."""
+"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section, or a feature pull request whose body lacks an 'Eval' section."""
 
 from __future__ import annotations
 
@@ -6,13 +6,14 @@ import re
 import subprocess
 import sys
 from collections.abc import Mapping
+from typing import NamedTuple
 from pathlib import Path
 
 hooks_directory = str(Path(__file__).resolve().parent.parent)
 if hooks_directory not in sys.path:
     sys.path.insert(0, hooks_directory)
 
-from blocking.followup_pr_dedupe import body_from_arguments
+from blocking.followup_pr_dedupe import body_from_arguments, create_tool_fields, title_from_arguments
 from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
 from hooks_constants.pull_request_proof_constants import (
     ALL_GH_CREATE_WORDS,
@@ -20,16 +21,18 @@ from hooks_constants.pull_request_proof_constants import (
     ALL_VISIBLE_FILE_SUFFIXES,
     CHANGED_FILES_SEPARATOR,
     COMMAND_MARKER,
-    CREATE_PULL_REQUEST_TOOL_SUFFIX,
     ALL_DEFAULT_BRANCH_REFERENCES,
     ALL_HEAD_FLAGS,
     HEAD_FLAG_ASSIGNMENT_PREFIX,
     REMOTE_BRANCH_PREFIX,
     UNREADABLE_CHANGES_REASON,
+    EVAL_HEADING_PATTERN,
     EXISTING_WORK_HEADING_PATTERN,
+    FEATURE_TITLE_PATTERN,
     GIT_TIMEOUT_SECONDS,
     LINE_SEPARATOR,
     MISSING_BODY_REASON,
+    MISSING_EVAL_SECTION_REASON,
     MISSING_EXISTING_WORK_REASON,
     MISSING_LOOK_REASON,
     MISSING_PROOF_REASON,
@@ -48,6 +51,13 @@ from hooks_constants.shell_command_wrappers import (
 )
 
 
+class CreateCall(NamedTuple):
+    """The title and body one pull request create call passes; None marks a value this gate cannot read."""
+
+    title: str | None
+    body: str | None
+
+
 def _heading_level(line: str, heading_pattern: str) -> int | None:
     heading = re.match(heading_pattern, line.strip(), re.IGNORECASE)
     return None if heading is None else len(heading.group(1))
@@ -120,9 +130,12 @@ def _create_arguments(all_segment_tokens: list[str]) -> list[str] | None:
     return _script_create_arguments(program, all_arguments)
 
 
-def _shell_create_bodies(command: str, working_directory: str) -> list[str | None]:
+def _shell_create_calls(command: str, working_directory: str) -> list[CreateCall]:
     return [
-        body_from_arguments(all_create_arguments, working_directory)
+        CreateCall(
+            title_from_arguments(all_create_arguments),
+            body_from_arguments(all_create_arguments, working_directory),
+        )
         for each_text in all_wrapped_command_texts(command)
         for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
         if (all_create_arguments := _create_arguments(each_segment)) is not None
@@ -139,13 +152,12 @@ def _head_flag_value(all_create_arguments: list[str]) -> str | None:
 
 
 def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
-    tool_input = all_payload_fields.get("tool_input")
-    if not isinstance(tool_input, dict):
-        return None
-    head_branch = tool_input.get("head")
+    create_fields = create_tool_fields(all_payload_fields)
+    head_branch = None if create_fields is None else create_fields.get("head")
     if isinstance(head_branch, str):
         return head_branch
-    command = tool_input.get("command")
+    tool_input = all_payload_fields.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
     if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
         return None
     all_head_flag_values = [
@@ -157,23 +169,77 @@ def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
     return next((each_value for each_value in all_head_flag_values if each_value), None)
 
 
-def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
-    tool_name = all_payload_fields.get("tool_name")
+def _create_calls(all_payload_fields: Mapping[str, object]) -> list[CreateCall]:
+    create_fields = create_tool_fields(all_payload_fields)
+    if create_fields is not None:
+        title = create_fields.get("title")
+        body = create_fields.get("body")
+        return [
+            CreateCall(
+                title if isinstance(title, str) else None,
+                body if isinstance(body, str) else "",
+            )
+        ]
     tool_input = all_payload_fields.get("tool_input")
-    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
-        return []
-    if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
-        body = tool_input.get("body")
-        return [body if isinstance(body, str) else ""]
-    command = tool_input.get("command")
-    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
         return []
     working_directory = all_payload_fields.get("cwd")
-    return _shell_create_bodies(
+    return _shell_create_calls(
         command, working_directory if isinstance(working_directory, str) else ""
     )
 
 
+def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
+    return [each_call.body for each_call in _create_calls(all_payload_fields)]
+
+
+def _is_feature_title(title: str | None) -> bool:
+    return title is not None and re.match(FEATURE_TITLE_PATTERN, title, re.IGNORECASE) is not None
+
+
+def is_feature_pull_request(all_payload_fields: Mapping[str, object]) -> bool:
+    """Return whether any pull request create call in the payload carries a feature title.
+
+    ::
+
+        mcp__github__create_pull_request, title "feat(hooks)!: x" -> True
+        gh pr create --title "fix: y" --body-file b.md             -> False
+        gh pr create --fill                                        -> False
+        gh pr edit, git push, any other tool                       -> False
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    return any(_is_feature_title(each_call.title) for each_call in _create_calls(all_payload_fields))
+
+
+def missing_eval_section_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a feature pull request's body has no eval section, else None.
+
+    ::
+
+        title "feat: x", body has the section     -> None
+        title "feat: x", body without it          -> MISSING_EVAL_SECTION_REASON
+        title "fix: y", body without it           -> None
+        title "feat: x", gh pr create --fill      -> None
+
+    The section is an 'Eval' heading whose text names at least one command in
+    backticks. A create command whose body this gate cannot read passes here,
+    because missing_proof_reason denies it first.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_call in _create_calls(all_payload_fields):
+        if each_call.body is None or not _is_feature_title(each_call.title):
+            continue
+        section = _section_text(each_call.body, EVAL_HEADING_PATTERN)
+        if not section or COMMAND_MARKER not in section:
+            return MISSING_EVAL_SECTION_REASON
+    return None
+
+
 def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
     """Return a deny reason when a new pull request's body has no proof, else None.
 

package/hooks/blocking/test_artifact_look_gate.py

@@ -101,6 +101,7 @@ def test_should_refuse_a_page_published_without_a_look(tmp_path: Path) -> None:
     specific_output = hook_output["hookSpecificOutput"]
     assert specific_output["permissionDecision"] == "deny"
     assert "--screenshot" in specific_output["permissionDecisionReason"]
+    assert "Attach" not in specific_output["permissionDecisionReason"]
 
 
 def test_should_allow_a_page_whose_newer_screenshot_was_read(tmp_path: Path) -> None:

package/hooks/blocking/test_followup_pr_dedupe.py

@@ -92,3 +92,36 @@ def test_body_from_arguments_reads_inline_text_and_body_files(tmp_path: Path) ->
     assert dedupe.body_from_arguments(["--body-file", "body.md"], str(tmp_path)) == "From the file."
     assert dedupe.body_from_arguments(["--body-file", "-"], str(tmp_path)) is None
     assert dedupe.body_from_arguments(["--fill"], str(tmp_path)) is None
+
+
+def test_title_from_arguments_should_read_each_title_flag_shape() -> None:
+    assert dedupe.title_from_arguments(["--title", "feat: x", "--fill"]) == "feat: x"
+    assert dedupe.title_from_arguments(["-t", "fix: y"]) == "fix: y"
+    assert dedupe.title_from_arguments(["--title=feat(x): z"]) == "feat(x): z"
+    assert dedupe.title_from_arguments(["--title-file", "t.txt"]) is None
+    assert dedupe.title_from_arguments(["--fill"]) is None
+
+
+def _dispatch_payload(all_inputs: dict[str, object]) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__actions_run_trigger",
+        "tool_input": {"method": "run_workflow", "owner": "jl-cmd", "repo": "claude-dev-env", "inputs": all_inputs},
+    }
+
+
+def test_create_tool_fields_should_read_a_pull_request_dispatch_as_a_create() -> None:
+    payload = _dispatch_payload({"head": "b", "title": "fix: y", "body": "Follow-up to #1731"})
+    assert dedupe.create_tool_fields(payload) == {
+        "head": "b",
+        "title": "fix: y",
+        "body": "Follow-up to #1731",
+        "owner": "jl-cmd",
+        "repo": "claude-dev-env",
+    }
+    reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
+    assert reason is not None and "#1769" in reason
+
+
+def test_create_tool_fields_should_skip_a_call_that_opens_no_pull_request() -> None:
+    assert dedupe.create_tool_fields(_dispatch_payload({"work_order": "wo-1"})) is None
+    assert dedupe.create_tool_fields({"tool_name": "Bash", "tool_input": {"command": "gh pr list"}}) is None