nerftools 2.1.0__tar.gz → 2.2.0__tar.gz

nerftools-2.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.2.0"
+}

{nerftools-2.1.0 → nerftools-2.2.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.2.0](https://github.com/WayfarerLabs/nerftools/compare/v2.1.0...v2.2.0) (2026-06-05)
+
+
+### Features
+
+* bash-hint hook opt-in via brand-namespaced env var ([aa2288e](https://github.com/WayfarerLabs/nerftools/commit/aa2288e5f15c37f3c439698f9457f923786301f5))
+* gate bash-hint hook behind brand-namespaced opt-in env var ([ee2801d](https://github.com/WayfarerLabs/nerftools/commit/ee2801d6bb5b641becdb623785729d029aad4f77))
+
+
+### Documentation
+
+* clarify claude code output ([d2094a9](https://github.com/WayfarerLabs/nerftools/commit/d2094a9b047dcfac56d90bf5cb77725abdf1fd32))
+* further readme updates ([e147e84](https://github.com/WayfarerLabs/nerftools/commit/e147e842d6281e25ed05bd8c8b28ccb830db47dc))
+* refresh README -- add Codex plugin, soften default-manifests section, update structure ([76cc678](https://github.com/WayfarerLabs/nerftools/commit/76cc6781269539463237c9aedacfbd3549aa2b54))
+* refresh README for Codex plugin and softened default-manifests section ([63d2f5b](https://github.com/WayfarerLabs/nerftools/commit/63d2f5ba93806bbbb2fed4e521c17199e1dbced4))
+
 ## [2.1.0](https://github.com/WayfarerLabs/nerftools/compare/v2.0.0...v2.1.0) (2026-06-03)
 
 

{nerftools-2.1.0 → nerftools-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nerftools
-Version: 2.1.0
+Version: 2.2.0
 Summary: Define and generate nerf tools: limited-scope wrappers for common CLI utilities that allow for fine-grained control over agent execution
 Project-URL: Homepage, https://github.com/WayfarerLabs/nerftools
 Project-URL: Repository, https://github.com/WayfarerLabs/nerftools

{nerftools-2.1.0 → nerftools-2.2.0}/README.md

@@ -42,9 +42,11 @@ For more detail on the manifest format and tool types/capabilities, see the
 [manifest reference](docs/nerf-manifest.md).
 
 This repo includes a set of [default manifests](nerftools/default_manifests/) that define a baseline
-set of nerf tools for common CLI utilities. Users are free to build upon these with their own custom
+set of nerf tools for common CLI utilities. Note that these are biased towards the author's stack
+(Azure, AZDO, Github, Kubectl, etc.). Users are free to build upon these with their own custom
 manifests or exclude them entirely by passing the `--no-default` flag to the CLI when generating
-tools.
+tools. Default manifest contributions that meet our exacting standards are very much encouraged,
+too.
 
 ### Targets
 
@@ -62,9 +64,9 @@ within that package along with the package-level information.
 
 This repo offers several ways to use the nerf tools. Choose the best one for your specific needs:
 
-- The repo exposes a fully-generated Claude Code plugin with the default tools that can be installed
-  into a Claude Code environment directly from this repository. This is super easy but does not
-  allow for customization of the tools or other changes to the plugin.
+- The repo exposes fully-generated plugins for Claude Code and Codex with the default tools, both
+  installable directly from this repository. This is super easy but does not allow for customization
+  of the tools or other changes to the plugins.
 - Alternatively, users can install the Python package and generate their own targets locally using
   the CLI.
 - Additionally, platforms like [Agentworks](https://github.com/WayfarerLabs/agentworks) integrate
@@ -103,6 +105,9 @@ uv run nerf generate --target skills --outdir ./skills
 # Generate a Claude Code plugin (uses built-in defaults if no config)
 uv run nerf generate --target claude-plugin --outdir ./claude-plugin
 
+# Generate a Codex plugin
+uv run nerf generate --target codex-plugin --outdir ./codex-plugin
+
 # Generate a Claude Code plugin with custom identity
 uv run nerf generate --target claude-plugin -c nerf.yaml --outdir ./claude-plugin
 ```
@@ -118,20 +123,16 @@ claude plugin marketplace add <plugin-dir>
 claude plugin install <plugin-name>@<marketplace-name>
 ```
 
-## Default Manifests/Packages
-
-| Package      | Tools | Description                                                      |
-| ------------ | ----- | ---------------------------------------------------------------- |
-| git          | 11    | Git workflow with commit, push, fetch, tag, amend, revert, reset |
-| az-repos     | 3     | Azure Repos PR management                                        |
-| az-pipelines | 3     | Azure Pipelines monitoring                                       |
-| az-boards    | 7     | Azure Boards work items (query, view, create, update)            |
-| nx           | 6     | Nx monorepo workspace operations                                 |
-| tg           | 10    | Terragrunt infrastructure management                             |
-| pkgrun       | 3     | npm package runners (cspell, markdownlint, prettier)             |
-| stdutils     | 4     | Unix utilities (find, grep) with safety guardrails               |
-| gh           | 10    | GitHub CLI (PRs, issues, workflow runs)                          |
-| uv           | 4     | Python dev tools via uv run (pytest, ruff, mypy)                 |
+## Default Manifests
+
+The repo ships a [default set of manifests](nerftools/default_manifests/) covering common CLI
+utilities -- git, gh, much of the `az` surface (Repos, Pipelines, Boards, AKS, network, storage,
+role assignments, and others), kubectl, terraform/terragrunt, nx, uv, and assorted utilities. Browse
+the directory for the current set; each YAML's package description and tool definitions explain
+what's covered and the threat profile of each tool.
+
+Use the defaults as-is, layer your own manifests on top, or skip them entirely with `--no-default`
+when generating.
 
 ## Nerf Control Tools
 
@@ -191,12 +192,15 @@ nerftools/             Python package
   builder.py           Bash script generation (3 execution modes)
   rendering.py         Shared display helpers (maps-to, usage tokens)
   skill.py             Rulesync skill generation
-  formats.py           Claude Code plugin builder
+  formats.py           Claude Code and Codex plugin builders
+  outdir.py            Output directory safety guard (refuses to wipe unmanaged dirs)
   config.py            Config loader, plugin metadata, defaults resolution
   cli.py               CLI (validate + generate)
-  nerfctl/claude/      Grant management shell scripts
+  nerfctl/claude/      Grant management shell scripts (Claude Code)
+  nerf_report/         Bundled agent-feedback tool template
   default_manifests/   Default tool package manifests (YAML)
 tests/                 Test suite
 out/claude-plugin/     Pre-built Claude Code plugin (auto-generated)
-docs/                  Manifest spec and other (future) docs
+out/codex-plugin/      Pre-built Codex plugin (auto-generated)
+docs/                  Manifest spec and design docs
 ```

{nerftools-2.1.0 → nerftools-2.2.0}/docs/nerf-manifest.md

@@ -147,6 +147,13 @@ constructs (lookaheads, named groups, etc.) will pass load-time validation but w
 runtime. Stick to ERE. As a convenience, `\b` boundaries are translated to portable POSIX ERE at
 generation time so manifests can keep using them.
 
+The hook is **opt-in at runtime**: even when generated and installed, it is a silent no-op unless
+the brand-namespaced env var `<BRAND>_ENABLE_BASH_HINT_HOOK` (e.g. `NERF_ENABLE_BASH_HINT_HOOK` for
+the default `nerf-` prefix, `MY_TOOL_ENABLE_BASH_HINT_HOOK` for `my-tool-`) is set to a truthy value
+(`1`, `true`, `yes`, or `on` — case-insensitive). The redirect is aggressive enough that we make
+this explicit rather than discover-by-surprise. Brand-namespacing the env var means two plugins with
+different brands installed side-by-side have independent kill switches.
+
 The hook automatically skips when it detects an actual wrapper invocation: it splits the command on
 shell separators (`&&`, `||`, `;`, `|`, `&`), finds the first non-env-var token of each segment, and
 checks whether that token's basename starts with the wrapper prefix. Compound forms like

{nerftools-2.1.0 → nerftools-2.2.0}/nerf.yaml

@@ -3,7 +3,7 @@
 
 package:
     name: nerftools
-    version: 2.1.0 # x-release-please-version
+    version: 2.2.0 # x-release-please-version
     description: Scoped, safety-constrained CLI wrappers for AI agents
     author:
         name: WayfarerLabs

{nerftools-2.1.0 → nerftools-2.2.0}/nerftools/formats.py

@@ -723,6 +723,12 @@ _HINT_HOOK_TEMPLATE = '''\
 # command allows the call through without matching. Empty reason still denies,
 # with an explanation.
 #
+# Opt-in: this hook is a no-op unless __BRAND_ENV__ is set to a truthy
+# value (1, true, yes, on -- case-insensitive). The redirect is aggressive
+# enough that we make agents/users explicitly opt in rather than discover
+# it by surprise. The env var is brand-namespaced so two plugins with
+# different brands installed side-by-side don't share a kill switch.
+#
 # Fail-open behavior: if bash < 4 or jq is missing, the hook exits 0 silently.
 # A SessionStart hook surfaces a warning so the user knows the redirect is
 # disabled.
@@ -732,6 +738,12 @@ if [[ "${BASH_VERSINFO[0]:-0}" -lt 4 ]]; then
   exit 0
 fi
 
+# Opt-in gate: silent no-op unless explicitly enabled.
+case "${__BRAND_ENV__:-}" in
+  1 | [tT][rR][uU][eE] | [yY][eE][sS] | [oO][nN]) ;;
+  *) exit 0 ;;
+esac
+
 set -uo pipefail
 
 _WRAPPER_PREFIX="__PREFIX__"
@@ -855,6 +867,21 @@ def _derive_brand(prefix: str) -> str:
     return prefix.rstrip("-_") or "nerf"
 
 
+def _derive_brand_env_var(brand: str) -> str:
+    """Derive the brand-namespaced env var that opts the hook in.
+
+    Two plugins with different brands installed side-by-side need
+    independent kill switches; namespacing the env var by brand makes
+    them non-interfering. ``"nerf"`` -> ``"NERF_ENABLE_BASH_HINT_HOOK"``,
+    ``"my-tool"`` -> ``"MY_TOOL_ENABLE_BASH_HINT_HOOK"``.
+    """
+    sanitized = re_module.sub(r"[^A-Z0-9]", "_", brand.upper())
+    # Env var names can't start with a digit.
+    if sanitized and sanitized[0].isdigit():
+        sanitized = "_" + sanitized
+    return f"{sanitized}_ENABLE_BASH_HINT_HOOK"
+
+
 def _build_bash_hint_hook_script(manifests: list[NerfManifest], *, prefix: str) -> str:
     """Render the PreToolUse hint dispatcher with patterns baked in."""
     brand = _derive_brand(prefix)
@@ -871,6 +898,7 @@ def _build_bash_hint_hook_script(manifests: list[NerfManifest], *, prefix: str)
         .replace("__PREFIX__", _bash_double_quote_escape(prefix))
         .replace("__BRAND__", _bash_double_quote_escape(brand))
         .replace("__BRAND_RE__", _bash_double_quote_escape(_ere_escape(brand)))
+        .replace("__BRAND_ENV__", _derive_brand_env_var(brand))
     )
 
 

{nerftools-2.1.0/out/codex-plugin/.codex-plugin → nerftools-2.2.0/out/claude-plugin/.claude-plugin}/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nerftools",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Scoped, safety-constrained CLI wrappers for AI agents",
   "skills": "./skills/",
   "author": {

{nerftools-2.1.0 → nerftools-2.2.0}/out/claude-plugin/hooks/nerf-bash-hint

@@ -10,6 +10,12 @@
 # command allows the call through without matching. Empty reason still denies,
 # with an explanation.
 #
+# Opt-in: this hook is a no-op unless NERF_ENABLE_BASH_HINT_HOOK is set to a truthy
+# value (1, true, yes, on -- case-insensitive). The redirect is aggressive
+# enough that we make agents/users explicitly opt in rather than discover
+# it by surprise. The env var is brand-namespaced so two plugins with
+# different brands installed side-by-side don't share a kill switch.
+#
 # Fail-open behavior: if bash < 4 or jq is missing, the hook exits 0 silently.
 # A SessionStart hook surfaces a warning so the user knows the redirect is
 # disabled.
@@ -19,6 +25,12 @@ if [[ "${BASH_VERSINFO[0]:-0}" -lt 4 ]]; then
   exit 0
 fi
 
+# Opt-in gate: silent no-op unless explicitly enabled.
+case "${NERF_ENABLE_BASH_HINT_HOOK:-}" in
+  1 | [tT][rR][uU][eE] | [yY][eE][sS] | [oO][nN]) ;;
+  *) exit 0 ;;
+esac
+
 set -uo pipefail
 
 _WRAPPER_PREFIX="nerf-"

{nerftools-2.1.0 → nerftools-2.2.0}/out/claude-plugin/skills/nerf-report/scripts/nerf-report

@@ -5,7 +5,7 @@
 set -euo pipefail
 
 # Stamped at plugin build time.
-NERFTOOLS_VERSION="2.1.0"
+NERFTOOLS_VERSION="2.2.0"
 
 # Reports live under $HOME; fail fast with an actionable message if it's
 # unset rather than relying on `set -u` to crash later with "unbound variable".

{nerftools-2.1.0/out/claude-plugin/.claude-plugin → nerftools-2.2.0/out/codex-plugin/.codex-plugin}/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nerftools",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Scoped, safety-constrained CLI wrappers for AI agents",
   "skills": "./skills/",
   "author": {

{nerftools-2.1.0 → nerftools-2.2.0}/out/codex-plugin/skills/nerf-report/scripts/nerf-report

@@ -5,7 +5,7 @@
 set -euo pipefail
 
 # Stamped at plugin build time.
-NERFTOOLS_VERSION="2.1.0"
+NERFTOOLS_VERSION="2.2.0"
 
 # Reports live under $HOME; fail fast with an actionable message if it's
 # unset rather than relying on `set -u` to crash later with "unbound variable".

{nerftools-2.1.0 → nerftools-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nerftools"
-version = "2.1.0"
+version = "2.2.0"
 description = "Define and generate nerf tools: limited-scope wrappers for common CLI utilities that allow for fine-grained control over agent execution"
 requires-python = ">=3.12"
 license = "MIT"

{nerftools-2.1.0 → nerftools-2.2.0}/tests/test_formats.py

@@ -278,14 +278,34 @@ def _manifest_with_hints(
     )
 
 
-def _run_hook(script: Path, payload: dict) -> tuple[str, int]:
+def _run_hook(
+    script: Path,
+    payload: dict,
+    *,
+    env: dict[str, str] | None = None,
+    brand: str = "nerf",
+) -> tuple[str, int]:
+    import os
     import subprocess
 
+    from nerftools.formats import _derive_brand_env_var
+
+    # The hook is opt-in via <BRAND>_ENABLE_BASH_HINT_HOOK -- default the
+    # brand to "nerf" (matches all existing tests' prefix="nerf-") and
+    # default the gate to truthy so the tests exercise the hook's logic.
+    # Tests of the gate itself pass an explicit env that overrides.
+    # Use the production helper directly so test/hook env-var derivation
+    # can't drift (e.g., on digit-leading brands).
+    enable_var = _derive_brand_env_var(brand)
+    merged_env = {**os.environ, enable_var: "true"}
+    if env is not None:
+        merged_env.update(env)
     result = subprocess.run(
         [str(script)],
         input=json.dumps(payload),
         capture_output=True,
         text=True,
+        env=merged_env,
         check=False,
     )
     return result.stdout, result.returncode
@@ -448,6 +468,70 @@ def test_claude_plugin_hook_script_executable(tmp_path: Path) -> None:
     assert script.stat().st_mode & 0o111  # executable
 
 
+@pytest.mark.parametrize("enable_value", ["true", "TRUE", "True", "1", "yes", "YES", "on", "ON"])
+def test_hook_runs_when_enable_env_is_truthy(tmp_path: Path, enable_value: str) -> None:
+    _build([_manifest_with_hints()], tmp_path, prefix="nerf-")
+    script = tmp_path / "hooks" / "nerf-bash-hint"
+    stdout, rc = _run_hook(
+        script,
+        {"tool_name": "Bash", "tool_input": {"command": "git status"}},
+        env={"NERF_ENABLE_BASH_HINT_HOOK": enable_value},
+    )
+    assert rc == 0
+    assert json.loads(stdout)["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+@pytest.mark.parametrize(
+    "enable_value", ["", "false", "0", "no", "off", "FaLsE", "anything-else"]
+)
+def test_hook_silent_noop_when_enable_env_is_not_truthy(tmp_path: Path, enable_value: str) -> None:
+    _build([_manifest_with_hints()], tmp_path, prefix="nerf-")
+    script = tmp_path / "hooks" / "nerf-bash-hint"
+    stdout, rc = _run_hook(
+        script,
+        {"tool_name": "Bash", "tool_input": {"command": "git status"}},
+        env={"NERF_ENABLE_BASH_HINT_HOOK": enable_value},
+    )
+    assert rc == 0
+    assert stdout == ""  # nothing printed -> Claude Code lets the command through
+
+
+def test_hook_silent_noop_when_enable_env_is_unset(tmp_path: Path) -> None:
+    """Explicit guard against accidentally clobbering os.environ: pass an env
+    dict that omits NERF_ENABLE_BASH_HINT_HOOK to confirm the unset case."""
+    import os
+    import subprocess
+
+    _build([_manifest_with_hints()], tmp_path, prefix="nerf-")
+    script = tmp_path / "hooks" / "nerf-bash-hint"
+    env = {k: v for k, v in os.environ.items() if k != "NERF_ENABLE_BASH_HINT_HOOK"}
+    result = subprocess.run(
+        [str(script)],
+        input=json.dumps({"tool_name": "Bash", "tool_input": {"command": "git status"}}),
+        capture_output=True,
+        text=True,
+        env=env,
+        check=False,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_hook_env_var_is_brand_namespaced(tmp_path: Path) -> None:
+    """A non-default brand gets its own env var so multiple plugins coexist."""
+    _build([_manifest_with_hints()], tmp_path, prefix="acme-")
+    script = tmp_path / "hooks" / "nerf-bash-hint"
+    script_text = script.read_text()
+    assert "ACME_ENABLE_BASH_HINT_HOOK" in script_text
+    assert "NERF_ENABLE_BASH_HINT_HOOK" not in script_text
+
+
+def test_hook_with_hyphenated_brand_uppercases_and_underscores(tmp_path: Path) -> None:
+    _build([_manifest_with_hints()], tmp_path, prefix="my-tool-")
+    script = tmp_path / "hooks" / "nerf-bash-hint"
+    assert "MY_TOOL_ENABLE_BASH_HINT_HOOK" in script.read_text()
+
+
 def test_hook_denies_matching_command(tmp_path: Path) -> None:
     _build([_manifest_with_hints()], tmp_path, prefix="nerf-")
     script = tmp_path / "hooks" / "nerf-bash-hint"
@@ -587,6 +671,7 @@ def test_hook_brand_regex_meta_safe(tmp_path: Path) -> None:
     stdout, _ = _run_hook(
         script,
         {"tool_name": "Bash", "tool_input": {"command": "git status  # myXtool:bypass reason"}},
+        brand="my.tool",
     )
     reason = json.loads(stdout)["hookSpecificOutput"]["permissionDecisionReason"]
     assert "`my.tool-git`" in reason
@@ -594,6 +679,7 @@ def test_hook_brand_regex_meta_safe(tmp_path: Path) -> None:
     stdout, _ = _run_hook(
         script,
         {"tool_name": "Bash", "tool_input": {"command": "git status  # my.tool:bypass reason"}},
+        brand="my.tool",
     )
     assert stdout == ""
 
@@ -660,12 +746,14 @@ def test_hook_brand_follows_prefix(tmp_path: Path) -> None:
     stdout, _ = _run_hook(
         script,
         {"tool_name": "Bash", "tool_input": {"command": "git status  # mytool:bypass yes"}},
+        brand="mytool",
     )
     assert stdout == ""
     # Bypass with the old "nerf:" brand does NOT match -> still denies
     stdout, _ = _run_hook(
         script,
         {"tool_name": "Bash", "tool_input": {"command": "git status  # nerf:bypass yes"}},
+        brand="mytool",
     )
     reason = json.loads(stdout)["hookSpecificOutput"]["permissionDecisionReason"]
     assert "`mytool-git`" in reason

{nerftools-2.1.0 → nerftools-2.2.0}/uv.lock

@@ -176,7 +176,7 @@ wheels = [
 
 [[package]]
 name = "nerftools"
-version = "2.1.0"
+version = "2.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

nerftools-2.1.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "2.1.0"
-}