az-brake 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,10 @@
+{
+  "name": "az-brake",
+  "description": "Asks before Claude runs an Azure CLI command that creates or starts a resource that costs money.",
+  "owner": { "name": "thisismairaj", "url": "https://github.com/thisismairaj" },
+  "plugins": [{
+    "name": "az-brake",
+    "source": "./",
+    "description": "Asks before Claude runs an Azure CLI command that creates or starts a resource that costs money."
+  }]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "az-brake",
+  "version": "0.1.0",
+  "description": "Asks before Claude runs an Azure CLI command that creates or starts a resource that costs money.",
+  "author": { "name": "thisismairaj", "url": "https://github.com/thisismairaj" },
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thisismairaj
+
+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

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# az-brake
 
-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.
+A Claude Code plugin that **asks before Claude runs an Azure CLI command that creates or starts a resource that costs money.**
+
+It only guards commands Claude runs. It does not guard the Azure portal, Terraform, scheduled jobs, or you typing in a terminal. And it reads command text, so it catches well-known shapes, not everything. It is a speed bump, not a security boundary.
+
+## Why this matters
+
+Azure bills for what exists and what runs, and the controls are mostly after the fact: a budget alert is an email, it does not stop anything. A coding agent can create a database, a cluster or a VM in one line. This asks you first, and names the resource.
+
+## What it asks about
+
+Everything else (reads, `list`, `show`, deletes, `--help`, resource groups, virtual networks, `az login`) runs without a prompt, because a hook that asks too often gets turned off.
+
+- **Creating resources that bill:** virtual machines and scale sets, disks and snapshots, storage accounts, AKS clusters and node pools, container registries, SQL databases, managed instances, elastic pools and dedicated pools, PostgreSQL and MySQL flexible servers, Cosmos DB, Redis, container apps and instances, web apps, function apps, App Service plans, Synapse, Data Factory, Event Hubs, Service Bus, AI Search, Azure AI services, Databricks workspaces, Log Analytics, Application Insights, public IPs, gateways, firewalls, NAT gateways, load balancers, Bastion, private endpoints, API Management, Front Door and CDN, and more (about 50 types, listed in `src/classify.ts`).
+- **Starting, scaling or resizing them:** `start`, `resume`, `scale`, `resize`, `aks nodepool add`, and an `update` that changes a size or tier.
+- **Commands that can create anything:** `az deployment ... create`, `az stack ... create`, `az resource create`, `az rest --method put`, `az webapp up` and `az containerapp up`. The prompt says it cannot see what a template contains. `--what-if` is not asked about.
+- **Not asked about on purpose:** `az group create` and `az sql server create` (free), and data movement such as `az storage blob upload-batch` (each operation costs a tiny amount).
+
+The prompt names each resource it can see: what it creates, its `--name`, and the size, SKU and location flags if present. In a chained command (`a && b`) every billable step is listed. It never shows a price, because the hook cannot see your rates or discounts.
+
+## Install
+
+```
+/plugin install az-brake --marketplace thisismairaj/az-brake
+```
+
+Nothing to configure. Needs Node 20 or newer on your PATH.
+
+## How it works
+
+A `PreToolUse` hook on `Bash|PowerShell` (both, because on Windows without Git Bash only PowerShell exists). If a command looks like it can create or start a billable resource, the hook answers `ask`, and Claude Code shows its normal approval prompt. Any error inside the hook fails open: the command runs.
+
+## Tested live (headless `claude -p`, Claude Code on Windows)
+
+- A `az storage account create` command is stopped by the hook in `dontAsk` and `bypassPermissions` modes. The command was pointed at a resource group that does not exist, so nothing could have been created if it had run.
+- A free command (`az group exists`) is not stopped.
+- 95 unit cases pass, and every command path in the table was checked against the installed Azure CLI (2.91.0) with `az <path> -h`. Ten of those paths come from Azure CLI extensions that the CLI offers to install on first use.
+
+Headless mode cannot answer a prompt, so these runs show the hook fires and the command does not run. They do not show the interactive approval dialog.
+
+## Not verified yet
+
+- The interactive approval dialog itself (approving a flagged command and seeing it run).
+- The PowerShell tool path, and Git Bash vs PowerShell on a machine without Git.
+- macOS and Linux (development was on Windows only).
+- Commands wrapped in another shell, such as `bash -c "az vm create ..."`, are not read.
+
+## Development
+
+```
+npm install
+npm test        # 95 cases, runs the TypeScript directly
+npm run build   # compiles src/ to dist/ (dist/ is committed so installs need no build)
+```

package/dist/classify.js

@@ -0,0 +1,263 @@
+// Decides whether a shell command can create or start an Azure resource that costs money.
+// Pure logic, no I/O, so it can be tested with plain strings.
+//
+// Heuristic, not a security boundary: it reads command text, so it only catches well-known
+// shapes. False negatives are expected. Anything it does not recognise passes.
+const PASS = { level: 'pass', reasons: [] };
+// Words that can sit in front of the real tool, e.g. `sudo az vm create` or `& az vm create`.
+const WRAPPERS = new Set(['sudo', 'time', 'command', 'exec', 'env', 'call', '&', 'nice']);
+// A line continuation (backslash in bash, backtick in PowerShell) joins two lines into one command.
+function joinContinuations(command) {
+    return command.replace(/(?:\\|`)\r?\n/g, ' ');
+}
+export function splitSegments(command) {
+    const segments = [];
+    let current = '';
+    let quote = null;
+    const text = joinContinuations(command);
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            current += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            current += c;
+            continue;
+        }
+        const two = text.slice(i, i + 2);
+        if (two === '&&' || two === '||') {
+            segments.push(current);
+            current = '';
+            i++;
+            continue;
+        }
+        if (c === ';' || c === '|' || c === '\n') {
+            segments.push(current);
+            current = '';
+            continue;
+        }
+        current += c;
+    }
+    segments.push(current);
+    return segments.map(s => s.trim()).filter(Boolean);
+}
+export function tokenize(segment) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let has = false;
+    for (const c of segment) {
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            else
+                current += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            has = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (has)
+                tokens.push(current);
+            current = '';
+            has = false;
+            continue;
+        }
+        current += c;
+        has = true;
+    }
+    if (has)
+        tokens.push(current);
+    return tokens;
+}
+function toolName(token) {
+    const base = token.split(/[\\/]/).pop() ?? token;
+    return base.toLowerCase().replace(/\.(exe|cmd|bat|ps1)$/, '');
+}
+function findTool(tokens) {
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t))
+            continue;
+        if (WRAPPERS.has(t.toLowerCase()))
+            continue;
+        return { name: toolName(t), rest: tokens.slice(i + 1) };
+    }
+    return undefined;
+}
+const isHelp = (rest) => rest.some(t => t === '--help' || t === '-h');
+// `az <group> [<subgroup>] <verb> --flags`: the command words come first, then flags.
+function commandPath(rest) {
+    const path = [];
+    for (const t of rest) {
+        if (t.startsWith('-'))
+            break;
+        path.push(t.toLowerCase());
+    }
+    return path;
+}
+function flagValue(rest, names) {
+    for (let i = 0; i < rest.length; i++) {
+        const t = rest[i];
+        for (const n of names) {
+            if (t === n)
+                return rest[i + 1];
+            if (t.startsWith(n + '='))
+                return t.slice(n.length + 1);
+        }
+    }
+    return undefined;
+}
+const hasFlag = (rest, names) => rest.some(t => names.some(n => t === n || t.startsWith(n + '=')));
+const DEFAULT_VERBS = ['create', 'start', 'resume', 'scale', 'resize'];
+const GENERIC_NOTE = 'This type of resource can bill for as long as it exists.';
+// Only types that bill for existing or running. Free ones (resource groups, vnets, subnets,
+// network security groups, `sql server`, managed identities, role assignments) are left out on purpose.
+const RESOURCES = [
+    { prefix: 'vm', label: 'virtual machine', note: 'Compute bills while it is allocated, and its disks bill until deleted.' },
+    { prefix: 'vmss', label: 'VM scale set', note: 'Every instance bills like a virtual machine.' },
+    { prefix: 'disk', label: 'managed disk', note: 'Bills for its size until deleted.' },
+    { prefix: 'snapshot', label: 'disk snapshot', note: 'Bills for stored data until deleted.' },
+    { prefix: 'storage account', label: 'storage account', note: 'Bills for stored data and for operations.' },
+    { prefix: 'aks', label: 'Kubernetes cluster (AKS)', note: 'The nodes are virtual machines and bill while they run.' },
+    { prefix: 'aks nodepool', label: 'AKS node pool', note: 'Each node is a virtual machine and bills while it runs.', verbs: [...DEFAULT_VERBS, 'add'] },
+    { prefix: 'acr', label: 'container registry', note: 'Bills a daily fee by tier, plus storage.', verbs: ['create', 'build'] },
+    { prefix: 'sql db', label: 'SQL database', note: 'Bills while it exists, by service tier.' },
+    { prefix: 'sql mi', label: 'SQL managed instance', note: 'Bills while it exists and is expensive to leave running.' },
+    { prefix: 'sql elastic-pool', label: 'SQL elastic pool', note: 'Bills while it exists.' },
+    { prefix: 'sql dw', label: 'dedicated SQL pool', note: 'Bills while it is running.' },
+    { prefix: 'postgres flexible-server', label: 'PostgreSQL flexible server', note: 'Bills while it runs, plus storage.' },
+    { prefix: 'mysql flexible-server', label: 'MySQL flexible server', note: 'Bills while it runs, plus storage.' },
+    { prefix: 'cosmosdb', label: 'Cosmos DB account', note: 'Bills for provisioned or consumed throughput and storage.' },
+    { prefix: 'redis', label: 'Redis cache', note: 'Bills per hour while it exists.' },
+    { prefix: 'containerapp', label: 'container app' },
+    { prefix: 'containerapp env', label: 'container apps environment' },
+    { prefix: 'container', label: 'container instance', note: 'Bills per second while it runs.' },
+    { prefix: 'webapp', label: 'web app' },
+    { prefix: 'functionapp', label: 'function app' },
+    { prefix: 'appservice plan', label: 'App Service plan', note: 'Bills while it exists, whatever runs on it.' },
+    { prefix: 'synapse workspace', label: 'Synapse workspace' },
+    { prefix: 'synapse spark pool', label: 'Synapse Spark pool' },
+    { prefix: 'synapse sql pool', label: 'Synapse dedicated SQL pool', note: 'Bills while it is running.' },
+    { prefix: 'datafactory', label: 'Data Factory' },
+    { prefix: 'eventhubs namespace', label: 'Event Hubs namespace' },
+    { prefix: 'servicebus namespace', label: 'Service Bus namespace' },
+    { prefix: 'search service', label: 'AI Search service', note: 'Bills per hour by tier while it exists.' },
+    { prefix: 'cognitiveservices account', label: 'Azure AI services account' },
+    { prefix: 'ml compute', label: 'Azure ML compute', note: 'Compute bills while it runs.' },
+    { prefix: 'batch account', label: 'Batch account' },
+    { prefix: 'databricks workspace', label: 'Databricks workspace' },
+    { prefix: 'kusto cluster', label: 'Data Explorer cluster', note: 'Bills while it runs.' },
+    { prefix: 'monitor log-analytics workspace', label: 'Log Analytics workspace', note: 'Bills for data ingested and retained.' },
+    { prefix: 'monitor app-insights component', label: 'Application Insights resource', note: 'Bills for data ingested.' },
+    { prefix: 'network public-ip', label: 'public IP address', note: 'Standard-tier addresses bill per hour.' },
+    { prefix: 'network vnet-gateway', label: 'virtual network gateway', note: 'Bills per hour while it exists.' },
+    { prefix: 'network firewall', label: 'Azure Firewall', note: 'Bills per hour while it exists.' },
+    { prefix: 'network nat gateway', label: 'NAT gateway', note: 'Bills per hour while it exists.' },
+    { prefix: 'network application-gateway', label: 'application gateway', note: 'Bills per hour while it exists.' },
+    { prefix: 'network lb', label: 'load balancer' },
+    { prefix: 'network bastion', label: 'Bastion host', note: 'Bills per hour while it exists.' },
+    { prefix: 'network private-endpoint', label: 'private endpoint', note: 'Bills per hour while it exists.' },
+    { prefix: 'cdn profile', label: 'CDN profile' },
+    { prefix: 'afd profile', label: 'Front Door profile' },
+    { prefix: 'apim', label: 'API Management service', note: 'Bills per hour by tier while it exists.' },
+    { prefix: 'backup vault', label: 'backup vault' },
+    { prefix: 'netappfiles account', label: 'NetApp Files account' },
+];
+// Longest prefix first, so `aks nodepool add` is read as a node pool and not as `aks`.
+const BY_PREFIX = [...RESOURCES].sort((a, b) => b.prefix.split(' ').length - a.prefix.split(' ').length);
+// Flags that change how big, and so how expensive, an existing resource is.
+const SIZE_FLAGS = [
+    '--sku', '--sku-name', '--size', '--vm-size', '--node-vm-size', '--node-count', '--tier',
+    '--capacity', '--instance-count', '--service-objective', '--edition', '--max-size',
+    '--storage-size', '--throughput', '--size-gb',
+];
+// Flags worth showing in the prompt, so you can see what you are approving.
+const DETAIL_FLAGS = [
+    ['sku', ['--sku', '--sku-name']],
+    ['size', ['--size', '--vm-size', '--node-vm-size']],
+    ['nodes', ['--node-count', '--instance-count']],
+    ['tier', ['--tier', '--edition', '--service-objective']],
+    ['location', ['--location', '-l']],
+];
+// Commands that can create any resource, or that create several at once.
+const ALWAYS_ASK = [
+    { prefix: 'deployment group create', why: 'deploy a template, which can create resources of any type', skipIf: ['--what-if', '-w'] },
+    { prefix: 'deployment sub create', why: 'deploy a template, which can create resources of any type', skipIf: ['--what-if', '-w'] },
+    { prefix: 'deployment mg create', why: 'deploy a template, which can create resources of any type', skipIf: ['--what-if', '-w'] },
+    { prefix: 'deployment tenant create', why: 'deploy a template, which can create resources of any type', skipIf: ['--what-if', '-w'] },
+    { prefix: 'group deployment create', why: 'deploy a template, which can create resources of any type' },
+    { prefix: 'stack group create', why: 'create a deployment stack, which can create resources of any type' },
+    { prefix: 'stack sub create', why: 'create a deployment stack, which can create resources of any type' },
+    { prefix: 'resource create', why: 'create a resource of any type from raw properties' },
+    { prefix: 'webapp up', why: 'create a resource group, an App Service plan and a web app if they do not exist' },
+    { prefix: 'containerapp up', why: 'create an environment, a registry and a container app if they do not exist' },
+];
+function detailsOf(rest) {
+    const parts = [];
+    for (const [label, flags] of DETAIL_FLAGS) {
+        const value = flagValue(rest, flags);
+        if (value)
+            parts.push(`${label} ${value}`);
+    }
+    return parts.join(', ');
+}
+const startsWithWords = (path, prefix) => {
+    const words = prefix.split(' ');
+    return words.every((w, i) => path[i] === w);
+};
+function classifyAz(rest) {
+    if (isHelp(rest))
+        return [];
+    const path = commandPath(rest);
+    if (path.length === 0)
+        return [];
+    for (const rule of ALWAYS_ASK) {
+        if (startsWithWords(path, rule.prefix) && !(rule.skipIf && hasFlag(rest, rule.skipIf))) {
+            return [`${rule.why}. The prompt cannot show what the template or properties contain`];
+        }
+    }
+    if (path[0] === 'rest' && (flagValue(rest, ['--method', '-m']) ?? '').toLowerCase() === 'put') {
+        return ['send an ARM PUT request, which can create a resource of any type'];
+    }
+    for (const res of BY_PREFIX) {
+        if (!startsWithWords(path, res.prefix))
+            continue;
+        const verb = path[res.prefix.split(' ').length];
+        if (!verb)
+            return [];
+        const verbs = res.verbs ?? DEFAULT_VERBS;
+        const isUpdate = verb === 'update' && hasFlag(rest, SIZE_FLAGS);
+        if (!verbs.includes(verb) && !isUpdate)
+            continue;
+        const name = flagValue(rest, ['--name', '-n']);
+        const details = detailsOf(rest);
+        const action = isUpdate ? 'change the size of' : verb === 'build' ? 'run a billed build in' : verb;
+        const text = `${action} ${res.label}` +
+            (name ? ` "${name}"` : '') +
+            (details ? ` (${details})` : '') +
+            `. ${res.note ?? GENERIC_NOTE}`;
+        return [text];
+    }
+    // `az vm disk attach --new` creates a new billed disk.
+    if (startsWithWords(path, 'vm disk attach') && hasFlag(rest, ['--new'])) {
+        return ['create a new managed disk and attach it to a VM. It bills for its size until deleted'];
+    }
+    return [];
+}
+export function classify(command) {
+    const reasons = [];
+    for (const segment of splitSegments(command)) {
+        const tool = findTool(tokenize(segment));
+        if (tool?.name === 'az')
+            reasons.push(...classifyAz(tool.rest));
+    }
+    return reasons.length ? { level: 'ask', reasons } : PASS;
+}

package/dist/hook.js

@@ -0,0 +1,30 @@
+// PreToolUse command hook. Reads the hook payload on stdin and, if the command can create or
+// start an Azure resource that costs money, answers "ask" so Claude Code shows its normal
+// approval prompt. Any failure here must fail OPEN: print nothing, exit 0, let the command run.
+import { readFileSync } from 'node:fs';
+import { classify } from "./classify.js";
+function main() {
+    const payload = JSON.parse(readFileSync(0, 'utf8'));
+    const command = payload.tool_input?.command;
+    if (typeof command !== 'string')
+        return;
+    const verdict = classify(command);
+    if (verdict.level !== 'ask')
+        return;
+    const steps = verdict.reasons.map((r, i) => (verdict.reasons.length > 1 ? `(${i + 1}) ` : '') + r);
+    const reason = `az-brake: this command would ${steps.join(' ')} ` +
+        `az-brake cannot see your Azure prices or discounts, so no cost estimate is shown. Approve?`;
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'ask',
+            permissionDecisionReason: reason,
+        },
+    }));
+}
+try {
+    main();
+}
+catch {
+    // fail open: a bug in this hook must never be the reason a command is blocked
+}

package/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Asks before a Bash or PowerShell command creates or starts an Azure resource that costs money.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/dist/hook.js"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "az-brake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Claude Code plugin that asks before an Azure CLI command creates or starts a resource that costs money.",
+  "license": "MIT",
+  "author": {
+    "name": "thisismairaj",
+    "url": "https://github.com/thisismairaj"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test \"test/*.test.ts\""
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thisismairaj/az-brake.git"
+  },
+  "homepage": "https://github.com/thisismairaj/az-brake#readme",
+  "bugs": {
+    "url": "https://github.com/thisismairaj/az-brake/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "azure",
+    "azure-cli",
+    "finops",
+    "cost-control",
+    "hook"
+  ],
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ]
+}