delimit-cli 3.12.1 → 3.13.0

package/README.md

@@ -7,6 +7,10 @@ Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, govern
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Glama](https://glama.ai/mcp/servers/delimit-ai/delimit-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/delimit-ai/delimit-mcp-server)
 
+<p align="center">
+  <img src="docs/demo.gif" alt="Delimit detecting breaking API changes" width="700">
+</p>
+
 Persistent ledger, API governance, security orchestration, and multi-model deliberation — all shared across Claude Code, Codex, Cursor, and Gemini CLI.
 
 ---
@@ -111,24 +115,46 @@ When installed into your AI coding assistant, Delimit provides tools across two
 
 ---
 
-## What it catches
-
-10 categories of breaking changes:
-
-| Change | Example |
-|--------|---------|
-| Endpoint removed | `DELETE /users/{id}` disappeared |
-| HTTP method removed | `PATCH /orders` no longer exists |
-| Required parameter added | New required header on `GET /items` |
-| Field removed from response | `email` dropped from user object |
-| Type changed | `id` went from string to integer |
-| Enum value removed | `status: "pending"` no longer valid |
-| Response code removed | `200 OK` response dropped |
-| Parameter removed | `sort` query param removed |
-| Required field added to request | Body now requires `tenant_id` |
-| Format changed | `date-time` changed to `date` |
-
-Detection is deterministic — rules, not AI inference. Same input always produces the same result.
+## What It Detects
+
+27 change types (17 breaking, 10 non-breaking) -- deterministic rules, not AI inference. Same input always produces the same result.
+
+### Breaking Changes
+
+| # | Change Type | Example |
+|---|-------------|---------|
+| 1 | `endpoint_removed` | `DELETE /users/{id}` removed entirely |
+| 2 | `method_removed` | `PATCH /orders` no longer exists |
+| 3 | `required_param_added` | New required header on `GET /items` |
+| 4 | `param_removed` | `sort` query parameter removed |
+| 5 | `response_removed` | `200 OK` response dropped |
+| 6 | `required_field_added` | Request body now requires `tenant_id` |
+| 7 | `field_removed` | `email` dropped from response object |
+| 8 | `type_changed` | `id` went from `string` to `integer` |
+| 9 | `format_changed` | `date-time` changed to `date` |
+| 10 | `enum_value_removed` | `status: "pending"` no longer valid |
+| 11 | `param_type_changed` | Query param `limit` changed from `integer` to `string` |
+| 12 | `param_required_changed` | `filter` param became required |
+| 13 | `response_type_changed` | Response `data` changed from `array` to `object` |
+| 14 | `security_removed` | OAuth2 security scheme removed |
+| 15 | `security_scope_removed` | `write:pets` scope removed from OAuth2 |
+| 16 | `max_length_decreased` | `name` maxLength reduced from 255 to 100 |
+| 17 | `min_length_increased` | `code` minLength increased from 1 to 5 |
+
+### Non-Breaking Changes
+
+| # | Change Type | Example |
+|---|-------------|---------|
+| 18 | `endpoint_added` | New `POST /webhooks` endpoint |
+| 19 | `method_added` | `PATCH /users/{id}` method added |
+| 20 | `optional_param_added` | Optional `format` query param added |
+| 21 | `response_added` | `201 Created` response added |
+| 22 | `optional_field_added` | Optional `nickname` field added to response |
+| 23 | `enum_value_added` | `status: "archived"` value added |
+| 24 | `description_changed` | Updated description for `/health` endpoint |
+| 25 | `security_added` | API key security scheme added |
+| 26 | `deprecated_added` | `GET /v1/users` marked as deprecated |
+| 27 | `default_changed` | Default value for `page_size` changed from 10 to 20 |
 
 ---
 

package/bin/delimit-cli.js

@@ -947,29 +947,59 @@ rules:
 `,
 };
 
-// Init command — scaffold .delimit/ config
+// Init command — guided onboarding wizard (Consensus: Build Next 2026-03-27)
 program
     .command('init')
     .description('Initialize Delimit API governance in this project')
-    .option('--preset <name>', 'Policy preset: strict, default, or relaxed', 'default')
+    .option('--preset <name>', 'Policy preset: strict, default, or relaxed')
+    .option('--yes', 'Skip prompts and use defaults')
     .action(async (options) => {
+        const startTime = Date.now();
         const configDir = path.join(process.cwd(), '.delimit');
         const policyFile = path.join(configDir, 'policies.yml');
 
+        console.log(chalk.bold('\n  Delimit — API Governance Setup\n'));
+
         if (fs.existsSync(policyFile)) {
-            console.log(chalk.yellow('Already initialized — .delimit/policies.yml exists'));
+            console.log(chalk.yellow('  Already initialized — .delimit/policies.yml exists'));
+            console.log(`  Run ${chalk.bold('delimit lint')} to check your API.\n`);
             return;
         }
 
-        const preset = options.preset.toLowerCase();
-        if (!POLICY_PRESETS[preset]) {
-            console.log(chalk.red(`Unknown preset "${preset}". Choose: strict, default, or relaxed`));
-            return;
-        }
+        // Step 1: Detect project type
+        console.log(chalk.gray('  Scanning project...'));
+        const projectDir = process.cwd();
+        const projectName = path.basename(projectDir);
+        let framework = 'unknown';
+        let frameworkLabel = '';
 
-        fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(policyFile, POLICY_PRESETS[preset]);
-        console.log(chalk.green(`\n  Created .delimit/policies.yml (preset: ${preset})\n`));
+        // Check for common frameworks
+        const pkgJsonPath = path.join(projectDir, 'package.json');
+        const pyprojectPath = path.join(projectDir, 'pyproject.toml');
+        const requirementsPath = path.join(projectDir, 'requirements.txt');
+
+        if (fs.existsSync(pkgJsonPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                if (allDeps['@nestjs/core']) { framework = 'nestjs'; frameworkLabel = 'NestJS'; }
+                else if (allDeps['express']) { framework = 'express'; frameworkLabel = 'Express'; }
+                else if (allDeps['fastify']) { framework = 'fastify'; frameworkLabel = 'Fastify'; }
+                else if (allDeps['hono']) { framework = 'hono'; frameworkLabel = 'Hono'; }
+                else if (allDeps['next']) { framework = 'nextjs'; frameworkLabel = 'Next.js'; }
+            } catch {}
+        }
+        if (framework === 'unknown') {
+            const pyFiles = [pyprojectPath, requirementsPath, path.join(projectDir, 'setup.py')];
+            for (const f of pyFiles) {
+                if (fs.existsSync(f)) {
+                    const content = fs.readFileSync(f, 'utf-8').toLowerCase();
+                    if (content.includes('fastapi')) { framework = 'fastapi'; frameworkLabel = 'FastAPI'; break; }
+                    if (content.includes('django')) { framework = 'django'; frameworkLabel = 'Django'; break; }
+                    if (content.includes('flask')) { framework = 'flask'; frameworkLabel = 'Flask'; break; }
+                }
+            }
+        }
 
         // Auto-detect OpenAPI spec files
         const specPatterns = [
@@ -982,45 +1012,89 @@ program
             'api/openapi.yaml', 'api/openapi.json',
             'contrib/openapi.json',
         ];
-        const foundSpecs = specPatterns.filter(p => fs.existsSync(path.join(process.cwd(), p)));
+        const foundSpecs = specPatterns.filter(p => fs.existsSync(path.join(projectDir, p)));
+        const specPath = foundSpecs.length > 0 ? foundSpecs[0] : null;
+
+        // Check for CI
+        const hasGitHub = fs.existsSync(path.join(projectDir, '.github'));
+        const hasGitLabCI = fs.existsSync(path.join(projectDir, '.gitlab-ci.yml'));
+        const ciProvider = hasGitHub ? 'github' : hasGitLabCI ? 'gitlab' : 'none';
+
+        // Display detection results
+        console.log(`  Project:   ${chalk.bold(projectName)}`);
+        if (frameworkLabel) console.log(`  Framework: ${chalk.bold(frameworkLabel)}`);
+        if (specPath) console.log(`  Spec:      ${chalk.bold(specPath)}`);
+        else if (['fastapi', 'nestjs', 'express'].includes(framework))
+            console.log(`  Spec:      ${chalk.gray('none found')} (Zero-Spec Mode available for ${frameworkLabel})`);
+        else console.log(`  Spec:      ${chalk.gray('none found')}`);
+        if (ciProvider !== 'none') console.log(`  CI:        ${chalk.bold(ciProvider === 'github' ? 'GitHub Actions' : 'GitLab CI')}`);
+        console.log('');
 
-        if (foundSpecs.length > 0) {
-            const specPath = foundSpecs[0];
-            console.log(`  Detected spec: ${chalk.bold(specPath)}`);
-            console.log('');
-            console.log(chalk.bold('  Workflow template:\n'));
-            console.log(chalk.gray(`  name: API Governance
-  on:
-    pull_request:
-      paths:
-        - '${specPath}'
-  permissions:
-    contents: read
-    pull-requests: write
-  jobs:
-    api-governance:
-      runs-on: ubuntu-latest
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/checkout@v4
-          with:
-            ref: \${{ github.event.pull_request.base.sha }}
-            path: _base
-        - uses: delimit-ai/delimit@v1
-          with:
-            old_spec: _base/${specPath}
-            new_spec: ${specPath}
-            mode: advisory`));
-            console.log('');
+        // Step 2: Choose preset
+        let preset = options.preset ? options.preset.toLowerCase() : null;
+        if (!preset && !options.yes) {
+            // Suggest preset based on project signals
+            let defaultPreset = 'default';
+            if (specPath) {
+                // If they have a checked-in spec, they probably care about stability
+                try {
+                    const specContent = fs.readFileSync(path.join(projectDir, specPath), 'utf-8');
+                    if (specContent.includes('/v2') || specContent.includes('/v3')) defaultPreset = 'strict';
+                } catch {}
+            }
+
+            try {
+                const answers = await inquirer.prompt([{
+                    type: 'list',
+                    name: 'preset',
+                    message: 'Policy preset:',
+                    choices: [
+                        { name: 'strict   — Block all breaking changes (public APIs, payment systems)', value: 'strict' },
+                        { name: 'default  — Balanced for most teams (block critical, warn on others)', value: 'default' },
+                        { name: 'relaxed  — Warnings only (internal APIs, early-stage projects)', value: 'relaxed' },
+                    ],
+                    default: defaultPreset,
+                }]);
+                preset = answers.preset;
+            } catch {
+                preset = defaultPreset;
+            }
+        }
+        if (!preset) preset = 'default';
+
+        if (!POLICY_PRESETS[preset]) {
+            console.log(chalk.red(`  Unknown preset "${preset}". Choose: strict, default, or relaxed`));
+            return;
+        }
+
+        // Step 3: Create policy file
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(policyFile, POLICY_PRESETS[preset]);
+        console.log(chalk.green(`  Created .delimit/policies.yml (${preset})`));
 
-            // Auto-write the workflow file
-            const workflowDir = path.join(process.cwd(), '.github', 'workflows');
+        // Step 4: Add GitHub Action workflow if spec found + GitHub CI
+        if (specPath && ciProvider === 'github') {
+            const workflowDir = path.join(projectDir, '.github', 'workflows');
             const workflowFile = path.join(workflowDir, 'api-governance.yml');
 
             if (!fs.existsSync(workflowFile)) {
-                try {
-                    fs.mkdirSync(workflowDir, { recursive: true });
-                    const workflowContent = `name: API Governance
+                let writeWorkflow = true;
+                if (!options.yes) {
+                    try {
+                        const ans = await inquirer.prompt([{
+                            type: 'confirm',
+                            name: 'addWorkflow',
+                            message: 'Add GitHub Action for PR governance?',
+                            default: true,
+                        }]);
+                        writeWorkflow = ans.addWorkflow;
+                    } catch {}
+                }
+
+                if (writeWorkflow) {
+                    try {
+                        fs.mkdirSync(workflowDir, { recursive: true });
+                        const workflowContent = `name: API Governance
 on:
   pull_request:
     paths:
@@ -1045,27 +1119,81 @@ jobs:
           new_spec: ${specPath}
           mode: advisory
 `;
-                    fs.writeFileSync(workflowFile, workflowContent);
-                    console.log(chalk.green(`  Created .github/workflows/api-governance.yml\n`));
-                } catch (err) {
-                    console.log(chalk.yellow(`  Could not write workflow file: ${err.message}`));
-                    console.log(chalk.bold('  Add this to .github/workflows/api-governance.yml manually (shown above)\n'));
+                        fs.writeFileSync(workflowFile, workflowContent);
+                        console.log(chalk.green('  Created .github/workflows/api-governance.yml'));
+                    } catch (err) {
+                        console.log(chalk.yellow(`  Could not write workflow: ${err.message}`));
+                    }
                 }
             } else {
-                console.log(chalk.yellow('  .github/workflows/api-governance.yml already exists — skipped\n'));
+                console.log(chalk.gray('  .github/workflows/api-governance.yml already exists'));
             }
-        } else {
-            console.log('  No OpenAPI spec file detected.');
-            console.log(`  Delimit also supports ${chalk.bold('Zero-Spec Mode')} — run ${chalk.bold('delimit lint')} in a FastAPI/NestJS/Express project.`);
-            console.log('');
         }
 
-        console.log(`  ${chalk.bold('Presets')}: strict | default | relaxed`);
-        console.log(`  Switch: ${chalk.bold('delimit init --preset strict')}\n`);
-        console.log('Next steps:');
-        console.log(`  ${chalk.bold('delimit lint')} old.yaml new.yaml   — check for breaking changes`);
-        console.log(`  ${chalk.bold('delimit diff')} old.yaml new.yaml   — see all changes`);
-        console.log(`  ${chalk.bold('delimit explain')} old.yaml new.yaml — human-readable summary`);
+        // Step 5: Run first lint to show immediate value
+        console.log('');
+        if (specPath) {
+            console.log(chalk.bold('  Running first lint...'));
+            try {
+                const result = apiEngine.lint(
+                    path.join(projectDir, specPath),
+                    path.join(projectDir, specPath),
+                    { policy: preset }
+                );
+                if (result && result.summary) {
+                    const s = result.summary;
+                    const breaking = s.breaking || 0;
+                    const warnings = s.warnings || 0;
+                    const safe = s.safe || s.non_breaking || 0;
+                    if (breaking === 0 && warnings === 0) {
+                        console.log(chalk.green('  PASS — No breaking changes detected'));
+                    } else if (breaking > 0) {
+                        console.log(chalk.red(`  FAIL — ${breaking} breaking change(s), ${warnings} warning(s)`));
+                    } else {
+                        console.log(chalk.yellow(`  WARN — ${warnings} warning(s)`));
+                    }
+                    if (result.paths_analyzed) {
+                        console.log(chalk.gray(`  Analyzed ${result.paths_analyzed} endpoint(s)`));
+                    }
+                } else {
+                    console.log(chalk.green('  Spec validated successfully'));
+                }
+            } catch (err) {
+                // Lint comparing same file = no changes, which is expected
+                console.log(chalk.green('  Spec validated — baseline set'));
+            }
+        } else if (['fastapi', 'nestjs', 'express'].includes(framework)) {
+            console.log(chalk.bold('  Running Zero-Spec lint...'));
+            try {
+                const zeroResult = apiEngine.zeroSpec(projectDir);
+                if (zeroResult && zeroResult.success) {
+                    console.log(chalk.green(`  Extracted: ${zeroResult.paths_count} paths, ${zeroResult.schemas_count} schemas`));
+                    // Save baseline
+                    const baselinePath = path.join(configDir, 'baseline.yaml');
+                    if (!fs.existsSync(baselinePath)) {
+                        fs.writeFileSync(baselinePath, yaml.dump(zeroResult.spec));
+                        console.log(chalk.green('  Saved baseline to .delimit/baseline.yaml'));
+                    }
+                } else {
+                    console.log(chalk.gray('  Zero-Spec extraction skipped — run `delimit lint` manually'));
+                }
+            } catch {
+                console.log(chalk.gray('  Zero-Spec extraction skipped — run `delimit lint` manually'));
+            }
+        }
+
+        // Summary
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        console.log(chalk.bold(`\n  Setup complete in ${elapsed}s\n`));
+        console.log('  Next steps:');
+        if (specPath) {
+            console.log(`    ${chalk.bold('delimit lint')} ${specPath} ${specPath}  — lint on every PR`);
+        } else {
+            console.log(`    ${chalk.bold('delimit lint')}                           — zero-spec mode`);
+        }
+        console.log(`    ${chalk.bold('delimit doctor')}                         — verify setup`);
+        console.log(`    ${chalk.bold('delimit explain')}                        — human-readable report`);
+        console.log('');
     });
 
 // Doctor command — verify setup is correct

package/gateway/ai/rate_limiter.py

@@ -0,0 +1,568 @@
+"""
+Delimit MCP Rate Limiter — per-tool call limits and session cost controls.
+
+Provides sliding-window rate limiting and cumulative cost tracking for all
+MCP tools. Designed to prevent runaway agent loops from burning through
+expensive API calls.
+
+Configuration:
+    ~/.delimit/rate_limits.yml — per-tool overrides
+    Defaults: 100 calls/hr (free), 20 calls/hr (Pro), 5 calls/hr (deliberation)
+
+Usage:
+    from ai.rate_limiter import limiter
+
+    block = limiter.check("delimit_lint")
+    if block:
+        return block  # contains error message + wait hint
+    # ... execute tool ...
+    limiter.record("delimit_lint", cost=0.001)
+"""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("delimit.rate_limiter")
+
+# ---------------------------------------------------------------------------
+#  Tool tier classification
+# ---------------------------------------------------------------------------
+
+# Tools that invoke multi-model deliberation (most expensive)
+DELIBERATION_TOOLS = frozenset({
+    "delimit_deliberate",
+    "delimit_security_deliberate",
+})
+
+# Pro tools that do significant computation but aren't deliberation
+# Mirrors the PRO_TOOLS set from ai/license.py
+PRO_TOOLS = frozenset({
+    "delimit_gov_evaluate", "delimit_gov_policy", "delimit_gov_run",
+    "delimit_gov_verify", "delimit_gov_new_task",
+    "delimit_os_plan", "delimit_os_status", "delimit_os_gates",
+    "delimit_deploy_plan", "delimit_deploy_build", "delimit_deploy_publish",
+    "delimit_deploy_verify", "delimit_deploy_rollback", "delimit_deploy_status",
+    "delimit_deploy_site", "delimit_deploy_npm",
+    "delimit_memory_search",
+    "delimit_vault_search", "delimit_vault_snapshot", "delimit_vault_health",
+    "delimit_evidence_collect", "delimit_evidence_verify",
+    "delimit_models",
+    "delimit_security_ingest",
+    "delimit_obs_metrics", "delimit_obs_logs", "delimit_obs_status",
+    "delimit_release_plan", "delimit_release_status", "delimit_release_sync",
+    "delimit_cost_analyze", "delimit_cost_optimize", "delimit_cost_alert",
+    "delimit_social_post", "delimit_social_generate", "delimit_social_history",
+    "delimit_repo_analyze", "delimit_repo_config_audit",
+    "delimit_repo_config_validate", "delimit_repo_diagnose",
+    "delimit_test_coverage",
+    "delimit_screen_record", "delimit_screenshot",
+    "delimit_notify",
+    "delimit_agent_dispatch", "delimit_agent_status",
+    "delimit_agent_complete", "delimit_agent_handoff",
+})
+
+# Per-tool cost estimates (USD).  Tools not listed default to 0.
+DEFAULT_COST_ESTIMATES: Dict[str, float] = {
+    # Deliberation — multiple LLM calls
+    "delimit_deliberate": 0.01,
+    "delimit_security_deliberate": 0.01,
+    # Lint / diff / semver — local computation, minimal cost
+    "delimit_lint": 0.001,
+    "delimit_diff": 0.001,
+    "delimit_semver": 0.001,
+    # Deploy actions — infrastructure cost
+    "delimit_deploy_publish": 0.005,
+    "delimit_deploy_build": 0.003,
+    "delimit_deploy_site": 0.005,
+    "delimit_deploy_npm": 0.005,
+    # Agent dispatch — orchestrates sub-agents
+    "delimit_agent_dispatch": 0.008,
+    # Social posting — API calls to external services
+    "delimit_social_post": 0.002,
+    "delimit_social_generate": 0.003,
+    # Screen recording / screenshots — browser automation
+    "delimit_screen_record": 0.005,
+    "delimit_screenshot": 0.002,
+    # Everything else is effectively free (local computation)
+}
+
+# Default hourly limits by tier
+DEFAULT_LIMIT_FREE = 100
+DEFAULT_LIMIT_PRO = 20
+DEFAULT_LIMIT_DELIBERATION = 5
+
+# Session cost cap
+DEFAULT_SESSION_COST_CAP = 5.0
+
+# Warning threshold (fraction of limit used before emitting a warning)
+WARNING_THRESHOLD = 0.80
+
+# Sliding window duration in seconds (1 hour)
+WINDOW_SECONDS = 3600
+
+
+def _classify_tool(tool_name: str) -> str:
+    """Return the tier for a tool: 'deliberation', 'pro', or 'free'."""
+    if tool_name in DELIBERATION_TOOLS:
+        return "deliberation"
+    if tool_name in PRO_TOOLS:
+        return "pro"
+    return "free"
+
+
+def _default_limit_for(tool_name: str) -> int:
+    """Return the default hourly call limit based on tool tier."""
+    tier = _classify_tool(tool_name)
+    if tier == "deliberation":
+        return DEFAULT_LIMIT_DELIBERATION
+    if tier == "pro":
+        return DEFAULT_LIMIT_PRO
+    return DEFAULT_LIMIT_FREE
+
+
+def _load_config(config_path: Optional[Path] = None) -> Dict[str, Any]:
+    """Load rate limit overrides from YAML config.
+
+    Returns a dict with optional keys:
+        session_cost_cap: float
+        tools: {tool_name: {limit: int, cost: float}}
+        tiers: {free: int, pro: int, deliberation: int}
+    """
+    if config_path is None:
+        config_path = Path.home() / ".delimit" / "rate_limits.yml"
+
+    if not config_path.exists():
+        return {}
+
+    try:
+        # Use PyYAML if available; fall back to a simple parser
+        try:
+            import yaml
+            with open(config_path) as f:
+                data = yaml.safe_load(f)
+            return data if isinstance(data, dict) else {}
+        except ImportError:
+            return _parse_simple_yaml(config_path)
+    except Exception as exc:
+        logger.warning("Failed to load rate_limits.yml: %s", exc)
+        return {}
+
+
+def _parse_simple_yaml(path: Path) -> Dict[str, Any]:
+    """Minimal YAML-subset parser for flat key-value and one level of nesting.
+
+    Handles the structure we actually emit in the default config file without
+    requiring PyYAML as a hard dependency.
+    """
+    result: Dict[str, Any] = {}
+    current_section: Optional[str] = None
+    current_dict: Dict[str, Any] = {}
+
+    for raw_line in path.read_text().splitlines():
+        # Strip comments
+        line = raw_line.split("#")[0].rstrip()
+        if not line or not line.strip():
+            continue
+
+        indent = len(line) - len(line.lstrip())
+        stripped = line.strip()
+
+        if stripped.startswith("-"):
+            continue  # skip list items for now
+
+        if ":" not in stripped:
+            continue
+
+        key, _, val = stripped.partition(":")
+        key = key.strip()
+        val = val.strip()
+
+        if indent == 0:
+            # Top-level key
+            if current_section and current_dict:
+                result[current_section] = current_dict
+                current_dict = {}
+            if val:
+                result[key] = _coerce_value(val)
+                current_section = None
+            else:
+                current_section = key
+                current_dict = {}
+        elif indent >= 2 and current_section:
+            if val:
+                current_dict[key] = _coerce_value(val)
+            else:
+                # Nested dict (two levels deep) — store sub-dict
+                current_dict[key] = {}
+
+    if current_section and current_dict:
+        result[current_section] = current_dict
+
+    return result
+
+
+def _coerce_value(val: str) -> Any:
+    """Coerce a YAML scalar string to int, float, or str."""
+    if not val:
+        return val
+    # Remove quotes
+    if (val.startswith('"') and val.endswith('"')) or \
+       (val.startswith("'") and val.endswith("'")):
+        return val[1:-1]
+    try:
+        return int(val)
+    except ValueError:
+        pass
+    try:
+        return float(val)
+    except ValueError:
+        pass
+    if val.lower() in ("true", "yes"):
+        return True
+    if val.lower() in ("false", "no"):
+        return False
+    return val
+
+
+class RateLimiter:
+    """Per-tool sliding-window rate limiter with session cost tracking.
+
+    Thread-safety: NOT thread-safe.  MCP servers are single-threaded per
+    session, so this is fine.  If that changes, add a lock.
+    """
+
+    def __init__(self, config_path: Optional[Path] = None):
+        # {tool_name: [timestamp, timestamp, ...]}  — sorted ascending
+        self._calls: Dict[str, List[float]] = {}
+        # {tool_name: float}  — cumulative cost per tool this session
+        self._costs: Dict[str, float] = {}
+        # Total session cost
+        self._session_cost: float = 0.0
+        # Session start time
+        self._session_start: float = time.time()
+        # Load config
+        self._config = _load_config(config_path)
+        self._custom_limits: Dict[str, int] = {}
+        self._load_custom_limits()
+
+    def _load_custom_limits(self) -> None:
+        """Extract per-tool limit overrides from the config."""
+        # Tier-level overrides
+        tiers = self._config.get("tiers", {})
+        if isinstance(tiers, dict):
+            self._tier_overrides = {
+                "free": int(tiers["free"]) if "free" in tiers else None,
+                "pro": int(tiers["pro"]) if "pro" in tiers else None,
+                "deliberation": int(tiers["deliberation"]) if "deliberation" in tiers else None,
+            }
+        else:
+            self._tier_overrides = {}
+
+        # Per-tool overrides
+        tools = self._config.get("tools", {})
+        if isinstance(tools, dict):
+            for tool_name, settings in tools.items():
+                if isinstance(settings, dict) and "limit" in settings:
+                    self._custom_limits[tool_name] = int(settings["limit"])
+                elif isinstance(settings, (int, float)):
+                    self._custom_limits[tool_name] = int(settings)
+
+    @property
+    def session_cost_cap(self) -> float:
+        """The maximum cost allowed per session."""
+        cap = self._config.get("session_cost_cap")
+        if cap is not None:
+            try:
+                return float(cap)
+            except (TypeError, ValueError):
+                pass
+        return DEFAULT_SESSION_COST_CAP
+
+    def _get_limit(self, tool_name: str) -> int:
+        """Resolve the effective hourly limit for a tool."""
+        # Per-tool override takes priority
+        if tool_name in self._custom_limits:
+            return self._custom_limits[tool_name]
+
+        # Tier override
+        tier = _classify_tool(tool_name)
+        tier_override = getattr(self, "_tier_overrides", {}).get(tier)
+        if tier_override is not None:
+            return tier_override
+
+        return _default_limit_for(tool_name)
+
+    def _get_cost_estimate(self, tool_name: str) -> float:
+        """Return the estimated cost per call for a tool."""
+        # Config override
+        tools = self._config.get("tools", {})
+        if isinstance(tools, dict) and tool_name in tools:
+            settings = tools[tool_name]
+            if isinstance(settings, dict) and "cost" in settings:
+                return float(settings["cost"])
+
+        return DEFAULT_COST_ESTIMATES.get(tool_name, 0.0)
+
+    def _prune_window(self, tool_name: str, now: float) -> List[float]:
+        """Remove call timestamps outside the sliding window, return remaining."""
+        if tool_name not in self._calls:
+            return []
+        cutoff = now - WINDOW_SECONDS
+        calls = self._calls[tool_name]
+        # Binary-ish prune: find first index >= cutoff
+        pruned = [t for t in calls if t >= cutoff]
+        self._calls[tool_name] = pruned
+        return pruned
+
+    def check(self, tool_name: str) -> Optional[Dict[str, Any]]:
+        """Check if calling tool_name is allowed right now.
+
+        Returns None if the call is permitted.
+        Returns an error dict if the call should be blocked.
+        """
+        now = time.time()
+
+        # 1. Session cost cap
+        if self._session_cost >= self.session_cost_cap:
+            return {
+                "error": "session_cost_exceeded",
+                "message": (
+                    f"Session cost cap reached (${self._session_cost:.3f} / "
+                    f"${self.session_cost_cap:.2f}). "
+                    "To continue, increase the cap in ~/.delimit/rate_limits.yml "
+                    "or call delimit_cost_controls to adjust."
+                ),
+                "session_cost": round(self._session_cost, 4),
+                "session_cost_cap": self.session_cost_cap,
+            }
+
+        # 2. Per-tool rate limit
+        recent = self._prune_window(tool_name, now)
+        limit = self._get_limit(tool_name)
+        count = len(recent)
+
+        if count >= limit:
+            # Calculate when the oldest call in the window will expire
+            oldest = recent[0] if recent else now
+            wait_seconds = int(oldest + WINDOW_SECONDS - now) + 1
+            wait_minutes = max(1, wait_seconds // 60)
+            tier = _classify_tool(tool_name)
+            return {
+                "error": "rate_limit_exceeded",
+                "message": (
+                    f"Rate limit exceeded for '{tool_name}': "
+                    f"{count}/{limit} calls/hour ({tier} tier). "
+                    f"Try again in ~{wait_minutes} minute(s), or increase the "
+                    f"limit in ~/.delimit/rate_limits.yml"
+                ),
+                "tool": tool_name,
+                "tier": tier,
+                "calls_used": count,
+                "calls_limit": limit,
+                "retry_after_seconds": wait_seconds,
+            }
+
+        # 3. Prospective cost check — would this call push us over?
+        estimated_cost = self._get_cost_estimate(tool_name)
+        if estimated_cost > 0 and (self._session_cost + estimated_cost) > self.session_cost_cap:
+            return {
+                "error": "session_cost_would_exceed",
+                "message": (
+                    f"Executing '{tool_name}' (~${estimated_cost:.4f}) would "
+                    f"exceed the session cost cap "
+                    f"(${self._session_cost:.3f} + ${estimated_cost:.4f} > "
+                    f"${self.session_cost_cap:.2f}). "
+                    "Increase session_cost_cap in ~/.delimit/rate_limits.yml "
+                    "or call delimit_cost_controls to adjust."
+                ),
+                "tool": tool_name,
+                "estimated_cost": estimated_cost,
+                "session_cost": round(self._session_cost, 4),
+                "session_cost_cap": self.session_cost_cap,
+            }
+
+        # 4. Warning at 80% usage
+        if count >= int(limit * WARNING_THRESHOLD) and count < limit:
+            remaining = limit - count
+            logger.warning(
+                "Rate limit warning: '%s' at %d/%d calls/hour (%d remaining)",
+                tool_name, count, limit, remaining,
+            )
+
+        return None  # Allowed
+
+    def record(self, tool_name: str, cost: Optional[float] = None) -> None:
+        """Record a tool call and its cost.
+
+        Args:
+            tool_name: The MCP tool that was called.
+            cost: Actual cost in USD.  If None, uses the default estimate.
+        """
+        now = time.time()
+
+        # Record timestamp
+        if tool_name not in self._calls:
+            self._calls[tool_name] = []
+        self._calls[tool_name].append(now)
+
+        # Record cost
+        if cost is None:
+            cost = self._get_cost_estimate(tool_name)
+        if cost > 0:
+            self._costs[tool_name] = self._costs.get(tool_name, 0.0) + cost
+            self._session_cost += cost
+
+        # Log periodic warnings
+        recent = self._prune_window(tool_name, now)
+        limit = self._get_limit(tool_name)
+        if len(recent) == int(limit * WARNING_THRESHOLD):
+            logger.warning(
+                "Rate limit 80%% reached for '%s': %d/%d calls this hour",
+                tool_name, len(recent), limit,
+            )
+
+    def get_usage(self) -> Dict[str, Any]:
+        """Return current session usage summary.
+
+        Returns a dict with:
+            session_cost: total cost this session
+            session_cost_cap: the configured cap
+            session_duration_seconds: how long the session has been active
+            tools: {tool_name: {calls_this_hour, limit, cost, tier, remaining}}
+        """
+        now = time.time()
+        tools_usage: Dict[str, Dict[str, Any]] = {}
+
+        # Collect all tools that have been called
+        all_tools = set(self._calls.keys()) | set(self._costs.keys())
+
+        for tool_name in sorted(all_tools):
+            recent = self._prune_window(tool_name, now)
+            limit = self._get_limit(tool_name)
+            count = len(recent)
+            tools_usage[tool_name] = {
+                "calls_this_hour": count,
+                "limit": limit,
+                "remaining": max(0, limit - count),
+                "cost_this_session": round(self._costs.get(tool_name, 0.0), 6),
+                "cost_per_call": self._get_cost_estimate(tool_name),
+                "tier": _classify_tool(tool_name),
+            }
+
+        return {
+            "session_cost": round(self._session_cost, 4),
+            "session_cost_cap": self.session_cost_cap,
+            "session_cost_remaining": round(
+                max(0, self.session_cost_cap - self._session_cost), 4
+            ),
+            "session_duration_seconds": int(now - self._session_start),
+            "tools": tools_usage,
+        }
+
+    def get_quota(self, tool_name: str) -> Dict[str, Any]:
+        """Return quota info for a single tool."""
+        now = time.time()
+        recent = self._prune_window(tool_name, now)
+        limit = self._get_limit(tool_name)
+        count = len(recent)
+        return {
+            "tool": tool_name,
+            "tier": _classify_tool(tool_name),
+            "calls_this_hour": count,
+            "limit": limit,
+            "remaining": max(0, limit - count),
+            "cost_this_session": round(self._costs.get(tool_name, 0.0), 6),
+            "cost_per_call": self._get_cost_estimate(tool_name),
+        }
+
+    def set_limit(self, tool_name: str, limit: int) -> None:
+        """Override the hourly limit for a tool (session-scoped, not persisted)."""
+        if limit < 0:
+            raise ValueError("Limit must be non-negative")
+        self._custom_limits[tool_name] = limit
+        logger.info("Rate limit for '%s' set to %d calls/hour", tool_name, limit)
+
+    def set_session_cost_cap(self, cap: float) -> None:
+        """Override the session cost cap (session-scoped, not persisted)."""
+        if cap < 0:
+            raise ValueError("Cost cap must be non-negative")
+        self._config["session_cost_cap"] = cap
+        logger.info("Session cost cap set to $%.2f", cap)
+
+    def reset(self) -> None:
+        """Reset all tracking state. Starts a fresh session."""
+        self._calls.clear()
+        self._costs.clear()
+        self._session_cost = 0.0
+        self._session_start = time.time()
+        logger.info("Rate limiter reset — new session started")
+
+    def reset_tool(self, tool_name: str) -> None:
+        """Reset tracking for a single tool."""
+        self._calls.pop(tool_name, None)
+        cost = self._costs.pop(tool_name, 0.0)
+        self._session_cost = max(0, self._session_cost - cost)
+        logger.info("Rate limiter reset for '%s'", tool_name)
+
+
+# ---------------------------------------------------------------------------
+#  Module-level singleton
+# ---------------------------------------------------------------------------
+
+limiter = RateLimiter()
+
+
+def create_cost_controls_response(
+    action: str = "status",
+    tool_name: str = "",
+    limit: Optional[int] = None,
+    cost_cap: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Handler logic for the delimit_cost_controls MCP tool.
+
+    Actions:
+        status  — show full session usage
+        quota   — show quota for a specific tool
+        set     — set a custom limit for a tool or session cost cap
+        reset   — reset all tracking
+    """
+    if action == "status":
+        return {
+            "status": "ok",
+            **limiter.get_usage(),
+            "hint": (
+                "Use action='quota' with tool_name to check a specific tool, "
+                "or action='set' to adjust limits."
+            ),
+        }
+
+    if action == "quota":
+        if not tool_name:
+            return {"error": "tool_name is required for action='quota'"}
+        return {"status": "ok", **limiter.get_quota(tool_name)}
+
+    if action == "set":
+        changes = []
+        if tool_name and limit is not None:
+            limiter.set_limit(tool_name, limit)
+            changes.append(f"{tool_name} limit set to {limit}/hour")
+        if cost_cap is not None:
+            limiter.set_session_cost_cap(cost_cap)
+            changes.append(f"session cost cap set to ${cost_cap:.2f}")
+        if not changes:
+            return {
+                "error": "Provide tool_name+limit to set a tool limit, "
+                "or cost_cap to set the session cost cap."
+            }
+        return {"status": "ok", "changes": changes}
+
+    if action == "reset":
+        limiter.reset()
+        return {"status": "ok", "message": "All rate limit tracking reset."}
+
+    return {
+        "error": f"Unknown action '{action}'",
+        "valid_actions": ["status", "quota", "set", "reset"],
+    }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
   "mcpName": "io.github.delimit-ai/delimit-mcp-server",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "description": "Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.",
   "main": "index.js",
   "files": [