@panchr/tyr 0.1.1 → 0.2.0

package/README.md

@@ -1,69 +1,63 @@
 # tyr
 
-> **Experimental** — tyr is under active development. The API, configuration schema, and CLI interface may change without notice.
+> **Experimental** — tyr is under active development. The API, configuration schema, and CLI interface may change without notice. If upgrading between minor versions, it's highly possible that a previous configuration needs some manual update.
 
-Intelligent permission management for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hooks. Tyr intercepts `PermissionRequest` events from Claude Code and evaluates them against your configured allow/deny patterns, so you can auto-approve safe commands and block dangerous ones without manual intervention.
+Tyr is a CLI for intelligently managing permissions for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It is added as a hook on `PermissionRequest` events and evaluates them against configured allow/deny patterns. In the standard mode, this evaluation is done by Claude (or another LLM) by comparing the requested Bash command to the user's configuration. The hook will auto-approve commands that fuzzily match the configuration, without manual intervention.
 
-Named after the [Norse god of justice](https://en.wikipedia.org/wiki/T%C3%BDr).
+The goal is to reduce the number of permission prompts sent to the user. As of now, Tyr only evaluates `Bash` tool requests; it abstains on all other tools.
 
-## How it works
-
-Tyr registers itself as a Claude Code [hook](https://docs.anthropic.com/en/docs/claude-code/hooks) on the `PermissionRequest` event. When Claude Code asks to run a shell command, tyr:
-
-1. Reads your Claude Code allow/deny permission patterns
-2. Parses compound commands (e.g. `git add . && git commit`) and checks each component
-3. Optionally asks an LLM to evaluate ambiguous commands against your patterns
-4. Returns allow/deny/abstain back to Claude Code
+It is named after the [Norse god of justice](https://en.wikipedia.org/wiki/T%C3%BDr).
 
 ## Why tyr?
 
-Claude Code's `--dangerously-skip-permissions` flag gives the agent full autonomy — it can run any command without asking. That's fast, but risky: a single bad tool call can delete files, leak secrets, or break your environment with no audit trail.
+Claude Code's `--dangerously-skip-permissions` flag gives the agent full autonomy -- it can run any command without asking. That's risky: a single bad tool call can delete files, leak secrets, or break your environment.
 
-Tyr gives you the same automation benefits with granular control and full observability. You choose how much autonomy to grant:
+Tyr gives a configurable degree of autonomy to Claude:
 
 | Mode | What happens | Use case |
 |------|-------------|----------|
-| **Audit** (`tyr install --audit`) | Logs every permission request without evaluating it | Understand what Claude Code is doing before changing anything |
-| **Shadow** (`tyr install --shadow`) | Runs the full allow/deny pipeline but always abstains to Claude Code | Validate your rules against real traffic before going live |
+| **Audit** (`tyr install --audit`) | Logs every permission request without evaluating it | Understand what Claude Code is doing without performing any of tyr's logic on the request |
+| **Shadow** (`tyr install --shadow`) | Runs the full allow/deny pipeline but always abstains to Claude Code | Validate your rules against real requests, before an impact |
 | **Active** (`tyr install`) | Evaluates requests and enforces allow/deny decisions | Full automation with pattern-based guardrails |
 
 Every decision is logged to a SQLite database, so you can review what was allowed, denied, or abstained — and why.
 
-## Prerequisites
-
-- [Bun](https://bun.sh) runtime
-- Claude Code (for integration — tyr can be tested standalone)
+## Quickstart
 
-## Install
+Requires [Bun](https://bun.sh) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 ```bash
-# Clone and install dependencies
-git clone git@github.com:panchr/tyr.git && cd tyr
-bun install
+# Install tyr
+bun install -g @panchr/tyr
 
-# Build and install the binary to /usr/local/bin
-bun run build
-
-# Register the hook in your project (writes to .claude/settings.json)
+# Register the hook (run this inside your project directory)
 tyr install
 
-# Or install globally (writes to ~/.claude/settings.json)
+# Start a Claude Code session and work as usual — tyr runs automatically.
+# When you're done, review what happened:
+tyr log
+tyr stats
+```
+
+That's it. Tyr evaluates every permission request against your Claude Code allow/deny patterns and logs the result. Commands that match an allowed pattern are auto-approved; everything else falls through to Claude Code's normal prompt.
+
+To install globally (applies to all projects):
+
+```bash
 tyr install --global
 ```
 
 To remove:
 
 ```bash
-tyr uninstall
-tyr uninstall --global
+tyr uninstall          # project
+tyr uninstall --global # global
 ```
 
 Use `--dry-run` with either command to preview changes without modifying anything.
 
 ## Usage
 
-Once installed, tyr runs automatically as a Claude Code hook. No manual invocation needed.
-
 ### Commands
 
 ```
@@ -79,7 +73,7 @@ tyr log [--last N] [--json] [--since T] [--until T] [--decision D] [--provider P
 tyr log clear
 tyr db migrate
 tyr stats [--since T] [--json]
-tyr suggest [--apply] [--global|--project] [--min-count N] [--json]
+tyr suggest [--global|--project] [--min-count N] [--all]
 tyr debug claude-config [--cwd C]
 tyr version
 ```
@@ -90,7 +84,7 @@ Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `providers` | string[] | `["chained-commands"]` | Ordered list of providers to run |
+| `providers` | string[] | `["chained-commands", "claude"]` | Ordered list of providers to run |
 | `failOpen` | boolean | `false` | Approve on error instead of failing closed |
 | `claude.model` | string | `"haiku"` | Model identifier for the Claude CLI |
 | `claude.timeout` | number | `10` | Claude request timeout in seconds |
@@ -99,6 +93,7 @@ Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_
 | `openrouter.endpoint` | string | `"https://openrouter.ai/api/v1"` | OpenRouter API endpoint |
 | `openrouter.timeout` | number | `10` | OpenRouter request timeout in seconds |
 | `openrouter.canDeny` | boolean | `false` | Whether OpenRouter can deny requests |
+| `conversationContext` | boolean | `false` | Give LLM providers recent conversation context to judge intent (can allow commands beyond configured patterns) |
 | `verboseLog` | boolean | `false` | Include LLM prompt/params in log entries |
 | `logRetention` | string | `"30d"` | Auto-prune logs older than this (`"0"` to disable) |
 
@@ -123,11 +118,11 @@ Existing process environment variables take precedence over `.env` values.
 
 ### Providers
 
-Tyr uses a **pipeline architecture** where providers are evaluated in sequence. The first provider to return a definitive `allow` or `deny` wins — remaining providers are skipped. If all providers `abstain`, the request falls through to Claude Code's default behavior (prompting the user), unless `failOpen` is `true`, in which case the request is approved.
+Tyr uses a **pipeline architecture** where providers are evaluated in sequence. The first provider to return a definitive `allow` or `deny` wins --- remaining providers are skipped. If all providers `abstain`, the request falls through to Claude Code's default behavior (prompting the user), unless `failOpen` is `true`, in which case the request is approved.
 
-Configure the pipeline via the `providers` array. **Order matters** — providers run left to right.
+Configure the pipeline via the `providers` array. **Order matters** -- providers run in order.
 
-Valid provider names: `cache`, `chained-commands`, `claude`, `openrouter`.
+Valid providers are listed below.
 
 #### `cache`
 
@@ -137,27 +132,27 @@ Caches prior decisions in SQLite. If the same command was previously allowed or
 
 #### `chained-commands`
 
-Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substitution) and checks each sub-command against your Claude Code allow/deny permission patterns (merged from all settings files).
+Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substitution) and checks each sub-command against your Claude Code allow/deny permission patterns.
 
 - **Allow:** All sub-commands match an allow pattern
-- **Deny:** Any sub-command matches a deny pattern
+- **Deny:** _Any_ sub-command matches a deny pattern
 - **Abstain:** Any sub-command has no matching pattern
 
-Only evaluates `Bash` tool requests; abstains on all other tools.
-
 #### `claude`
 
-Sends ambiguous commands to a local Claude CLI for semantic evaluation. The LLM sees your permission rules, the command, and the working directory, then reasons about whether the command is safe.
+Sends ambiguous commands to the local Claude CLI for semantic evaluation. The LLM sees your permission rules, the command, and the working directory, then reasons about whether the command is safe.
 
-When `claude.canDeny` is `false` (the default), the LLM can only approve commands — deny decisions are converted to abstain, forcing the user to decide. Set `canDeny: true` for stricter enforcement.
+When `claude.canDeny` is `false` (the default), the LLM can only approve commands -- deny decisions are converted to abstain, forcing the user to decide. Set `canDeny: true` for stricter enforcement.
 
-Requires a local `claude` CLI binary (installed with Claude Code). Timeouts and errors are treated as abstain.
+When `conversationContext` is enabled, the LLM also sees recent conversation messages from the Claude Code session. This lets it allow commands that don't match any configured pattern if the user clearly requested the action and it's a typical, safe development command. The deny list is always checked first -- no amount of context overrides a denied pattern.
 
-Only evaluates `Bash` tool requests; abstains on all other tools.
+Requires a local `claude` CLI binary. While this is somewhat slow due to the subprocess required to run `claude` (generally a decision is made in about 5 seconds), this slowness is acceptable given that it will still be faster than a human understanding and approving a command.
+
+The main benefit of this provider is that it reuses the authentication that `claude` is already configured with, whether that's an Anthropic API key or a subscription.
 
 #### `openrouter`
 
-Sends ambiguous commands to the OpenRouter API for evaluation. Same semantics as the `claude` provider but uses an HTTP API instead of the local CLI.
+Sends ambiguous commands to the OpenRouter API for evaluation. Same semantics as the `claude` provider but uses an HTTP API instead of the local CLI. Supports `conversationContext` in the same way.
 
 Requires `OPENROUTER_API_KEY` set in your environment or `.env` file.
 
@@ -166,13 +161,13 @@ Only evaluates `Bash` tool requests; abstains on all other tools.
 #### Pipeline examples
 
 ```jsonc
-// Safe & fast (default) — pattern matching only
+// Safe & fast (default) -- pattern matching only
 { "providers": ["chained-commands"] }
 
-// With caching — faster repeated evaluations
+// With caching -- faster repeated evaluations
 { "providers": ["cache", "chained-commands"] }
 
-// Full pipeline — patterns first, then Claude for ambiguous commands
+// Full pipeline -- patterns first, then Claude for ambiguous commands
 { "providers": ["cache", "chained-commands", "claude"] }
 
 // Using OpenRouter instead of local Claude
@@ -231,37 +226,26 @@ Shows: total checks, decision breakdown (allow/deny/abstain/error), cache hit ra
 
 ### Suggestions
 
-Tyr can analyze your decision history and recommend new allow rules to add to Claude Code's settings:
+Tyr can analyze your decision history and start an interactive Claude session to help you refine and apply allow rules:
 
 ```bash
-# View suggestions (commands approved >= 5 times by default)
+# Start an interactive session with suggested rules (commands approved >= 5 times)
 tyr suggest
 
-# Lower the threshold
+# Lower the threshold for which commands are surfaced
 tyr suggest --min-count 3
 
-# Apply suggestions to global settings
-tyr suggest --apply --global
-
-# Apply to project settings
-tyr suggest --apply --project
-```
-
-### Debugging
-
-```bash
-# Print the merged Claude Code permission config for the current project
-tyr debug claude-config
-
-# Print for a different project directory
-tyr debug claude-config --cwd /path/to/project
+# Target project settings instead of global
+tyr suggest --project
 
-# Print tyr version and runtime info
-tyr version
+# Include commands from all projects, not just the current directory
+tyr suggest --all
 ```
 
 ### Database migrations
 
+When upgrading from one `tyr` version to another, run
+
 ```bash
 # Run pending schema migrations
 tyr db migrate

package/package.json

@@ -3,7 +3,7 @@
   "description": "Intelligent permission management for Claude Code hooks",
   "module": "src/index.ts",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "bin": {
     "tyr": "src/index.ts"
   },

package/src/cache.ts

@@ -26,6 +26,7 @@ export function computeConfigHash(
 		"claude.canDeny": config.claude.canDeny,
 		"openrouter.model": config.openrouter.model,
 		"openrouter.canDeny": config.openrouter.canDeny,
+		conversationContext: config.conversationContext,
 	});
 	return createHash("sha256").update(data).digest("hex");
 }

package/src/commands/judge.ts

@@ -18,9 +18,12 @@ import { CacheProvider } from "../providers/cache.ts";
 import { ChainedCommandsProvider } from "../providers/chained-commands.ts";
 import { ClaudeProvider } from "../providers/claude.ts";
 import { OpenRouterProvider } from "../providers/openrouter.ts";
+import { formatTranscriptForPrompt, readTranscript } from "../transcript.ts";
 import type { HookResponse, Provider, TyrConfig } from "../types.ts";
 import { resolveProviders } from "../types.ts";
 
+const MAX_TRANSCRIPT_MESSAGES = 10;
+
 const judgeArgs = {
 	verbose: {
 		type: "boolean" as const,
@@ -77,6 +80,11 @@ const judgeArgs = {
 		type: "boolean" as const,
 		description: "Include LLM prompt and parameters in log entries",
 	},
+	"conversation-context": {
+		type: "boolean" as const,
+		description:
+			"Override conversationContext config (include transcript in LLM prompts)",
+	},
 };
 
 export default defineCommand({
@@ -224,6 +232,8 @@ export default defineCommand({
 			config.openrouter.canDeny = args["openrouter-can-deny"];
 		if (args["verbose-log"] !== undefined)
 			config.verboseLog = args["verbose-log"];
+		if (args["conversation-context"] !== undefined)
+			config.conversationContext = args["conversation-context"];
 
 		const agent = new ClaudeAgent();
 		try {
@@ -232,6 +242,21 @@ export default defineCommand({
 			if (verbose) console.error("[tyr] failed to init agent config:", err);
 		}
 
+		// Read conversation context from transcript if enabled
+		let transcriptContext: string | undefined;
+		if (config.conversationContext) {
+			const messages = await readTranscript(
+				req.transcript_path,
+				MAX_TRANSCRIPT_MESSAGES,
+			);
+			transcriptContext = formatTranscriptForPrompt(messages) || undefined;
+			if (verbose && transcriptContext) {
+				console.error(
+					`[tyr] conversation context (${messages.length} messages):\n${transcriptContext}`,
+				);
+			}
+		}
+
 		// Build provider pipeline from config
 		const providers: Provider[] = [];
 		let cacheProvider: CacheProvider | null = null;
@@ -248,11 +273,23 @@ export default defineCommand({
 					providers.push(new ChainedCommandsProvider(agent, verbose));
 					break;
 				case "claude":
-					providers.push(new ClaudeProvider(agent, config.claude, verbose));
+					providers.push(
+						new ClaudeProvider(
+							agent,
+							config.claude,
+							verbose,
+							transcriptContext,
+						),
+					);
 					break;
 				case "openrouter":
 					providers.push(
-						new OpenRouterProvider(agent, config.openrouter, verbose),
+						new OpenRouterProvider(
+							agent,
+							config.openrouter,
+							verbose,
+							transcriptContext,
+						),
 					);
 					break;
 			}
@@ -319,12 +356,22 @@ export default defineCommand({
 		if (config.verboseLog) {
 			if (result.provider === "claude") {
 				llm = {
-					prompt: buildPrompt(req, agent, config.claude.canDeny),
+					prompt: buildPrompt(
+						req,
+						agent,
+						config.claude.canDeny,
+						transcriptContext,
+					),
 					model: config.claude.model,
 				};
 			} else if (result.provider === "openrouter") {
 				llm = {
-					prompt: buildPrompt(req, agent, config.openrouter.canDeny),
+					prompt: buildPrompt(
+						req,
+						agent,
+						config.openrouter.canDeny,
+						transcriptContext,
+					),
 					model: config.openrouter.model,
 				};
 			} else {
@@ -332,14 +379,24 @@ export default defineCommand({
 				for (const name of resolveProviders(config)) {
 					if (name === "claude") {
 						llm = {
-							prompt: buildPrompt(req, agent, config.claude.canDeny),
+							prompt: buildPrompt(
+								req,
+								agent,
+								config.claude.canDeny,
+								transcriptContext,
+							),
 							model: config.claude.model,
 						};
 						break;
 					}
 					if (name === "openrouter") {
 						llm = {
-							prompt: buildPrompt(req, agent, config.openrouter.canDeny),
+							prompt: buildPrompt(
+								req,
+								agent,
+								config.openrouter.canDeny,
+								transcriptContext,
+							),
 							model: config.openrouter.model,
 						};
 						break;

package/src/commands/suggest.ts

@@ -8,13 +8,9 @@ import {
 } from "../agents/claude.ts";
 import { rejectUnknownArgs } from "../args.ts";
 import { closeDb, getDb } from "../db.ts";
-import { readSettings, writeSettings } from "../install.ts";
+import { readSettings } from "../install.ts";
 
 const suggestArgs = {
-	apply: {
-		type: "boolean" as const,
-		description: "Write suggestions into Claude's settings.json",
-	},
 	global: {
 		type: "boolean" as const,
 		description: "Target global (~/.claude/settings.json)",
@@ -27,9 +23,10 @@ const suggestArgs = {
 		type: "string" as const,
 		description: "Minimum approval count to suggest (default: 5)",
 	},
-	json: {
+	all: {
 		type: "boolean" as const,
-		description: "Output raw JSON",
+		description:
+			"Include commands from all projects (default: current directory)",
 	},
 };
 
@@ -44,23 +41,39 @@ export interface Suggestion {
 	rule: string;
 }
 
-/** Query frequently-allowed commands and filter out those already in allow lists. */
+/** Query frequently-allowed commands and filter out those already in allow lists.
+ *  When `cwd` is provided, only includes commands from that directory (or subdirs). */
 export function getSuggestions(
 	minCount: number,
 	allowPatterns: string[],
+	cwd?: string,
 ): Suggestion[] {
 	const db = getDb();
 
-	const rows = db
-		.query(
-			`SELECT tool_input, COUNT(*) as count
+	let query: string;
+	let params: (number | string)[];
+
+	if (cwd) {
+		const escapedCwd = cwd.replace(/[%_]/g, "\\$&");
+		query = `SELECT tool_input, COUNT(*) as count
+			 FROM logs
+			 WHERE decision = 'allow' AND mode IS NULL AND tool_name = 'Bash'
+			   AND (cwd = ? OR cwd LIKE ? || '/%' ESCAPE '\\')
+			 GROUP BY tool_input
+			 HAVING COUNT(*) >= ?
+			 ORDER BY COUNT(*) DESC`;
+		params = [cwd, escapedCwd, minCount];
+	} else {
+		query = `SELECT tool_input, COUNT(*) as count
 			 FROM logs
 			 WHERE decision = 'allow' AND mode IS NULL AND tool_name = 'Bash'
 			 GROUP BY tool_input
 			 HAVING COUNT(*) >= ?
-			 ORDER BY COUNT(*) DESC`,
-		)
-		.all(minCount) as CommandFrequency[];
+			 ORDER BY COUNT(*) DESC`;
+		params = [minCount];
+	}
+
+	const rows = db.query(query).all(...params) as CommandFrequency[];
 
 	const suggestions: Suggestion[] = [];
 	for (const row of rows) {
@@ -79,20 +92,35 @@ export function getSuggestions(
 	return suggestions;
 }
 
-/** Merge new allow rules into existing settings without clobbering. */
-export function mergeAllowRules(
-	settings: Record<string, unknown>,
-	rules: string[],
-): Record<string, unknown> {
-	const result = { ...settings };
-	const perms = (result.permissions ?? {}) as Record<string, unknown>;
-	const existing = Array.isArray(perms.allow) ? (perms.allow as string[]) : [];
+function buildSuggestSystemPrompt(
+	suggestions: Suggestion[],
+	settingsPath: string,
+): string {
+	const commandList = suggestions
+		.map((s) => `- \`${s.command}\` (approved ${s.count} times)`)
+		.join("\n");
+
+	return `You are helping configure permission rules for Claude Code.
+
+The user has been manually approving shell commands while using Claude Code. Tyr has identified frequently-approved commands that could be added as permanent allow rules.
 
-	const existingSet = new Set(existing);
-	const merged = [...existing, ...rules.filter((r) => !existingSet.has(r))];
+## Frequently Approved Commands (not yet in allow rules)
 
-	result.permissions = { ...perms, allow: merged };
-	return result;
+${commandList}
+
+## Settings File
+- Path: ${settingsPath}
+- Format: JSON with a \`permissions.allow\` array of strings
+- Each rule is a string like \`Bash(pattern)\` where \`pattern\` can use \`*\` as a glob wildcard
+- Example: \`Bash(bun *)\` allows any command starting with \`bun \`
+
+## Your Task
+Help the user decide which commands to add as allow rules:
+1. Suggest generalized glob patterns that group similar commands (e.g., "bun test" and "bun lint" → "Bash(bun *)")
+2. Explain what each pattern would match
+3. When the user is ready, write the rules to the settings file at the path above
+
+Be concise. Start by presenting your suggested rules and ask if the user wants to adjust them.`;
 }
 
 export default defineCommand({
@@ -118,67 +146,42 @@ export default defineCommand({
 			return;
 		}
 
-		try {
-			// Load all allow patterns from Claude settings to filter suggestions
-			const allPaths = settingsPaths(process.cwd());
-			const allowPatterns: string[] = [];
-			for (const path of allPaths) {
-				const settings = await readSettings(path);
-				const perms = settings.permissions as
-					| Record<string, unknown>
-					| undefined;
-				if (perms && Array.isArray(perms.allow)) {
-					allowPatterns.push(...extractBashPatterns(perms.allow));
-				}
+		const allPaths = settingsPaths(process.cwd());
+		const allowPatterns: string[] = [];
+		for (const path of allPaths) {
+			const settings = await readSettings(path);
+			const perms = settings.permissions as Record<string, unknown> | undefined;
+			if (perms && Array.isArray(perms.allow)) {
+				allowPatterns.push(...extractBashPatterns(perms.allow));
 			}
+		}
 
-			const suggestions = getSuggestions(minCount, allowPatterns);
+		const cwdFilter = args.all ? undefined : process.cwd();
+		const suggestions = getSuggestions(minCount, allowPatterns, cwdFilter);
+		closeDb();
 
-			if (args.json) {
-				console.log(JSON.stringify(suggestions));
-				return;
-			}
+		if (suggestions.length === 0) {
+			console.log("No new suggestions found.");
+			return;
+		}
 
-			if (suggestions.length === 0) {
-				console.log("No new suggestions found.");
-				return;
-			}
+		const scope: "global" | "project" = args.project ? "project" : "global";
+		const configDir =
+			process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+		const settingsPath =
+			scope === "global"
+				? join(configDir, "settings.json")
+				: join(process.cwd(), ".claude", "settings.json");
 
-			if (!args.apply) {
-				console.log(
-					`Suggested allow rules (commands approved >= ${minCount} times):`,
-				);
-				console.log();
-				for (const s of suggestions) {
-					console.log(`  ${s.rule}  (${s.count} approvals)`);
-				}
-				console.log();
-				console.log("Run with --apply to add these rules to Claude settings.");
-				return;
-			}
+		const systemPrompt = buildSuggestSystemPrompt(suggestions, settingsPath);
 
-			// Apply mode: write rules to settings
-			const scope: "global" | "project" = args.project ? "project" : "global";
-			const configDir =
-				process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
-			const settingsPath =
-				scope === "global"
-					? join(configDir, "settings.json")
-					: join(process.cwd(), ".claude", "settings.json");
-			const settings = await readSettings(settingsPath);
-
-			const newRules = suggestions.map((s) => s.rule);
-			const merged = mergeAllowRules(settings, newRules);
-			await writeSettings(settingsPath, merged);
-
-			console.log(
-				`Added ${newRules.length} allow rule(s) to ${scope} settings (${settingsPath}):`,
-			);
-			for (const rule of newRules) {
-				console.log(`  ${rule}`);
-			}
-		} finally {
-			closeDb();
-		}
+		const proc = Bun.spawn(["claude", "--append-system-prompt", systemPrompt], {
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+			env: { ...process.env, CLAUDECODE: undefined },
+		});
+
+		process.exitCode = await proc.exited;
 	},
 });

package/src/config.ts

@@ -101,6 +101,7 @@ const VALID_KEY_TYPES: Record<
 > = {
 	providers: "providers",
 	failOpen: "boolean",
+	conversationContext: "boolean",
 	verboseLog: "boolean",
 	logRetention: "string",
 	"claude.model": "string",

package/src/prompts.ts

@@ -3,7 +3,7 @@ import type { PermissionRequest } from "./types.ts";
 
 /** Expected shape of the LLM's JSON response. */
 export interface LlmDecision {
-	decision: "allow" | "deny";
+	decision: "allow" | "deny" | "abstain";
 	reason: string;
 }
 
@@ -12,20 +12,56 @@ export function buildPrompt(
 	req: PermissionRequest,
 	agent: ClaudeAgent,
 	canDeny: boolean,
+	conversationContext?: string,
 ): string {
 	const info = agent.getDebugInfo();
 	const command =
 		typeof req.tool_input.command === "string" ? req.tool_input.command : "";
 
-	const rules = canDeny
-		? `- If the command is a variation of one of the ALLOWED patterns → allow.
+	const fallthrough = canDeny ? "deny" : "abstain";
+
+	const conversationSection = conversationContext
+		? `\n## Recent conversation\n${conversationContext}\n`
+		: "";
+
+	let rules: string;
+	if (conversationContext) {
+		rules = `1. If the command matches a DENIED pattern → deny. No exceptions, regardless of context.
+2. If the command is a variation of an ALLOWED pattern → allow.
+3. If the command matches neither pattern, allow ONLY if ALL of these are true:
+   - The user clearly requested or implied this action in the conversation
+   - It is a typical development command (build, test, lint, search, read, install, etc.)
+   - It does not access sensitive resources (credentials, .env, auth tokens)
+   - It does not make irreversible system-wide changes
+4. Otherwise → ${fallthrough}.
+5. Only allow commands clearly within the spirit of an existing allowed pattern OR clearly supported by conversation context.`;
+	} else if (canDeny) {
+		rules = `- If the command is a variation of one of the ALLOWED patterns → allow.
 - If the command is a variation of one of the DENIED patterns → deny.
 - If the command is not clearly similar to either set of patterns → deny (fail-closed).
-- Only allow commands that are clearly within the spirit of an existing allowed pattern.`
-		: `- If the command is a variation of one of the ALLOWED patterns → allow.
+- Only allow commands that are clearly within the spirit of an existing allowed pattern.`;
+	} else {
+		rules = `- If the command is a variation of one of the ALLOWED patterns → allow.
 - If the command is NOT clearly similar to an allowed pattern → abstain.
 - Only allow commands that are clearly within the spirit of an existing allowed pattern.
 - You CANNOT deny commands. Your only options are allow or abstain.`;
+	}
+
+	const examples = conversationContext
+		? `
+
+## Examples
+- User: "run the tests" → agent runs \`pytest\` → allow (clear intent, common dev command)
+- User: "check the bundle size" → agent runs \`du -sh dist/\` → allow (clear intent, read-only)
+- User: "install the dependencies" → agent runs \`npm install\` → allow (clear intent, standard workflow)
+- User: "format the code" → agent runs \`prettier --write src/\` → allow (clear intent, common dev tool)
+- User: "check what's listening on port 3000" → agent runs \`lsof -i :3000\` → allow (clear intent, read-only)
+- User: "fix the bug" → agent runs \`curl https://example.com\` → ${fallthrough} (user didn't ask for network requests)
+- User: "deploy this" → agent runs \`rm -rf /tmp/*\` → ${fallthrough} (destructive, not clearly related)
+- Agent runs \`cat .env\` with no relevant user message → ${fallthrough} (no clear intent, sensitive file)
+- Agent runs \`ssh remote-host\` with no relevant context → ${fallthrough} (network access, no clear intent)
+- User: "clean up the build" → agent runs \`rm -rf node_modules/ dist/\` → allow (clear intent, scoped to project)`
+		: "";
 
 	const responseFormat = canDeny
 		? `{"decision": "allow", "reason": "brief explanation"}
@@ -43,7 +79,7 @@ A coding assistant is requesting permission to run a shell command. Your job is
 - Working directory: ${req.cwd}
 - Tool: ${req.tool_name}
 - Command: ${command}
-
+${conversationSection}
 ## Configured permission patterns
 - Allowed patterns: ${JSON.stringify(info.allow)}
 - Denied patterns: ${JSON.stringify(info.deny)}
@@ -51,7 +87,7 @@ A coding assistant is requesting permission to run a shell command. Your job is
 The command did not exactly match any pattern, so you must judge by similarity.
 
 ## Rules
-${rules}
+${rules}${examples}
 
 Respond with ONLY a JSON object in this exact format, no other text:
 ${responseFormat}`;
@@ -71,7 +107,9 @@ export function parseLlmResponse(stdout: string): LlmDecision | null {
 	try {
 		const parsed = JSON.parse(jsonStr) as Record<string, unknown>;
 		if (
-			(parsed.decision === "allow" || parsed.decision === "deny") &&
+			(parsed.decision === "allow" ||
+				parsed.decision === "deny" ||
+				parsed.decision === "abstain") &&
 			typeof parsed.reason === "string"
 		) {
 			return { decision: parsed.decision, reason: parsed.reason };

package/src/providers/claude.ts

@@ -20,14 +20,18 @@ export class ClaudeProvider implements Provider {
 	private model: string;
 	private canDeny: boolean;
 
+	private conversationContext?: string;
+
 	constructor(
 		private agent: ClaudeAgent,
 		config: ClaudeConfig,
 		private verbose: boolean = false,
+		conversationContext?: string,
 	) {
 		this.model = config.model;
 		this.timeoutMs = config.timeout * S_TO_MS;
 		this.canDeny = config.canDeny;
+		this.conversationContext = conversationContext;
 	}
 
 	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
@@ -37,7 +41,12 @@ export class ClaudeProvider implements Provider {
 		if (typeof command !== "string" || command.trim() === "")
 			return { decision: "abstain" };
 
-		const prompt = buildPrompt(req, this.agent, this.canDeny);
+		const prompt = buildPrompt(
+			req,
+			this.agent,
+			this.canDeny,
+			this.conversationContext,
+		);
 
 		// Clear CLAUDECODE env var so claude -p doesn't refuse to run
 		// inside a Claude Code session (tyr is invoked as a hook).
@@ -110,6 +119,10 @@ export class ClaudeProvider implements Provider {
 		const llmDecision = parseLlmResponse(result.stdout);
 		if (!llmDecision) return { decision: "abstain" };
 
+		if (llmDecision.decision === "abstain") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
 		// When canDeny is false, convert deny→abstain so the user gets prompted
 		if (!this.canDeny && llmDecision.decision === "deny") {
 			return { decision: "abstain", reason: llmDecision.reason };

package/src/providers/openrouter.ts

@@ -19,15 +19,19 @@ export class OpenRouterProvider implements Provider {
 	private endpoint: string;
 	private canDeny: boolean;
 
+	private conversationContext?: string;
+
 	constructor(
 		private agent: ClaudeAgent,
 		config: OpenRouterConfig,
 		private verbose: boolean = false,
+		conversationContext?: string,
 	) {
 		this.model = config.model;
 		this.timeoutMs = config.timeout * S_TO_MS;
 		this.canDeny = config.canDeny;
 		this.endpoint = config.endpoint;
+		this.conversationContext = conversationContext;
 	}
 
 	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
@@ -45,7 +49,12 @@ export class OpenRouterProvider implements Provider {
 			return { decision: "abstain" };
 		}
 
-		const prompt = buildPrompt(req, this.agent, this.canDeny);
+		const prompt = buildPrompt(
+			req,
+			this.agent,
+			this.canDeny,
+			this.conversationContext,
+		);
 		const url = `${this.endpoint}/chat/completions`;
 
 		const controller = new AbortController();
@@ -102,6 +111,10 @@ export class OpenRouterProvider implements Provider {
 		const llmDecision = parseLlmResponse(responseText);
 		if (!llmDecision) return { decision: "abstain" };
 
+		if (llmDecision.decision === "abstain") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
 		// When canDeny is false, convert deny→abstain so the user gets prompted
 		if (!this.canDeny && llmDecision.decision === "deny") {
 			return { decision: "abstain", reason: llmDecision.reason };

package/src/transcript.ts

@@ -0,0 +1,97 @@
+import { readFile } from "node:fs/promises";
+
+export interface TranscriptMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+/** Content block within an assistant message. */
+interface ContentBlock {
+	type: string;
+	text?: string;
+}
+
+/** Shape of a single JSONL line in the transcript file. */
+interface TranscriptLine {
+	type: string;
+	isSidechain?: boolean;
+	isMeta?: boolean;
+	message?: {
+		role?: string;
+		content?: string | ContentBlock[];
+	};
+}
+
+/** Read the last N conversation messages from a Claude transcript JSONL file.
+ *  Returns an empty array on any error (graceful degradation). */
+export async function readTranscript(
+	path: string,
+	maxMessages: number,
+): Promise<TranscriptMessage[]> {
+	let text: string;
+	try {
+		text = await readFile(path, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const messages: TranscriptMessage[] = [];
+
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+
+		let entry: TranscriptLine;
+		try {
+			entry = JSON.parse(trimmed) as TranscriptLine;
+		} catch {
+			continue;
+		}
+
+		// Skip non-conversation entries
+		if (entry.type !== "user" && entry.type !== "assistant") continue;
+		if (entry.isSidechain || entry.isMeta) continue;
+		if (!entry.message) continue;
+
+		if (entry.type === "user") {
+			if (typeof entry.message.content !== "string") continue;
+			messages.push({ role: "user", content: entry.message.content });
+		} else {
+			// Assistant: extract text content blocks
+			const content = entry.message.content;
+			if (!Array.isArray(content)) continue;
+			const textParts = content
+				.filter(
+					(block): block is ContentBlock & { text: string } =>
+						block.type === "text" && typeof block.text === "string",
+				)
+				.map((block) => block.text);
+			if (textParts.length === 0) continue;
+			messages.push({ role: "assistant", content: textParts.join("\n") });
+		}
+	}
+
+	return messages.slice(-maxMessages);
+}
+
+const DEFAULT_MAX_CHARS = 500;
+
+/** Format transcript messages for inclusion in an LLM prompt.
+ *  Each message is truncated to maxCharsPerMessage characters.
+ *  Returns an empty string if there are no messages. */
+export function formatTranscriptForPrompt(
+	messages: TranscriptMessage[],
+	maxCharsPerMessage: number = DEFAULT_MAX_CHARS,
+): string {
+	if (messages.length === 0) return "";
+
+	const lines = messages.map((msg) => {
+		const truncated =
+			msg.content.length > maxCharsPerMessage
+				? `${msg.content.slice(0, maxCharsPerMessage)}...`
+				: msg.content;
+		return `[${msg.role}]: ${truncated}`;
+	});
+
+	return lines.join("\n");
+}

package/src/types.ts

@@ -87,6 +87,8 @@ export const TyrConfigSchema = z.object({
 	claude: ClaudeConfigSchema.default(ClaudeConfigSchema.parse({})),
 	/** OpenRouter API provider configuration. */
 	openrouter: OpenRouterConfigSchema.default(OpenRouterConfigSchema.parse({})),
+	/** Include recent conversation messages in LLM judge prompts for better context. */
+	conversationContext: z.boolean().default(false),
 	/** 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.