@blogic-cz/agent-tools 1.6.16 → 1.6.17

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                                                                                                      |

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;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,CA4arF;AAQD,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,UAl8GD,SAAS,UAAU,UAAU,KAAK,IAk8GM,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,aAAa,YAp8GC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAo8GjB,CAAC;AAExD,yEAAyE;AACzE,eAAO,MAAM,aAAa,aAt8GE,MAAM,KAAK,OAs8GgB,CAAC;AAExD,yDAAyD;AACzD,eAAO,MAAM,aAAa,aAx8GE,MAAM,KAAK,OAw8GgB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,YA18GC,MAAM,KAAK,OA08G0B,CAAC;AAE1E,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,YA58GC,MAAM,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IA48Gf,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,YA98GC,MAAM,KAAK,OA88GsB,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,YAh9GC,MAAM,KAAK,MAAM,GAAG,IAg9Ga,CAAC"}

package/package.json

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

package/src/credential-guard/index.ts

@@ -3426,6 +3426,55 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
     }
   }
 
+  function blockedCliRecovery(blockedTool: { name: string; wrapper: string }): string {
+    // Custom suggestions can be prose or commands. Preserve them without inventing a binary.
+    const hasKnownHelp = DEFAULT_BLOCKED_CLI_TOOLS.some(
+      ({ wrapper }) => wrapper === blockedTool.wrapper,
+    );
+    return (
+      `Configured recovery: ${blockedTool.wrapper}\n` +
+      (hasKnownHelp ? `Discover supported operations: ${blockedTool.wrapper} --help\n` : "") +
+      `Check the project README and the tool's documented help for the bounded operation.`
+    );
+  }
+
+  function dangerousCommandRecovery(command: string, reason: string): string {
+    if (reason.startsWith("invokes a blocked CLI")) {
+      const blockedTool = getBlockedCliTool(command);
+      if (blockedTool) return blockedCliRecovery(blockedTool);
+    }
+    const externalExecutionRecovery =
+      `The guard sees the command, not external script contents. Removing shell flags does not certify a script. ` +
+      `No generic approved external-script executor is provided by this guard. Review or implement a repository-owned bounded operation ` +
+      `with secret injection and filtered output; discover existing operations in the project README and tool help.`;
+    if (reason.startsWith("cannot prove") && reason.includes("shell")) {
+      return (
+        `Interactive and login shells load startup files, which can execute code or load credentials. ` +
+        `Only supported noninteractive literal forms, such as sh -c or zsh -f -c, with a completely proved closed body can pass. ` +
+        externalExecutionRecovery
+      );
+    }
+    if (reason.includes("file")) {
+      return (
+        `Use a nonsensitive example/template or a bounded wrapper operation that returns only the needed fields. ` +
+        `A matched sensitive path or an unverifiable file-access form remains blocked; do not copy or dump credential files.`
+      );
+    }
+    if (reason.includes("environment")) {
+      return (
+        `Do not dump or forward the environment. For a known nonsensitive value, use an exact approved name ` +
+        `with printenv NAME; approval is configured in credentialGuard.allowedEnvironmentVariables. ` +
+        `This does not approve execution or secret values. ` +
+        externalExecutionRecovery
+      );
+    }
+    return (
+      `The guard cannot verify this command form as permitted. Check the project README and tool help ` +
+      `for an existing bounded operation, or review the guard proof and add a regression test before changing policy. ` +
+      externalExecutionRecovery
+    );
+  }
+
   function enforceToolExecuteBefore(input: HookInput, output: HookOutput): void {
     // Normalize tool name across platforms:
     // - AI coding agents pass capitalized: "Bash", "Read", "Write", "Edit"
@@ -3472,8 +3521,8 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
         throw new Error(
           `\u{1F6AB} Command blocked: ${dangerousReason}; this command might expose secrets.\n\n` +
             `Command: ${command}\n\n` +
-            `Use a supported command form or the appropriate wrapper tool.\n\n` +
-            `Think this is wrong? Review the project repository, adjust the patterns, and submit a PR.`,
+            `${dangerousCommandRecovery(command, dangerousReason)}\n\n` +
+            `Tool inventory and usage: https://github.com/blogic-cz/agent-tools#tools`,
         );
       }
 
@@ -3489,14 +3538,10 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
 
       const blockedTool = getBlockedCliTool(command);
       if (blockedTool) {
-        const skillName = blockedTool.wrapper.replace("agent-tools-", "") + "-tool";
         throw new Error(
           `\u{1F6AB} Direct ${blockedTool.name} usage blocked.\n\n` +
             `AI agents must use wrapper tools for security and audit.\n\n` +
-            `Use instead: bun ${skillName}\n\n` +
-            `Example: bun ${skillName} --help\n\n` +
-            `Think this tool should be allowed? Review the project repository, extend the whitelist, and submit a PR.\n` +
-            `→ Skill "${skillName}"`,
+            blockedCliRecovery(blockedTool),
         );
       }
     }