@veda-hq/sarathi 0.5.6 → 0.5.7

package/README.md

@@ -71,6 +71,22 @@ sarathi for every event the list names, with a matcher that lets every
 handler fire and a timeout at least the longest handler's. Run it in the
 project's tests.
 
+### Forbidden variables
+
+Some switches turn a session's tooling off from the environment, where no
+committed file can see them: `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` turns the
+advisor off whatever the settings say. The hook list's top-level `forbidEnv`
+names each such variable with why:
+
+```json
+{ "forbidEnv": { "CLAUDE_CODE_DISABLE_ADVISOR_TOOL": "this project works with the advisor on" } }
+```
+
+While one is set (anything but empty, `0` or `false`), `sarathi hook` refuses
+every `PreToolUse` call before any handler runs, and at `SessionStart` and
+`UserPromptSubmit` tells both Claude and the user why and how to fix it. Other
+events are left alone. It acts only on events the settings route to sarathi.
+
 ## The plugin
 
 `sarathi@veda`, from this repository's marketplace, carries two agents:

package/dist/cli.js

@@ -9,10 +9,10 @@
  */
 import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ConfigError, compileMatcher, entriesFor, loadConfig, longestTimeout, settingsMatcher } from './config.js';
+import { ConfigError, compileMatcher, entriesFor, forbiddenSet, loadConfig, longestTimeout, settingsMatcher } from './config.js';
 import { merge } from './merge.js';
 import { runAll } from './run.js';
-export const VERSION = '0.5.6';
+export const VERSION = '0.5.7';
 const USAGE = `usage: sarathi hook <Event> [--config <file>]
        sarathi check [--config <file>] [--settings <file>]
        sarathi --version
@@ -61,6 +61,31 @@ export function matchTarget(event) {
     }
     return '';
 }
+/** Events where a forbidden variable is told to the session and the user. */
+const WARNED_EVENTS = new Set(['SessionStart', 'UserPromptSubmit']);
+/**
+ * What sarathi answers, beside the handlers, when the session sets a variable
+ * the project forbids: PreToolUse refuses, SessionStart and UserPromptSubmit
+ * warn both Claude and the user, other events say nothing.
+ */
+export function forbidOutcome(event, set) {
+    if (set.length === 0)
+        return undefined;
+    const lines = set.map(([name, why]) => `${name} is set, and this project forbids it: ${why}`);
+    const fix = `Unset ${set.map(([name]) => name).join(' and ')} and start a new session; until then sarathi refuses every tool call.`;
+    const base = { label: 'sarathi forbidEnv', timedOut: false, failClosed: true };
+    if (GUARDED_EVENTS.has(event))
+        return { ...base, code: 2, stdout: '', stderr: `BLOCKED: sarathi: ${lines.join('; ')}. ${fix}\n` };
+    if (!WARNED_EVENTS.has(event))
+        return undefined;
+    const message = `sarathi: ${lines.join('; ')}. ${fix}`;
+    return {
+        ...base,
+        code: 0,
+        stdout: JSON.stringify({ systemMessage: message, hookSpecificOutput: { hookEventName: event, additionalContext: message } }),
+        stderr: '',
+    };
+}
 async function hook(io, options) {
     const event = options.positional[1];
     if (event === undefined || options.positional.length > 2) {
@@ -89,11 +114,19 @@ async function hook(io, options) {
         io.err(`${refuse ? 'BLOCKED: ' : ''}sarathi cannot use its hook list: ${message}. No ${event} handler ran.\n`);
         return refuse ? 2 : 1;
     }
+    const forbidden = forbidOutcome(event, forbiddenSet(config, io.env));
+    if (forbidden?.code === 2) {
+        io.err(forbidden.stderr);
+        return 2;
+    }
     const entries = entriesFor(config, event, matchTarget(parsed));
-    if (entries.length === 0)
+    if (entries.length === 0 && forbidden === undefined)
         return 0;
-    const outcomes = await (io.run ?? runAll)(entries, config, input, io.cwd);
-    const answer = merge(event, outcomes);
+    const outcomes = entries.length === 0 ? [] : await (io.run ?? runAll)(entries, config, input, io.cwd);
+    const merged = merge(event, forbidden === undefined ? outcomes : [forbidden, ...outcomes]);
+    // A handler that blocks drops every JSON answer, the warning among them; keep it in the reason.
+    const warning = forbidden === undefined ? undefined : JSON.parse(forbidden.stdout).systemMessage;
+    const answer = merged.code === 2 && warning !== undefined ? { ...merged, stderr: `${warning}\n${merged.stderr}` } : merged;
     if (answer.stdout !== '')
         io.out(answer.stdout);
     if (answer.stderr !== '')

package/dist/config.js

@@ -10,7 +10,8 @@ import { readFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 export const DEFAULT_TIMEOUT_SECONDS = 60;
 const ENTRY_KEYS = new Set(['matcher', 'command', 'guard', 'timeout', 'failClosed']);
-const TOP_KEYS = new Set(['$schema', 'kavach', 'hooks']);
+const TOP_KEYS = new Set(['$schema', 'kavach', 'hooks', 'forbidEnv']);
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const KAVACH_KEYS = new Set(['config', 'python']);
 const PLAIN = /^[\w|-]+$/;
 export class ConfigError extends Error {
@@ -103,8 +104,23 @@ export function parseConfig(text, path, root) {
             throw new ConfigError(`${path} ${event}: must be a list of entries`);
         hooks[event] = list.map((entry, index) => parseEntry(entry, `${path} ${event}[${index}]`));
     }
+    // Only an absent key means none: `null` is malformed, not empty.
+    const forbidRaw = Object.hasOwn(raw, 'forbidEnv') ? raw.forbidEnv : {};
+    if (!isRecord(forbidRaw))
+        throw new ConfigError(`${path}: "forbidEnv" must be an object of variable names`);
+    const forbidden = [];
+    for (const [name, why] of Object.entries(forbidRaw)) {
+        if (!ENV_NAME.test(name))
+            throw new ConfigError(`${path} forbidEnv: "${name}" is not an environment variable name`);
+        if (typeof why !== 'string' || why.trim() === '')
+            throw new ConfigError(`${path} forbidEnv ${name}: give why it is forbidden`);
+        forbidden.push([name, why]);
+    }
+    // fromEntries defines own properties, so a name like `__proto__` is kept, not sent to the prototype setter.
+    const forbidEnv = Object.fromEntries(forbidden);
     const fromRoot = (value) => (isAbsolute(value) ? value : resolve(root, value));
     return {
+        forbidEnv,
         path,
         root,
         kavach: {
@@ -145,6 +161,18 @@ export function settingsMatcher(config, event) {
     }
     return [...names].sort().join('|');
 }
+/** Is a variable set, as a switch reads it? Absent, empty, `0` and `false` are off. */
+export function isOn(value) {
+    return value !== undefined && !['', '0', 'false'].includes(value.trim().toLowerCase());
+}
+/** The forbidden variables `env` sets, each with why. */
+export function forbiddenSet(config, env) {
+    // Only the environment's own string values: `toString` is a legal name an unset variable must not inherit.
+    return Object.entries(config.forbidEnv).filter(([name]) => {
+        const value = Object.hasOwn(env, name) ? env[name] : undefined;
+        return typeof value === 'string' && isOn(value);
+    });
+}
 /** The longest timeout among an event's entries, in seconds. */
 export function longestTimeout(config, event) {
     return Math.max(0, ...(config.hooks[event] ?? []).map(entry => entry.timeout ?? DEFAULT_TIMEOUT_SECONDS));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/sarathi",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Runs a project's Claude Code hooks from one entry per event, with kavach's guards built in, and carries the sarathi plugin's agents.",
   "keywords": [
     "coding agents",