@odingard/guardian-hook 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @odingard/guardian-hook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Guardian for coding agents.** A [Claude Code](https://code.claude.com/docs/en/hooks) `PreToolUse` hook that sends every consequential tool call (shell commands, file writes, web fetches, MCP tools) to Guardian before it runs.
+
+- `npm test` runs under **Allow**.
+- `terraform apply` waits until **you approve it on your phone**.
+- `rm -rf` is **denied** if that is the mode you set.
+
+There is no model in the decision: Guardian decides ALLOW / ASK / DENY deterministically from the permissions you set, and every allowed call carries a signed receipt you can verify offline.
+
+## How it works
+
+| Guardian says | What happens                                                                                                                                                                 |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ALLOW**     | The hook redeems the single-use capability (revocation and expiry are checked now, and the receipt is recorded), then tells the agent to run the call.                       |
+| **ASK**       | The agent waits. You get the request on your phone or in the console. On approval the hook claims and redeems the capability, then the call runs. It is never auto-approved. |
+| **DENY**      | The agent is told no, with the reason. Nothing runs.                                                                                                                         |
+
+**Fail closed.** If Guardian can't be reached, the configuration is wrong, approval times out or redemption fails, the call is denied. Each request stays open for 5 minutes (Guardian's limit), and the hook waits that long for an approval, under Claude Code's 600-second hook timeout, because a hook that times out does not block. An ASK not approved within 5 minutes expires; the call is denied and the agent can ask again.
+
+## Tools the hook proposes
+
+Shell commands are routed by consequence. That routing is what lets you put deploys behind your phone while ordinary commands flow freely.
+
+| Guardian tool         | Suggested mode | Covers                                                                                                                                             |
+| --------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shell`               | Allow          | Ordinary commands (build, test, inspect)                                                                                                           |
+| `shell_deploy`        | Ask me first   | terraform/tofu apply and destroy, pulumi up, kubectl apply and delete, helm install and upgrade, cloud deploy CLIs, package publish, `gh pr merge` |
+| `shell_destructive`   | Ask me first   | rm -rf, git reset --hard, git clean, force push, DROP/TRUNCATE, disk tools                                                                         |
+| `git_push`            | Ask me first   | Pushing commits                                                                                                                                    |
+| `file_write`          | Allow          | Write and edit (the approver sees the path, size and a SHA-256 of the content; the content itself is not sent)                                     |
+| `web_fetch`           | Allow          | Fetching a URL                                                                                                                                     |
+| `mcp.<server>.<tool>` | your choice    | Any MCP tool, e.g. `mcp.github.create_pull_request`                                                                                                |
+
+Read-only tools (Read, Grep, Glob, LS, WebSearch) are not routed through Guardian.
+
+## Setup
+
+Guardian sets modes **per connection**, not per tool. So the hook uses two record-only tool servers, one per risk tier. That lets `ls` run straight away while `terraform apply` waits for your phone.
+
+1. In the Guardian console, go to **Connections → Register a tool server → record-only** and create two:
+   - **"Coding agent — everyday"** with `shell`, `file_write` and `web_fetch`.
+   - **"Coding agent — needs approval"** with `shell_deploy`, `shell_destructive`, `git_push`, and any MCP tools you use. `npx @odingard/guardian-mcp tools -- <server>` lists them.
+2. Under **Agents**, open your coding agent:
+   - set **Allow** on the first connection and **Ask me first** on the second;
+   - on each connection's card, type every tool name into **"Allow a tool by name"** and press **Allow tool**, once per tool.
+
+   Without this, every call is denied as `INVALID_REQUEST`.
+
+3. In the shell that starts Claude Code, export:
+   - `GUARDIAN_AGENT_CREDENTIAL`;
+   - `GUARDIAN_CONNECTION_ID`: the everyday connection;
+   - `GUARDIAN_HOOK_ASK_CONNECTION_ID`: the needs-approval connection;
+   - `GUARDIAN_BASE_URL`: optional, defaults to `https://guardian-api.odingard.com`.
+
+   With only `GUARDIAN_CONNECTION_ID` set, every tool shares that one connection and its single mode.
+
+4. Add the hook to `.claude/settings.json` (one project) or `~/.claude/settings.json` (all projects):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|WebFetch|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @odingard/guardian-hook",
+            "timeout": 600
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`npx @odingard/guardian-hook setup` prints all of this. To see where a command would be routed, run `npx @odingard/guardian-hook classify "terraform apply"`, which prints `shell_deploy`.
+
+## Limits (read these)
+
+- **Decision-gated.** The agent performs the effect after Guardian authorizes and redeems the call. The receipt proves Guardian's authorization of that exact call, not the command's own outcome.
+- **Routing is local.** The classification patterns run on your machine and err toward the Ask tools. An agent that can edit your settings or environment can remove the hook. Use managed settings (or `allow_managed_hooks_only`-style controls) where that matters.
+- **Only calls through the hook are governed.** Commands you run yourself, or other credentials on the machine, are not.
+- **Arguments are bounded.** Commands over 2,000 characters are truncated in what the approver sees; MCP inputs over that size are sent as a digest.
+- **Claude Code only for now.** Cursor and Codex adapters will ship once their hook contracts are verified against their documentation.
+
+Licensed Apache-2.0.

package/dist/index.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createGuardianClient } from "@odingard/guardian-sdk";
+
+// src/classify.ts
+import { createHash } from "node:crypto";
+var HOOK_TOOLS = [
+  {
+    name: "shell",
+    suggestedMode: "allow",
+    description: "Ordinary shell commands (build, test, read-only inspection)."
+  },
+  {
+    name: "shell_deploy",
+    suggestedMode: "ask",
+    description: "Infrastructure and deploy commands: terraform/tofu apply or destroy, pulumi up, kubectl apply/delete, helm install/upgrade, cdk/serverless/fly/vercel deploys, cloud deploy CLIs."
+  },
+  {
+    name: "shell_destructive",
+    suggestedMode: "ask",
+    description: "Destructive commands: rm -rf, git reset --hard, git clean, force pushes, dropping databases, disk formatting."
+  },
+  {
+    name: "git_push",
+    suggestedMode: "ask",
+    description: "Pushing commits to a remote."
+  },
+  {
+    name: "file_write",
+    suggestedMode: "allow",
+    description: "Creating or editing files in the workspace."
+  },
+  {
+    name: "web_fetch",
+    suggestedMode: "allow",
+    description: "Fetching a URL."
+  }
+];
+var MAX_COMMAND = 2e3;
+var DEPLOY = [
+  /\b(terraform|tofu)\b.*\s(apply|destroy|import|state\s+(rm|mv|push))\b/,
+  /\bpulumi\s+(up|destroy|update)\b/,
+  /\bkubectl\b.*\s(apply|delete|create|replace|patch|scale|rollout|drain|cordon)\b/,
+  /\bhelm\s+(install|upgrade|uninstall|rollback|delete)\b/,
+  /\b(cdk|serverless|sls|sam)\s+(deploy|destroy|remove)\b/,
+  /\bfly(ctl)?\s+(deploy|destroy|apps\s+destroy|scale)\b/,
+  /\bvercel\b.*(--prod\b|\bdeploy\b|\bpromote\b|\bremove\b)/,
+  /\bnetlify\s+deploy\b.*--prod\b/,
+  /\bgcloud\s+.*\b(deploy|delete)\b/,
+  /\baws\s+.*\b(deploy|delete-stack|create-stack|update-stack|terminate-instances|delete-db-instance)\b/,
+  /\baz\s+.*\b(deploy|delete|create)\b/,
+  /\bwrangler\s+(deploy|publish|delete)\b/,
+  /\bdocker\s+(push|compose\s+.*\bup\b.*--remote)\b/,
+  /\b(npm|pnpm|yarn)\s+publish\b/,
+  /\btwine\s+upload\b/,
+  /\bgh\s+(release\s+create|workflow\s+run|pr\s+merge)\b/
+];
+var DESTRUCTIVE = [
+  /\brm\s+(?:-\S*[rR]\S*\s+(?:-\S+\s+)*|-\S*f\S*\s+-\S*[rR])/,
+  /\bgit\s+reset\s+.*--hard\b/,
+  /\bgit\s+clean\s+-\S*f/,
+  /\bgit\s+push\b.*(\s--force\b|\s-f\b|--force-with-lease|\s\+\S)/,
+  /\bgit\s+(branch\s+-D|checkout\s+--\s|restore\s+--source)\b/,
+  /\b(drop|truncate)\s+(table|database|schema)\b/i,
+  /\bdelete\s+from\s+\w+\s*(;|$)/i,
+  /\b(mkfs|dd\s+if=|shred|wipefs)\b/,
+  /\bchmod\s+-R\s+777\b/,
+  /\bfind\b.*\s-delete\b/
+];
+var GIT_PUSH = /\bgit\s+push\b/;
+function classifyCommand(command) {
+  if (DESTRUCTIVE.some((re) => re.test(command))) return "shell_destructive";
+  if (DEPLOY.some((re) => re.test(command))) return "shell_deploy";
+  if (GIT_PUSH.test(command)) return "git_push";
+  return "shell";
+}
+function mcpToolName(server, tool) {
+  const part = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/^(\d)/, "x$1") || "x";
+  return `mcp.${part(server)}.${part(tool)}`.slice(0, 64).replace(/[._-]+$/, "");
+}
+function bounded(text, max = MAX_COMMAND) {
+  return text.length <= max ? text : `${text.slice(0, max)}\u2026 [${text.length - max} more chars]`;
+}
+function digest(text) {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+function str(value) {
+  return typeof value === "string" ? value : "";
+}
+function governedCall(call) {
+  const { tool, input } = call;
+  const cwd = call.cwd ? { cwd: call.cwd } : {};
+  if (tool === "Bash" || tool === "shell") {
+    const command = str(input.command);
+    const toolName = classifyCommand(command);
+    return {
+      toolName,
+      arguments: { command: bounded(command), ...cwd },
+      summary: `Run: ${bounded(command, 160)}`
+    };
+  }
+  if (["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(tool)) {
+    const path = str(input.file_path) || str(input.notebook_path);
+    const content = str(input.content) || str(input.new_string) || str(input.new_source) || (Array.isArray(input.edits) ? JSON.stringify(input.edits) : "");
+    return {
+      toolName: "file_write",
+      arguments: {
+        operation: tool,
+        path,
+        contentBytes: Buffer.byteLength(content),
+        contentDigest: digest(content),
+        ...cwd
+      },
+      summary: `${tool === "Write" ? "Write" : "Edit"} ${path}`
+    };
+  }
+  if (tool === "WebFetch") {
+    const url = str(input.url);
+    return {
+      toolName: "web_fetch",
+      arguments: { url: bounded(url, 500) },
+      summary: `Fetch ${bounded(url, 160)}`
+    };
+  }
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(tool);
+  if (mcp) {
+    const [, server, name] = mcp;
+    const json = JSON.stringify(input);
+    return {
+      toolName: mcpToolName(server, name),
+      arguments: json.length <= MAX_COMMAND ? { server, tool: name, input } : {
+        server,
+        tool: name,
+        inputBytes: json.length,
+        inputDigest: digest(json)
+      },
+      summary: `MCP ${server} \u2192 ${name}`
+    };
+  }
+  return null;
+}
+function tierOf(toolName) {
+  const known = HOOK_TOOLS.find((t) => t.name === toolName);
+  return known ? known.suggestedMode : "ask";
+}
+
+// src/decide.ts
+var PLAIN = {
+  NOT_AUTHORIZED: "this agent is not authorized for it",
+  APPROVAL_DENIED: "the approver declined it",
+  APPROVAL_NOT_SATISFIED: "the approver declined it",
+  APPROVAL_EXPIRED: "the approval expired",
+  UNAUTHENTICATED: "the Guardian agent credential was rejected",
+  INVALID_REQUEST: `this tool is not allowed for the agent yet. In the Guardian console: Agents \u2192 this agent \u2192 the connection's card \u2192 "Allow a tool by name"`,
+  SERVICE_UNAVAILABLE: "Guardian could not be reached",
+  REQUEST_CONFLICT: "Guardian saw a conflicting request"
+};
+function plain(code) {
+  return PLAIN[code] ?? code;
+}
+function denied(call, code, extra = {}) {
+  return {
+    decision: "deny",
+    reason: `Guardian blocked ${call.toolName} (${code}): ${plain(code)}. Do not retry or work around this; ask the developer to review it in the Guardian console.`,
+    ...extra
+  };
+}
+var isPending = (r) => !r.ok && (r.reasonCode === "APPROVAL_REQUIRED" || r.reasonCode === "APPROVAL_PENDING") || r.ok && r.decision === "ASK";
+async function decide(call, options) {
+  const wait = options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = options.now ?? Date.now;
+  const log = options.log ?? (() => {
+  });
+  let result;
+  try {
+    result = await options.client.request({
+      action: "tool.invoke",
+      connectionId: options.connectionId,
+      toolName: call.toolName,
+      arguments: call.arguments,
+      purpose: `${options.agentName}: ${call.summary}`,
+      ...options.requestTtlMs !== void 0 ? { ttlMs: options.requestTtlMs } : {}
+    });
+  } catch {
+    return denied(call, "SERVICE_UNAVAILABLE");
+  }
+  const requestId = result.requestId;
+  let approvedByHuman = false;
+  if (isPending(result)) {
+    if (!requestId) return denied(call, "MISSING_REQUEST_ID");
+    log(
+      `Guardian: "${call.summary}" is held for approval (request ${requestId}). Approve it on your phone or in the console.`
+    );
+    const deadline = now() + options.approvalTimeoutMs;
+    const maxInterval = Math.max(
+      options.maxPollIntervalMs ?? 1e4,
+      options.pollIntervalMs
+    );
+    let interval = options.pollIntervalMs;
+    for (; ; ) {
+      await wait(interval);
+      interval = Math.min(Math.ceil(interval * 1.5), maxInterval);
+      let claimed;
+      try {
+        claimed = await options.client.claim(requestId);
+      } catch {
+        claimed = { ok: false, reasonCode: "APPROVAL_REQUIRED", requestId };
+      }
+      if (!isPending(claimed)) {
+        result = claimed;
+        approvedByHuman = claimed.ok && claimed.decision === "ALLOW";
+        break;
+      }
+      if (now() >= deadline) {
+        return {
+          decision: "deny",
+          reason: `Guardian is still waiting for a human to approve ${call.toolName} (request ${requestId}). Nothing ran. Tell the developer it needs approval in the Guardian app, then try again.`,
+          requestId,
+          guardianDecision: "ASK"
+        };
+      }
+    }
+  }
+  if (!result.ok || result.decision !== "ALLOW" || !result.capabilityToken) {
+    const code = result.ok ? result.reasonCode ?? (result.decision === "DENY" ? "DENIED" : "MISSING_CAPABILITY") : result.reasonCode;
+    return denied(call, code, {
+      ...requestId ? { requestId } : {},
+      guardianDecision: "DENY"
+    });
+  }
+  let executed;
+  try {
+    executed = await options.client.execute({
+      requestId: result.requestId,
+      capabilityToken: result.capabilityToken
+    });
+  } catch {
+    executed = { ok: false, reasonCode: "SERVICE_UNAVAILABLE" };
+  }
+  if (!executed.ok) {
+    return denied(call, executed.reasonCode, {
+      requestId: result.requestId,
+      guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+      approvedByHuman
+    });
+  }
+  return {
+    decision: "allow",
+    reason: approvedByHuman ? `Approved by a human in Guardian (request ${result.requestId}).` : `Allowed by Guardian policy (request ${result.requestId}).`,
+    requestId: result.requestId,
+    guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+    approvedByHuman
+  };
+}
+
+// src/index.ts
+var DEFAULT_BASE_URL = "https://guardian-api.odingard.com";
+var REQUEST_TTL_MS = 3e5;
+var MAX_WAIT_MS = REQUEST_TTL_MS;
+function claudeCodeOutput(verdict) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: verdict.decision,
+      permissionDecisionReason: verdict.reason
+    }
+  });
+}
+var SETTINGS_SNIPPET = {
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: "Bash|Write|Edit|MultiEdit|NotebookEdit|WebFetch|mcp__.*",
+        hooks: [
+          {
+            type: "command",
+            command: "npx -y @odingard/guardian-hook",
+            timeout: 600
+          }
+        ]
+      }
+    ]
+  }
+};
+function connectionFor(toolName, env) {
+  const allow = env.GUARDIAN_CONNECTION_ID?.trim() || void 0;
+  if (tierOf(toolName) === "allow") return allow;
+  return env.GUARDIAN_HOOK_ASK_CONNECTION_ID?.trim() || allow;
+}
+function setupText() {
+  const list = (mode) => HOOK_TOOLS.filter((t) => t.suggestedMode === mode).map((t) => `     ${t.name.padEnd(18)} ${t.description}`).join("\n");
+  return [
+    "Guardian modes are set per connection, so the hook uses two record-only tool servers.",
+    "",
+    "1. In the Guardian console, Connections \u2192 Register a tool server \u2192 record-only:",
+    '   a) "Coding agent \u2014 everyday" with these tools:',
+    list("allow"),
+    '   b) "Coding agent \u2014 needs approval" with these tools:',
+    list("ask"),
+    "      plus any MCP tools you use, named mcp.<server>.<tool>",
+    "      (`npx @odingard/guardian-mcp tools -- <server>` lists them).",
+    "",
+    "2. Agents \u2192 your coding agent:",
+    "   - set Allow on (a) and Ask me first on (b);",
+    "   - on each of the two connection cards, type every tool name above into",
+    '     "Allow a tool by name" and press Allow tool (once per tool).',
+    "     Without this step every call is denied as INVALID_REQUEST.",
+    "",
+    "3. In the shell that starts the agent, export GUARDIAN_AGENT_CREDENTIAL,",
+    "   GUARDIAN_CONNECTION_ID (a) and GUARDIAN_HOOK_ASK_CONNECTION_ID (b).",
+    "",
+    "4. Add this to .claude/settings.json (project) or ~/.claude/settings.json (all projects):",
+    JSON.stringify(SETTINGS_SNIPPET, null, 2),
+    "",
+    "Read-only tools (Read, Grep, Glob, LS, WebSearch) are not routed through Guardian."
+  ].join("\n");
+}
+async function runHook(stdin, env, deps = {}) {
+  const failClosed = (reason) => claudeCodeOutput({ decision: "deny", reason: `Guardian hook: ${reason}` });
+  let input;
+  try {
+    input = JSON.parse(stdin);
+  } catch {
+    return failClosed(
+      "could not read the tool call from the agent. Nothing ran."
+    );
+  }
+  if (typeof input.tool_name !== "string") {
+    return failClosed("the tool call had no tool name. Nothing ran.");
+  }
+  const call = governedCall({
+    tool: input.tool_name,
+    input: input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {},
+    ...typeof input.cwd === "string" ? { cwd: input.cwd } : {}
+  });
+  if (call === null) return "";
+  const connectionId = connectionFor(call.toolName, env);
+  const credential = env.GUARDIAN_AGENT_CREDENTIAL?.trim();
+  const baseUrl = (env.GUARDIAN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(
+    /\/+$/,
+    ""
+  );
+  if (!deps.client && (!credential || !connectionId)) {
+    return failClosed(
+      "GUARDIAN_AGENT_CREDENTIAL and GUARDIAN_CONNECTION_ID must be set (run `npx @odingard/guardian-hook setup`). Nothing ran."
+    );
+  }
+  if (!deps.client && !baseUrl.startsWith("https://")) {
+    return failClosed("GUARDIAN_BASE_URL must be https. Nothing ran.");
+  }
+  const requested = Number(
+    env.GUARDIAN_HOOK_APPROVAL_TIMEOUT_MS ?? MAX_WAIT_MS
+  );
+  const approvalTimeoutMs = Number.isFinite(requested) ? Math.min(Math.max(requested, 0), MAX_WAIT_MS) : MAX_WAIT_MS;
+  const verdict = await decide(call, {
+    client: deps.client ?? createGuardianClient({
+      baseUrl,
+      credential,
+      ...env.GUARDIAN_ADAPTER_ID ? { adapterId: env.GUARDIAN_ADAPTER_ID } : {}
+    }),
+    connectionId: connectionId ?? "",
+    agentName: env.GUARDIAN_HOOK_AGENT_NAME?.trim() || "Claude Code",
+    approvalTimeoutMs,
+    requestTtlMs: REQUEST_TTL_MS,
+    pollIntervalMs: 2e3,
+    ...deps.wait ? { wait: deps.wait } : {},
+    ...deps.now ? { now: deps.now } : {},
+    ...deps.log ? { log: deps.log } : {}
+  });
+  return claudeCodeOutput(verdict);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === "setup") {
+    process.stdout.write(`${setupText()}
+`);
+    return;
+  }
+  if (command === "classify") {
+    process.stdout.write(`${classifyCommand(rest.join(" "))}
+`);
+    return;
+  }
+  if (command === "--help" || command === "-h") {
+    process.stdout.write("guardian-hook [setup | classify <command>]\n");
+    return;
+  }
+  const output = await runHook(await readStdin(), process.env, {
+    log: (line) => process.stderr.write(`${line}
+`)
+  });
+  if (output) process.stdout.write(`${output}
+`);
+}
+var invokedDirectly = process.argv[1] !== void 0 && /guardian-hook|hook[\\/]dist[\\/]index\.js$/.test(process.argv[1]);
+if (invokedDirectly) {
+  main(process.argv.slice(2)).catch(() => {
+    process.stdout.write(
+      `${claudeCodeOutput({ decision: "deny", reason: "Guardian hook crashed. Nothing ran." })}
+`
+    );
+  });
+}
+export {
+  DEFAULT_BASE_URL,
+  MAX_WAIT_MS,
+  REQUEST_TTL_MS,
+  SETTINGS_SNIPPET,
+  claudeCodeOutput,
+  connectionFor,
+  runHook,
+  setupText
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@odingard/guardian-hook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Guardian for coding agents: a Claude Code PreToolUse hook that sends shell commands, file writes and MCP calls to Guardian for a deterministic ALLOW/ASK/DENY decision. Deploys and destructive commands wait for a human approval on your phone; every allowed call carries a verifiable receipt.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "guardian-hook": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --outfile=dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@odingard/guardian-sdk": "^0.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Odingard/guardian-sdk.git",
+    "directory": "packages/hook"
+  },
+  "homepage": "https://guardian.odingard.com"
+}