claude-dev-env 8.108.2 → 8.109.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/correction/SKILL.md +1 -1
- package/.agents/skills/mod-playbooks/SKILL.md +5 -1
- package/.agents/skills/sync-dev-env/SKILL.md +1 -1
- package/hooks/context_budget/findings.py +76 -10
- package/hooks/context_budget/model.py +19 -0
- package/hooks/context_budget/policy_changes.py +7 -0
- package/hooks/context_budget/policy_file.py +6 -0
- package/hooks/context_budget/sections.py +88 -8
- package/hooks/context_budget/tests/budget_support.py +12 -0
- package/hooks/context_budget/tests/test_findings.py +106 -1
- package/hooks/context_budget/tests/test_policy_changes.py +19 -0
- package/hooks/context_budget/tests/test_policy_file.py +11 -0
- package/hooks/context_budget/tests/test_prose_rule_eval.py +144 -0
- package/hooks/context_budget/tests/test_sections.py +89 -1
- package/hooks/features/README.md +1 -1
- package/hooks/features/session-context.md +4 -1
- package/hooks/hooks.json +5 -0
- package/hooks/hooks_constants/context_budget_constants.py +18 -0
- package/hooks/hooks_constants/npx_pele_guidance_constants.py +59 -0
- package/hooks/session/npx_pele_guidance.py +229 -0
- package/hooks/session/test_npx_pele_guidance.py +295 -0
- package/package.json +1 -1
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
"""Grade the prose rule on labeled agent and Claude instruction files.
|
|
2
|
+
|
|
3
|
+
Each case's label comes from the rule's text. A case is positive when the
|
|
4
|
+
prose rule must report a finding for its file. The scope strings are spelled
|
|
5
|
+
out here so the eval grades the findings the rule reports.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
|
|
12
|
+
import pytest
|
|
13
|
+
|
|
14
|
+
from context_budget.findings import file_findings
|
|
15
|
+
from context_budget.policy_file import default_policy
|
|
16
|
+
from context_budget.tests.budget_support import words_text
|
|
17
|
+
|
|
18
|
+
NO_POINTER_SCOPE = "no pointer line"
|
|
19
|
+
LONG_LINE_SCOPE_PREFIX = "prose line: "
|
|
20
|
+
POINTER_LINE = "Read [the plan](reference/plan.md)."
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class LabeledCase:
|
|
25
|
+
"""One file and whether the prose rule must reject it.
|
|
26
|
+
|
|
27
|
+
Attributes:
|
|
28
|
+
name: Test id.
|
|
29
|
+
path: Repository-relative POSIX path.
|
|
30
|
+
text: File text.
|
|
31
|
+
should_fail: Whether the prose rule must report a finding.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
name: str
|
|
35
|
+
path: str
|
|
36
|
+
text: str
|
|
37
|
+
should_fail: bool
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
ALL_LABELED_CASES = (
|
|
41
|
+
LabeledCase("blank-agents-file", "app/AGENTS.md", "", False),
|
|
42
|
+
LabeledCase("import-only-agents-file", "app/AGENTS.md", "@CLAUDE.md\n", False),
|
|
43
|
+
LabeledCase("relative-import-claude-file", "app/CLAUDE.md", "@../AGENTS.md\n", False),
|
|
44
|
+
LabeledCase(
|
|
45
|
+
"link-index",
|
|
46
|
+
"app/AGENTS.md",
|
|
47
|
+
"# Index\n- [Plan](reference/plan.md)\n- [Rules](reference/rules.md)\n",
|
|
48
|
+
False,
|
|
49
|
+
),
|
|
50
|
+
LabeledCase("one-pointer-line", "app/AGENTS.md", f"{POINTER_LINE}\n", False),
|
|
51
|
+
LabeledCase(
|
|
52
|
+
"prose-without-pointer",
|
|
53
|
+
"app/AGENTS.md",
|
|
54
|
+
"Selection records own icon choice.\n",
|
|
55
|
+
True,
|
|
56
|
+
),
|
|
57
|
+
LabeledCase(
|
|
58
|
+
"long-unlinked-line-with-pointer",
|
|
59
|
+
"app/AGENTS.md",
|
|
60
|
+
f"{words_text(26)}\n{POINTER_LINE}\n",
|
|
61
|
+
True,
|
|
62
|
+
),
|
|
63
|
+
LabeledCase(
|
|
64
|
+
"line-at-word-limit",
|
|
65
|
+
"app/AGENTS.md",
|
|
66
|
+
f"{words_text(25)}\n{POINTER_LINE}\n",
|
|
67
|
+
False,
|
|
68
|
+
),
|
|
69
|
+
LabeledCase(
|
|
70
|
+
"long-line-with-its-own-link",
|
|
71
|
+
"app/CLAUDE.md",
|
|
72
|
+
f"{words_text(26)} [plan](reference/plan.md)\n",
|
|
73
|
+
False,
|
|
74
|
+
),
|
|
75
|
+
LabeledCase(
|
|
76
|
+
"import-with-long-unlinked-line",
|
|
77
|
+
"app/CLAUDE.md",
|
|
78
|
+
f"@AGENTS.md\n{words_text(26)}\n",
|
|
79
|
+
True,
|
|
80
|
+
),
|
|
81
|
+
LabeledCase("mention-is-not-an-import", "app/AGENTS.md", "@reviewer please review\n", True),
|
|
82
|
+
LabeledCase(
|
|
83
|
+
"long-list-item-with-link",
|
|
84
|
+
"app/AGENTS.md",
|
|
85
|
+
f"- {words_text(30)} [plan](reference/plan.md)\n",
|
|
86
|
+
False,
|
|
87
|
+
),
|
|
88
|
+
LabeledCase(
|
|
89
|
+
"long-line-inside-fence",
|
|
90
|
+
"app/AGENTS.md",
|
|
91
|
+
f"```\n{words_text(30)}\n```\n{POINTER_LINE}\n",
|
|
92
|
+
False,
|
|
93
|
+
),
|
|
94
|
+
LabeledCase(
|
|
95
|
+
"long-table-row",
|
|
96
|
+
"app/AGENTS.md",
|
|
97
|
+
f"| {words_text(30)} |\n{POINTER_LINE}\n",
|
|
98
|
+
False,
|
|
99
|
+
),
|
|
100
|
+
LabeledCase(
|
|
101
|
+
"short-intro-lines-with-pointer",
|
|
102
|
+
"app/AGENTS.md",
|
|
103
|
+
f"Holds shared helpers.\nCallers copy and publish trees.\n{POINTER_LINE}\n",
|
|
104
|
+
False,
|
|
105
|
+
),
|
|
106
|
+
LabeledCase("not-an-agent-file", "docs/notes.md", f"{words_text(40)}\n", False),
|
|
107
|
+
LabeledCase(
|
|
108
|
+
"import-and-pointer-claude-file",
|
|
109
|
+
"app/CLAUDE.md",
|
|
110
|
+
f"@AGENTS.md\n{POINTER_LINE}\n",
|
|
111
|
+
False,
|
|
112
|
+
),
|
|
113
|
+
LabeledCase(
|
|
114
|
+
"wordy-paragraph-with-pointer",
|
|
115
|
+
"app/AGENTS.md",
|
|
116
|
+
f"{words_text(52)}\n{POINTER_LINE}\n",
|
|
117
|
+
True,
|
|
118
|
+
),
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _prose_rule_fails(each_case: LabeledCase) -> bool:
|
|
123
|
+
all_findings = file_findings(default_policy(), each_case.path, each_case.text, None)
|
|
124
|
+
return any(
|
|
125
|
+
each_finding.scope == NO_POINTER_SCOPE
|
|
126
|
+
or each_finding.scope.startswith(LONG_LINE_SCOPE_PREFIX)
|
|
127
|
+
for each_finding in all_findings
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@pytest.mark.parametrize("each_case", ALL_LABELED_CASES, ids=lambda each_case: each_case.name)
|
|
132
|
+
def test_prose_rule_grades_each_labeled_case_as_labeled(each_case: LabeledCase) -> None:
|
|
133
|
+
assert _prose_rule_fails(each_case) == each_case.should_fail
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def test_prose_rule_confusion_matrix_has_perfect_precision_and_recall() -> None:
|
|
137
|
+
all_outcomes = [
|
|
138
|
+
(each_case.should_fail, _prose_rule_fails(each_case)) for each_case in ALL_LABELED_CASES
|
|
139
|
+
]
|
|
140
|
+
|
|
141
|
+
false_positives = sum(not each_label and each_grade for each_label, each_grade in all_outcomes)
|
|
142
|
+
false_negatives = sum(each_label and not each_grade for each_label, each_grade in all_outcomes)
|
|
143
|
+
|
|
144
|
+
assert (false_positives, false_negatives) == (0, 0)
|
|
@@ -9,10 +9,17 @@ from context_budget.tests.budget_support import (
|
|
|
9
9
|
fixture_text,
|
|
10
10
|
policy_text,
|
|
11
11
|
section_text,
|
|
12
|
+
words_text,
|
|
12
13
|
)
|
|
13
14
|
from context_budget.findings import file_findings
|
|
14
15
|
from context_budget.policy_file import default_policy, parse_policy
|
|
15
|
-
from context_budget.sections import
|
|
16
|
+
from context_budget.sections import (
|
|
17
|
+
context_kind_for_path,
|
|
18
|
+
is_path_skipped,
|
|
19
|
+
path_matches_pattern,
|
|
20
|
+
scan_prose,
|
|
21
|
+
scan_sections,
|
|
22
|
+
)
|
|
16
23
|
|
|
17
24
|
|
|
18
25
|
def test_calibration_old_orchestrator_fails_on_oversee_delegated_work() -> None:
|
|
@@ -72,6 +79,14 @@ def test_first_matching_kind_wins_and_a_skipped_kind_hides_the_path() -> None:
|
|
|
72
79
|
assert context_kind_for_path(policy, "docs/notes.md") is None
|
|
73
80
|
|
|
74
81
|
|
|
82
|
+
def test_path_is_skipped_only_when_its_first_matching_kind_has_no_line_limit() -> None:
|
|
83
|
+
policy = parse_policy(policy_text())
|
|
84
|
+
|
|
85
|
+
assert is_path_skipped(policy, "pkg/skills-archived/old/SKILL.md") is True
|
|
86
|
+
assert is_path_skipped(policy, "pkg/live/SKILL.md") is False
|
|
87
|
+
assert is_path_skipped(policy, "docs/notes.md") is False
|
|
88
|
+
|
|
89
|
+
|
|
75
90
|
def test_section_rule_counts_detail_and_skips_tables_link_lists_and_frontmatter() -> None:
|
|
76
91
|
text = (
|
|
77
92
|
"---\nname: x\ndescription: y\nmore: z\nand: w\nkeys: v\nhere: u\nlast: t\n---\n"
|
|
@@ -110,3 +125,76 @@ def test_relative_link_is_a_pointer_and_external_or_anchor_links_are_not() -> No
|
|
|
110
125
|
|
|
111
126
|
assert scan_sections(pointed)[1].has_pointer is True
|
|
112
127
|
assert scan_sections(external)[1].has_pointer is False
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def test_scan_prose_collects_unlinked_detail_lines_over_the_word_limit() -> None:
|
|
131
|
+
long_unlinked = words_text(26)
|
|
132
|
+
exact_unlinked = words_text(25)
|
|
133
|
+
text = f"# Index\n{long_unlinked}\n{exact_unlinked}\nRead [the plan](reference/plan.md).\n"
|
|
134
|
+
|
|
135
|
+
scan = scan_prose(text, 25)
|
|
136
|
+
|
|
137
|
+
assert scan.all_long_unlinked_lines == (long_unlinked,)
|
|
138
|
+
assert scan.has_detail_line is True
|
|
139
|
+
assert scan.has_pointer_line is True
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def test_scan_prose_ignores_fenced_code_tables_and_lines_that_link() -> None:
|
|
143
|
+
long_words = words_text(30)
|
|
144
|
+
text = "\n".join(
|
|
145
|
+
[
|
|
146
|
+
"```",
|
|
147
|
+
long_words,
|
|
148
|
+
"```",
|
|
149
|
+
f"| {long_words} |",
|
|
150
|
+
f"- [{long_words}](reference/plan.md)",
|
|
151
|
+
f"{long_words} [plan](reference/plan.md)",
|
|
152
|
+
]
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
scan = scan_prose(text + "\n", 25)
|
|
156
|
+
|
|
157
|
+
assert scan.all_long_unlinked_lines == ()
|
|
158
|
+
assert scan.has_pointer_line is True
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def test_scan_prose_counts_words_after_a_list_marker() -> None:
|
|
162
|
+
twenty_five = words_text(25)
|
|
163
|
+
|
|
164
|
+
assert scan_prose(f"- {twenty_five}\n", 25).all_long_unlinked_lines == ()
|
|
165
|
+
assert scan_prose(f"- {twenty_five} more\n", 25).all_long_unlinked_lines == (
|
|
166
|
+
f"- {twenty_five} more",
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def test_scan_prose_does_not_count_a_lone_dash_as_a_word() -> None:
|
|
171
|
+
twenty_five = words_text(25)
|
|
172
|
+
|
|
173
|
+
assert scan_prose(f"{twenty_five} -\n", 25).all_long_unlinked_lines == ()
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def test_scan_prose_reports_a_file_with_no_relative_link() -> None:
|
|
177
|
+
scan = scan_prose("Selection records own icon choice.\n", 25)
|
|
178
|
+
|
|
179
|
+
assert scan.has_detail_line is True
|
|
180
|
+
assert scan.has_pointer_line is False
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def test_scan_prose_of_blank_or_heading_only_text_has_no_detail_line() -> None:
|
|
184
|
+
assert scan_prose("", 25).has_detail_line is False
|
|
185
|
+
assert scan_prose("# Only a heading\n", 25).has_detail_line is False
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def test_import_line_counts_as_a_pointer_and_a_mention_does_not() -> None:
|
|
189
|
+
assert scan_prose("@AGENTS.md\n", 25).has_pointer_line is True
|
|
190
|
+
assert scan_prose(" @../shared/AGENTS.md\n", 25).has_pointer_line is True
|
|
191
|
+
assert scan_prose("@reviewer\n", 25).has_pointer_line is False
|
|
192
|
+
assert scan_prose("@reviewer review this\n", 25).has_pointer_line is False
|
|
193
|
+
assert scan_prose("@https://example.com/guide\n", 25).has_pointer_line is False
|
|
194
|
+
assert scan_prose("@MAILTO:team@example.com\n", 25).has_pointer_line is False
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def test_import_line_is_not_a_section_pointer() -> None:
|
|
198
|
+
all_scans = scan_sections("## Plan\n@reference/plan.md\n")
|
|
199
|
+
|
|
200
|
+
assert all_scans[1].has_pointer is False
|
package/hooks/features/README.md
CHANGED
|
@@ -26,7 +26,7 @@ Each family page starts with a title and an agent-facing behavior summary. Its f
|
|
|
26
26
|
- [Bash dispatchers](./bash-dispatchers.md) covers command rewriting and the post-call reminder.
|
|
27
27
|
- [Post-write validation](./post-write-validation.md) covers the after-write dispatcher and formatter.
|
|
28
28
|
- [Conduct gates](./conduct-gates.md) covers chat replies, edit markers, step notes, checked claims, and the pull request lifecycle skill.
|
|
29
|
-
- [Session context](./session-context.md) covers skill reminders, startup guidance, and the auto mode denial quick fix.
|
|
29
|
+
- [Session context](./session-context.md) covers skill reminders, startup guidance, the npx_pele_guidance hook, and the auto mode denial quick fix.
|
|
30
30
|
- [Spawn routing](./spawn-routing.md) covers spawn readiness, pacing, and model selection.
|
|
31
31
|
- [Observability](./observability.md) covers instruction loads and edited files.
|
|
32
32
|
- [Read gates](./read-gates.md) covers the image size cap on Read.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Session context
|
|
2
2
|
|
|
3
|
-
This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, starts a workflow helper, starts an artifact page, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
|
|
3
|
+
This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, starts a workflow helper, starts an artifact page, runs `npx pele`, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
|
|
4
4
|
|
|
5
5
|
## Checks
|
|
6
6
|
|
|
@@ -13,6 +13,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
|
|
|
13
13
|
- `session/plugin_session_baseline_writer.py` records each plugin's `version` and `installPath` from `installed_plugins.json` to a per-session file in the system temp folder. It writes on `startup`, or when the session has no baseline yet, and leaves an existing baseline alone on `resume`, `clear`, and `compact`.
|
|
14
14
|
- `session/plugin_change_warning.py` compares `installed_plugins.json` with that baseline before each prompt. It names each plugin whose version or install path changed, or that the baseline lacks, once per session, and tells the user to restart Claude Code.
|
|
15
15
|
- `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.
|
|
16
|
+
- `session/npx_pele_guidance.py` tells an agent that runs `npx pele` how to render Mermaid instead. Pele is a library with no command, so the hook names the installed copy and a Node snippet that renders with it. When no copy is installed, it points to the pele.run playground.
|
|
16
17
|
- `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.
|
|
17
18
|
|
|
18
19
|
## When it fires
|
|
@@ -22,6 +23,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
|
|
|
22
23
|
- `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`.
|
|
23
24
|
- `session/plugin_session_baseline_writer.py` runs on `SessionStart`, matcher empty, at `10` seconds, so it sees every source. `session/plugin_change_warning.py` runs on `UserPromptSubmit`, matcher empty, at `10` seconds in `hooks.json`.
|
|
24
25
|
- `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`.
|
|
26
|
+
- `session/npx_pele_guidance.py` runs on `PreToolUse` matcher `Bash|PowerShell` at `10` seconds in `hooks.json`. It speaks only on an `npx` command with a `pele` argument, or an `npm exec` or `npm x` command with one after `exec` or `x`.
|
|
25
27
|
- `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
|
|
26
28
|
|
|
27
29
|
## Proving it
|
|
@@ -38,6 +40,7 @@ Preconditions:
|
|
|
38
40
|
- **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.
|
|
39
41
|
- **Plugin restart warning.** Input is a SessionStart event, an `installed_plugins.json` change, and a prompt. Run `python -m pytest packages/claude-dev-env/hooks/session/test_plugin_session_baseline_writer.py packages/claude-dev-env/hooks/session/test_plugin_change_warning.py packages/claude-dev-env/hooks/test_plugin_session_baseline.py -q`. The tests observe one warning for a changed version, a changed install path, and a plugin new since start, silence on a `lastUpdated` refresh and on a second prompt, and a warning that still fires after a `compact` SessionStart.
|
|
40
42
|
- **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.
|
|
43
|
+
- **npx pele guidance.** Input is a `Bash` or `PowerShell` call whose command runs `npx pele`. Run `python -m pytest packages/claude-dev-env/hooks/session/test_npx_pele_guidance.py -q`. The adjacent test observes the guidance for each install state, a snippet that renders an SVG file under node, and silence on other commands and malformed input.
|
|
41
44
|
- **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.
|
|
42
45
|
|
|
43
46
|
## Gotchas
|
package/hooks/hooks.json
CHANGED
|
@@ -114,6 +114,11 @@
|
|
|
114
114
|
"type": "command",
|
|
115
115
|
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verify_before_commit_gate.py",
|
|
116
116
|
"timeout": 30
|
|
117
|
+
},
|
|
118
|
+
{
|
|
119
|
+
"type": "command",
|
|
120
|
+
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/npx_pele_guidance.py",
|
|
121
|
+
"timeout": 10
|
|
117
122
|
}
|
|
118
123
|
]
|
|
119
124
|
},
|
|
@@ -10,6 +10,7 @@ GIT_MARKER_NAME = ".git"
|
|
|
10
10
|
UTF8_ENCODING = "utf-8"
|
|
11
11
|
|
|
12
12
|
SECTION_DETAIL_LINE_LIMIT_KEY = "section_detail_line_limit"
|
|
13
|
+
PROSE_LINE_WORD_LIMIT_KEY = "prose_line_word_limit"
|
|
13
14
|
KINDS_KEY = "kinds"
|
|
14
15
|
HOOKS_KEY = "hooks"
|
|
15
16
|
BASELINE_KEY = "baseline"
|
|
@@ -26,6 +27,8 @@ LINES_KEY = "lines"
|
|
|
26
27
|
SECTIONS_KEY = "sections"
|
|
27
28
|
|
|
28
29
|
DEFAULT_SECTION_DETAIL_LINE_LIMIT = 6
|
|
30
|
+
DEFAULT_PROSE_LINE_WORD_LIMIT = 25
|
|
31
|
+
ALL_PROSE_RULE_FILE_NAMES: frozenset[str] = frozenset({"AGENTS.md", "CLAUDE.md"})
|
|
29
32
|
ALL_DEFAULT_KIND_SPECS: tuple[tuple[str, tuple[str, ...], int, bool], ...] = (
|
|
30
33
|
("skill entry", ("**/SKILL.md",), 200, True),
|
|
31
34
|
("agent instructions", ("**/AGENTS.md", "**/CLAUDE.md"), 60, True),
|
|
@@ -34,6 +37,8 @@ ALL_DEFAULT_KIND_SPECS: tuple[tuple[str, tuple[str, ...], int, bool], ...] = (
|
|
|
34
37
|
|
|
35
38
|
TOP_SECTION_HEADING = "(top)"
|
|
36
39
|
FILE_SCOPE = "file"
|
|
40
|
+
NO_POINTER_SCOPE = "no pointer line"
|
|
41
|
+
PROSE_LINE_SCOPE_PREFIX = "prose line: "
|
|
37
42
|
FRONTMATTER_DELIMITER = "---"
|
|
38
43
|
TABLE_ROW_PREFIX = "|"
|
|
39
44
|
PATH_SEPARATOR = "/"
|
|
@@ -43,6 +48,9 @@ ATX_HEADING_PATTERN = re.compile(r"^ {0,3}#{1,6}(?:[ \t]+(?P<text>.*?))?(?:[ \t]
|
|
|
43
48
|
FENCE_OPEN_PATTERN = re.compile(r"^ {0,3}(?P<marker>`{3,}|~{3,})")
|
|
44
49
|
PURE_LINK_LIST_ITEM_PATTERN = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+\[[^\]]*\]\([^)]*\)\s*$")
|
|
45
50
|
LINK_TARGET_PATTERN = re.compile(r"\[[^\]]*\]\(\s*<?(?P<target>[^)\s>]+)")
|
|
51
|
+
IMPORT_DIRECTIVE_PATTERN = re.compile(
|
|
52
|
+
r"^\s*@(?!(?:https?|mailto):)(?=\S*[./])\S+\s*$", re.IGNORECASE
|
|
53
|
+
)
|
|
46
54
|
ALL_NON_RELATIVE_TARGET_PREFIXES: tuple[str, ...] = (
|
|
47
55
|
"http:",
|
|
48
56
|
"https:",
|
|
@@ -51,6 +59,7 @@ ALL_NON_RELATIVE_TARGET_PREFIXES: tuple[str, ...] = (
|
|
|
51
59
|
"//",
|
|
52
60
|
)
|
|
53
61
|
NON_KEBAB_CHARACTER_PATTERN = re.compile(r"[^a-z0-9]+")
|
|
62
|
+
LIST_MARKER_PATTERN = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+")
|
|
54
63
|
|
|
55
64
|
ENV_COMMAND_NAME = "env"
|
|
56
65
|
ENV_ASSIGNMENT_SEPARATOR = "="
|
|
@@ -75,6 +84,14 @@ SECTION_FINDING_TEMPLATE = (
|
|
|
75
84
|
"Move it to a reference file, for example reference/{kebab}.md, "
|
|
76
85
|
"and replace the section with a one-line pointer to it. Cutting the section down to the limit keeps the detail inline and is not the fix."
|
|
77
86
|
)
|
|
87
|
+
NO_POINTER_FINDING_TEMPLATE = (
|
|
88
|
+
MESSAGE_PREFIX + "file has no pointer line (a relative Markdown link or an @import line). "
|
|
89
|
+
"Add a one-line pointer to a reference file."
|
|
90
|
+
)
|
|
91
|
+
PROSE_LINE_FINDING_TEMPLATE = (
|
|
92
|
+
MESSAGE_PREFIX + 'line "{excerpt}" has {count} words and no pointer (limit {limit}). '
|
|
93
|
+
"Move the detail to a reference file and replace the line with a one-line pointer to it."
|
|
94
|
+
)
|
|
78
95
|
FILE_FINDING_TEMPLATE = (
|
|
79
96
|
MESSAGE_PREFIX + "file has {count} lines ({kind} limit {limit}). "
|
|
80
97
|
"Move detail sections to reference files and leave one-line pointers."
|
|
@@ -122,6 +139,7 @@ CHANGE_ADDS_SECTION = 'baseline adds section "{heading}" to "{subject}"'
|
|
|
122
139
|
CHANGE_ADDS_HOOK = 'baseline adds hook "{subject}"'
|
|
123
140
|
CHANGE_RAISES_HOOK = 'baseline raises hook "{subject}" from {prior} to {current} characters'
|
|
124
141
|
CHANGE_RAISES_SECTION_LIMIT = SECTION_DETAIL_LINE_LIMIT_KEY + " rises from {prior} to {current}"
|
|
142
|
+
CHANGE_RAISES_PROSE_LIMIT = PROSE_LINE_WORD_LIMIT_KEY + " rises from {prior} to {current}"
|
|
125
143
|
CHANGE_RAISES_LINE_LIMIT = 'kind "{subject}" line_limit rises from {prior} to {current}'
|
|
126
144
|
CHANGE_DISABLES_SECTION_RULE = 'kind "{subject}" turns its section rule off'
|
|
127
145
|
CHANGE_DELETES_KIND = 'kind "{subject}" is deleted'
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""Names and guidance text for the npx_pele_guidance PreToolUse hook."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"ABSENT_GUIDANCE_TEMPLATE",
|
|
7
|
+
"ALL_NPM_EXEC_SUBCOMMANDS",
|
|
8
|
+
"ALL_NPM_PROGRAM_NAMES",
|
|
9
|
+
"ALL_NPX_PROGRAM_NAMES",
|
|
10
|
+
"ALL_PELE_ENTRY_PATH_PARTS",
|
|
11
|
+
"COMMAND_INPUT_KEY",
|
|
12
|
+
"INSTALLED_GUIDANCE_TEMPLATE",
|
|
13
|
+
"NODE_MODULES_DIRECTORY_NAME",
|
|
14
|
+
"NPX_PELE_FAILURE_SENTENCE",
|
|
15
|
+
"OPTION_VALUE_SEPARATOR",
|
|
16
|
+
"PACKAGE_MANIFEST_NAME",
|
|
17
|
+
"PACKAGE_VERSION_SEPARATOR",
|
|
18
|
+
"PELE_PACKAGE_NAME",
|
|
19
|
+
"PELE_TOOLS_DIRECTORY_NAME",
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
COMMAND_INPUT_KEY = "command"
|
|
23
|
+
ALL_NPX_PROGRAM_NAMES = ("npx", "npx.cmd", "npx.exe", "npx.ps1")
|
|
24
|
+
ALL_NPM_PROGRAM_NAMES = ("npm", "npm.cmd", "npm.exe", "npm.ps1")
|
|
25
|
+
ALL_NPM_EXEC_SUBCOMMANDS = ("exec", "x")
|
|
26
|
+
OPTION_VALUE_SEPARATOR = "="
|
|
27
|
+
PACKAGE_VERSION_SEPARATOR = "@"
|
|
28
|
+
PELE_PACKAGE_NAME = "pele"
|
|
29
|
+
PELE_TOOLS_DIRECTORY_NAME = "tools"
|
|
30
|
+
NODE_MODULES_DIRECTORY_NAME = "node_modules"
|
|
31
|
+
PACKAGE_MANIFEST_NAME = "package.json"
|
|
32
|
+
ALL_PELE_ENTRY_PATH_PARTS = ("dist", "pele.js")
|
|
33
|
+
NPX_PELE_FAILURE_SENTENCE = (
|
|
34
|
+
"`npx pele` cannot run: pele is a library with no command, so npx stops with"
|
|
35
|
+
' "could not determine executable to run".'
|
|
36
|
+
)
|
|
37
|
+
INSTALLED_GUIDANCE_TEMPLATE = (
|
|
38
|
+
NPX_PELE_FAILURE_SENTENCE
|
|
39
|
+
+ " Pele {version} is installed at {package_directory}. Render Mermaid from Node instead."
|
|
40
|
+
" Save the diagram as a .mmd file, save this script as pele-render.mjs in the same folder, and"
|
|
41
|
+
" run `node pele-render.mjs <diagram.mmd>`. It writes the SVG next to the diagram.\n\n"
|
|
42
|
+
"```js\n"
|
|
43
|
+
"import {{ readFileSync, writeFileSync }} from 'node:fs';\n"
|
|
44
|
+
"import {{ pathToFileURL }} from 'node:url';\n\n"
|
|
45
|
+
"const [inputPath] = process.argv.slice(2);\n"
|
|
46
|
+
"if (!inputPath) {{ console.error('usage: node pele-render.mjs <diagram.mmd>'); process.exit(1); }}\n"
|
|
47
|
+
"const {{ render }} = await import(pathToFileURL({package_entry}).href);\n"
|
|
48
|
+
"const {{ svg }} = render(readFileSync(inputPath, 'utf8'));\n"
|
|
49
|
+
"const outputPath = inputPath.replace(/\\.mmd$/, '') + '.svg';\n"
|
|
50
|
+
"writeFileSync(outputPath, svg);\n"
|
|
51
|
+
"console.log('svg bytes:', svg.length);\n"
|
|
52
|
+
"```"
|
|
53
|
+
)
|
|
54
|
+
ABSENT_GUIDANCE_TEMPLATE = (
|
|
55
|
+
NPX_PELE_FAILURE_SENTENCE
|
|
56
|
+
+ " No usable Pele package was found at {package_directory}. This hook checks only the Claude home,"
|
|
57
|
+
" so a copy kept elsewhere, such as one from an install run with --target, is not seen."
|
|
58
|
+
" Render the Mermaid text in the playground at pele.run instead, which needs no install."
|
|
59
|
+
)
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""PreToolUse hook: tell an agent how to render Mermaid when it runs ``npx pele``.
|
|
3
|
+
|
|
4
|
+
Registered on ``Bash|PowerShell``. Pele is a library with no command, so
|
|
5
|
+
``npx pele`` fails. When the command matches, the hook adds one block of
|
|
6
|
+
``additionalContext`` that names the installed copy and a Node snippet that
|
|
7
|
+
renders with it. When no copy is installed, the block points to the pele.run
|
|
8
|
+
playground instead. A command gets the guidance when an argument equal to ``pele``
|
|
9
|
+
(or ``pele@<version>``) follows ``npx``, or follows ``exec`` or ``x`` after ``npm``.
|
|
10
|
+
The match is loose on purpose: a stray match shows a harmless hint, while a missed
|
|
11
|
+
flag fails silently. Every other command gets no output:
|
|
12
|
+
|
|
13
|
+
::
|
|
14
|
+
|
|
15
|
+
Bash {"command": "npx -y pele chain.mmd"} -> the guidance block
|
|
16
|
+
Bash {"command": "npm install pele"} -> no output
|
|
17
|
+
|
|
18
|
+
The command runs with its normal permission flow.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import json
|
|
24
|
+
import sys
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
|
|
27
|
+
hooks_root_directory = str(Path(__file__).resolve().parent.parent)
|
|
28
|
+
if hooks_root_directory not in sys.path:
|
|
29
|
+
sys.path.insert(0, hooks_root_directory)
|
|
30
|
+
|
|
31
|
+
from hooks_constants.hook_specific_output_keys import (
|
|
32
|
+
HOOK_EVENT_NAME_KEY,
|
|
33
|
+
HOOK_SPECIFIC_OUTPUT_KEY,
|
|
34
|
+
)
|
|
35
|
+
from hooks_constants.npx_pele_guidance_constants import (
|
|
36
|
+
ABSENT_GUIDANCE_TEMPLATE,
|
|
37
|
+
ALL_NPM_EXEC_SUBCOMMANDS,
|
|
38
|
+
ALL_NPM_PROGRAM_NAMES,
|
|
39
|
+
ALL_NPX_PROGRAM_NAMES,
|
|
40
|
+
ALL_PELE_ENTRY_PATH_PARTS,
|
|
41
|
+
COMMAND_INPUT_KEY,
|
|
42
|
+
INSTALLED_GUIDANCE_TEMPLATE,
|
|
43
|
+
NODE_MODULES_DIRECTORY_NAME,
|
|
44
|
+
OPTION_VALUE_SEPARATOR,
|
|
45
|
+
PACKAGE_MANIFEST_NAME,
|
|
46
|
+
PACKAGE_VERSION_SEPARATOR,
|
|
47
|
+
PELE_PACKAGE_NAME,
|
|
48
|
+
PELE_TOOLS_DIRECTORY_NAME,
|
|
49
|
+
)
|
|
50
|
+
from hooks_constants.pre_tool_use_context_runner import run_context_hook
|
|
51
|
+
from hooks_constants.pytest_invocation import unquoted_token
|
|
52
|
+
from hooks_constants.shell_command_wrappers import (
|
|
53
|
+
all_wrapped_command_segments,
|
|
54
|
+
segment_program_and_arguments,
|
|
55
|
+
)
|
|
56
|
+
from hooks_constants.spawn_readiness_hook_constants import (
|
|
57
|
+
ADDITIONAL_CONTEXT_KEY,
|
|
58
|
+
PRE_TOOL_USE_EVENT_NAME,
|
|
59
|
+
TOOL_INPUT_KEY,
|
|
60
|
+
)
|
|
61
|
+
from json_file_reader import read_json_object
|
|
62
|
+
from open_task_asks import claude_home
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def pele_package_directory_under(claude_root: Path) -> Path:
|
|
66
|
+
"""Return the folder a Claude root keeps its Pele package in.
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
claude_root: The Claude home, or the root an install was given.
|
|
70
|
+
|
|
71
|
+
Returns:
|
|
72
|
+
``<claude_root>/tools/pele/node_modules/pele``, where the claude-dev-env
|
|
73
|
+
installer places Pele.
|
|
74
|
+
"""
|
|
75
|
+
return (
|
|
76
|
+
claude_root
|
|
77
|
+
/ PELE_TOOLS_DIRECTORY_NAME
|
|
78
|
+
/ PELE_PACKAGE_NAME
|
|
79
|
+
/ NODE_MODULES_DIRECTORY_NAME
|
|
80
|
+
/ PELE_PACKAGE_NAME
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def installed_pele_version(manifest: dict) -> str | None:
|
|
85
|
+
"""Read the version from a parsed Pele package manifest.
|
|
86
|
+
|
|
87
|
+
Args:
|
|
88
|
+
manifest: The parsed Pele ``package.json``.
|
|
89
|
+
|
|
90
|
+
Returns:
|
|
91
|
+
The version string, or None when the manifest holds none.
|
|
92
|
+
"""
|
|
93
|
+
version = manifest.get("version")
|
|
94
|
+
return version if isinstance(version, str) and version else None
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def installed_pele_manifest(package_directory: Path) -> dict:
|
|
98
|
+
"""Read the Pele package manifest as a dict.
|
|
99
|
+
|
|
100
|
+
Args:
|
|
101
|
+
package_directory: The folder that holds Pele's ``package.json``.
|
|
102
|
+
|
|
103
|
+
Returns:
|
|
104
|
+
The parsed manifest, or an empty dict when it is missing, unreadable, or not an object.
|
|
105
|
+
"""
|
|
106
|
+
return read_json_object(package_directory / PACKAGE_MANIFEST_NAME, "utf-8") or {}
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def is_npx_pele_command(tool_input: object) -> bool:
|
|
110
|
+
"""Return True when the shell command runs Pele through npx.
|
|
111
|
+
|
|
112
|
+
Args:
|
|
113
|
+
tool_input: The Bash or PowerShell ``tool_input``.
|
|
114
|
+
|
|
115
|
+
Returns:
|
|
116
|
+
True when a command segment runs ``npx`` with a ``pele`` argument
|
|
117
|
+
anywhere after it, or ``npm`` with a ``pele`` argument after ``exec``
|
|
118
|
+
or ``x``. The shared shell parser reads wrapper words, quotes,
|
|
119
|
+
substitutions, and heredocs.
|
|
120
|
+
"""
|
|
121
|
+
if not isinstance(tool_input, dict):
|
|
122
|
+
return False
|
|
123
|
+
command_text = tool_input.get(COMMAND_INPUT_KEY)
|
|
124
|
+
if not isinstance(command_text, str):
|
|
125
|
+
return False
|
|
126
|
+
return any(
|
|
127
|
+
_segment_runs_npx_pele(each_segment)
|
|
128
|
+
for each_segment in all_wrapped_command_segments(command_text)
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _segment_runs_npx_pele(all_segment_tokens: list[str]) -> bool:
|
|
133
|
+
program_name, all_arguments = segment_program_and_arguments(all_segment_tokens)
|
|
134
|
+
if program_name in ALL_NPX_PROGRAM_NAMES:
|
|
135
|
+
return _has_pele_argument(all_arguments)
|
|
136
|
+
if program_name not in ALL_NPM_PROGRAM_NAMES:
|
|
137
|
+
return False
|
|
138
|
+
exec_index = next(
|
|
139
|
+
(
|
|
140
|
+
each_index
|
|
141
|
+
for each_index, each_argument in enumerate(all_arguments)
|
|
142
|
+
if unquoted_token(each_argument) in ALL_NPM_EXEC_SUBCOMMANDS
|
|
143
|
+
),
|
|
144
|
+
None,
|
|
145
|
+
)
|
|
146
|
+
return exec_index is not None and _has_pele_argument(all_arguments[exec_index + 1 :])
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _has_pele_argument(all_arguments: list[str]) -> bool:
|
|
150
|
+
return any(
|
|
151
|
+
_is_pele_package(each_word)
|
|
152
|
+
for each_argument in all_arguments
|
|
153
|
+
for each_word in unquoted_token(each_argument).split()
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _is_pele_package(argument: str) -> bool:
|
|
158
|
+
package_spec = unquoted_token(argument).rsplit(OPTION_VALUE_SEPARATOR, 1)[-1]
|
|
159
|
+
package_name = package_spec.split(PACKAGE_VERSION_SEPARATOR, 1)[0]
|
|
160
|
+
return package_name == PELE_PACKAGE_NAME
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def installed_pele_entry(package_directory: Path, manifest: dict) -> Path:
|
|
164
|
+
"""Return the entry file the installed Pele manifest names.
|
|
165
|
+
|
|
166
|
+
Args:
|
|
167
|
+
package_directory: The folder that holds Pele's ``package.json``.
|
|
168
|
+
manifest: The parsed Pele ``package.json``.
|
|
169
|
+
|
|
170
|
+
Returns:
|
|
171
|
+
The file at the manifest's ``main`` path, or ``dist/pele.js`` when the
|
|
172
|
+
manifest names no usable ``main``.
|
|
173
|
+
"""
|
|
174
|
+
main_path = manifest.get("main")
|
|
175
|
+
if isinstance(main_path, str) and main_path:
|
|
176
|
+
return package_directory / main_path
|
|
177
|
+
return package_directory.joinpath(*ALL_PELE_ENTRY_PATH_PARTS)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def guidance_text() -> str:
|
|
181
|
+
"""Return the guidance for the Pele copy this machine has, or none.
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
The installed-copy snippet when the Pele manifest names a version and
|
|
185
|
+
its entry file exists, else the playground guidance.
|
|
186
|
+
"""
|
|
187
|
+
package_directory = pele_package_directory_under(claude_home())
|
|
188
|
+
manifest = installed_pele_manifest(package_directory)
|
|
189
|
+
package_entry = installed_pele_entry(package_directory, manifest)
|
|
190
|
+
version = installed_pele_version(manifest)
|
|
191
|
+
if version is None or not package_entry.is_file():
|
|
192
|
+
return ABSENT_GUIDANCE_TEMPLATE.format(package_directory=package_directory)
|
|
193
|
+
return INSTALLED_GUIDANCE_TEMPLATE.format(
|
|
194
|
+
version=version,
|
|
195
|
+
package_directory=package_directory,
|
|
196
|
+
package_entry=json.dumps(str(package_entry)),
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
|
|
201
|
+
"""Return the guidance as additionalContext output, or None to stay quiet.
|
|
202
|
+
|
|
203
|
+
Args:
|
|
204
|
+
all_hook_fields: The parsed PreToolUse payload.
|
|
205
|
+
|
|
206
|
+
Returns:
|
|
207
|
+
The ``hookSpecificOutput`` object, or None when the command does not run Pele through npx.
|
|
208
|
+
"""
|
|
209
|
+
if not is_npx_pele_command(all_hook_fields.get(TOOL_INPUT_KEY)):
|
|
210
|
+
return None
|
|
211
|
+
return {
|
|
212
|
+
HOOK_SPECIFIC_OUTPUT_KEY: {
|
|
213
|
+
HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
|
|
214
|
+
ADDITIONAL_CONTEXT_KEY: guidance_text(),
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def main() -> int:
|
|
220
|
+
"""Read the PreToolUse payload and print the guidance when the command runs npx pele.
|
|
221
|
+
|
|
222
|
+
Returns:
|
|
223
|
+
0 in every case; the guidance travels in the JSON output.
|
|
224
|
+
"""
|
|
225
|
+
return run_context_hook(decide_hook_output)
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
if __name__ == "__main__":
|
|
229
|
+
sys.exit(main())
|