auto-mode 0.4.4 → 0.6.0

package/README.md

@@ -6,9 +6,10 @@
   </p>
 </div>
 
-**auto-mode** judges coding-agent tool calls through a permission hook. It returns allow, deny, or
-no verdict to Claude Code, Codex, and Muse Code. Local rules settle read-only actions and build
-cleanup; Jev evaluates the remaining actions against a written policy.
+**auto-mode** judges the tool calls that Claude Code would prompt for. It is a core library and a
+Claude Code mod. The mod returns allow, deny, or no verdict before the permission dialog appears.
+Local rules settle read-only actions and build cleanup; Jev evaluates the remaining actions against
+a written policy.
 
 The Jev request includes the policy, your configured environment and permissions, the complete
 proposed action, and the last direct user message. It excludes the rest of the session. Configure
@@ -19,12 +20,12 @@ classifier.
 
 ```sh
 npm i -g auto-mode
-auto-mode init claude --event permission-request
+claude --plugin-dir "$(npm root -g)/auto-mode/mods/auto-mode"
 ```
 
-Paste the printed hook entry into the file it identifies. `init` prints configuration and never
-writes into a harness's settings. [Harnesses](./docs/guides/harnesses.md) covers registration for
-each harness.
+The package ships the mod in `mods/auto-mode`. The mod runs the `auto-mode` executable on `PATH`;
+its `command` option takes another executable. [Claude permission mod](./docs/guides/claude-mod.md)
+covers the mod, its time limits, and a trial session.
 
 Create the classifier configuration:
 
@@ -35,8 +36,8 @@ Create the classifier configuration:
 }
 ```
 
-Save it as `~/.config/auto-mode/config.json` and export your TypeSafe API key. Hooks that run with a
-scrubbed environment need `provider.apiKeyCommand` instead.
+Save it as `~/.config/auto-mode/config.json` and export your TypeSafe API key, or set
+`provider.apiKeyCommand` to a command that prints it.
 [Configuration](./docs/guides/configuration.md) covers credentials and provider overrides.
 
 ## Standing permissions
@@ -51,44 +52,59 @@ consent. [False-positive clarification](./docs/guides/policy.md#false-positive-c
 clear Policy Tampering and Audit Tampering. The last direct user message can supply the exact action
 and target that a soft block needs; replies such as “go ahead” cannot supply an unseen proposal.
 
-Read [the policy](./policy/rules.md) before you enable the hook.
+Read [the policy](./policy/rules.md) before you enable the mod.
 [Writing a policy](./docs/guides/policy.md) covers the precedence and the limits of an action-only
 assessment.
 
 ## Decisions and failures
 
 Jev evaluates each named rule with a typed choice. auto-mode returns a denial for a confident block,
-approval when every rule confidently allows the action, and manual approval for uncertain decisions.
-The confidence threshold is configurable and needs evaluation against your actions.
+approval when every rule confidently allows the action, and a denial for uncertain decisions. Every
+denial names its rule, the harm, and what clears it, and the agent continues on another path. The
+confidence threshold is configurable and needs evaluation against your actions.
 
 A missing key, failed API call, malformed response, or oversized request follows `onFailure`. The
-default `defer` writes no verdict and leaves the harness to decide; `deny` fails closed. Failures
-write a diagnostic to stderr. auto-mode never truncates a Jev action to make it fit.
+default `defer` writes no verdict and keeps the prompt; `deny` fails closed. Failures write a
+diagnostic to stderr. auto-mode never truncates a Jev action to make it fit.
 
 ## Commands
 
 | Command                      | Effect                                    |
 | ---------------------------- | ----------------------------------------- |
-| `auto-mode run`              | Read a hook payload and write a verdict   |
+| `auto-mode run`              | Read a mod request and write a verdict    |
 | `auto-mode run --explain`    | Write decision details to stderr          |
 | `auto-mode run --local-only` | Skip the model tier                       |
 | `auto-mode run --jev-only`   | Require Jev with a 5-second API timeout   |
 | `auto-mode print-prompt`     | Print the selected provider's base policy |
-| `auto-mode init <harness>`   | Print a hook entry                        |
 
-Existing `spark`, `claude`, and `glm` presets use the Messages API and conversation history. Select
-`jev` explicitly to change an existing provider configuration.
+The mod evaluates only ask decisions and preserves existing allow and deny decisions. It runs the
+CLI as a bounded child process with `--jev-only`. The `spark`, `claude`, and `glm` presets use the
+Messages API and serve library callers.
 
-The optional [Claude permission mod](./docs/guides/claude-mod.md) evaluates ask decisions before the
-permission dialog. It preserves existing allow and deny decisions and has a bounded child process.
+## Library
+
+```ts
+import { classifyAction, loadConfig, parseActionRequest } from 'auto-mode';
+
+const request = parseActionRequest(body);
+
+if (request !== null) {
+  const outcome = await classifyAction(request, await loadConfig());
+}
+```
+
+`classifyAction` runs both tiers and returns the verdict, a note, and diagnostics. A request carries
+the session identity, the action, and the task context; `parseActionRequest` builds one from the
+mod's JSON.
 
 ## Documentation
 
-- [Architecture](./docs/architecture/overview.md) covers the request, decision combination, and wire
-  contract.
+- [Architecture](./docs/architecture/overview.md) covers the request, decision combination, and the
+  mod contract.
 - [Configuration](./docs/guides/configuration.md) covers every setting and the imported Claude
   rules.
-- [Harnesses](./docs/guides/harnesses.md) covers registration and hook trust.
+- [Claude permission mod](./docs/guides/claude-mod.md) covers the request, the verdict, and the time
+  limits.
 - [Writing a policy](./docs/guides/policy.md) covers rule edits and evaluation.
 
 ## Licence

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as SETTINGS_PATHS, d as renderVerdict, f as parsePayload, g as loadConfig, i as loadClaudeRules, l as SETUP_NOTES, n as classifyWithModel, o as loadPolicy, s as EVENT_NOTES, t as classifyLocally, u as buildHookConfig, v as resolveConfigPath } from "./classify-locally-BdXQYjfj.js";
+import { n as parseActionRequest, r as classifyAction, s as loadPolicy, t as renderVerdict, u as loadConfig } from "./render-verdict-9pnm4JBS.js";
 import { appendFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -24,15 +24,12 @@ async function writeActionDiagnostic(payload, entry) {
 	const stateDir = stateHome === void 0 || stateHome === "" ? join(homedir(), ".local", "state") : stateHome;
 	const path = process.env["AUTO_MODE_DIAGNOSTICS_PATH"] ?? join(stateDir, "auto-mode", "actions.jsonl");
 	if (path === "") return;
-	const actionID = payload.raw["tool_use_id"] ?? payload.raw["prompt_id"] ?? payload.raw["turn_id"];
 	const record = {
-		schemaVersion: 1,
+		schemaVersion: 2,
 		time: (/* @__PURE__ */ new Date()).toISOString(),
 		invocationID: entry.invocationID,
-		sessionHash: toHash(payload.sessionId),
-		actionHash: typeof actionID === "string" ? toHash(actionID) : null,
-		harness: payload.harness,
-		event: payload.event,
+		sessionHash: toHash(payload.sessionID),
+		actionHash: payload.toolUseID === void 0 ? null : toHash(payload.toolUseID),
 		status: entry.status,
 		verdict: entry.verdict ?? null,
 		diagnostics: entry.diagnostics ?? null
@@ -52,17 +49,15 @@ function toHash(value) {
 }
 //#endregion
 //#region src/cli.ts
-const USAGE = `auto-mode — a permission classifier that runs as a hook
+const USAGE = `auto-mode — a permission classifier for the auto-mode Claude Code mod
 
 Usage:
-  auto-mode run              Read a hook payload on stdin, write a verdict on stdout
+  auto-mode run              Read an action request on stdin, write a verdict on stdout
   auto-mode print-prompt     Print the system prompt the classifier receives
-  auto-mode init <harness>   Print the hook entry to add: claude, codex or muse
 
 Options:
   --classifier <path>   Use this framework file instead of the shipped one
   --rules <path>        Use this rule list instead of the shipped one
-  --event <event>       With init: pre-tool-use, the default, or permission-request
   --explain             With run: also write the reasoning to stderr
   --local-only          With run: skip the model tier
   --jev-only            With run: require Jev and cap its API timeout at 5 seconds
@@ -79,10 +74,10 @@ async function run(explain, localOnly, jevOnly, deadline) {
 	} catch {
 		return printNote(explain, "stdin is not JSON, so no verdict");
 	}
-	const payload = parsePayload(body);
-	if (payload === null) return printNote(explain, "not a tool gate this hook judges, so no verdict");
+	const request = parseActionRequest(body);
+	if (request === null) return printNote(explain, "not an action request this classifier judges, so no verdict");
 	const invocationID = randomUUID();
-	await writeActionDiagnostic(payload, {
+	await writeActionDiagnostic(request, {
 		invocationID,
 		status: "started"
 	});
@@ -90,64 +85,30 @@ async function run(explain, localOnly, jevOnly, deadline) {
 	try {
 		loaded = await loadConfig();
 	} catch {
-		await writeActionDiagnostic(payload, {
+		await writeActionDiagnostic(request, {
 			invocationID,
 			status: "failure",
 			verdict: "defer"
 		});
-		return printNote(true, "configuration unreadable; deferring to the harness");
+		return printNote(true, "configuration unreadable; no verdict");
 	}
 	const config = jevOnly ? buildJevOnlyConfig(loaded) : loaded;
 	if (config === null) {
-		await writeActionDiagnostic(payload, {
+		await writeActionDiagnostic(request, {
 			invocationID,
 			status: "failure",
 			verdict: "defer"
 		});
-		return printNote(true, "Jev-only evaluation requires system-one; deferring to the harness");
-	}
-	let configured = null;
-	if (config.provider.protocol === "system-one") try {
-		configured = await loadClaudeRules(config.claudeSettingsPath);
-	} catch {
-		if (config.onFailure === "deny") writeVerdict(payload.event, {
-			kind: "deny",
-			rule: "Classifier Unavailable",
-			reason: "Claude settings unreadable"
-		});
-		await writeActionDiagnostic(payload, {
-			invocationID,
-			status: "failure",
-			verdict: config.onFailure === "deny" ? "deny" : "defer"
-		});
-		return printNote(true, "Claude settings unreadable; classifier unavailable");
-	}
-	const local = configured !== null && (configured.hard_deny.length > 0 || configured.soft_deny.length > 0) ? { kind: "escalate" } : classifyLocally(payload);
-	if (local.kind === "allow") {
-		writeVerdict(payload.event, { kind: "allow" });
-		await writeActionDiagnostic(payload, {
-			invocationID,
-			status: "allow",
-			verdict: "allow"
-		});
-		return printNote(explain, `allowed by ${local.exception} (${payload.harness}, local)`);
-	}
-	if (localOnly) {
-		await writeActionDiagnostic(payload, {
-			invocationID,
-			status: "skipped",
-			verdict: "defer"
-		});
-		return printNote(explain, `${payload.toolName} needs the model tier, which --local-only skipped`);
+		return printNote(true, "Jev-only evaluation requires system-one; no verdict");
 	}
 	const deadlineAt = deadline === void 0 ? void 0 : Number(deadline);
 	if (deadlineAt !== void 0 && (!jevOnly || !Number.isSafeInteger(deadlineAt) || deadlineAt <= 0)) {
-		await writeActionDiagnostic(payload, {
+		await writeActionDiagnostic(request, {
 			invocationID,
 			status: "failure",
 			verdict: "defer"
 		});
-		return printNote(true, "invalid Jev evaluation deadline; deferring to the harness");
+		return printNote(true, "invalid Jev evaluation deadline; no verdict");
 	}
 	const controller = new AbortController();
 	const stopEvaluation = () => {
@@ -158,14 +119,15 @@ async function run(explain, localOnly, jevOnly, deadline) {
 		process.on("SIGINT", stopEvaluation);
 	}
 	try {
-		const outcome = await classifyWithModel(payload, config, {
+		const outcome = await classifyAction(request, config, {
+			localOnly,
 			deadlineAt,
 			signal: controller.signal
 		});
-		if (outcome.verdict !== null) writeVerdict(payload.event, outcome.verdict);
-		await writeActionDiagnostic(payload, {
+		if (outcome.verdict !== null) writeVerdict(outcome.verdict);
+		await writeActionDiagnostic(request, {
 			invocationID,
-			status: outcome.diagnostics?.status ?? outcome.verdict?.kind ?? "failure",
+			status: outcome.status,
 			verdict: outcome.verdict?.kind ?? "defer",
 			...outcome.diagnostics === void 0 ? {} : { diagnostics: outcome.diagnostics }
 		});
@@ -175,18 +137,13 @@ async function run(explain, localOnly, jevOnly, deadline) {
 		process.off("SIGINT", stopEvaluation);
 	}
 }
-function writeVerdict(event, verdict) {
-	const rendered = renderVerdict(event, verdict);
-	if (rendered !== null) process.stdout.write(rendered);
+function writeVerdict(verdict) {
+	process.stdout.write(renderVerdict(verdict));
 }
 function printNote(explain, message) {
 	if (explain) process.stderr.write(`auto-mode: ${message}\n`);
 	return 0;
 }
-const HOOK_EVENTS = {
-	"pre-tool-use": "PreToolUse",
-	"permission-request": "PermissionRequest"
-};
 async function main(argv) {
 	const args = parseArgs({
 		args: [...argv],
@@ -194,7 +151,6 @@ async function main(argv) {
 		options: {
 			classifier: { type: "string" },
 			rules: { type: "string" },
-			event: { type: "string" },
 			explain: { type: "boolean" },
 			"local-only": { type: "boolean" },
 			"jev-only": { type: "boolean" },
@@ -213,28 +169,7 @@ async function main(argv) {
 	if (command === "run") try {
 		return await run(args.values.explain === true, args.values["local-only"] === true, args.values["jev-only"] === true, args.values["evaluation-deadline"]);
 	} catch {
-		process.stderr.write("auto-mode: configuration unreadable; deferring to the harness\n");
-		return 0;
-	}
-	if (command === "init") {
-		const [, harness] = args.positionals;
-		if (harness !== "claude" && harness !== "codex" && harness !== "muse") {
-			process.stderr.write("auto-mode init: name a harness — claude, codex or muse\n");
-			return 2;
-		}
-		const event = HOOK_EVENTS[args.values.event ?? "pre-tool-use"];
-		if (event === void 0) {
-			process.stderr.write("auto-mode init: --event takes pre-tool-use or permission-request\n");
-			return 2;
-		}
-		if (event === "PermissionRequest" && harness !== "claude") {
-			process.stderr.write(`auto-mode init: only Claude Code sends PermissionRequest\n`);
-			return 2;
-		}
-		process.stdout.write(`# Add this to ${SETTINGS_PATHS[harness]}\n`);
-		process.stdout.write(`# Configuration lives at ${resolveConfigPath()}\n`);
-		process.stdout.write(`${buildHookConfig(harness, `${process.execPath} ${process.argv[1] ?? "auto-mode"} run`, event)}\n`);
-		for (const line of [...SETUP_NOTES[harness], ...EVENT_NOTES[event]]) process.stdout.write(`# ${line}\n`);
+		process.stderr.write("auto-mode: configuration unreadable; no verdict\n");
 		return 0;
 	}
 	if (command === "print-prompt") {

package/dist/index.d.ts

@@ -19,7 +19,6 @@ interface Config {
   readonly provider: ProviderConfig;
   readonly classifierPath?: string | undefined;
   readonly rulesPath?: string | undefined;
-  readonly transcriptEntries: number;
   readonly onFailure: 'defer' | 'deny';
   readonly claudeSettingsPath?: string | null | undefined;
   readonly minConfidence?: number | undefined;
@@ -30,9 +29,7 @@ export declare function resolveConfigPath(): string;
 export declare function loadConfig(path?: string): Promise<Config>;
 export declare function resolveApiKey(provider: ProviderConfig, options?: EvaluationOptions): Promise<string | null>;
 //#endregion
-//#region src/harness/types.d.ts
-type Harness = 'claude' | 'codex' | 'muse';
-type HookEvent = 'PreToolUse' | 'PermissionRequest';
+//#region src/request/types.d.ts
 interface UserTask {
   readonly text: string;
   readonly origin: 'composer' | 'bridge' | 'sdk';
@@ -50,40 +47,22 @@ interface DecisionContext {
     readonly reason: 'unavailable' | 'budget';
   }[];
 }
-interface HookPayload {
-  readonly harness: Harness;
-  readonly event: HookEvent;
-  readonly sessionId: string;
+interface ActionRequest {
+  readonly sessionID: string;
+  readonly toolUseID?: string | undefined;
   readonly cwd: string;
   readonly toolName: string;
   readonly toolInput: Readonly<Record<string, unknown>>;
-  readonly transcriptPath?: string | undefined;
   readonly decisionContext?: DecisionContext | undefined;
-  readonly raw: Readonly<Record<string, unknown>>;
 }
 type Verdict = {
   readonly kind: 'allow';
-} | {
-  readonly kind: 'ask';
 } | {
   readonly kind: 'deny';
   readonly rule: string;
   readonly reason: string;
 };
 //#endregion
-//#region src/harness/detect-harness.d.ts
-export declare function detectHarness(payload: Readonly<Record<string, unknown>>): Harness | null;
-//#endregion
-//#region src/harness/parse-payload.d.ts
-export declare function parsePayload(body: unknown): HookPayload | null;
-//#endregion
-//#region src/harness/render-verdict.d.ts
-export declare function renderVerdict(event: HookEvent, verdict: Verdict): string | null;
-//#endregion
-//#region src/install/hook-config.d.ts
-export declare function buildHookConfig(harness: Harness, command: string, event?: HookEvent): string;
-export declare const SETTINGS_PATHS: Readonly<Record<Harness, string>>;
-//#endregion
 //#region src/model/types.d.ts
 interface DecisionRule {
   readonly name: string;
@@ -99,7 +78,7 @@ interface DecisionAnswer {
 }
 type DecisionFailureReason = 'request-too-large' | 'aborted' | 'network' | 'http-status' | 'invalid-response';
 interface DecisionDiagnostics {
-  readonly status: 'allow' | 'deny' | 'ask' | 'failure' | 'timeout' | 'cancelled';
+  readonly status: 'allow' | 'deny' | 'failure' | 'timeout' | 'cancelled';
   readonly stage: 'credential' | 'evidence' | 'request' | 'response';
   readonly keyResolved: boolean;
   readonly keySource: 'environment' | 'command' | 'none';
@@ -117,6 +96,19 @@ interface DecisionDiagnostics {
   }[];
 }
 //#endregion
+//#region src/classify-action.d.ts
+interface ActionOutcome {
+  readonly verdict: Verdict | null;
+  readonly note: string;
+  readonly status: 'allow' | 'skipped' | 'failure' | DecisionDiagnostics['status'];
+  readonly unavailable?: boolean;
+  readonly diagnostics?: DecisionDiagnostics;
+}
+interface ClassifyOptions extends EvaluationOptions {
+  readonly localOnly?: boolean;
+}
+export declare function classifyAction(request: ActionRequest, config: Config, options?: ClassifyOptions): Promise<ActionOutcome>;
+//#endregion
 //#region src/model/classify-with-model.d.ts
 interface ModelOutcome {
   readonly verdict: Verdict | null;
@@ -124,7 +116,7 @@ interface ModelOutcome {
   readonly unavailable?: boolean;
   readonly diagnostics?: DecisionDiagnostics;
 }
-export declare function classifyWithModel(payload: HookPayload, config: Config, options?: EvaluationOptions): Promise<ModelOutcome>;
+export declare function classifyWithModel(payload: ActionRequest, config: Config, options?: EvaluationOptions): Promise<ModelOutcome>;
 //#endregion
 //#region src/model/parse-verdict.d.ts
 export declare function parseModelVerdict(text: string): Verdict;
@@ -136,6 +128,12 @@ interface PolicyPaths {
 }
 export declare function loadPolicy(paths?: PolicyPaths, framework?: 'classifier.md' | 'decision.md'): Promise<string>;
 //#endregion
+//#region src/request/parse-action-request.d.ts
+export declare function parseActionRequest(body: unknown): ActionRequest | null;
+//#endregion
+//#region src/request/render-verdict.d.ts
+export declare function renderVerdict(verdict: Verdict): string;
+//#endregion
 //#region src/rules/classify-locally.d.ts
 type LocalVerdict = {
   readonly kind: 'allow';
@@ -143,13 +141,6 @@ type LocalVerdict = {
 } | {
   readonly kind: 'escalate';
 };
-export declare function classifyLocally(payload: HookPayload): LocalVerdict;
-//#endregion
-//#region src/transcript/read-transcript.d.ts
-interface TranscriptEntry {
-  readonly role: string;
-  readonly text: string;
-}
-export declare function readTranscript(path: string | undefined, limit: number): Promise<readonly TranscriptEntry[]>;
+export declare function classifyLocally(payload: ActionRequest): LocalVerdict;
 //#endregion
-export type { Config, Harness, HookEvent, HookPayload, LocalVerdict, ModelOutcome, PolicyPaths, ProviderConfig, TranscriptEntry, Verdict };
+export type { ActionOutcome, ActionRequest, ClassifyOptions, Config, DecisionContext, LocalVerdict, ModelOutcome, PolicyPaths, ProviderConfig, Verdict };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { _ as resolveApiKey, a as readTranscript, c as SETTINGS_PATHS, d as renderVerdict, f as parsePayload, g as loadConfig, h as PRESETS, m as DEFAULT_CONFIG, n as classifyWithModel, o as loadPolicy, p as detectHarness, r as parseModelVerdict, t as classifyLocally, u as buildHookConfig, v as resolveConfigPath } from "./classify-locally-BdXQYjfj.js";
-export { DEFAULT_CONFIG, PRESETS, SETTINGS_PATHS, buildHookConfig, classifyLocally, classifyWithModel, detectHarness, loadConfig, loadPolicy, parseModelVerdict, parsePayload, readTranscript, renderVerdict, resolveApiKey, resolveConfigPath };
+import { a as classifyWithModel, c as DEFAULT_CONFIG, d as resolveApiKey, f as resolveConfigPath, i as classifyLocally, l as PRESETS, n as parseActionRequest, o as parseModelVerdict, r as classifyAction, s as loadPolicy, t as renderVerdict, u as loadConfig } from "./render-verdict-9pnm4JBS.js";
+export { DEFAULT_CONFIG, PRESETS, classifyAction, classifyLocally, classifyWithModel, loadConfig, loadPolicy, parseActionRequest, parseModelVerdict, renderVerdict, resolveApiKey, resolveConfigPath };