@veda-hq/sarathi 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veda Authors
+
+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,85 @@
-# Temporary Holding Version
+# @veda-hq/sarathi
 
-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.
+सारथि, charioteer. Runs a project's Claude Code hooks from one settings entry
+per event, with [kavach](../kavach)'s guards built in, and carries the
+sarathi plugin's agents. Part of [Veda](https://github.com/veda-hq/veda).
+
+## Why a package and not only a plugin
+
+A Claude Code plugin cannot carry permissions or environment (a plugin's
+settings apply only `agent` and `subagentStatusLine`), and a cloud session
+does not install the plugins a repository lists, because that needs the
+folder-trust dialog a cloud session never shows. A pinned package installs
+wherever the repository's dependencies do: a laptop, a cloud session, a second
+repository. So the hooks run from the package, and the plugin carries what
+only a plugin can: the agents.
+
+## The hooks
+
+The project's settings keep one entry per event that runs sarathi:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash|Edit|Write|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "npx --no-install sarathi hook PreToolUse", "timeout": 70 }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "npx --no-install sarathi hook Stop", "timeout": 130 }] }
+    ]
+  }
+}
+```
+
+and the handlers live in `.claude/sarathi.json`, in the shape of the
+settings' own `hooks` block, one entry per handler:
+
+```json
+{
+  "kavach": { "config": ".claude/kavach.json", "python": "python3" },
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash|Edit|Write|NotebookEdit", "guard": "worktree" },
+      { "matcher": "Bash", "guard": "command" },
+      { "matcher": "Edit|Write", "command": "./scripts/check-edit.sh", "timeout": 10 }
+    ],
+    "Stop": [{ "command": "./scripts/keep-going.sh", "timeout": 120 }]
+  }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `matcher` | Claude Code's: absent or `*` for all, `A\|B` for exact names, else a regular expression |
+| `command` | Run through `sh -c` with the event on stdin, as Claude Code runs a hook |
+| `guard` | `worktree` or `command`: kavach's guard, run by `kavach.python` with `KAVACH_CONFIG` set to `kavach.config` |
+| `timeout` | Seconds before the handler and its children are stopped (60) |
+| `failClosed` | Any end but exit 0 refuses the call; always true for guards |
+
+`sarathi hook <Event>` runs the matching handlers side by side and answers
+Claude Code once, as Claude Code combines several hooks' answers: any exit 2
+blocks with every blocker's reason; a fail-closed handler that crashes or
+runs out of time blocks too; JSON answers merge with the strictest decision
+winning (deny over ask over allow, block over none, `continue: false` over
+true) and every handler's context kept; a handler that failed without
+blocking is named in `systemMessage`, or on stderr with exit 1. A hook list
+that cannot be read refuses `PreToolUse` and only warns on other events.
+
+`sarathi check --settings .claude/settings.json` proves the settings run
+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.
+
+## The plugin
+
+`sarathi@veda`, from this repository's marketplace, carries two agents:
+`sarathi:worker` (carries out one decided task end to end) and
+`sarathi:researcher` (answers an external question with sources, read-only).
+
+```sh
+claude plugin marketplace add veda-hq/veda
+claude plugin install sarathi@veda
+```
+
+Node 24 or later. MIT.

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+};
+process.exitCode = await main({
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    readStdin,
+    out: text => process.stdout.write(text),
+    err: text => process.stderr.write(text),
+});

package/dist/cli.js

@@ -0,0 +1,227 @@
+/**
+ * `sarathi hook <Event>`: the one command a project's Claude Code settings run
+ * per event. It reads the event on stdin, runs the project's handlers for it
+ * (`.claude/sarathi.json`), and gives Claude Code their combined answer.
+ *
+ * `sarathi check`: validates the hook list, and with `--settings` that the
+ * settings run sarathi for every event it lists, with a matcher and timeout
+ * that let every handler fire.
+ */
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ConfigError, compileMatcher, entriesFor, loadConfig, longestTimeout, settingsMatcher } from './config.js';
+import { merge } from './merge.js';
+import { runAll } from './run.js';
+export const VERSION = '0.4.0';
+const USAGE = `usage: sarathi hook <Event> [--config <file>]
+       sarathi check [--config <file>] [--settings <file>]
+       sarathi --version
+`;
+/** Events where a broken hook list must refuse the call rather than let it through unguarded. */
+const GUARDED_EVENTS = new Set(['PreToolUse']);
+function parseOptions(args) {
+    const positional = [];
+    let config;
+    let settings;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--config' || arg === '--settings') {
+            const value = args[index + 1];
+            if (value === undefined || value === '')
+                return `${arg} needs a file`;
+            if (arg === '--config')
+                config = value;
+            else
+                settings = value;
+            index += 1;
+        }
+        else if (arg.startsWith('--')) {
+            return `unknown option ${arg}`;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, ...(config === undefined ? {} : { config }), ...(settings === undefined ? {} : { settings }) };
+}
+function projectRoot(io) {
+    const dir = io.env.CLAUDE_PROJECT_DIR;
+    return dir === undefined || dir === '' ? io.cwd : dir;
+}
+function configPath(io, options) {
+    const root = projectRoot(io);
+    return options.config === undefined ? join(root, '.claude', 'sarathi.json') : resolve(io.cwd, options.config);
+}
+/** What an event's matchers are tested against: the tool, or the event's own matcher field. */
+export function matchTarget(event) {
+    for (const key of ['tool_name', 'source', 'trigger', 'notification_type', 'agent_type']) {
+        const value = event[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return '';
+}
+async function hook(io, options) {
+    const event = options.positional[1];
+    if (event === undefined || options.positional.length > 2) {
+        io.err(USAGE);
+        return 1;
+    }
+    const refuse = GUARDED_EVENTS.has(event);
+    const input = await io.readStdin();
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        io.err(`${refuse ? 'BLOCKED: ' : ''}sarathi: the ${event} event on stdin is not a JSON object, so no handler ran.\n`);
+        return refuse ? 2 : 1;
+    }
+    let config;
+    try {
+        config = loadConfig(configPath(io, options), projectRoot(io));
+    }
+    catch (error) {
+        const message = error instanceof ConfigError ? error.message : String(error);
+        io.err(`${refuse ? 'BLOCKED: ' : ''}sarathi cannot use its hook list: ${message}. No ${event} handler ran.\n`);
+        return refuse ? 2 : 1;
+    }
+    const entries = entriesFor(config, event, matchTarget(parsed));
+    if (entries.length === 0)
+        return 0;
+    const outcomes = await (io.run ?? runAll)(entries, config, input, io.cwd);
+    const answer = merge(event, outcomes);
+    if (answer.stdout !== '')
+        io.out(answer.stdout);
+    if (answer.stderr !== '')
+        io.err(answer.stderr);
+    return answer.code;
+}
+function settingsHooks(text, path) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return `${path} is not JSON`;
+    }
+    const found = new Map();
+    const hooks = raw?.hooks;
+    if (typeof hooks !== 'object' || hooks === null)
+        return found;
+    for (const [event, groups] of Object.entries(hooks)) {
+        const list = [];
+        for (const group of Array.isArray(groups) ? groups : []) {
+            const { matcher, hooks: inner } = (group ?? {});
+            for (const item of Array.isArray(inner) ? inner : []) {
+                const { command, timeout } = (item ?? {});
+                if (typeof command !== 'string')
+                    continue;
+                list.push({
+                    matcher: typeof matcher === 'string' ? matcher : undefined,
+                    command,
+                    timeout: typeof timeout === 'number' ? timeout : undefined,
+                });
+            }
+        }
+        found.set(event, list);
+    }
+    return found;
+}
+/**
+ * Does a settings command run sarathi for `event`? It names sarathi (the
+ * program, or a launcher script named after it) and passes the event as a
+ * word of its own: `sarathi hook Stop`, `"$DIR"/hooks/sarathi.sh Stop`.
+ */
+export function runsSarathiFor(command, event) {
+    return /\bsarathi\b/.test(command) && new RegExp(`(?:^|[\\s"'])${event}(?:$|[\\s"'])`).test(command);
+}
+/** The settings' problems in running `config`: a missing event, a matcher that hides a handler, a timeout shorter than one. */
+export function settingsProblems(config, settings) {
+    const problems = [];
+    for (const event of Object.keys(config.hooks)) {
+        if ((config.hooks[event] ?? []).length === 0)
+            continue;
+        const runner = (settings.get(event) ?? []).find(item => runsSarathiFor(item.command, event));
+        if (runner === undefined) {
+            problems.push(`${event}: no settings hook runs \`sarathi hook ${event}\``);
+            continue;
+        }
+        const needed = settingsMatcher(config, event);
+        const covers = compileMatcher(runner.matcher);
+        if (needed === undefined) {
+            if (runner.matcher !== undefined && runner.matcher !== '' && runner.matcher !== '*') {
+                problems.push(`${event}: a handler matches every tool, so the settings entry needs no matcher (has "${runner.matcher}")`);
+            }
+        }
+        else {
+            const hidden = needed.split('|').filter(name => name !== '' && !covers(name));
+            if (hidden.length > 0)
+                problems.push(`${event}: the settings matcher leaves out ${hidden.join(', ')}`);
+        }
+        const longest = longestTimeout(config, event);
+        if (runner.timeout === undefined || runner.timeout < longest) {
+            problems.push(`${event}: the settings timeout must be at least ${longest} s, the longest handler's (has ${runner.timeout ?? 'none'})`);
+        }
+    }
+    return problems;
+}
+function check(io, options) {
+    if (options.positional.length > 1) {
+        io.err(USAGE);
+        return 1;
+    }
+    let config;
+    try {
+        config = loadConfig(configPath(io, options), projectRoot(io));
+    }
+    catch (error) {
+        io.err(`sarathi: ${error instanceof ConfigError ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const counts = Object.entries(config.hooks).map(([event, list]) => `${event} ${list.length}`);
+    if (options.settings !== undefined) {
+        const path = resolve(io.cwd, options.settings);
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch {
+            io.err(`sarathi: cannot read ${path}\n`);
+            return 1;
+        }
+        const settings = settingsHooks(text, path);
+        if (typeof settings === 'string') {
+            io.err(`sarathi: ${settings}\n`);
+            return 1;
+        }
+        const problems = settingsProblems(config, settings);
+        if (problems.length > 0) {
+            io.err(problems.map(problem => `sarathi: ${problem}\n`).join(''));
+            return 1;
+        }
+    }
+    io.out(`sarathi: ${config.path} is valid (${counts.join(', ')})\n`);
+    return 0;
+}
+export async function main(io) {
+    if (io.argv.length === 1 && io.argv[0] === '--version') {
+        io.out(`${VERSION}\n`);
+        return 0;
+    }
+    const options = parseOptions(io.argv);
+    if (typeof options === 'string') {
+        io.err(`sarathi: ${options}\n${USAGE}`);
+        return 1;
+    }
+    const command = options.positional[0];
+    if (command === 'hook')
+        return hook(io, options);
+    if (command === 'check')
+        return check(io, options);
+    io.err(USAGE);
+    return 1;
+}

package/dist/config.js

@@ -0,0 +1,151 @@
+/**
+ * The project's hook list: which commands run on which Claude Code event.
+ *
+ * A project keeps one JSON file (by default `.claude/sarathi.json`) and one
+ * short entry per event in its Claude Code settings that runs
+ * `sarathi hook <Event>`. The file has the shape of the settings' own `hooks`
+ * block, flattened: each event lists entries, each entry one handler.
+ */
+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 KAVACH_KEYS = new Set(['config', 'python']);
+const PLAIN = /^[\w|-]+$/;
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, known, where) {
+    const extra = Object.keys(value).filter(key => !known.has(key));
+    if (extra.length > 0)
+        throw new ConfigError(`${where}: unknown key ${extra.map(key => `"${key}"`).join(', ')}`);
+}
+/** Claude Code's matcher rules: absent, empty or `*` match all; plain names and `A|B` match exactly; anything else is a regular expression. */
+export function compileMatcher(matcher, where = 'matcher') {
+    if (matcher === undefined || matcher === '' || matcher === '*')
+        return () => true;
+    if (PLAIN.test(matcher)) {
+        const names = new Set(matcher.split('|'));
+        return target => names.has(target);
+    }
+    let pattern;
+    try {
+        pattern = new RegExp(matcher);
+    }
+    catch (error) {
+        throw new ConfigError(`${where}: "matcher" is not a regular expression (${error.message})`);
+    }
+    return target => pattern.test(target);
+}
+function parseEntry(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where}: an entry must be an object`);
+    rejectUnknownKeys(raw, ENTRY_KEYS, where);
+    const { matcher, command, guard, timeout, failClosed } = raw;
+    if (matcher !== undefined && typeof matcher !== 'string')
+        throw new ConfigError(`${where}: "matcher" must be a string`);
+    if (command !== undefined && (typeof command !== 'string' || command.trim() === '')) {
+        throw new ConfigError(`${where}: "command" must be a non-empty string`);
+    }
+    if (guard !== undefined && guard !== 'worktree' && guard !== 'command') {
+        throw new ConfigError(`${where}: "guard" must be "worktree" or "command"`);
+    }
+    if ((command === undefined) === (guard === undefined)) {
+        throw new ConfigError(`${where}: give exactly one of "command" and "guard"`);
+    }
+    if (timeout !== undefined && (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0)) {
+        throw new ConfigError(`${where}: "timeout" must be a positive number of seconds`);
+    }
+    if (failClosed !== undefined && typeof failClosed !== 'boolean') {
+        throw new ConfigError(`${where}: "failClosed" must be true or false`);
+    }
+    if (typeof matcher === 'string')
+        compileMatcher(matcher, where);
+    return {
+        ...(typeof matcher === 'string' ? { matcher } : {}),
+        ...(typeof command === 'string' ? { command } : {}),
+        ...(guard === 'worktree' || guard === 'command' ? { guard } : {}),
+        ...(typeof timeout === 'number' ? { timeout } : {}),
+        ...(typeof failClosed === 'boolean' ? { failClosed } : {}),
+    };
+}
+/** Parses the file's text; `path` names it in errors, `root` is where its relative paths start. */
+export function parseConfig(text, path, root) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${path} is not JSON (${error.message})`);
+    }
+    if (!isRecord(raw))
+        throw new ConfigError(`${path}: the file must hold an object`);
+    rejectUnknownKeys(raw, TOP_KEYS, path);
+    const kavachRaw = raw.kavach ?? {};
+    if (!isRecord(kavachRaw))
+        throw new ConfigError(`${path}: "kavach" must be an object`);
+    rejectUnknownKeys(kavachRaw, KAVACH_KEYS, `${path} kavach`);
+    const { config, python } = kavachRaw;
+    if (config !== undefined && typeof config !== 'string')
+        throw new ConfigError(`${path}: "kavach.config" must be a path`);
+    if (python !== undefined && typeof python !== 'string')
+        throw new ConfigError(`${path}: "kavach.python" must be a program`);
+    const hooksRaw = raw.hooks;
+    if (!isRecord(hooksRaw))
+        throw new ConfigError(`${path}: "hooks" must be an object of events`);
+    const hooks = {};
+    for (const [event, list] of Object.entries(hooksRaw)) {
+        if (!Array.isArray(list))
+            throw new ConfigError(`${path} ${event}: must be a list of entries`);
+        hooks[event] = list.map((entry, index) => parseEntry(entry, `${path} ${event}[${index}]`));
+    }
+    const fromRoot = (value) => (isAbsolute(value) ? value : resolve(root, value));
+    return {
+        path,
+        root,
+        kavach: {
+            ...(typeof config === 'string' ? { config: fromRoot(config) } : {}),
+            python: typeof python !== 'string' ? 'python3' : python.includes('/') ? fromRoot(python) : python,
+        },
+        hooks,
+    };
+}
+/** Reads the file at `path`; relative paths in it resolve from `root`. */
+export function loadConfig(path, root) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new ConfigError(`cannot read ${path} (${error.code ?? 'error'})`);
+    }
+    return parseConfig(text, path, root);
+}
+/** The entries for `event` whose matcher takes `target` (the tool name, or the event's own matcher field). */
+export function entriesFor(config, event, target) {
+    return (config.hooks[event] ?? []).filter(entry => compileMatcher(entry.matcher)(target));
+}
+/**
+ * The matcher the one settings entry for `event` needs so that every entry here
+ * can fire: the union of their names, or `undefined` (all) when one entry
+ * matches all or uses a regular expression.
+ */
+export function settingsMatcher(config, event) {
+    const names = new Set();
+    for (const entry of config.hooks[event] ?? []) {
+        const matcher = entry.matcher;
+        if (matcher === undefined || matcher === '' || matcher === '*' || !PLAIN.test(matcher))
+            return undefined;
+        for (const name of matcher.split('|'))
+            names.add(name);
+    }
+    return [...names].sort().join('|');
+}
+/** 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/dist/merge.js

@@ -0,0 +1,132 @@
+/** Events whose plain stdout Claude Code adds to Claude's context. */
+const CONTEXT_EVENTS = new Set(['SessionStart', 'UserPromptSubmit']);
+const PERMISSION_ORDER = ['deny', 'ask', 'allow'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function strings(values) {
+    return values.filter((value) => typeof value === 'string' && value.trim() !== '');
+}
+function joined(values) {
+    const kept = strings(values);
+    return kept.length === 0 ? undefined : kept.join('\n\n');
+}
+function ends(text) {
+    return text === '' || text.endsWith('\n') ? text : `${text}\n`;
+}
+function blocks(outcome) {
+    if (outcome.code === 2)
+        return true;
+    return outcome.failClosed && outcome.code !== 0;
+}
+function blockReason(outcome) {
+    if (outcome.code === 2)
+        return ends(outcome.stderr);
+    const how = outcome.timedOut ? 'ran out of time' : outcome.code === null ? 'did not finish' : `exited ${outcome.code}`;
+    return `${ends(outcome.stderr)}BLOCKED: ${outcome.label} ${how} instead of giving a verdict, so the call is refused.\n`;
+}
+function failureNote(outcome) {
+    const how = outcome.timedOut ? 'ran out of time' : outcome.code === null ? 'did not finish' : `exited ${outcome.code}`;
+    const detail = outcome.stderr.trim();
+    return detail === '' ? `${outcome.label} ${how}` : `${outcome.label} ${how}: ${detail}`;
+}
+/** Merges the hook-specific fields of several JSON answers for `event`. */
+function mergeSpecific(event, answers, extraContext) {
+    const specifics = answers.map(answer => answer.hookSpecificOutput).filter(isRecord);
+    const merged = {};
+    for (const specific of specifics) {
+        for (const [key, value] of Object.entries(specific)) {
+            if (!(key in merged))
+                merged[key] = value;
+        }
+    }
+    const decisions = specifics.map(specific => specific.permissionDecision).filter((value) => typeof value === 'string');
+    const winner = PERMISSION_ORDER.find(decision => decisions.includes(decision)) ?? decisions[0];
+    if (winner !== undefined) {
+        merged.permissionDecision = winner;
+        const reason = joined(specifics.filter(specific => specific.permissionDecision === winner).map(specific => specific.permissionDecisionReason));
+        if (reason === undefined)
+            delete merged.permissionDecisionReason;
+        else
+            merged.permissionDecisionReason = reason;
+    }
+    const context = joined([...specifics.map(specific => specific.additionalContext), ...extraContext]);
+    if (context === undefined)
+        delete merged.additionalContext;
+    else
+        merged.additionalContext = context;
+    if (Object.keys(merged).length === 0)
+        return undefined;
+    merged.hookEventName = event;
+    return merged;
+}
+const MANAGED = new Set(['continue', 'stopReason', 'suppressOutput', 'decision', 'reason', 'systemMessage', 'hookSpecificOutput']);
+function mergeJson(event, answers, extraContext, notes) {
+    const merged = {};
+    for (const answer of answers) {
+        for (const [key, value] of Object.entries(answer)) {
+            if (!MANAGED.has(key) && !(key in merged))
+                merged[key] = value;
+        }
+    }
+    if (answers.some(answer => answer.continue === false)) {
+        merged.continue = false;
+        const stop = joined(answers.map(answer => answer.stopReason));
+        if (stop !== undefined)
+            merged.stopReason = stop;
+    }
+    if (answers.some(answer => answer.suppressOutput === true))
+        merged.suppressOutput = true;
+    const blockers = answers.filter(answer => answer.decision === 'block');
+    if (blockers.length > 0) {
+        merged.decision = 'block';
+        const reason = joined(blockers.map(answer => answer.reason));
+        if (reason !== undefined)
+            merged.reason = reason;
+    }
+    const message = joined([...answers.map(answer => answer.systemMessage), ...notes]);
+    if (message !== undefined)
+        merged.systemMessage = message;
+    const specific = mergeSpecific(event, answers, extraContext);
+    if (specific !== undefined)
+        merged.hookSpecificOutput = specific;
+    return merged;
+}
+/** Combines the outcomes of `event`'s handlers into the one answer sarathi gives. */
+export function merge(event, outcomes) {
+    const blockers = outcomes.filter(blocks);
+    if (blockers.length > 0)
+        return { code: 2, stdout: '', stderr: blockers.map(blockReason).join('') };
+    const failed = outcomes.filter(outcome => outcome.code !== 0);
+    const passed = outcomes.filter(outcome => outcome.code === 0);
+    const answers = [];
+    const texts = [];
+    for (const outcome of passed) {
+        const json = parseJson(outcome.stdout);
+        if (json !== undefined)
+            answers.push(json);
+        else if (outcome.stdout.trim() !== '')
+            texts.push(outcome.stdout.trim());
+    }
+    const contextTexts = CONTEXT_EVENTS.has(event) ? texts : [];
+    const notes = failed.map(failureNote);
+    if (answers.length > 0 || (failed.length > 0 && contextTexts.length > 0)) {
+        return { code: 0, stdout: `${JSON.stringify(mergeJson(event, answers, contextTexts, notes))}\n`, stderr: '' };
+    }
+    if (failed.length > 0) {
+        return { code: 1, stdout: '', stderr: failed.map(outcome => ends(failureNote(outcome))).join('') };
+    }
+    return { code: 0, stdout: texts.length === 0 ? '' : `${texts.join('\n\n')}\n`, stderr: '' };
+}

package/dist/run.js

@@ -0,0 +1,86 @@
+/**
+ * Runs one event's handlers side by side, as Claude Code runs a settings
+ * block's hooks: each gets the event on stdin and the session's environment,
+ * and each is stopped at its own timeout.
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { DEFAULT_TIMEOUT_SECONDS } from './config.js';
+const GUARD_SCRIPTS = {
+    worktree: 'worktree_guard.py',
+    command: 'command_guard.py',
+};
+/** The folder holding kavach's Python guards, from this package's own dependency. */
+export function kavachDir() {
+    const require = createRequire(import.meta.url);
+    return join(dirname(require.resolve('@veda-hq/kavach/package.json')), 'python', 'kavach');
+}
+/** How one entry runs: a command through `sh -c`, a guard through the configured Python. */
+export function plan(entry, config, guardDir = kavachDir) {
+    const timeoutMs = (entry.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000;
+    if (entry.guard !== undefined) {
+        const env = config.kavach.config === undefined ? {} : { KAVACH_CONFIG: config.kavach.config };
+        return {
+            label: `kavach ${entry.guard} guard`,
+            file: config.kavach.python,
+            args: [join(guardDir(), GUARD_SCRIPTS[entry.guard])],
+            env,
+            timeoutMs,
+            failClosed: true,
+        };
+    }
+    const command = entry.command ?? '';
+    return { label: command, file: '/bin/sh', args: ['-c', command], env: {}, timeoutMs, failClosed: entry.failClosed === true };
+}
+/** Runs one plan with `input` on stdin. Never rejects: a handler that cannot start ends with code `null`. */
+export function runPlan(step, input, cwd) {
+    return new Promise(done => {
+        const out = [];
+        const err = [];
+        let timedOut = false;
+        let settled = false;
+        const finish = (code, extra = '') => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            done({
+                label: step.label,
+                code,
+                stdout: Buffer.concat(out).toString('utf8'),
+                stderr: Buffer.concat(err).toString('utf8') + extra,
+                timedOut,
+                failClosed: step.failClosed,
+            });
+        };
+        const child = spawn(step.file, [...step.args], {
+            cwd,
+            env: { ...process.env, ...step.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            detached: true,
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                // already gone: the close event still comes
+            }
+        }, step.timeoutMs);
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        child.on('error', error => finish(null, `${step.label} could not start (${error.message})\n`));
+        child.on('close', code => finish(timedOut ? null : code));
+        child.stdin.on('error', () => {
+            // a handler that exits without reading its input is not a failure
+        });
+        child.stdin.end(input);
+    });
+}
+/** Runs every entry at once and returns their outcomes in the entries' order. */
+export function runAll(entries, config, input, cwd) {
+    return Promise.all(entries.map(entry => runPlan(plan(entry, config), input, cwd)));
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@veda-hq/sarathi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "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",
+    "claude code",
+    "hooks",
+    "plugin",
+    "guard"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veda-hq/veda.git",
+    "directory": "packages/sarathi"
+  },
+  "homepage": "https://github.com/veda-hq/veda/tree/main/packages/sarathi#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "sarathi": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js"
+  ],
+  "dependencies": {
+    "@veda-hq/kavach": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts --test-coverage-exclude=src/bin.ts src/**/*.test.ts",
+    "smoke": "node dist/bin.js --version && node dist/bin.js check --config test/fixture/sarathi.json --settings test/fixture/settings.json",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
+  }
 }