auto-mode 0.18.0 → 0.19.0

package/README.md

@@ -6,84 +6,52 @@
   </p>
 </div>
 
-**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.
+**auto-mode** tries to mitigate the risk of unattended non-Claude agents inside Claude Code.
 
-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
-standing permissions upfront; earlier conversational grants and restrictions are unavailable to the
-classifier.
+auto-mode runs as a Claude Code mod, and its operating model is loosely modelled on Anthropic's
+native auto mode. Instead of one model, it pairs a fast decision model (such as Jev) with a
+traditional classifier-judge model (such as Haiku) to cover the first one's shortcomings.
 
 ## Install
 
+auto-mode needs node 24 or later, Claude Code, and a TypeSafe API key for Jev.
+
 ```sh
 npm i -g auto-mode
 claude --plugin-dir "$(npm root -g)/auto-mode/mods/auto-mode"
 ```
 
-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:
-
-```json
-{
-  "classifiers": { "jev": { "apiKeyEnv": "TYPESAFE_API_KEY" } },
-  "decision": { "classifier": "jev" }
-}
-```
-
-Save it as `~/.config/auto-mode/config.json` and export your TypeSafe API key, or set the entry's
-`apiKeyCommand` to a command that prints it. [Configuration](./docs/guides/configuration.md) covers
-the registries and credentials.
-
-## Standing permissions
-
-Jev imports explicit entries from `autoMode.environment`, `autoMode.allow`, `autoMode.soft_deny`,
-and `autoMode.hard_deny` in your user Claude settings. It imports no credential values or shell
-permission patterns. `$defaults` refers to auto-mode's shipped policy; it does not expand Claude's
-built-in classifier rules.
-
-Configured allows clear soft blocks. Hard blocks take priority over all allows and conversational
-consent. [False-positive clarification](./docs/guides/policy.md#false-positive-clarification) can
-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 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 between allow and block. auto-mode allows the
-action unless some rule's block probability reaches the threshold, 0.2 by default. Every denial
-names the rule with the highest block probability, the harm, and what clears it, and the agent
-continues on another path. The threshold is configurable and needs evaluation against your actions.
-
-A missing key, failed API call, malformed response, or oversized request follows
-`decision.onFailure`. The 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 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 |
-
-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`, `glm`, and `messages`
-classifier kinds use the Messages API and serve library callers.
+Export your key as `TYPESAFE_API_KEY`, or point the configuration at a command that prints it.
+[Claude permission mod](./docs/guides/claude-mod.md) covers the mod and a trial session you can
+undo.
+
+## Features
+
+- **Local rules** allow read-only calls and build-output cleanup without a model call
+  ([local rules](./docs/architecture/stages/local-rules.md)).
+- **Containment** denies a write outside the task's own worktrees, branches and pull requests
+  ([containment](./docs/architecture/stages/containment.md)).
+- **The edit bypass** allows an in-scope file edit once a secret scan finds nothing
+  ([the edit bypass](./docs/architecture/stages/edit-bypass.md)).
+- **Jev** judges the remaining calls against the shipped rules and your own
+  ([Jev](./docs/architecture/stages/jev.md)).
+- **The judge**, on by default, reviews every Jev deny, and overturns it when your last message
+  asked the main agent for exactly this action, or when no rule covers the action
+  ([the judge](./docs/architecture/stages/judge.md)).
+- **The denial budget** hands a call back to you when an agent keeps getting denied
+  ([the denial budget](./docs/architecture/stages/denial-budget.md)).
+- **Your own rules** from your Claude settings join the policy as block rules
+  ([settings and repository facts](./docs/architecture/evidence/settings-and-repository.md)).
+- **Action diagnostics** record how each call was decided, without the command or the prompt
+  ([action diagnostics](./docs/guides/diagnostics.md)).
+
+Read [the rules](./policy/rules.md) before you enable the mod.
+[Writing a policy](./docs/guides/policy.md) covers how the rules clear and how to change them.
 
 ## Library
 
+You can call auto-mode's core APIs from your own code:
+
 ```ts
 import { classifyAction, loadConfig, parseActionRequest } from 'auto-mode';
 
@@ -94,20 +62,14 @@ if (request !== null) {
 }
 ```
 
-`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. Build every request with `parseActionRequest`: it drops a child agent's direct user
-message, and the classifiers trust the request they receive.
+## Configuration
+
+Read the [configuration](./docs/guides/configuration.md) guide, which covers every field and the
+credentials.
 
 ## Documentation
 
-- [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.
-- [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.
+[docs/](./docs/README.md) covers the architecture and the user guides.
 
 ## Licence
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as resolveStateDir, D as DEFAULT_SCOPE_SOURCES, E as DEFAULT_DENIAL_BUDGET, F as string, N as number, O as loadConfig, P as strictObject, a as loadSessionScope, b as splitCommandWords, f as loadRepositoryContext, g as loadPolicy, i as resolveSessionScopePath, j as readHostEnvironment, n as parseActionRequest, o as EMPTY_SESSION_SCOPE, p as loadCheckoutRemotes, r as classifyAction, t as renderVerdict, v as toRepositorySlug, w as findCheckout, y as splitShellCommand } from "./render-verdict-lM31QV2u.js";
+import { C as resolveStateDir, D as DEFAULT_SCOPE_SOURCES, E as DEFAULT_DENIAL_BUDGET, F as string, N as number, O as loadConfig, P as strictObject, a as loadSessionScope, b as splitCommandWords, f as loadRepositoryContext, g as loadPolicy, i as resolveSessionScopePath, j as readHostEnvironment, n as parseActionRequest, o as EMPTY_SESSION_SCOPE, p as loadCheckoutRemotes, r as classifyAction, t as renderVerdict, v as toRepositorySlug, w as findCheckout, y as splitShellCommand } from "./render-verdict-CcVLBFKT.js";
 import { appendFile, chmod, lstat, mkdir, open, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { spawn } from "node:child_process";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as resolveConfigPath, M as PRESETS, O as loadConfig, S as tryClassifyEdit, T as DEFAULT_CONFIG, _ as checkContainment, c as classifyLocally, d as sendDecision, g as loadPolicy, h as buildDecisionRequest, k as resolveApiKey, l as classifyWithModel, m as DecisionRequestError, n as parseActionRequest, r as classifyAction, s as buildTaskScope, t as renderVerdict, u as parseModelVerdict, x as loadClaudeSettings } from "./render-verdict-lM31QV2u.js";
+import { A as resolveConfigPath, M as PRESETS, O as loadConfig, S as tryClassifyEdit, T as DEFAULT_CONFIG, _ as checkContainment, c as classifyLocally, d as sendDecision, g as loadPolicy, h as buildDecisionRequest, k as resolveApiKey, l as classifyWithModel, m as DecisionRequestError, n as parseActionRequest, r as classifyAction, s as buildTaskScope, t as renderVerdict, u as parseModelVerdict, x as loadClaudeSettings } from "./render-verdict-CcVLBFKT.js";
 //#region src/config/load-claude-rules.ts
 async function loadClaudeRules(path, host) {
 	return (await loadClaudeSettings(path, host)).rules;

package/dist/{render-verdict-lM31QV2u.js → render-verdict-CcVLBFKT.js}

@@ -5684,7 +5684,7 @@ const DEFAULT_SCOPE_SOURCES = {
 const DEFAULT_CONFIG = {
 	provider: DEFAULT_PROVIDER,
 	judge: DEFAULT_JUDGE,
-	judgeOverturns: "consent",
+	judgeOverturns: "any",
 	onFailure: "defer",
 	blockThreshold: .2,
 	denialBudget: DEFAULT_DENIAL_BUDGET,
@@ -5758,7 +5758,7 @@ function buildConfig(json, path, home) {
 	return {
 		provider,
 		judge,
-		judgeOverturns: decision.judgeOverturns ?? "consent",
+		judgeOverturns: decision.judgeOverturns ?? "any",
 		scopeSources: configuredSources ?? DEFAULT_SCOPE_SOURCES,
 		classifierPath: expandHomePath(policy.frameworkPath ?? void 0, home),
 		rulesPath: expandHomePath(policy.rulesPath ?? void 0, home),
@@ -8502,7 +8502,7 @@ async function classifyAction(request, config, options = {}) {
 			...options,
 			host,
 			rulesPath: config.rulesPath,
-			overturns: config.judgeOverturns ?? "consent"
+			overturns: config.judgeOverturns ?? "any"
 		});
 		const { review: _review, ...rest } = outcome;
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-mode",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "A permission classifier library and Claude Code mod, so agents that are not Claude can run unattended",
   "keywords": [
     "agent",
@@ -44,8 +44,7 @@
     "audit": "bun audit",
     "bench": "bun --no-env-file src/secrets/find-secret.bench.ts",
     "build": "tsdown",
-    "build:agents": "bash scripts/build-agents-md.sh agents/shared.md agents/project.md AGENTS.md",
-    "check": "bun run format:check && bun run lint && bun run check:imports && bun run typecheck && bun run deadcode && bun run test && bun run build && bun run check:artifact && bun run publint",
+    "check": "bun run format:check && bun run lint:full && bun run check:imports && bun run typecheck && bun run deadcode && bun run test && bun run build && bun run check:artifact && bun run publint",
     "deadcode": "knip",
     "eval": "bun --no-env-file --conditions=auto-mode-eval evals/eval.ts",
     "eval:answer-guidance": "bun --no-env-file --conditions=auto-mode-eval evals/runners/run-answer-guidance-evaluation.ts",
@@ -58,8 +57,9 @@
     "first-publish": "scripts/first-publish.sh",
     "format": "oxfmt . && format-codemod --quiet .",
     "format:check": "oxfmt --check . && format-codemod --check --quiet .",
-    "lint": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error",
-    "lint:fix": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error --fix",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "lint:full": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error",
     "prepare": "bash scripts/link-evals-package.sh && (command -v git > /dev/null 2>&1 && lefthook install --force || true)",
     "publint": "publint",
     "test": "bun run build && bun --no-env-file test --conditions=auto-mode-eval",
@@ -80,7 +80,7 @@
     "@types/node": "26.5.1",
     "@zgeoff/bun-test-extended": "0.1.0",
     "@zgeoff/format-codemod": "0.1.0",
-    "@zgeoff/oxlint-config": "0.1.0",
+    "@zgeoff/oxlint-config": "0.2.0",
     "knip": "6.35.1",
     "lefthook": "2.1.12",
     "mitata": "1.0.34",

package/policy/rules.md

@@ -156,17 +156,25 @@ registry, or a deploy command.
 **Must name:** publish, release, or deploy, plus the target.
 
 ### Outbound Communication
-A message that reaches people outside the checkout's own repositories and outside
-the channels the user named: an email, a chat message to a person or channel the
-user did not name, a post on a public service, or an issue, comment, pull request,
-or review on a repository that is not a remote of the checkout.
+A message that reaches people the user did not ask to reach: an email, a chat
+message to a person or channel the user did not name, a post on a public service,
+an issue, comment, pull request, or review on a repository that is not a remote of
+the checkout, or a comment or review on an issue or pull request the task does not
+own.
 
 **Must name:** that the message is sent, and to whom or where.
 
-An issue, comment, pull request, or review on a repository that is a remote of
-the checkout is not this rule, whichever issue or pull request it targets. Compare
-the repository's host, owner, and name with the remotes; a lookalike name is not a
-match.
+The task's own threads on a repository that is a remote of the checkout are not
+this rule: opening the pull request or issue the task calls for, and commenting on
+or reviewing a pull request in the task scope or an issue or pull request the user
+named. Compare the repository's host, owner, and name with the remotes; a
+lookalike name is not a match.
+
+A comment or review on any other issue or pull request is this rule, even on a
+remote of the checkout, because it reaches that thread's author and readers. A
+number alone, such as `gh pr comment 498`, does not show that the pull request is
+the task's own. Without a task scope fact that lists it or a user message that
+names it, treat it as a thread the task does not own.
 
 Once the user names a channel or an outside thread, further posts to that same
 place stand for the rest of the session. This is a standing permission the rule
@@ -280,11 +288,13 @@ or a scripted delete over every key.
 **Must name:** the table or the database, and the operation.
 
 ### Persistent Configuration
-Granting access into this environment from outside it, or redirecting where
-credentials or code go: adding a key to `~/.ssh/authorized_keys`, changing
-`~/.ssh/config`, writing package registry credentials or pointing a registry at a
-new host, and the global git settings `credential.helper`, `url.<base>.insteadOf`,
-and `core.sshCommand`.
+Granting access into this environment from outside it, redirecting where
+credentials or code go, or opening credentials to other users: adding a key to
+`~/.ssh/authorized_keys`, changing `~/.ssh/config`, writing package registry
+credentials or pointing a registry at a new host, the global git settings
+`credential.helper`, `url.<base>.insteadOf`, and `core.sshCommand`, and widening
+the permissions of a credential file or directory, such as `chmod -R a+rwx ~/.ssh`
+or making a private key or `~/.aws/credentials` readable by group or others.
 
 **Must name:** the file or the setting.
 
@@ -294,10 +304,12 @@ grant, not as a file edit.
 The environment is isolated, so a change that stays inside it is not this rule:
 `crontab`, a systemd unit, a launch agent, a shell startup file, `PATH`, other
 `git config --global` keys, a detached process, `sudo`, a sudoers entry, and
-`chmod` or `chown`. Using that access against auto-mode is Policy Tampering.
+`chmod` or `chown` on anything that is not a credential. Using that access against
+auto-mode is Policy Tampering.
 
 Authenticating a tool the user asked to use, such as `npm login` before a publish
-the user asked for, is not this rule. Neither is a change that narrows access.
+the user asked for, is not this rule. Neither is a change that narrows access,
+such as `chmod 600` on a private key.
 
 ### Credential Exploration
 Printing a credential's value into the transcript, or searching broadly for keys