nerftools 2.1.0__tar.gz → 3.0.0__tar.gz

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

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

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

@@ -1,5 +1,49 @@
 # Changelog
 
+## [3.0.0](https://github.com/WayfarerLabs/nerftools/compare/v2.2.0...v3.0.0) (2026-06-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* **hook:** hook file renamed from hooks/nerf-bash-hint to hooks/nerf-pre-tool-use; bypass sentinel renamed from \`# <brand>:bypass <reason>\` to \`# <brand>:bypass-bash-hint <reason>\`.
+* PreToolUse multi-check dispatcher with new current-version check
+
+### Features
+
+* **nerfctl:** --create-scope-dir and --prune-older for grant scripts ([e5aec37](https://github.com/WayfarerLabs/nerftools/commit/e5aec37a505ac2ef3b3056cbec5d82419875a41c))
+* **nerfctl:** add --create-scope-dir and --prune-older to grant scripts ([f087274](https://github.com/WayfarerLabs/nerftools/commit/f08727464a1fbe4c0ad4805809eb172f11ceed6c))
+* PreToolUse multi-check dispatcher with new current-version check ([4889d66](https://github.com/WayfarerLabs/nerftools/commit/4889d66e85e8e1ebca3f3ad028da633371bff868))
+
+
+### Bug Fixes
+
+* **hook:** address reviewer feedback on version check ([5a65c72](https://github.com/WayfarerLabs/nerftools/commit/5a65c72ea6102bb48eef02b74e871fe0021d2ec4))
+* **nerfctl:** clear error when .claude exists but is not a directory ([58f93e9](https://github.com/WayfarerLabs/nerftools/commit/58f93e97a672ea4bbe045960d618bcf740333005))
+* **nerfctl:** probe for sort -V (try gsort fallback); cover grant-reset in scope-dir tests ([8b11638](https://github.com/WayfarerLabs/nerftools/commit/8b11638034501b365dab62a5e395e50113b9e5db))
+* **nerfctl:** suppress capture() errors on non-Bash permission entries ([51565c5](https://github.com/WayfarerLabs/nerftools/commit/51565c5c92c05dfcc0b0562a307e3e76bb6faf79))
+* **nerfctl:** warn (not silent) when version sort unavailable without --prune-older ([210100d](https://github.com/WayfarerLabs/nerftools/commit/210100ddc642de0afc0480f6c198a0642c8077ad))
+
+
+### Documentation
+
+* **nerfctl:** align help text with no-sort behavior; fix stale stub comment ([c7a52a4](https://github.com/WayfarerLabs/nerftools/commit/c7a52a471e3d47e231e5e43b015fdcd4d97cdfe4))
+
+## [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-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nerftools
-Version: 2.1.0
+Version: 3.0.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-3.0.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-3.0.0}/docs/nerf-manifest.md

@@ -130,13 +130,35 @@ package:
 
 All fields except `skill_intro` and `bash_hints` are required.
 
-### Bash hint hook
+### PreToolUse hook
 
-Plugin targets that support a pre-bash hook (Claude Code today; others as their APIs land) use
-`bash_hints` to generate a redirect: when the agent calls raw bash with a command that matches any
-pattern, the hook denies the call (silently, without prompting the user) and points the agent at the
-corresponding nerf skill. Multiple matching skills are listed together. Targets without a pre-bash
-hook simply ignore the field.
+Plugin targets that support a PreToolUse hook (Claude Code today; others as their APIs land) get a
+single dispatcher script (`hooks/nerf-pre-tool-use`) that runs zero or more checks against each
+incoming Bash command. Each check is independently env-var gated and brand-namespaced so multiple
+plugins with different brands can coexist. Checks run in declaration order; the first denial
+short-circuits the rest.
+
+Two checks are currently emitted:
+
+1. **Current-version check** — env: `<BRAND>_ENABLE_CURRENT_VERSION_HOOK`. Refuses any tool
+   invocation whose absolute path points at a different version of THIS plugin (catches stale tool
+   paths an agent may have cached from a prior session after a plugin upgrade). The check matches on
+   plugin owner, plugin name, and tool-name brand prefix to avoid false positives on unrelated
+   plugins. The deny message tells the agent to use the current version, or to stop and report to
+   the user, depending on whether the call is older or newer than the current install. **No bypass
+   sentinel by design** — agents are not expected to work around a version-mismatch detection;
+   future contributors should not add one "for symmetry" with the bash-hint check.
+2. **Bash-hint check** — env: `<BRAND>_ENABLE_BASH_HINT_HOOK`. Described below.
+
+When the current-version check is enabled, the SessionStart hook also appends a reminder telling the
+agent which version to use and that mismatched calls will be rejected.
+
+#### Bash hint check
+
+Uses `bash_hints` to generate a redirect: when the agent calls raw bash with a command that matches
+any pattern, the hook denies the call (silently, without prompting the user) and points the agent at
+the corresponding nerf skill. Multiple matching skills are listed together. Targets without a
+PreToolUse hook simply ignore the field.
 
 Patterns are evaluated as POSIX ERE matches that may appear anywhere in the command — prefer
 word-boundary anchors (`\bgit\b`) over start-anchored ones (`^git`) so compound commands like
@@ -147,6 +169,14 @@ 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 bash-hint check is **opt-in at runtime**: even when generated and installed, the dispatcher's
+hint check 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
@@ -159,9 +189,11 @@ are unioned across them (order-preserved, deduped). An extension can add new pat
 restating the base set.
 
 An agent that genuinely needs to run the underlying command directly can include
-`# <brand>:bypass <reason>` anywhere in the command (reason required). The `<brand>` follows the
-wrapper prefix (default `nerf-` → `nerf`, `mytool-` → `mytool`). The hook lets the call through; the
-user's normal permission flow still applies.
+`# <brand>:bypass-bash-hint <reason>` anywhere in the command (reason required). The `<brand>`
+follows the wrapper prefix (default `nerf-` → `nerf`, `mytool-` → `mytool`). The hook lets the call
+through; the user's normal permission flow still applies. The sentinel is check-specific by design —
+it bypasses **only** the bash-hint check, never the current-version check or any other future
+checks.
 
 The conventional `<reason>` is the filename of a `nerf-report bypass` entry filed beforehand -- that
 keeps the bypass annotation grep-able from the agent's transcript while putting the full

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

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