@jqntn/agentdoctor 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@jqntn/agentdoctor",
+  "version": "0.1.0",
+  "description": "Lint and grade your AI coding-agent configuration: permissions, hooks, MCP servers, skills, subagents and CLAUDE.md. Catches silent failures, security holes and context waste, with fixes. Zero dependencies, no telemetry.",
+  "keywords": [
+    "agent",
+    "agent-config",
+    "agents-md",
+    "ai-agent",
+    "audit",
+    "ci",
+    "claude",
+    "claude-code",
+    "claude-md",
+    "cli",
+    "config-audit",
+    "developer-experience",
+    "devtools",
+    "grade",
+    "hooks",
+    "lint",
+    "linter",
+    "llms-txt",
+    "mcp",
+    "model-context-protocol",
+    "permissions",
+    "sarif",
+    "security",
+    "static-analysis"
+  ],
+  "license": "MIT",
+  "author": "Julien QUENTIN <jqntn88@gmail.com>",
+  "homepage": "https://jqntn.github.io/agentdoctor/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jqntn/agentdoctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jqntn/agentdoctor/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "agentdoctor": "bin/agentdoctor.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./rules": "./src/rules/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "schemas",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "selfcheck": "node bin/agentdoctor.js --version",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "docs": "node tools/gen-docs.mjs && node tools/build-site.mjs",
+    "commits": "node tools/check-commits.mjs HEAD"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/schemas/policy.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jqntn.github.io/agentdoctor/schemas/policy.schema.json",
+  "title": "agentdoctor team policy",
+  "description": "Org-wide standards for AI coding-agent configuration, enforced by the policy/* rules when this file is committed at the repo root as agentdoctor.policy.json.",
+  "type": "object",
+  "properties": {
+    "requiredDeny": {
+      "type": "array", "items": { "type": "string" },
+      "description": "Permission deny rules every repo must carry, e.g. \"Read(./.env*)\". A single * is literal; ** is the wildcard."
+    },
+    "forbiddenAllow": {
+      "type": "array", "items": { "type": "string" },
+      "description": "Permission allow rules no repo may carry, e.g. \"Bash(*)\" (that exact rule) or \"Bash(**sudo**)\" (any Bash rule mentioning sudo)."
+    },
+    "allowedMcpServers": {
+      "type": "array", "items": { "type": "string" },
+      "description": "Approved MCP server names (** wildcards allowed). If present, unlisted servers are errors. Omit the field to skip the check; an empty array approves none."
+    },
+    "requiredHooks": {
+      "type": "array",
+      "items": { "enum": ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Notification", "Stop", "SubagentStop", "PreCompact", "SessionStart", "SessionEnd"] },
+      "description": "Hook events that must be configured in every repo."
+    },
+    "maxMemoryTokens": {
+      "type": "number", "exclusiveMinimum": 0,
+      "description": "Ceiling on the estimated token size of project memory files (CLAUDE.md et al., user scope excluded)."
+    },
+    "forbiddenPermissionModes": {
+      "type": "array",
+      "items": { "enum": ["default", "acceptEdits", "plan", "bypassPermissions"] },
+      "description": "Values of permissions.defaultMode that no repo may set. Usually [\"bypassPermissions\"]."
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/report.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jqntn.github.io/agentdoctor/schemas/report.schema.json",
+  "title": "agentdoctor JSON report (format version 1)",
+  "description": "Shape of `agentdoctor --json`. Additions are the only change ever made to version 1.",
+  "type": "object",
+  "required": ["version", "tool", "toolVersion", "root", "scannedFiles", "skippedFiles", "rulesRun", "suppressed", "summary", "findings"],
+  "properties": {
+    "version": { "const": 1 },
+    "tool": { "const": "agentdoctor" },
+    "toolVersion": { "type": "string" },
+    "root": { "type": "string" },
+    "scannedFiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind", "scope", "bytes"],
+        "properties": {
+          "path": { "type": "string" },
+          "kind": { "enum": ["settings", "mcp", "memory", "agent", "skill", "command", "hook", "keybindings"] },
+          "scope": { "enum": ["project", "local", "user", "enterprise"] },
+          "bytes": { "type": "integer" }
+        }
+      }
+    },
+    "skippedFiles": { "type": "array", "items": { "type": "string" } },
+    "rulesRun": { "type": "array", "items": { "type": "string" } },
+    "suppressed": { "type": "integer" },
+    "grade": { "enum": ["A+", "A", "B", "C", "D", "F"], "description": "Health grade. A+ zero findings; A info only; B 1-2 warnings; C 3+ warnings; D 1-2 errors; F 3+ errors." },
+    "summary": {
+      "type": "object",
+      "required": ["error", "warning", "info"],
+      "properties": {
+        "error": { "type": "integer" }, "warning": { "type": "integer" }, "info": { "type": "integer" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "severity", "category", "message", "file", "absolutePath", "line"],
+        "properties": {
+          "ruleId": { "type": "string", "pattern": "^[a-z]+/[a-z0-9-]+$" },
+          "severity": { "enum": ["error", "warning", "info"] },
+          "category": { "enum": ["correctness", "security", "cost", "hygiene", "policy", "internal"] },
+          "message": { "type": "string" },
+          "help": { "type": ["string", "null"] },
+          "file": { "type": "string", "description": "Display path (repo-relative or ~-prefixed)" },
+          "absolutePath": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 },
+          "column": { "type": ["integer", "null"] },
+          "configPath": { "type": ["string", "null"] },
+          "snippet": { "type": ["string", "null"], "description": "Offending value; secrets are redacted" }
+        }
+      }
+    }
+  }
+}

package/skills/config-audit/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: config-audit
+description: Audit and fix AI coding-agent configuration with agentdoctor. Use whenever the user asks to audit, lint, review, secure, or fix their agent config, .claude directory, permissions, hooks, MCP servers, skills, subagents, or CLAUDE.md; after any edit to those files; when a hook "isn't firing" or a permission rule "isn't working"; or when the user asks for their config grade. Requires only npx.
+---
+
+# Audit agent configuration with agentdoctor
+
+agentdoctor is a zero-dependency linter for agent config (72 rules: security, correctness,
+cost, hygiene, team policy). It makes no network calls and never opens credential files, so it
+is safe to run unattended in any project.
+
+## Run the audit
+
+```sh
+npx @jqntn/agentdoctor . --no-user --json
+```
+
+Nothing is installed by this skill itself: `npx` uses the project's own `agentdoctor` if one
+is in `node_modules`, and otherwise fetches it on first use (then caches it). If the user
+wants it permanent and versioned, offer `npm install -D @jqntn/agentdoctor`; if `npx` cannot fetch
+(offline/registry-blocked environment) and there is no local install, say so and stop rather
+than improvising an audit by hand.
+
+Exit codes: `0` clean, `1` findings with severity error exist, `2` usage error. **Exit 1 is a
+successful audit** — valid JSON is still on stdout; only exit 2 means the run itself failed.
+
+Key fields per finding (already sorted most-severe-first):
+
+| Field | Use it to |
+|---|---|
+| `severity` | `error` > `warning` > `info` |
+| `message` | explain the problem to the user in one line |
+| `help` | apply the fix — it states what to change and why |
+| `file` + `line` | locate the edit |
+| `configPath` | the exact config key, e.g. `permissions.allow[2]` |
+| `snippet` | the offending value (secrets arrive redacted) |
+| top-level `grade` | `A+` (clean) through `F` (3+ errors) — report it to the user |
+
+## Fix loop
+
+For each finding, most severe first:
+
+1. State the problem in one line (use `message`).
+2. Edit `file` at `line`, guided by `help`; `configPath` names the exact key. Typical fixes
+   are in `references/fix-recipes.md` — read it when a fix is not obvious from `help`.
+3. If the finding is clearly intentional for this project, do NOT silently skip it: add a
+   suppression comment to that file and tell the user why:
+   `agentdoctor-disable <ruleId>`
+
+Then verify:
+
+```sh
+npx @jqntn/agentdoctor . --no-user --quiet
+```
+
+Exit 0 means clean. Re-run the JSON audit if it is still 1 and continue.
+
+## Hard rules
+
+- **Never delete or weaken a `deny` rule to silence a finding.** Fix the rule (usually a
+  casing or tool-name typo) so it actually blocks what it names.
+- **Never widen an allow rule as a "fix".** Findings about broad rules are fixed by
+  narrowing, moving to `permissions.ask`, or adding deny rules.
+- **Never echo secrets.** Findings arrive redacted; keep them that way in your summary.
+- If more than ~10 findings exist, fix all errors, then ask the user whether to continue
+  with warnings or record a baseline instead (see `references/fix-recipes.md`).
+
+## Report back
+
+End with: the grade before and after, what you fixed (rule ids), what you suppressed and why,
+and anything needing a human decision. If the user wants to track this in CI or show the
+grade, the one-command options are `npx @jqntn/agentdoctor --init-ci` and `npx @jqntn/agentdoctor --badge`.

package/skills/config-audit/references/fix-recipes.md

@@ -0,0 +1,107 @@
+# Fix recipes
+
+Read this when a finding's `help` text is not enough to act on. Recipes are grouped by rule
+id prefix. Full rationale for any rule: `npx @jqntn/agentdoctor --explain <rule-id>`.
+
+## security/unrestricted-bash, security/unrestricted-egress
+
+Replace the wildcard with the narrowest set of commands the project genuinely runs
+unattended. Derive them from the project itself (package.json scripts, Makefile, CI):
+
+```json
+"allow": ["Bash(npm test:*)", "Bash(npm run lint)", "Bash(git status)", "Bash(git diff:*)"]
+```
+
+For WebFetch, scope to domains: `"WebFetch(domain:docs.example.com)"`. If the user insists on
+a blanket rule, move it to `permissions.ask` instead of `allow` so a prompt survives.
+
+## security/destructive-allow
+
+Move the rule from `allow` to `ask`. If only part of the command is dangerous, split it:
+allow the safe subset (`Bash(git push origin main)`), ask for the rest (`Bash(git push:*)`).
+
+## security/sensitive-read-allowed, security/missing-secret-denies
+
+Remove the offending allow rule, then ensure the deny list contains at least:
+
+```json
+"deny": ["Read(./.env*)", "Read(**/.ssh/**)", "Read(**/*.pem)", "Read(**/.aws/credentials)"]
+```
+
+## security/secret-in-config
+
+Move the value into the environment or a secret manager, reference it indirectly, and tell
+the user to **rotate the credential** — it must be treated as leaked once committed. Do not
+just delete the line; the value remains in git history.
+
+## security/hook-remote-code
+
+Download the remote script once, commit it under `.claude/hooks/`, make it executable, and
+point the hook at `$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh`. Show the user the script
+content before committing it.
+
+## security/mcp-unpinned-package
+
+Pin the exact version currently in use: run `npm view <pkg> version` (or check the lockfile)
+and change `@latest`/no-version to `@<that version>`.
+
+## correctness/* typos (unknown-settings-key, unknown-hook-event, permission-unknown-tool, hook-matcher-unknown-tool, invalid-model)
+
+The message contains a `Did you mean "X"` suggestion — apply exactly that casing. These are
+the highest-value fixes in the catalogue: each one turns dead config back on.
+
+## correctness/invalid-json
+
+Fix the syntax error at the reported line/column (common: trailing comma before `}`, missing
+comma, unquoted key). The whole file is ignored until this parses, so fix it first — other
+findings in that file only appear on the next run.
+
+## correctness/agent-* and skill-* mismatches
+
+Rename to agree: frontmatter `name` should match the filename (agents) or directory (skills).
+Prefer renaming the frontmatter unless other config references the old name.
+
+## cost/memory-file-too-large, cost/memory-contains-generated-content
+
+Move reference material (pasted code, long command lists, API docs) out of CLAUDE.md into a
+regular file, and replace it with one line: `See docs/<topic>.md for <thing>.` Keep in
+CLAUDE.md only what must apply to every session: build/test commands, conventions, hard
+invariants.
+
+## cost/duplicated-memory-instructions
+
+Keep the instruction in the more general file (usually the repo root CLAUDE.md); delete the
+copy. Never keep both — they drift until they contradict.
+
+## Adopting on a repo with many findings (baseline)
+
+If the user wants CI green today without fixing the backlog:
+
+```sh
+npx @jqntn/agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+```
+
+Commit the baseline. CI then runs with `--baseline .agentdoctor-baseline.json` and fails only
+on new findings. Fix errors before baselining if at all possible — baselines are for debt,
+not for hazards.
+
+## Setting up a team policy
+
+If the user manages multiple repos, offer:
+
+```sh
+npx @jqntn/agentdoctor --init-policy
+```
+
+Then edit `agentdoctor.policy.json` with them. Wildcards: a single `*` is literal (matches
+exactly that rule text); `**` is the wildcard (`Bash(**sudo**)` = any Bash rule mentioning
+sudo).
+
+## Permanent installation
+
+```sh
+npx @jqntn/agentdoctor --init-ci      # GitHub Actions: SARIF PR annotations + error gate
+npx @jqntn/agentdoctor --badge        # README badge showing the current grade
+```
+
+Both are overwrite-safe (they refuse if the file exists).

package/src/adopt.js

@@ -0,0 +1,178 @@
+/**
+ * Adoption commands: the one-command paths from "ran it once" to "installed".
+ *
+ * Each writes exactly one well-known file, refuses to overwrite, and prints
+ * what it did plus the next step. They exist because the gap between a
+ * drive-by `npx @jqntn/agentdoctor` and a permanent CI check is where most tools
+ * lose people (and agents) - these close that gap in a single action that is
+ * safe to run unattended.
+ */
+import { existsSync, writeFileSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { computeGrade, GRADE_COLORS } from './grade.js';
+import { REPO_URL, BADGE_BASE_URL } from './links.js';
+
+export const CI_WORKFLOW_PATH = '.github/workflows/agentdoctor.yml';
+
+const CI_WORKFLOW = `name: agentdoctor
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      # Findings annotate the PR diff via code scanning.
+      - run: npx @jqntn/agentdoctor --no-user --sarif > agentdoctor.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: agentdoctor.sarif
+        continue-on-error: true
+
+      # The actual gate: exit 1 on errors.
+      # Adopting on a repo with existing findings? Commit a baseline first:
+      #   npx @jqntn/agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+      # then change the line below to:
+      #   npx @jqntn/agentdoctor --no-user --baseline .agentdoctor-baseline.json --quiet
+      - run: npx @jqntn/agentdoctor --no-user --quiet
+`;
+
+export const SKILL_PATH = '.claude/skills/config-audit';
+
+/**
+ * The canonical skill ships inside the package at skills/config-audit/ - the
+ * same files served by the plugin marketplace - so an installed skill can
+ * never drift from the published one.
+ */
+const PACKAGED_SKILL = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'config-audit');
+
+/** Writes a file if absent. Returns a { written, path, message } outcome. */
+function writeOnce(root, relative, contents) {
+  const target = join(root, relative);
+  if (existsSync(target)) {
+    return { written: false, path: relative, message: `${relative} already exists; not overwriting.` };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, contents);
+  return { written: true, path: relative, message: `Wrote ${relative}` };
+}
+
+export function initCi(root) {
+  return writeOnce(root, CI_WORKFLOW_PATH, CI_WORKFLOW);
+}
+
+export const AGENTS_PATH = 'AGENTS.md';
+const AGENTS_MARKER_START = '<!-- agentdoctor:start -->';
+const AGENTS_MARKER_END = '<!-- agentdoctor:end -->';
+
+/**
+ * The section is deliberately short: AGENTS.md rides along in every session's
+ * context for the agents that read it, so this must not become the kind of
+ * memory bloat agentdoctor's own cost rules exist to flag.
+ */
+const AGENTS_SECTION = `${AGENTS_MARKER_START}
+## Agent configuration hygiene (agentdoctor)
+
+After editing any agent config (.claude/ settings, hooks, permissions, .mcp.json, skills,
+subagents, CLAUDE.md/AGENTS.md), audit it:
+
+\`\`\`sh
+npx @jqntn/agentdoctor . --no-user --json
+\`\`\`
+
+Exit 1 means findings exist (the JSON on stdout is still valid); exit 2 means the run itself
+failed. Findings arrive most-severe-first; fix each by editing \`file\` at \`line\` as its
+\`help\` field describes (\`configPath\` names the exact key), then verify with
+\`npx @jqntn/agentdoctor . --no-user --quiet\` (exit 0 = clean). Suppress an intentional finding with
+an \`agentdoctor-disable <rule-id>\` comment in that file and state why. Never delete or
+weaken a \`deny\` rule, never widen an \`allow\` rule, never echo unredacted secrets.
+${AGENTS_MARKER_END}`;
+
+/**
+ * Installs the audit instructions where Codex, Cursor, Gemini CLI, Jules and
+ * every other AGENTS.md-reading tool will see them. Creates the file if
+ * missing, appends if present, refuses if the marker already exists.
+ */
+export function initAgents(root) {
+  const target = join(root, AGENTS_PATH);
+  if (existsSync(target)) {
+    const current = readFileSync(target, 'utf8');
+    if (current.includes(AGENTS_MARKER_START)) {
+      return { written: false, path: AGENTS_PATH, message: `${AGENTS_PATH} already has an agentdoctor section; not duplicating it.` };
+    }
+    writeFileSync(target, `${current.replace(/\n*$/, '')}\n\n${AGENTS_SECTION}\n`);
+    return { written: true, path: AGENTS_PATH, message: `Appended the agentdoctor section to ${AGENTS_PATH}` };
+  }
+  writeFileSync(target, `# AGENTS.md\n\n${AGENTS_SECTION}\n`);
+  return { written: true, path: AGENTS_PATH, message: `Wrote ${AGENTS_PATH} with the agentdoctor section` };
+}
+
+export function initSkill(root) {
+  const target = join(root, SKILL_PATH);
+  if (existsSync(target)) {
+    return { written: false, path: SKILL_PATH, message: `${SKILL_PATH} already exists; not overwriting.` };
+  }
+  cpSync(PACKAGED_SKILL, target, { recursive: true });
+  return { written: true, path: SKILL_PATH, message: `Wrote ${SKILL_PATH}/ (SKILL.md + fix recipes)` };
+}
+
+/**
+ * A paste-ready score card for chat, issues, or a launch thread.
+ *
+ * Contains only rule ids and counts - never messages, paths, or snippets - so
+ * it is safe to share from a private repo without reviewing it first.
+ */
+export function shareCard(result) {
+  const { findings, workspace } = result;
+  const grade = computeGrade(findings);
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  const info = findings.filter((f) => f.severity === 'info').length;
+  const files = workspace.files.length;
+
+  const counts = [
+    errors && `${errors} error${errors === 1 ? '' : 's'}`,
+    warnings && `${warnings} warning${warnings === 1 ? '' : 's'}`,
+    info && `${info} info`,
+  ].filter(Boolean).join(', ') || 'no findings';
+
+  const topRules = [...new Set(findings.map((f) => f.ruleId))].slice(0, 3);
+
+  const lines = [
+    `## agentdoctor grade: ${grade}`,
+    '',
+    `${files} agent config file${files === 1 ? '' : 's'} scanned - ${counts}.`,
+  ];
+  if (topRules.length) {
+    lines.push('', ...topRules.map((id) => `- \`${id}\``));
+  }
+  lines.push('', 'Check your own agent config:', '', '```', 'npx @jqntn/agentdoctor', '```', '', REPO_URL);
+  return `${lines.join('\n')}\n`;
+}
+
+/** Markdown for a README badge that states the current grade. */
+export function badgeMarkdown(result) {
+  const grade = computeGrade(result.findings);
+  const color = GRADE_COLORS[grade] ?? '64748B';
+  const img = `${BADGE_BASE_URL}/agentdoctor-${encodeURIComponent(grade)}-${color}`;
+  return [
+    `[![agentdoctor: ${grade}](${img})](${REPO_URL})`,
+    '',
+    '<!-- Keep it honest: regenerate after config changes with `npx @jqntn/agentdoctor --badge`,',
+    '     or let CI gate on the real thing: `npx @jqntn/agentdoctor --init-ci` -->',
+  ].join('\n') + '\n';
+}

package/src/constants.js

@@ -0,0 +1,139 @@
+/**
+ * Known-good vocabulary for agent harness config.
+ *
+ * These lists drive typo detection, so they are intentionally permissive:
+ * anything unrecognised is reported at `info` unless it is a near-miss for a
+ * real key, which is reported as a likely typo. New harness releases add keys,
+ * and a linter that shouts about every unknown field is a linter people delete.
+ */
+
+export const SETTINGS_KEYS = new Set([
+  'permissions', 'env', 'model', 'hooks', 'apiKeyHelper', 'cleanupPeriodDays',
+  'includeCoAuthoredBy', 'enableAllProjectMcpServers', 'enabledMcpjsonServers',
+  'disabledMcpjsonServers', 'statusLine', 'forceLoginMethod', 'outputStyle',
+  'disableAllHooks', 'awsAuthRefresh', 'awsCredentialExport', 'otelHeadersHelper',
+  'sandbox', 'agents', 'alwaysThinkingEnabled', 'spinnerTipsEnabled',
+  'attributionSuffix', 'autoUpdates', 'installMethod', 'mcpServers',
+  'extraKnownMarkdownFiles', 'schema', '$schema',
+]);
+
+export const PERMISSION_KEYS = new Set([
+  'allow', 'deny', 'ask', 'defaultMode', 'additionalDirectories',
+  'disableBypassPermissionsMode',
+]);
+
+export const PERMISSION_MODES = new Set([
+  'default', 'acceptEdits', 'plan', 'bypassPermissions',
+]);
+
+export const HOOK_EVENTS = new Set([
+  'PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Notification', 'Stop',
+  'SubagentStop', 'PreCompact', 'SessionStart', 'SessionEnd',
+]);
+
+/** Hook events that receive a tool matcher; the rest ignore `matcher`. */
+export const MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PreCompact']);
+
+export const TOOL_NAMES = new Set([
+  'Agent', 'Task', 'Bash', 'BashOutput', 'KillBash', 'KillShell', 'Glob', 'Grep',
+  'Read', 'Edit', 'MultiEdit', 'Write', 'NotebookEdit', 'NotebookRead',
+  'WebFetch', 'WebSearch', 'TodoWrite', 'ExitPlanMode', 'SlashCommand', 'Skill',
+  'ListMcpResources', 'ReadMcpResource',
+]);
+
+export const MODEL_ALIASES = new Set([
+  'opus', 'sonnet', 'haiku', 'opusplan', 'inherit', 'default', 'fable',
+]);
+
+/** Tools that can read arbitrary local content. */
+export const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'NotebookRead']);
+
+/** Tools that can move data off the machine. */
+export const EGRESS_TOOLS = new Set(['WebFetch', 'WebSearch', 'Bash']);
+
+/** Tools that mutate the working tree. */
+export const WRITE_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+
+/**
+ * Command fragments that are destructive or irreversible enough that a blanket
+ * allow rule is very likely a mistake.
+ */
+export const DESTRUCTIVE_PATTERNS = [
+  { pattern: /\brm\s+(-[a-zA-Z]*[rRf][a-zA-Z]*\s+)+/, label: 'recursive/forced delete (rm -rf)' },
+  { pattern: /\bgit\s+push\s+.*(--force\b|-f\b)/, label: 'force push' },
+  { pattern: /\bgit\s+reset\s+--hard\b/, label: 'hard reset (discards local work)' },
+  { pattern: /\bgit\s+clean\s+-[a-zA-Z]*[fd]/, label: 'git clean (deletes untracked files)' },
+  { pattern: /\bdd\s+.*\bof=/, label: 'raw disk write (dd)' },
+  { pattern: /\bmkfs(\.|\s)/, label: 'filesystem format' },
+  { pattern: /\bchmod\s+(-R\s+)?777\b/, label: 'chmod 777' },
+  { pattern: /\bsudo\b/, label: 'privilege escalation (sudo)' },
+  { pattern: /\bshutdown\b|\breboot\b|\bhalt\b/, label: 'host shutdown' },
+  { pattern: /\bkubectl\s+delete\b/, label: 'kubectl delete' },
+  { pattern: /\bterraform\s+(destroy|apply)\b/, label: 'terraform destroy/apply' },
+  { pattern: /\baws\s+s3\s+rb\b|\baws\s+s3\s+rm\b.*--recursive/, label: 'recursive S3 delete' },
+  { pattern: /\bdrop\s+(table|database)\b/i, label: 'SQL DROP' },
+  { pattern: /\btruncate\s+table\b/i, label: 'SQL TRUNCATE' },
+  { pattern: /\bnpm\s+publish\b|\bcargo\s+publish\b|\btwine\s+upload\b/, label: 'package publish' },
+  { pattern: /\bgh\s+(pr|release)\s+(merge|create|delete)\b/, label: 'GitHub state change' },
+  { pattern: /:\(\)\s*\{.*\}\s*;\s*:/, label: 'fork bomb' },
+];
+
+/**
+ * Shell fragments that download and execute code in one step. These turn any
+ * allowed hook or command into a remote-code-execution channel.
+ */
+export const REMOTE_EXEC_PATTERNS = [
+  { pattern: /\b(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(ba|z|k|da)?sh\b/, label: 'curl | sh' },
+  { pattern: /\b(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(python3?|node|perl|ruby)\b/, label: 'download piped to interpreter' },
+  { pattern: /\bIEX\s*\(|\bInvoke-Expression\b/i, label: 'PowerShell Invoke-Expression' },
+  { pattern: /\bNet\.WebClient\b/i, label: 'PowerShell remote download' },
+  { pattern: /\beval\s+"?\$\((curl|wget)/, label: 'eval of remote output' },
+  { pattern: /\bbash\s+<\(\s*(curl|wget)/, label: 'process substitution of remote script' },
+  { pattern: /\bsource\s+<\(\s*(curl|wget)/, label: 'sourcing a remote script' },
+];
+
+/**
+ * Secret shapes worth flagging. Each entry is anchored enough to avoid firing
+ * on ordinary prose or placeholder text.
+ */
+export const SECRET_PATTERNS = [
+  { pattern: /\bsk-ant-[A-Za-z0-9_-]{16,}/, label: 'Anthropic API key' },
+  { pattern: /\bsk-(proj-)?[A-Za-z0-9]{32,}/, label: 'OpenAI-style API key' },
+  { pattern: /\bgh[pousr]_[A-Za-z0-9]{30,}/, label: 'GitHub token' },
+  { pattern: /\bgithub_pat_[A-Za-z0-9_]{30,}/, label: 'GitHub fine-grained PAT' },
+  { pattern: /\bAKIA[0-9A-Z]{16}\b/, label: 'AWS access key id' },
+  { pattern: /\bASIA[0-9A-Z]{16}\b/, label: 'AWS temporary access key id' },
+  { pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/, label: 'Slack token' },
+  { pattern: /\bAIza[0-9A-Za-z_-]{35}\b/, label: 'Google API key' },
+  { pattern: /\bglpat-[A-Za-z0-9_-]{20,}/, label: 'GitLab personal access token' },
+  { pattern: /-----BEGIN (RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/, label: 'private key' },
+  { pattern: /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\./, label: 'JWT' },
+  { pattern: /\bsk_live_[A-Za-z0-9]{20,}/, label: 'Stripe live secret key' },
+  { pattern: /\bnpm_[A-Za-z0-9]{36}\b/, label: 'npm access token' },
+  { pattern: /\bhf_[A-Za-z0-9]{30,}/, label: 'Hugging Face token' },
+];
+
+/** Environment variables that change how child processes load code. */
+export const DANGEROUS_ENV_VARS = new Map([
+  ['LD_PRELOAD', 'injects a shared library into every child process'],
+  ['LD_LIBRARY_PATH', 'redirects dynamic library resolution'],
+  ['DYLD_INSERT_LIBRARIES', 'injects a dylib into every child process (macOS)'],
+  ['NODE_OPTIONS', 'can preload arbitrary JavaScript into every Node process'],
+  ['PYTHONSTARTUP', 'executes a file on every interactive Python start'],
+  ['PATH', 'changes which binaries commands resolve to'],
+  ['GIT_SSH_COMMAND', 'replaces the transport used for every git operation'],
+  ['BASH_ENV', 'executes a file on every non-interactive bash start'],
+]);
+
+/** Paths that should generally be unreadable to an agent. */
+export const SENSITIVE_READ_TARGETS = [
+  '.env', '.env.*', '**/.ssh/**', '**/*.pem', '**/*.key',
+  '**/.aws/credentials', '**/.kube/config', '**/.npmrc', '**/.netrc',
+  '**/id_rsa', '**/.git-credentials',
+];
+
+/** Rough per-turn context budget before a memory file starts costing real money. */
+export const MEMORY_TOKEN_WARN = 4000;
+export const MEMORY_TOKEN_ERROR = 12000;
+export const TOTAL_MEMORY_TOKEN_WARN = 10000;
+export const MCP_SERVER_WARN_COUNT = 8;