claude-dev-env 8.108.1 → 8.108.3

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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: correction
3
- description: Turn a correction the user made to an agent into a Suggested task card that starts a fix session in one click, list the corrections filed as issues before the card, write a handoff brief, or land the fix in this session with the fix playbook. Use when the user types /correction, /correction fix, says "file this as a correction", or asks to show the open corrections.
3
+ description: Turn a correction into a Suggested task card that starts a fix session in one click, list the corrections filed as issues, write a handoff brief, or land the fix in this session with the fix playbook. Use when the user types /correction, /correction fix, says "file this as a correction", or asks to show the open corrections.
4
4
  argument-hint: "[fix] <what the agent got wrong, in the user's words>"
5
5
  ---
6
6
 
@@ -1,7 +1,11 @@
1
1
  ---
2
2
  name: mod-playbooks
3
3
  description: >-
4
- Map of playbooks for driving a Claude Code mod (plugin) and seeing its screen: press keys, open menus and drawers, hover a reply to show its action row, click a dropdown, type in a field, fire a toast or a question card, and capture each screen as text and PNG. Use when an agent must test a mod, check a fix by looking at it, or show a mod to the operator on their own desktop.
4
+ Playbooks for driving a Claude Code mod (plugin) and seeing its screen: press keys,
5
+ open menus and drawers, hover a reply to show its action row, click a dropdown, type in
6
+ a field, fire a toast or a question card, and capture each screen as text and PNG. Use
7
+ when an agent must test a mod, check a fix by looking at it, or show a mod to the
8
+ operator on their own desktop.
5
9
  ---
6
10
 
7
11
  # Mod playbooks
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sync-dev-env
3
- description: Install or update claude-dev-env in a running session, link the skills of every enabled plugin so a running session loads them, and schedule a daily re-sync at 6:00 AM local by default. Use when the user asks to sync claude-dev-env into a session, to load the skills of a plugin without a restart, when a /skill fails to resolve, to set up the daily sync, to check which session prompt a session uses, or to turn the claude-dev-env session prompt off for one session.
3
+ description: Install or update claude-dev-env in a running session, link every enabled plugin's skills so a running session loads them, and schedule a daily re-sync at 6:00 AM local by default. Use when the user asks to sync claude-dev-env into a session, to load the skills of a plugin without a restart, when a /skill fails to resolve, to set up the daily sync, to check which session prompt a session uses, or to turn the claude-dev-env session prompt off for one session.
4
4
  argument-hint: "[HH:MM] [IANA time zone]"
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Codex accounts
2
2
 
3
- The account broker assigns agent work across the Codex accounts.
3
+ The [account broker](account-broker.md) assigns agent work across the Codex accounts.
4
4
  Each account signs in under its own Codex home, and every home
5
5
  shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
6
6
  A job asks the broker which account to use.
@@ -24,6 +24,8 @@ Run `codex-compat bridge --surface <name> --payload '<json-object>'`. The bridge
24
24
 
25
25
  ## Automatic model routing
26
26
 
27
+ See [child model choices](subagent-model-routing.md).
28
+
27
29
  The package installer seeds `subagent-model-policy.json` in the agents-home
28
30
  `rules/` directory when the file is absent. It registers one `PreToolUse` group
29
31
  for `multi_agent_v1__spawn_agent` in `$CODEX_HOME/hooks.json`.
@@ -8,7 +8,7 @@ Source bones: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agent
8
8
 
9
9
  `/team-advisor` is the repository's advisor implementation. On a Claude host with the built-in `advisor` tool on, it calls `advisor()`, which reads the whole transcript. Otherwise it carries the full first packet explicitly, sends later deltas, and owns the warm Agent/SendMessage or read-only Astra CLI lifecycle.
10
10
 
11
- See `team-advisor-skill.md` for the bind and lifecycle map.
11
+ See [`team-advisor-skill.md`](team-advisor-skill.md) for the bind and lifecycle map.
12
12
 
13
13
  ## When to call
14
14
 
@@ -97,6 +97,6 @@ Size the ask at roughly 80 percent of the ceiling; direct address to the advisor
97
97
  | Doc | Holds |
98
98
  |---|---|
99
99
  | [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | API shape, model pairs, cost, caching, full best practices |
100
- | `team-advisor-skill.md` | Standing warm advisor for this repository |
100
+ | [`team-advisor-skill.md`](team-advisor-skill.md) | Standing warm advisor for this repository |
101
101
  | `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle — a read map routes each bind or consult moment to its `reference/` detail file |
102
- | `weak-executor-advisor.md` | Consult deltas for an executor spawned below the advisor's own tier |
102
+ | [`weak-executor-advisor.md`](weak-executor-advisor.md) | Consult deltas for an executor spawned below the advisor's own tier |
@@ -15,13 +15,11 @@ Three anti-hallucination constraints are always active.
15
15
  Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
16
16
 
17
17
  ## 1. Settle the fact, then cite it
18
- Source: the repository owner's policy, recorded in [jl-cmd/claude-dev-env#1607](https://github.com/jl-cmd/claude-dev-env/pull/1607). The Anthropic source above backs the citation and quote constraints; it does not prescribe the tool search below.
18
+ Source: the repository owner's policy, recorded in [jl-cmd/claude-dev-env#1607](https://github.com/jl-cmd/claude-dev-env/pull/1607). The Anthropic source above backs the citation and quote constraints; it does not prescribe the evidence rules linked below.
19
19
 
20
20
  Never state a claim without a credible source. Don't guess. Don't infer.
21
21
 
22
- Before an answer depends on an unsettled fact, list every tool that could settle it: repository files, `gh api` contents and code search, workflow files, a live run, another repository. Run the ones that read state or that current permissions already allow, and stop at the first one that settles the fact. The answer states the fact with its source.
23
-
24
- When no permitted tool can reach the fact, name the exact check that would settle it and who can run or approve it. A probe that changes state, or that needs confirmation first, goes here. "I don't know" alone is never the answer.
22
+ For an unsettled fact, follow [evidence](../agents-guidance/evidence.md). When no permitted tool reaches the fact, name the exact check and who can run or approve it.
25
23
 
26
24
  ## 2. Verify with citations
27
25
  Every recommendation, claim, or piece of advice must cite a specific source:
@@ -5,8 +5,8 @@ Three templates live here. Pick the one that fits the ask before you write a lin
5
5
  | Ask | Template |
6
6
  |---|---|
7
7
  | A status or progress report on one piece of work: what is done, where it is stuck, and what comes next. Prefer it for every such report unless the person asks for another shape | `status-flowchart.html` |
8
- | A tracker, board, review page or dashboard that lists many items for people to read and click | `template.html` |
9
- | A picture of how things connect: a map, a flow, who calls what, old next to new. Also any ask for "only visuals" or "no words" | `diagram.html` |
8
+ | A tracker, board, review page or dashboard that lists many items for people to read and click | [`template.html`](template.html) |
9
+ | A picture of how things connect: a map, a flow, who calls what, old next to new. Also any ask for "only visuals" or "no words" | [`diagram.html`](diagram.html) |
10
10
 
11
11
  `diagram.html` draws the content in inline SVG: boxes for things, arrows for links, and color for state. Labels are a few words. Text in bordered cards is a tracker, so it never answers a visual-only ask.
12
12
 
@@ -1,6 +1,6 @@
1
1
  # html-plan page template
2
2
 
3
- Build a complex visual, such as a multi-part plan or evidence, from the html-plan skill. A status or progress report prefers the [status flowchart](../artifact-page/status-flowchart.html), unless the person asks for another shape. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
3
+ Build a complex visual, such as a multi-part plan or evidence, from the html-plan skill. A status or progress report prefers the [status flowchart](../artifact-page/status-flowchart.html), unless the person asks for another shape. Load [`house.css`](house.css) from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
4
4
 
5
5
  ## Get the skill
6
6
 
@@ -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
  },
@@ -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())
@@ -0,0 +1,295 @@
1
+ import json
2
+ import os
3
+ import subprocess
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ import pytest
8
+
9
+ _SESSION_DIR = Path(__file__).resolve().parent
10
+ _HOOKS_ROOT = _SESSION_DIR.parent
11
+ for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
12
+ if each_sys_path_entry not in sys.path:
13
+ sys.path.insert(0, each_sys_path_entry)
14
+
15
+ import npx_pele_guidance
16
+ from hooks_constants.npx_pele_guidance_constants import (
17
+ PACKAGE_MANIFEST_NAME,
18
+ PELE_PACKAGE_NAME,
19
+ )
20
+
21
+ HOOK_SCRIPT = _SESSION_DIR / "npx_pele_guidance.py"
22
+ CLAUDE_CONFIG_DIRECTORY_VARIABLE = "CLAUDE_CONFIG_DIR"
23
+ JS_FENCE_OPEN = "```js\n"
24
+ JS_FENCE_CLOSE = "\n```"
25
+ CHAIN_TEXT = "flowchart LR\n A --> B\n"
26
+
27
+
28
+ def _write_installed_pele(claude_root: Path, version: str) -> Path:
29
+ package_directory = npx_pele_guidance.pele_package_directory_under(claude_root)
30
+ (package_directory / "dist").mkdir(parents=True)
31
+ (package_directory / PACKAGE_MANIFEST_NAME).write_text(
32
+ json.dumps({"name": PELE_PACKAGE_NAME, "version": version, "type": "module"}),
33
+ encoding="utf-8",
34
+ )
35
+ (package_directory / "dist" / "pele.js").write_text(
36
+ "export function render(text) {\n return { svg: `<svg>${text.length}</svg>` };\n}\n",
37
+ encoding="utf-8",
38
+ )
39
+ return package_directory
40
+
41
+
42
+ def _payload(command_text: str) -> dict[str, object]:
43
+ return {
44
+ "hook_event_name": "PreToolUse",
45
+ "tool_name": "Bash",
46
+ "tool_input": {"command": command_text},
47
+ }
48
+
49
+
50
+ def _run_hook(payload_text: str, claude_root: Path) -> subprocess.CompletedProcess[str]:
51
+ environment = dict(os.environ)
52
+ environment[CLAUDE_CONFIG_DIRECTORY_VARIABLE] = str(claude_root)
53
+ return subprocess.run(
54
+ [sys.executable, str(HOOK_SCRIPT)],
55
+ input=payload_text,
56
+ capture_output=True,
57
+ text=True,
58
+ check=True,
59
+ env=environment,
60
+ )
61
+
62
+
63
+ @pytest.mark.parametrize(
64
+ "command_text",
65
+ [
66
+ "npx pele",
67
+ "npx -y pele chain.mmd",
68
+ "npx --yes pele@1.12.0 chain.mmd",
69
+ "npx --cache ./c pele chain.mmd",
70
+ "npx --registry https://r.example pele chain.mmd",
71
+ "npx --timeout 5000 pele chain.mmd",
72
+ "npx -p pele mmdc -i a.mmd",
73
+ "npx --package=pele mmdc chain.mmd",
74
+ "npx -c 'pele a.mmd'",
75
+ "npm.cmd exec pele a.mmd",
76
+ "npx.ps1 pele a.mmd",
77
+ "npm.ps1 exec pele a.mmd",
78
+ "npm --prefix exec pele chain.mmd",
79
+ "cd diagrams && npx pele chain.mmd",
80
+ "npm exec pele chain.mmd",
81
+ "npm --silent exec pele chain.mmd",
82
+ "npm --prefix ./p exec pele chain.mmd",
83
+ "npm --globalconfig ./g exec pele chain.mmd",
84
+ "npm --otp 123 exec pele chain.mmd",
85
+ "npx.cmd pele chain.mmd",
86
+ "CI=1 npx pele chain.mmd",
87
+ "NODE_ENV=prod CI=1 npx -y pele",
88
+ "env CI=1 npx pele chain.mmd",
89
+ "sudo npx pele chain.mmd",
90
+ "time npx pele chain.mmd",
91
+ "timeout 60 npx pele chain.mmd",
92
+ "if [ -f x ]; then npx pele chain.mmd; fi",
93
+ "timeout --foreground 60 npx pele chain.mmd",
94
+ 'bash -c "npx pele chain.mmd"',
95
+ "env -i npx pele a.mmd",
96
+ 'npm exec "pele" chain.mmd',
97
+ "echo `npx pele chain.mmd`",
98
+ "echo \\'; npx pele a.mmd; echo \\'",
99
+ ],
100
+ )
101
+ def test_npx_pele_commands_match(command_text: str) -> None:
102
+ assert npx_pele_guidance.is_npx_pele_command({"command": command_text})
103
+
104
+
105
+ @pytest.mark.parametrize(
106
+ "command_text",
107
+ [
108
+ "npx prettier --check .",
109
+ "npm install pele",
110
+ "npx -y claude-dev-env@latest",
111
+ "npx pelee",
112
+ "npx -y create-pele-app my-app",
113
+ "CI=1 npx prettier --check .",
114
+ 'git commit -m "fix; npx pele docs"',
115
+ "cat > notes.md <<'EOF'\nnpx pele chain.mmd\nEOF",
116
+ "cat > notes.md <<'EOF'\nnpx pele chain.mmd",
117
+ "npx @scope/pele chain.mmd",
118
+ "echo pele",
119
+ ],
120
+ )
121
+ def test_other_commands_do_not_match(command_text: str) -> None:
122
+ assert not npx_pele_guidance.is_npx_pele_command({"command": command_text})
123
+
124
+
125
+ @pytest.mark.parametrize("tool_input", [None, "npx pele", {}, {"command": 7}])
126
+ def test_input_without_a_command_string_does_not_match(tool_input: object) -> None:
127
+ assert not npx_pele_guidance.is_npx_pele_command(tool_input)
128
+
129
+
130
+ def test_installed_version_reads_the_manifest(tmp_path: Path) -> None:
131
+ package_directory = _write_installed_pele(tmp_path, "1.12.0")
132
+ manifest = npx_pele_guidance.installed_pele_manifest(package_directory)
133
+ assert npx_pele_guidance.installed_pele_version(manifest) == "1.12.0"
134
+
135
+
136
+ def test_installed_version_is_none_without_a_manifest(tmp_path: Path) -> None:
137
+ manifest = npx_pele_guidance.installed_pele_manifest(npx_pele_guidance.pele_package_directory_under(tmp_path))
138
+ assert npx_pele_guidance.installed_pele_version(manifest) is None
139
+
140
+
141
+ @pytest.mark.parametrize("manifest_text", ["not json", '["list"]', '{"version": 1}', '{"version": ""}'])
142
+ def test_unreadable_manifest_reads_as_no_version(tmp_path: Path, manifest_text: str) -> None:
143
+ package_directory = npx_pele_guidance.pele_package_directory_under(tmp_path)
144
+ package_directory.mkdir(parents=True)
145
+ (package_directory / PACKAGE_MANIFEST_NAME).write_text(manifest_text, encoding="utf-8")
146
+ manifest = npx_pele_guidance.installed_pele_manifest(package_directory)
147
+ assert npx_pele_guidance.installed_pele_version(manifest) is None
148
+
149
+
150
+ def test_package_directory_follows_the_claude_config_directory(
151
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
152
+ ) -> None:
153
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
154
+ package_directory = npx_pele_guidance.pele_package_directory_under(npx_pele_guidance.claude_home())
155
+ assert package_directory == npx_pele_guidance.pele_package_directory_under(tmp_path)
156
+
157
+
158
+ def test_installed_copy_gets_its_version_path_and_snippet(
159
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
160
+ ) -> None:
161
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
162
+ package_directory = _write_installed_pele(tmp_path, "1.12.0")
163
+ hook_output = npx_pele_guidance.decide_hook_output(_payload("npx pele chain.mmd"))
164
+ assert hook_output is not None
165
+ specific_output = hook_output["hookSpecificOutput"]
166
+ assert specific_output["hookEventName"] == "PreToolUse"
167
+ assert "permissionDecision" not in specific_output
168
+ context_text = specific_output["additionalContext"]
169
+ assert "could not determine executable to run" in context_text
170
+ assert f"Pele 1.12.0 is installed at {package_directory}" in context_text
171
+ assert json.dumps(str(package_directory / "dist" / "pele.js")) in context_text
172
+ assert "pele.run" not in context_text
173
+
174
+
175
+ def test_missing_copy_points_to_the_playground(
176
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
177
+ ) -> None:
178
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
179
+ hook_output = npx_pele_guidance.decide_hook_output(_payload("npx -y pele chain.mmd"))
180
+ assert hook_output is not None
181
+ context_text = hook_output["hookSpecificOutput"]["additionalContext"]
182
+ assert "could not determine executable to run" in context_text
183
+ assert "No usable Pele package was found at" in context_text
184
+ assert "checks only the Claude home" in context_text
185
+ assert "playground at pele.run" in context_text
186
+ assert "pathToFileURL" not in context_text
187
+
188
+
189
+ def test_manifest_without_an_entry_file_points_to_the_playground(
190
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
191
+ ) -> None:
192
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
193
+ package_directory = npx_pele_guidance.pele_package_directory_under(tmp_path)
194
+ package_directory.mkdir(parents=True)
195
+ (package_directory / PACKAGE_MANIFEST_NAME).write_text(
196
+ json.dumps({"name": PELE_PACKAGE_NAME, "version": "1.12.0"}),
197
+ encoding="utf-8",
198
+ )
199
+ hook_output = npx_pele_guidance.decide_hook_output(_payload("npx pele chain.mmd"))
200
+ assert hook_output is not None
201
+ context_text = hook_output["hookSpecificOutput"]["additionalContext"]
202
+ assert "playground at pele.run" in context_text
203
+ assert "pathToFileURL" not in context_text
204
+
205
+
206
+ def test_installed_snippet_renders_an_svg_file(
207
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
208
+ ) -> None:
209
+ claude_root = tmp_path / "claude"
210
+ _write_installed_pele(claude_root, "1.12.0")
211
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(claude_root))
212
+ work_directory = tmp_path / "work"
213
+ work_directory.mkdir()
214
+ (work_directory / "diagram.mmd").write_text(CHAIN_TEXT, encoding="utf-8")
215
+ context_text = npx_pele_guidance.guidance_text()
216
+ snippet = context_text.split(JS_FENCE_OPEN, 1)[1].split(JS_FENCE_CLOSE, 1)[0]
217
+ (work_directory / "pele-render.mjs").write_text(snippet, encoding="utf-8")
218
+ completed = subprocess.run(
219
+ ["node", "pele-render.mjs", "diagram.mmd"],
220
+ cwd=work_directory,
221
+ capture_output=True,
222
+ text=True,
223
+ check=True,
224
+ )
225
+ rendered_svg = (work_directory / "diagram.svg").read_text(encoding="utf-8")
226
+ assert rendered_svg == f"<svg>{len(CHAIN_TEXT)}</svg>"
227
+ assert "svg bytes:" in completed.stdout
228
+
229
+
230
+ def test_decide_hook_output_is_silent_for_other_commands(
231
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
232
+ ) -> None:
233
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
234
+ assert npx_pele_guidance.decide_hook_output(_payload("npm install pele")) is None
235
+
236
+
237
+ def test_hook_prints_the_guidance_as_json_for_npx_pele(tmp_path: Path) -> None:
238
+ completed = _run_hook(json.dumps(_payload("npx pele chain.mmd")), tmp_path)
239
+ hook_output = json.loads(completed.stdout)
240
+ assert hook_output["hookSpecificOutput"]["hookEventName"] == "PreToolUse"
241
+ assert "permissionDecision" not in hook_output["hookSpecificOutput"]
242
+ assert "playground at pele.run" in hook_output["hookSpecificOutput"]["additionalContext"]
243
+
244
+
245
+ def test_hook_is_silent_on_malformed_stdin(tmp_path: Path) -> None:
246
+ completed = _run_hook("not json", tmp_path)
247
+ assert completed.returncode == 0
248
+ assert completed.stdout == ""
249
+
250
+
251
+ def test_pele_argument_outside_the_package_slot_gets_only_the_hint(tmp_path: Path) -> None:
252
+ completed = _run_hook(json.dumps(_payload("npx prettier --check pele")), tmp_path)
253
+ assert completed.returncode == 0
254
+ hook_output = json.loads(completed.stdout)
255
+ assert "permissionDecision" not in hook_output["hookSpecificOutput"]
256
+ assert "playground at pele.run" in hook_output["hookSpecificOutput"]["additionalContext"]
257
+
258
+
259
+ def test_installed_guidance_points_at_the_manifest_main_entry(
260
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
261
+ ) -> None:
262
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(tmp_path))
263
+ package_directory = npx_pele_guidance.pele_package_directory_under(tmp_path)
264
+ (package_directory / "lib").mkdir(parents=True)
265
+ (package_directory / PACKAGE_MANIFEST_NAME).write_text(
266
+ json.dumps({"name": PELE_PACKAGE_NAME, "version": "2.0.0", "main": "./lib/index.js"}),
267
+ encoding="utf-8",
268
+ )
269
+ entry_path = package_directory / "lib" / "index.js"
270
+ entry_path.write_text("export function render(text) {\n return { svg: '' };\n}\n", encoding="utf-8")
271
+ manifest = npx_pele_guidance.installed_pele_manifest(package_directory)
272
+ assert npx_pele_guidance.installed_pele_entry(package_directory, manifest) == entry_path
273
+ assert str(entry_path) in npx_pele_guidance.guidance_text()
274
+ assert "pele.run" not in npx_pele_guidance.guidance_text()
275
+
276
+
277
+ def test_installed_snippet_prints_usage_without_a_diagram(
278
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
279
+ ) -> None:
280
+ claude_root = tmp_path / "claude"
281
+ _write_installed_pele(claude_root, "1.12.0")
282
+ monkeypatch.setenv(CLAUDE_CONFIG_DIRECTORY_VARIABLE, str(claude_root))
283
+ work_directory = tmp_path / "work"
284
+ work_directory.mkdir()
285
+ context_text = npx_pele_guidance.guidance_text()
286
+ snippet = context_text.split(JS_FENCE_OPEN, 1)[1].split(JS_FENCE_CLOSE, 1)[0]
287
+ (work_directory / "pele-render.mjs").write_text(snippet, encoding="utf-8")
288
+ completed = subprocess.run(
289
+ ["node", "pele-render.mjs"],
290
+ cwd=work_directory,
291
+ capture_output=True,
292
+ text=True,
293
+ )
294
+ assert completed.returncode == 1
295
+ assert "usage: node pele-render.mjs <diagram.mmd>" in completed.stderr
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.108.1",
3
+ "version": "8.108.3",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {