@panchr/tyr 0.1.0

package/src/providers/cache.ts

@@ -0,0 +1,34 @@
+import { checkCache, writeCache } from "../cache.ts";
+import type { PermissionRequest, Provider, ProviderResult } from "../types.ts";
+
+/** Provider that checks the decision cache. Sits at the front of the pipeline
+ *  so cached results short-circuit more expensive providers.
+ *
+ *  After the pipeline runs, call `cacheResult()` to store a new result from
+ *  a downstream provider. */
+export class CacheProvider implements Provider {
+	readonly name = "cache";
+
+	constructor(private configHash: string) {}
+
+	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
+		const hit = checkCache(req, this.configHash);
+		if (hit) {
+			return {
+				decision: hit.decision,
+				reason: hit.reason ?? undefined,
+			};
+		}
+		return { decision: "abstain" };
+	}
+
+	/** Store a definitive result from a downstream provider. */
+	cacheResult(
+		req: PermissionRequest,
+		decision: "allow" | "deny",
+		provider: string,
+		reason: string | undefined,
+	): void {
+		writeCache(req, decision, provider, reason, this.configHash);
+	}
+}

package/src/providers/chained-commands.ts

@@ -0,0 +1,45 @@
+import type { ClaudeAgent } from "../agents/claude.ts";
+import type { PermissionRequest, Provider, ProviderResult } from "../types.ts";
+import { parseCommands } from "./shell-parser.ts";
+
+/** Provider that splits chained shell commands and checks each sub-command
+ *  against the Claude agent's configured permissions.
+ *
+ *  - If every sub-command is individually allowed → allow.
+ *  - If any sub-command is denied → deny.
+ *  - Otherwise (any unknown) → abstain. */
+export class ChainedCommandsProvider implements Provider {
+	readonly name = "chained-commands";
+
+	constructor(
+		private agent: ClaudeAgent,
+		private verbose = false,
+	) {}
+
+	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
+		if (req.tool_name !== "Bash") return { decision: "abstain" };
+
+		const command = req.tool_input.command;
+		if (typeof command !== "string" || command.trim() === "")
+			return { decision: "abstain" };
+
+		const subCommands = parseCommands(command);
+		if (subCommands.length === 0) return { decision: "abstain" };
+
+		let allAllowed = true;
+		for (const sub of subCommands) {
+			const result = this.agent.isCommandAllowed(sub.command);
+			if (this.verbose) {
+				console.error(`[tyr] chained-commands: "${sub.command}" → ${result}`);
+			}
+			if (result === "deny") return { decision: "deny" };
+			if (result !== "allow") allAllowed = false;
+		}
+
+		const decision = allAllowed ? "allow" : "abstain";
+		if (this.verbose) {
+			console.error(`[tyr] chained-commands: overall → ${decision}`);
+		}
+		return { decision };
+	}
+}

package/src/providers/claude.ts

@@ -0,0 +1,120 @@
+import type { ClaudeAgent } from "../agents/claude.ts";
+import { buildPrompt, parseLlmResponse } from "../prompts.ts";
+import type {
+	ClaudeConfig,
+	PermissionRequest,
+	Provider,
+	ProviderResult,
+} from "../types.ts";
+
+export { buildPrompt, parseLlmResponse };
+
+const S_TO_MS = 1000;
+
+/** Provider that asks an LLM (via `claude -p`) to evaluate permission requests.
+ *  Only handles Bash tool requests. Abstains for everything else. */
+export class ClaudeProvider implements Provider {
+	readonly name = "claude";
+
+	private timeoutMs: number;
+	private model: string;
+	private canDeny: boolean;
+
+	constructor(
+		private agent: ClaudeAgent,
+		config: ClaudeConfig,
+		private verbose: boolean = false,
+	) {
+		this.model = config.model;
+		this.timeoutMs = config.timeout * S_TO_MS;
+		this.canDeny = config.canDeny;
+	}
+
+	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
+		if (req.tool_name !== "Bash") return { decision: "abstain" };
+
+		const command = req.tool_input.command;
+		if (typeof command !== "string" || command.trim() === "")
+			return { decision: "abstain" };
+
+		const prompt = buildPrompt(req, this.agent, this.canDeny);
+
+		// Clear CLAUDECODE env var so claude -p doesn't refuse to run
+		// inside a Claude Code session (tyr is invoked as a hook).
+		const env: Record<string, string | undefined> = {
+			...process.env,
+			CLAUDECODE: undefined,
+		};
+
+		const proc = Bun.spawn(
+			[
+				"claude",
+				"-p",
+				"--output-format",
+				"text",
+				"--no-session-persistence",
+				"--model",
+				this.model,
+			],
+			{
+				stdin: new Response(prompt).body,
+				stdout: "pipe",
+				stderr: "pipe",
+				env,
+			},
+		);
+
+		let timer: Timer | undefined;
+		const result = await Promise.race([
+			(async () => {
+				const [stdout, stderr] = await Promise.all([
+					new Response(proc.stdout).text(),
+					new Response(proc.stderr).text(),
+				]);
+				const exitCode = await proc.exited;
+				return { stdout, stderr, exitCode, timedOut: false };
+			})(),
+			new Promise<{
+				stdout: string;
+				stderr: string;
+				exitCode: number;
+				timedOut: boolean;
+			}>((resolve) => {
+				timer = setTimeout(() => {
+					proc.kill();
+					resolve({
+						stdout: "",
+						stderr: "timeout",
+						exitCode: -1,
+						timedOut: true,
+					});
+				}, this.timeoutMs);
+			}),
+		]);
+		clearTimeout(timer);
+
+		if (this.verbose) {
+			console.error(
+				`[tyr] claude: exitCode=${result.exitCode} timedOut=${result.timedOut}`,
+			);
+			if (result.stdout)
+				console.error(`[tyr] claude stdout: ${result.stdout.trim()}`);
+			if (result.stderr)
+				console.error(`[tyr] claude stderr: ${result.stderr.trim()}`);
+		}
+
+		if (result.timedOut || result.exitCode !== 0) {
+			return { decision: "abstain" };
+		}
+
+		const llmDecision = parseLlmResponse(result.stdout);
+		if (!llmDecision) return { decision: "abstain" };
+
+		// When canDeny is false, convert deny→abstain so the user gets prompted
+		if (!this.canDeny && llmDecision.decision === "deny") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
+		return { decision: llmDecision.decision, reason: llmDecision.reason };
+	}
+}

package/src/providers/openrouter.ts

@@ -0,0 +1,112 @@
+import type { ClaudeAgent } from "../agents/claude.ts";
+import { buildPrompt, parseLlmResponse } from "../prompts.ts";
+import type {
+	OpenRouterConfig,
+	PermissionRequest,
+	Provider,
+	ProviderResult,
+} from "../types.ts";
+
+const S_TO_MS = 1000;
+
+/** Provider that calls OpenRouter's chat completions API to evaluate permission requests.
+ *  Only handles Bash tool requests. Abstains for everything else. */
+export class OpenRouterProvider implements Provider {
+	readonly name = "openrouter";
+
+	private timeoutMs: number;
+	private model: string;
+	private endpoint: string;
+	private canDeny: boolean;
+
+	constructor(
+		private agent: ClaudeAgent,
+		config: OpenRouterConfig,
+		private verbose: boolean = false,
+	) {
+		this.model = config.model;
+		this.timeoutMs = config.timeout * S_TO_MS;
+		this.canDeny = config.canDeny;
+		this.endpoint = config.endpoint;
+	}
+
+	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
+		if (req.tool_name !== "Bash") return { decision: "abstain" };
+
+		const command = req.tool_input.command;
+		if (typeof command !== "string" || command.trim() === "")
+			return { decision: "abstain" };
+
+		const apiKey = process.env.OPENROUTER_API_KEY;
+		if (!apiKey) {
+			console.error(
+				"[tyr] openrouter: OPENROUTER_API_KEY not set, skipping LLM check",
+			);
+			return { decision: "abstain" };
+		}
+
+		const prompt = buildPrompt(req, this.agent, this.canDeny);
+		const url = `${this.endpoint}/chat/completions`;
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+		let responseText: string;
+		try {
+			const res = await fetch(url, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${apiKey}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					model: this.model,
+					messages: [{ role: "user", content: prompt }],
+					temperature: 0,
+					max_tokens: 256,
+				}),
+				signal: controller.signal,
+			});
+
+			if (!res.ok) {
+				if (this.verbose) {
+					const body = await res.text().catch(() => "<unreadable>");
+					console.error(
+						`[tyr] openrouter: HTTP ${res.status}: ${body.slice(0, 200)}`,
+					);
+				}
+				return { decision: "abstain" };
+			}
+
+			const json = (await res.json()) as {
+				choices?: { message?: { content?: string } }[];
+			};
+			responseText = json.choices?.[0]?.message?.content ?? "";
+		} catch (err) {
+			if (this.verbose) {
+				const label =
+					err instanceof DOMException && err.name === "AbortError"
+						? "timeout"
+						: String(err);
+				console.error(`[tyr] openrouter: ${label}`);
+			}
+			return { decision: "abstain" };
+		} finally {
+			clearTimeout(timer);
+		}
+
+		if (this.verbose) {
+			console.error(`[tyr] openrouter response: ${responseText.trim()}`);
+		}
+
+		const llmDecision = parseLlmResponse(responseText);
+		if (!llmDecision) return { decision: "abstain" };
+
+		// When canDeny is false, convert deny→abstain so the user gets prompted
+		if (!this.canDeny && llmDecision.decision === "deny") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
+		return { decision: llmDecision.decision, reason: llmDecision.reason };
+	}
+}

package/src/providers/shell-parser.ts

@@ -0,0 +1,76 @@
+import { syntax } from "mvdan-sh";
+
+/** A simple command extracted from a shell string. */
+export interface SimpleCommand {
+	/** The full command text reconstructed from the AST (e.g. "git commit -m test"). */
+	command: string;
+	/** Individual arguments including the command name. */
+	args: string[];
+}
+
+/** Extract the string value of a Word AST node. */
+function wordToString(word: unknown): string {
+	const w = word as { Parts: unknown[] };
+	let result = "";
+	for (let i = 0; i < w.Parts.length; i++) {
+		const part = w.Parts[i] as Record<string, unknown>;
+		const partType = syntax.NodeType(part) as string;
+		if (partType === "Lit") {
+			result += part.Value;
+		} else if (partType === "SglQuoted") {
+			result += part.Value;
+		} else if (partType === "DblQuoted") {
+			const inner = part.Parts as unknown[];
+			for (let j = 0; j < inner.length; j++) {
+				const ip = inner[j] as Record<string, unknown>;
+				if (syntax.NodeType(ip) === "Lit") {
+					result += ip.Value;
+				}
+				// For parameter expansions, command substitutions inside
+				// double quotes we skip — they're dynamic and can't be
+				// statically resolved.
+			}
+		}
+		// CmdSubst, ParamExp, etc. are dynamic — we skip them.
+	}
+	return result;
+}
+
+/** Parse a shell command string and extract all simple commands.
+ *
+ *  Handles pipes (`|`), logical operators (`&&`, `||`), semicolons (`;`),
+ *  subshells (`(cmd)`), and command substitution (`$(cmd)`).
+ *  Returns an empty array if parsing fails. */
+export function parseCommands(input: string): SimpleCommand[] {
+	const parser = syntax.NewParser();
+	let file: import("mvdan-sh").ShellNode;
+	try {
+		file = parser.Parse(input, "");
+	} catch {
+		return [];
+	}
+
+	const commands: SimpleCommand[] = [];
+
+	syntax.Walk(file, (node) => {
+		if (!node) return true;
+		if (syntax.NodeType(node) !== "CallExpr") return true;
+
+		const call = node as { Args: unknown[] };
+		if (!call.Args || call.Args.length === 0) return true;
+
+		const args: string[] = [];
+		for (let i = 0; i < call.Args.length; i++) {
+			args.push(wordToString(call.Args[i]));
+		}
+
+		commands.push({
+			command: args.join(" "),
+			args,
+		});
+
+		return true;
+	});
+
+	return commands;
+}

package/src/types/mvdan-sh.d.ts

@@ -0,0 +1,23 @@
+/** Minimal type declarations for mvdan-sh (GopherJS shell parser). */
+declare module "mvdan-sh" {
+	interface ShellNode {
+		[key: string]: unknown;
+	}
+
+	interface Parser {
+		/** Parse a shell string into an AST. Throws on syntax errors. */
+		Parse(input: string, name: string): ShellNode;
+	}
+
+	interface Syntax {
+		/** Return the AST node type name (e.g. "CallExpr", "Lit", "DblQuoted"). */
+		NodeType(node: unknown): string;
+		/** Create a new shell parser instance. */
+		NewParser(): Parser;
+		/** Walk an AST tree, calling the visitor for each node. Return true to continue. */
+		Walk(node: ShellNode, visitor: (node: ShellNode | null) => boolean): void;
+	}
+
+	const syntax: Syntax;
+	export { syntax, type ShellNode };
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+import { z } from "zod/v4";
+
+// -- Hook interface types (Claude Code PermissionRequest) --
+
+/** Schema for the JSON payload Claude Code sends to hooks on PermissionRequest events. */
+export const PermissionRequestSchema = z.object({
+	session_id: z.string(),
+	transcript_path: z.string(),
+	cwd: z.string(),
+	permission_mode: z.string(),
+	hook_event_name: z.literal("PermissionRequest"),
+	tool_name: z.string(),
+	tool_input: z.record(z.string(), z.unknown()),
+});
+
+export type PermissionRequest = z.infer<typeof PermissionRequestSchema>;
+
+/** A provider's verdict on a permission request. */
+export type PermissionResult = "allow" | "deny" | "abstain";
+
+/** Extended result from a provider, carrying an optional reason. */
+export interface ProviderResult {
+	decision: PermissionResult;
+	reason?: string;
+}
+
+/** The JSON structure tyr writes to stdout to communicate a decision back to Claude. */
+export interface HookResponse {
+	hookSpecificOutput: {
+		hookEventName: "PermissionRequest";
+		decision: {
+			behavior: "allow" | "deny";
+			message?: string;
+		};
+	};
+}
+
+// -- Provider interface --
+
+/** A strategy for evaluating permission requests. */
+export interface Provider {
+	readonly name: string;
+	checkPermission(req: PermissionRequest): Promise<ProviderResult>;
+}
+
+// -- Tyr's own config --
+
+export const ClaudeConfigSchema = z.object({
+	/** Model identifier passed to the Claude CLI. */
+	model: z.string().default("haiku"),
+	/** Request timeout in seconds. */
+	timeout: z.number().default(10),
+	/** Whether the provider can deny requests. When false, it can only allow or abstain. */
+	canDeny: z.boolean().default(false),
+});
+
+export type ClaudeConfig = z.infer<typeof ClaudeConfigSchema>;
+
+export const OpenRouterConfigSchema = z.object({
+	/** Model identifier passed to the OpenRouter API. */
+	model: z.string().default("anthropic/claude-3.5-haiku"),
+	/** OpenRouter API endpoint. */
+	endpoint: z.string().default("https://openrouter.ai/api/v1"),
+	/** Request timeout in seconds. */
+	timeout: z.number().default(10),
+	/** Whether the provider can deny requests. When false, it can only allow or abstain. */
+	canDeny: z.boolean().default(false),
+});
+
+export type OpenRouterConfig = z.infer<typeof OpenRouterConfigSchema>;
+
+/** Valid provider names for the pipeline. */
+export const PROVIDER_NAMES = [
+	"cache",
+	"chained-commands",
+	"claude",
+	"openrouter",
+] as const;
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+
+export const TyrConfigSchema = z.object({
+	/** Ordered list of providers to run in the pipeline. */
+	providers: z.array(z.enum(PROVIDER_NAMES)).default(["chained-commands"]),
+	/** If true, approve requests when tyr encounters an error. Default: false (fail-closed). */
+	failOpen: z.boolean().default(false),
+	/** Claude CLI provider configuration. */
+	claude: ClaudeConfigSchema.default(ClaudeConfigSchema.parse({})),
+	/** OpenRouter API provider configuration. */
+	openrouter: OpenRouterConfigSchema.default(OpenRouterConfigSchema.parse({})),
+	/** Include LLM prompt and parameters in log entries for debugging. */
+	verboseLog: z.boolean().default(false),
+	/** Maximum age of log entries. Entries older than this are pruned on the next tyr invocation.
+	 *  Use relative duration syntax: "30d", "12h", "0" to disable. Default: "30d". */
+	logRetention: z
+		.string()
+		.default("30d")
+		.refine((v) => v === "0" || /^\d+[smhd]$/.test(v), {
+			message: "Must be '0' or a duration like '30d', '12h', '45m', '60s'",
+		}),
+});
+
+export type TyrConfig = z.infer<typeof TyrConfigSchema>;
+
+export const DEFAULT_TYR_CONFIG: TyrConfig = TyrConfigSchema.parse({});
+
+/** Return the ordered provider list from config. */
+export function resolveProviders(config: TyrConfig): ProviderName[] {
+	return config.providers;
+}

package/src/version.ts

@@ -0,0 +1,9 @@
+import pkg from "../package.json";
+
+/**
+ * For compiled binaries, TYR_VERSION is injected via --define at build time.
+ * When running from source, reads from package.json.
+ */
+declare const TYR_VERSION: string | undefined;
+export const VERSION: string =
+	typeof TYR_VERSION === "string" ? TYR_VERSION : pkg.version;