@contro1/claude-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contro1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @contro1/claude-code
+
+Route Claude Code `PreToolUse` approvals to CENTCOM.
+
+The hook reads Claude tool calls from stdin, creates an approval request in CENTCOM, polls for the operator decision, then returns a Claude-compatible permission decision.
+
+## Install
+
+```bash
+npm install -g @contro1/claude-code
+```
+
+## Configuration
+
+Set env vars (or use `.centcom.json` in working directory):
+
+- `CENTCOM_API_KEY` (required)
+- `CENTCOM_BASE_URL` (default: `https://contro1.com/api/centcom/v1`)
+- `CENTCOM_TOOLS` (default: `Write,Edit,Bash`)
+- `CENTCOM_TIMEOUT` (default: `300000` ms)
+- `CENTCOM_POLL_INTERVAL` (default: `3000` ms)
+- `CENTCOM_PRIORITY` (default: `urgent`)
+- `CENTCOM_SLA_MINUTES` (optional)
+- `CENTCOM_REQUIRED_ROLE` (optional)
+- `CENTCOM_FALLBACK` (`deny` default; supported: `deny`, `ask`, `allow`)
+- `CENTCOM_CALLBACK_URL` (default internal placeholder, can be overridden)
+
+## Claude Code Hook Setup
+
+Add this in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "command": "centcom-claude-code",
+        "timeout": 310000
+      }
+    ]
+  }
+}
+```
+
+## Behavior
+
+- Tools outside `CENTCOM_TOOLS` are auto-allowed.
+- Approved response -> `allow`.
+- Rejected response -> `deny`.
+- Timeout -> request cancel attempt + `deny`.
+- API errors -> fallback decision (`CENTCOM_FALLBACK`).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm pack
+```

package/dist/centcomClient.d.ts

@@ -0,0 +1,33 @@
+interface CentcomClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+}
+interface CreateRequestParams {
+    type: "approval" | "yes_no" | "free_text";
+    context: string;
+    question: string;
+    callback_url: string;
+    priority: "normal" | "urgent";
+    required_role?: string;
+    metadata?: Record<string, unknown>;
+    sla_minutes?: number;
+    idempotency_key?: string;
+}
+export interface CentcomRequest {
+    id: string;
+    state: string;
+    response?: Record<string, unknown> | null;
+}
+export declare class CentcomClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: CentcomClientConfig);
+    private request;
+    createRequest(params: CreateRequestParams): Promise<CentcomRequest>;
+    getRequest(requestId: string): Promise<CentcomRequest>;
+    cancelRequest(requestId: string): Promise<void>;
+    waitForResponse(requestId: string, intervalMs: number, timeoutMs: number): Promise<CentcomRequest>;
+}
+export {};

package/dist/centcomClient.js

@@ -0,0 +1,66 @@
+export class CentcomClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.timeoutMs = config.timeoutMs;
+    }
+    async request(method, path, body, extraHeaders) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                    ...(extraHeaders ?? {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            const json = (await res.json());
+            if (!res.ok) {
+                throw new Error(json.message || `HTTP ${res.status}`);
+            }
+            return json;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async createRequest(params) {
+        const { idempotency_key, ...body } = params;
+        const headers = {};
+        if (idempotency_key)
+            headers["Idempotency-Key"] = idempotency_key;
+        return this.request("POST", "/requests", body, headers);
+    }
+    async getRequest(requestId) {
+        return this.request("GET", `/requests/${requestId}`);
+    }
+    async cancelRequest(requestId) {
+        await this.request("DELETE", `/requests/${requestId}`);
+    }
+    async waitForResponse(requestId, intervalMs, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        const terminal = new Set([
+            "answered",
+            "callback_pending",
+            "callback_delivered",
+            "callback_failed",
+            "closed",
+            "expired",
+            "cancelled",
+        ]);
+        while (Date.now() < deadline) {
+            const req = await this.getRequest(requestId);
+            if (terminal.has(req.state))
+                return req;
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+        throw new Error(`Timeout waiting for response on request ${requestId}`);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { CentcomClaudeConfig } from "./types.js";
+export declare function loadConfig(): CentcomClaudeConfig;

package/dist/config.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_BASE_URL = "https://contro1.com/api/centcom/v1";
+const DEFAULT_TOOLS = "Write,Edit,Bash";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_PRIORITY = "urgent";
+const DEFAULT_FALLBACK = "deny";
+const DEFAULT_CALLBACK_URL = "https://centcom.local/claude-code";
+function readLocalConfig() {
+    const path = join(process.cwd(), ".centcom.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = readFileSync(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function parseTools(value) {
+    return new Set((value ?? DEFAULT_TOOLS)
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean));
+}
+export function loadConfig() {
+    const file = readLocalConfig();
+    const env = process.env;
+    const apiKey = env.CENTCOM_API_KEY ?? file.CENTCOM_API_KEY;
+    if (!apiKey) {
+        throw new Error("CENTCOM_API_KEY is required");
+    }
+    const baseUrl = env.CENTCOM_BASE_URL ?? file.CENTCOM_BASE_URL ?? DEFAULT_BASE_URL;
+    const tools = parseTools(env.CENTCOM_TOOLS ?? file.CENTCOM_TOOLS);
+    const timeoutMs = Number(env.CENTCOM_TIMEOUT ?? file.CENTCOM_TIMEOUT ?? DEFAULT_TIMEOUT_MS);
+    const pollIntervalMs = Number(env.CENTCOM_POLL_INTERVAL ?? file.CENTCOM_POLL_INTERVAL ?? DEFAULT_POLL_INTERVAL_MS);
+    const priorityRaw = env.CENTCOM_PRIORITY ?? file.CENTCOM_PRIORITY ?? DEFAULT_PRIORITY;
+    const priority = priorityRaw === "normal" ? "normal" : "urgent";
+    const fallbackRaw = (env.CENTCOM_FALLBACK ?? file.CENTCOM_FALLBACK ?? DEFAULT_FALLBACK);
+    const fallback = fallbackRaw === "ask" || fallbackRaw === "allow" ? fallbackRaw : "deny";
+    const slaValue = env.CENTCOM_SLA_MINUTES ?? file.CENTCOM_SLA_MINUTES;
+    const slaMinutes = slaValue !== undefined ? Number(slaValue) : undefined;
+    const requiredRole = env.CENTCOM_REQUIRED_ROLE ?? file.CENTCOM_REQUIRED_ROLE;
+    const callbackUrl = env.CENTCOM_CALLBACK_URL ?? file.CENTCOM_CALLBACK_URL ?? DEFAULT_CALLBACK_URL;
+    return {
+        apiKey,
+        baseUrl,
+        tools,
+        timeoutMs,
+        pollIntervalMs,
+        priority,
+        slaMinutes: Number.isFinite(slaMinutes) ? slaMinutes : undefined,
+        requiredRole: requiredRole || undefined,
+        fallback,
+        callbackUrl,
+    };
+}

package/dist/formatter.d.ts

@@ -0,0 +1,7 @@
+import type { HookInput } from "./types.js";
+export declare function buildIdempotencyKey(input: HookInput): string;
+export declare function formatRequest(input: HookInput): {
+    question: string;
+    context: string;
+    metadata: Record<string, unknown>;
+};

package/dist/formatter.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+const MAX_PREVIEW = 500;
+function redactSecrets(text) {
+    return text
+        .replace(/(cc_(?:live|test)_[a-zA-Z0-9_-]{8,})/g, "[REDACTED_API_KEY]")
+        .replace(/(whsec_[a-zA-Z0-9_-]{8,})/g, "[REDACTED_WEBHOOK_SECRET]")
+        .replace(/(Bearer\s+)[^\s]+/gi, "$1[REDACTED_TOKEN]");
+}
+function clip(text, size = MAX_PREVIEW) {
+    if (text.length <= size)
+        return text;
+    return `${text.slice(0, size)}... [truncated]`;
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+export function buildIdempotencyKey(input) {
+    const raw = `${input.session_id}|${input.tool_name}|${stableStringify(input.tool_input)}`;
+    const hash = createHash("sha256").update(raw).digest("hex").slice(0, 24);
+    return `claude:${input.session_id}:${input.tool_name}:${hash}`;
+}
+export function formatRequest(input) {
+    const tool = input.tool_name;
+    const toolInput = input.tool_input ?? {};
+    const safeJson = redactSecrets(stableStringify(toolInput));
+    let question = `Approve ${tool}?`;
+    let context = `Tool input:\n${safeJson}`;
+    if (tool === "Write" || tool === "Edit") {
+        const path = typeof toolInput.file_path === "string" ? toolInput.file_path : "unknown file";
+        const contentRaw = typeof toolInput.content === "string"
+            ? toolInput.content
+            : typeof toolInput.new_string === "string"
+                ? toolInput.new_string
+                : safeJson;
+        question = `Approve ${tool} to ${path}?`;
+        context = `Preview:\n${clip(redactSecrets(contentRaw))}`;
+    }
+    else if (tool === "Bash" || tool === "Shell") {
+        const command = typeof toolInput.command === "string" ? toolInput.command : clip(safeJson, MAX_PREVIEW);
+        question = `Approve command: ${redactSecrets(command)}?`;
+        context = `Command detail:\n${redactSecrets(command)}`;
+    }
+    return {
+        question,
+        context,
+        metadata: {
+            source: "claude-code",
+            session_id: input.session_id,
+            tool_name: tool,
+            cwd: input.cwd ?? "",
+        },
+    };
+}

package/dist/hook.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hook.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { stdin, stdout, stderr } from "node:process";
+import { CentcomClient } from "./centcomClient.js";
+import { loadConfig } from "./config.js";
+import { buildIdempotencyKey, formatRequest } from "./formatter.js";
+let activeRequestId = null;
+let activeClient = null;
+let fallbackDecision = "deny";
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stdin.setEncoding("utf8");
+        stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        stdin.on("end", () => resolve(data));
+        stdin.on("error", reject);
+    });
+}
+function writeDecision(permissionDecision, systemMessage) {
+    const output = {
+        hookSpecificOutput: { permissionDecision },
+        ...(systemMessage ? { systemMessage } : {}),
+    };
+    stdout.write(JSON.stringify(output));
+    process.exit(0);
+}
+async function safeCancel() {
+    if (!activeClient || !activeRequestId)
+        return;
+    try {
+        await activeClient.cancelRequest(activeRequestId);
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}
+function registerSignalHandlers() {
+    const handler = async () => {
+        await safeCancel();
+        writeDecision(fallbackDecision, "Approval interrupted before decision.");
+    };
+    process.on("SIGINT", handler);
+    process.on("SIGTERM", handler);
+}
+function parseInput(raw) {
+    if (!raw.trim()) {
+        throw new Error("Hook input is empty");
+    }
+    return JSON.parse(raw);
+}
+function responseApproved(response) {
+    if (!response || typeof response !== "object")
+        return false;
+    if (typeof response.approved === "boolean")
+        return response.approved;
+    if (typeof response.value === "boolean")
+        return response.value;
+    return false;
+}
+async function main() {
+    const config = loadConfig();
+    fallbackDecision = config.fallback;
+    registerSignalHandlers();
+    const raw = await readStdin();
+    const input = parseInput(raw);
+    if (!config.tools.has(input.tool_name)) {
+        writeDecision("allow");
+    }
+    const client = new CentcomClient({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        timeoutMs: Math.min(config.timeoutMs, 30_000),
+    });
+    activeClient = client;
+    const formatted = formatRequest(input);
+    const idempotencyKey = buildIdempotencyKey(input);
+    try {
+        const request = await client.createRequest({
+            type: "approval",
+            question: formatted.question,
+            context: formatted.context,
+            callback_url: config.callbackUrl,
+            priority: config.priority,
+            required_role: config.requiredRole,
+            metadata: formatted.metadata,
+            sla_minutes: config.slaMinutes,
+            idempotency_key: idempotencyKey,
+        });
+        activeRequestId = request.id;
+        const result = await client.waitForResponse(request.id, config.pollIntervalMs, config.timeoutMs);
+        const approved = responseApproved(result.response ?? null);
+        writeDecision(approved ? "allow" : "deny");
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.toLowerCase().includes("timeout") &&
+            activeRequestId) {
+            await safeCancel();
+            writeDecision("deny", "Approval timed out and was denied.");
+        }
+        const message = error instanceof Error ? error.message : "Unknown approval error";
+        stderr.write(`centcom-claude-code: ${message}\n`);
+        writeDecision(config.fallback, `CENTCOM unavailable, fallback=${config.fallback}.`);
+    }
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unhandled error";
+    stderr.write(`centcom-claude-code: ${message}\n`);
+    writeDecision(fallbackDecision, `CENTCOM hook failed, fallback=${fallbackDecision}.`);
+});

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export type PermissionDecision = "allow" | "deny" | "ask";
+export interface HookInput {
+    session_id: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    cwd?: string;
+    permission_mode?: string;
+    hook_event_name?: string;
+}
+export interface HookOutput {
+    hookSpecificOutput: {
+        permissionDecision: PermissionDecision;
+    };
+    systemMessage?: string;
+}
+export interface CentcomClaudeConfig {
+    apiKey: string;
+    baseUrl: string;
+    tools: Set<string>;
+    timeoutMs: number;
+    pollIntervalMs: number;
+    priority: "normal" | "urgent";
+    slaMinutes?: number;
+    requiredRole?: string;
+    fallback: PermissionDecision;
+    callbackUrl: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@contro1/claude-code",
+  "version": "0.1.0",
+  "description": "CENTCOM approval hook for Claude Code PreToolUse",
+  "type": "module",
+  "main": "dist/hook.js",
+  "types": "dist/hook.d.ts",
+  "bin": {
+    "centcom-claude-code": "dist/hook.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "centcom",
+    "claude-code",
+    "approval",
+    "hook",
+    "hitl"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}