@blogic-cz/agent-tools 1.6.16 → 1.6.18

package/README.md

@@ -249,6 +249,17 @@ import { handleToolExecuteBefore } from "@blogic-cz/agent-tools/credential-guard
 export default { handleToolExecuteBefore };
 ```
 
+Guard refusals include recovery guidance for the policy that blocked the command. Direct CLI
+refusals preserve the configured wrapper or suggestion. Built-in wrappers support `--help`;
+consult this README and the tool's own help to find an existing bounded operation.
+
+Interactive and login shells load startup files. Supported noninteractive literal forms pass
+only when the guard proves their complete closed body. The guard sees command text, not external
+script contents, so removing shell flags does not certify a script. The guard provides no generic
+approved external-script executor. Review or implement a repository-owned bounded operation with
+secret injection and filtered output when existing tools do not cover the task. Environment
+approval permits exact nonsensitive reads, not script execution or environment forwarding.
+
 ## Tools
 
 | Binary               | Description                                                                                                      |
@@ -672,14 +683,36 @@ Literal `herdr agent prompt` commands can be composed with independent `cat` rea
 
 Prompt composition also supports one `cd [--] PATH` with a literal relative or absolute directory at the start of the final `&&` chain. All subsequent inspection must remain in that chain, so a failed `cd` cannot reach its readers. Directory names may contain quoted spaces. Multiple `cd` commands, later `;` or newline boundaries, tilde or variable expansion, other `cd` options, background jobs, `||`, and navigation in pipelines remain unproved. Supported Git inspection can use literal `-C PATH` prefixes with `grep`, `status`, `rev-parse`, or `rev-list`; execution and startup options remain unsupported. Navigation composition refuses relative file redirects, including redirects on `cd` and Git commands, because those use the shell directory before the command runs. Absolute redirects still receive ordinary path checks. Named directories receive sensitive-path checks with directory-prefix semantics. Only a proved `cd` chain qualifies relative reader operands with that directory; Git `-C` qualifies that command's file operands without changing shell state. Git grep uses the shared grep pattern-versus-file checks. This checks textual operands and does not resolve aliases, symlinks, ambient directories, or command lookup.
 
-The guard recognizes `rtk`, `rtk proxy`, `command`, and supported `env` prefixes and checks commands in pipelines and chains. Quoted filenames, comments, and redirects retain sensitive-path checks. Jq object selectors and inline awk programs qualify only when their actual program and options establish passive behavior. Literal environment-command text in `rg`, `grep`, `git grep`, `echo`, and `printf` is allowed only with supported command roles and passive pipeline consumers. Environment-source evidence and startup identity checks also apply to the complete original invocation. Custom dangerous-command patterns apply to both the original input and proved expansions.
+The guard recognizes `rtk`, `rtk proxy`, `command`, and supported `env` prefixes and checks commands in pipelines and chains. Quoted filenames, comments, and redirects retain sensitive-path checks. Jq filters and inline awk programs qualify only when their actual program and options establish passive behavior. Literal environment-command text in `rg`, `grep`, `git grep`, `echo`, and `printf` is allowed only with supported command roles and passive pipeline consumers. Environment-source evidence and startup identity checks also apply to the complete original invocation. Custom dangerous-command patterns apply to both the original input and proved expansions.
+
+Jq admission uses a closed grammar for `.field` traversal, literal string/numeric indexes, `[]`/`[]?`, parentheses, `//`, pipelines, nested objects/arrays, literal JSON values, comparisons, arithmetic and `and`/`or`. It admits the pure zero-argument filters `length`, `keys`, `keys_unsorted`, `type`, `values`, `empty`, `add`, `min`, `max`, `sort`, `unique`, `flatten`, `not`, `reverse`, `to_entries` and `from_entries`; single-argument calls are `map`, `map_values`, `select`, `contains`, `has`, `sort_by`, `group_by`, `unique_by`, `any`, `all` and `join`. Operator precedence remains jq's responsibility; the guard validates complete operands and delimiters without evaluating a filter. Unknown functions/syntax, comments, interpolation, variables, `env`/`$ENV`, imports/includes and program-loading options refuse. A string or field named `env` stays data. Limits are 65,536 UTF-8 bytes, 4,096 tokens and 64 nested expression levels. Known formatting/input flags must precede the literal filter. File operands, redirects, downstream consumers and configured command/path rules still apply. Unquoted file globs and tilde paths anywhere in a compound jq invocation refuse; quote or escape genuinely literal filenames, or provide explicit nonsensitive paths.
+
+This is a textual jq proof under trusted native executables and host startup configuration. Normal jq loads a home `.jq` file, which can redefine builtins; the guard does not inspect it or prove module provenance. `-L` does not suppress that startup file. The supported exact POSIX child-process form `env HOME=/dev/null jq 'FILTER' file.json` avoids the user home-file lookup. Other explicit startup assignments/env prefixes anywhere in the compound invocation do not receive the jq proof, including producer/consumer cwd mutations. Literal directory changes must satisfy the existing gated navigation proof. Neither form certifies JSON contents, native binaries, aliases or symlinks.
+
+Every jq compound command must have a supported native data, navigation, declared frontend or existing literal-script role. Unknown heads, `builtin` wrappers, directory-stack commands and shell state mutations cannot establish context. Declared CLI producers and literal script roles retain their ordinary policies; their source contents are not certified passive.
+
+Syntax compilation supports `python3 -I -S -m py_compile src/main.py`, also `python`, known RTK/command wrappers and combined/reordered `-I`, `-S`, `-B` flags before `-m`. Both isolation flags are required: `-I` excludes cwd/user imports and Python startup variables, and `-S` disables site hooks. The module must be exactly `py_compile`, followed by 1–32 literal nonsensitive `.py` paths. Stdin filename lists, unknown flags/modules, expansions, startup mutations and executable output consumers refuse. Target source is compiled without execution, but `__pycache__` writes still occur with `-B`, and error output may quote source. This does not inspect source contents or attest filesystem/runtime identity.
+
+With any `additionalBlockedPaths` rule, implicit compiler cache/temp filenames cannot be proved against that policy, so `py_compile` refuses. Use a cache-free syntax parse instead: `python3 -I -S -B -c 'import ast; ast.parse(open("src/main.py", "rb").read(), filename="src/main.py")'`. This form remains subject to source-path, inline-program and command policies. It parses the named source without executing it or writing target bytecode caches. The refusal explains the cache boundary separately from environment access.
 
-Paths are checked against sensitive filename patterns and configured path rules. Supported proofs apply those checks to their expanded operands. Ordinary parent-directory and absolute paths may be allowed; the guard does not resolve filesystem paths or symlinks, or enforce repository confinement.
+Paths are checked against sensitive filename patterns and configured path rules. Supported proofs apply those checks to their expanded operands. Ordinary parent-directory and absolute paths may be allowed; the guard does not resolve filesystem paths or symlinks, or enforce repository confinement. The default kubeconfig pattern protects every path segment containing `kubeconfig`, including ancestor directories and names without separators such as `mykubeconfig` or `kubeconfig2`. Only a final ordinary Markdown basename that does not start with `kubeconfig`, such as `check-kubeconfig-topology.md` or `cluster-kubeconfig-notes.md`, has the documentation exception; the `.md` suffix must be the exact end of the path. A kubeconfig-containing ancestor still matches the blocked pattern; `kubeconfig.md` remains protected. Existing explicit path allowances take precedence over blocked patterns, including template names such as `prod-kubeconfig/.env.example` and configured `additionalAllowedPaths`. Otherwise, configured blocked paths still apply to documentation names. This filename convention does not attest file contents, and there is no blanket Markdown or memory-directory exception.
 
 Recognized Linux process-environment paths such as `/proc/self/environ`, `/proc/thread-self/environ`, and PID/task variants are blocked before configured path exceptions.
 
 Single literal `echo`/`printf` writes with output redirection and single `cat`/`tee` heredoc writes are allowed. Heredoc braces are data. Use a quoted delimiter for literal code; unquoted heredocs containing `$`, backticks, or backslashes do not receive the literal-write exception. The exception permits only supported combinations with navigation or selected inspections; unsupported following commands remain outside it. Supported complete Python stdin heredocs are checked as inline programs, with the normal runtime-argument, path, execution, and environment checks.
 
+A supported Python stdin heredoc can be followed by complete literal `cat`/`tee` heredoc writers and passive consumers. The guard retains every writer header, file operand and redirect while excluding only the proved literal bodies from path evidence. Incomplete bodies, executable/unknown headers and unsupported following commands gain no exception. Heredoc composition is bounded to 32 bodies and 65,536 bytes. This separates prose from path operands; Bash writes/output are not content attestation, and Write/Edit secret scanning remains separate.
+
+Quoted single-letter literal bindings such as `D="/workspace/docs/topic"; ls -la "$D"; grep -n X "$D/file.md"` receive the existing closed path proof. Finite literal loops can use the binder inside a jq filename, for example `for i in 1 2; do jq '.rows // [] | length' sample-$i.json; done`; the filter/options and every materialized path are checked. A derived path list such as `f=$(git grep -l PATTERN -- '*.cs')` remains unproved: the input-only guard cannot inspect output paths, shell splitting or sensitive matches. Use direct `git grep` output or separately checked literal paths. This refusal identifies a local derived binding rather than claiming ambient environment access. A literal binding in a script/executable operand also remains outside the file-data proof.
+
+The same finite loop proof admits numeric `--pr` selectors for `bun run gh-tool pr checks`, `checks-failed`, `info` and `review-triage`, with optional literal `--repo`, and `git diff [one literal revision-shaped operand] -- literal filenames`. Git diff loop prefix options, including output/order files and no-index mode, remain unproved. Git can implicitly compare filesystem paths outside a worktree or when a path points outside it. The optional operand also receives ordinary/custom file policy as a potential path, including proved cwd and Git `-C` qualification; the guard does not certify repository context or guarantee that it is a revision. Every generated path receives the ordinary policy. One literal local directory binding may be used only by the first successful gated `cd`, followed by supported literal commands including Git clone without executable configuration/upload-pack options. Variable script operands and HOME-dependent tilde bindings remain unproved.
+
+Literal Herdr prompt pipelines may compose with independent commands such as pane close or a literal script operation. The prompt pipeline's consumers must be supported data commands; each sibling still receives ordinary path, environment, runtime and configured policy checks. If the lexer finds an unterminated quoted argument, recovery explains shell encoding. A single-quoted apostrophe can be encoded as `'don'"'"'t'`. File-input options are recommended only when the command documents one.
+
+Bun's late startup-flag scan respects a separate `--` after a supported literal task/file operand. Words thereafter are tool argv for this scan, including `-p:Example=false`; actual startup controls before the separator still refuse. Missing targets, runtime subcommands and embedded/attached separator text do not receive this boundary. Task/file lookup retains the existing trusted host/project assumption, including task lifecycle hooks; source contents are not inspected. Explicit interpreter lookup/loader variables such as `BUN_OPTIONS`, `NODE_OPTIONS`, `PYTHONPATH` and `BASH_ENV` cannot establish startup context. Literal ordinary selector/deadline prefixes remain subject to the existing path/environment rules.
+
+Shared Git diff inspection uses a finite argv-role table. Output/order-file values and positional revision/file words receive ordinary/custom path policy, with proved cwd and Git `-C` qualification. Known required search/prefix values are data; optional context/rename/color/relative values attach to their option and never consume the next file. Short clusters are read left to right, so `-pO.env` has a file role and `-S-O.env` has a search-data role. Exact long options take priority over unique supported abbreviations; ambiguous/unknown options, incomplete roles and executable callbacks refuse with Git-specific recovery. This does not inspect repository state, trusted native executables/configuration, task contents, aliases or symlinks.
+
 Python JSON parsing, dictionary iteration, and printing are not themselves evidence of credential access. They follow the same access and execution rules as other supported inline programs. This intentionally permits ordinary JSON output that older versions refused. Unknown secrets in ordinary files can therefore reach arbitrary shell output; wrapper content checks do not protect that output. A refusal caused by unsupported syntax means the guard could not establish its policy conditions, not that it observed a secret being read.
 
 The bounded Python subprocess proof supports one immutable literal argv binding followed by one `subprocess.run` call. A literal `cwd` is replayed as a quoted, success-gated directory change before the nested argv, so relative reader operands and named directories receive the ordinary path policies. Supported directories are literal relative or absolute paths, including quoted spaces. Empty, dynamic, Unicode, escaped, tilde and other unsupported directory forms refuse rather than dropping the context. Cwd proof recursively unwraps only supported command, RTK proxy and environment wrappers. Environment directory/split-string options and unproved wrapper forms refuse. Only supported passive text, reader, metadata, literal Bun script and blocked CLI roles receive nested replay; shell executors, inline interpreter programs, unproved sed programs, find execution actions and unknown command roles refuse. Nested blocked CLI, environment, sensitive-path and custom-command policies remain active. Outer shell redirects retain their original shell directory. Arbitrary multi-call Python and `check_output` programs remain unsupported; direct Git metadata commands provide index/tree inspection.

package/dist/credential-guard/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/credential-guard/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAK5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM/D,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAAC;AAQF,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxE,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3E,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,sBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACxD,CAAC;AA4+FF,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAErE;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEpE;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEpE;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CA+XrF;AAQD,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,UAr5GD,SAAS,UAAU,UAAU,KAAK,IAq5GM,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,aAAa,YAv5GC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAu5GjB,CAAC;AAExD,yEAAyE;AACzE,eAAO,MAAM,aAAa,aAz5GE,MAAM,KAAK,OAy5GgB,CAAC;AAExD,yDAAyD;AACzD,eAAO,MAAM,aAAa,aA35GE,MAAM,KAAK,OA25GgB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,YA75GC,MAAM,KAAK,OA65G0B,CAAC;AAE1E,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,YA/5GC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IA+5Gf,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,YAj6GC,MAAM,KAAK,OAi6GsB,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,YAn6GC,MAAM,KAAK,MAAM,GAAG,IAm6Ga,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/credential-guard/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAM5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM/D,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAAC;AAQF,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxE,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3E,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,sBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACxD,CAAC;AA83GF,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAErE;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEpE;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEpE;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CA6hBrF;AAQD,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,UAr8HD,SAAS,UAAU,UAAU,KAAK,IAq8HM,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,aAAa,YAv8HC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAu8HjB,CAAC;AAExD,yEAAyE;AACzE,eAAO,MAAM,aAAa,aAz8HE,MAAM,KAAK,OAy8HgB,CAAC;AAExD,yDAAyD;AACzD,eAAO,MAAM,aAAa,aA38HE,MAAM,KAAK,OA28HgB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,YA78HC,MAAM,KAAK,OA68H0B,CAAC;AAE1E,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,YA/8HC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IA+8Hf,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,YAj9HC,MAAM,KAAK,OAi9HsB,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,YAn9HC,MAAM,KAAK,MAAM,GAAG,IAm9Ha,CAAC"}

package/dist/credential-guard/passive-jq.d.ts

@@ -0,0 +1,5 @@
+/** Closed admission grammar, not an evaluator. Unknown syntax never acquires a proof. */
+export declare function isPassiveJqFilter(filter: string): boolean;
+/** Only known formatting/input flags and one literal program, followed by file operands. */
+export declare function passiveJqProgramIndex(argv: string[]): number | undefined;
+//# sourceMappingURL=passive-jq.d.ts.map

package/dist/credential-guard/passive-jq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-jq.d.ts","sourceRoot":"","sources":["../../src/credential-guard/passive-jq.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAoIzD;AAED,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAsBxE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "1.6.16",
+  "version": "1.6.18",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure platform, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",