assent-cli 0.0.0-stage → 0.6.1

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# assent-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command line agents use to talk to Assent: ask the person a question and wait for the answer, record runs, write notes and tasks, take shared locks, check standing rules and hand work to other agents. Every command prints one JSON line; `--get <field>` prints a single field, for shell scripts.
+
+## Install
+
+Needs Node.js 20 or later.
+
+    npm install -g assent-cli
+    assent --version
+
+## Configure
+
+Create an agent in Assent (Agents), and copy its agent key (it starts with `oak_`; Assent shows it once). Then either set it in the environment:
+
+    export ASSENT_AGENT_KEY=oak_...
+
+or write it to `~/.assent/config.json` (mode 600):
+
+    { "agentKey": "oak_..." }
+
+Requests go to the hosted Assent service unless you set `ASSENT_API_URL` (or `apiUrl` in the config file). The URL must use https (plain http only for localhost), and redirects are refused, so the agent key is never sent in the clear or to another host.
+
+| Setting | What it does |
+|---|---|
+| `ASSENT_AGENT_KEY` | The agent key. Overrides `agentKey` in the config file. |
+| `ASSENT_API_URL` | The Assent API to talk to. Overrides `apiUrl` in the config file. Default `https://ordia-api.specvista.com/api/v1`. |
+| `ASSENT_CONFIG` | Path of the config file to read instead of `~/.assent/config.json`, for example one file per agent. |
+| `ASSENT_TIMEOUT_MS` | Request timeout in milliseconds. Default 10000. |
+| `ASSENT_RUN_UUID` | Run that `ask`, `task add`, `note` and `handoff` link their new item to when `--run` is not given. |
+| `ASSENT_HOOK_TIMEOUT_MS` | Timeout for each request `assent hook pre-tool-use` makes. Default 3000. |
+| `ASSENT_HOOK_WAIT_SECONDS` | How long `assent hook pre-tool-use --ask` waits for the person. Overrides `hook.waitSeconds` in the config file. Default 120. |
+
+## Examples
+
+    RUN=$(assent run start --summary "job scan" --get uuid)
+    assent run progress "$RUN" --done 3 --total 7 --label "Race entries"
+    assent run finish "$RUN" --exit-code 0 --log-file run.log
+
+    assent ask --title "Submit 2 applications" --item "01:Acme, Staff Engineer" --action "submit:Submit selected:primary" --action "skip:Skip all" --dedupe jobs:2026-09-29
+    assent ask --kind pay --title "Pay: Leeds Half" --url https://example.com/entry --due "2026-10-20 18:00"
+    assent ask --kind reply --title "Reply to Ada" --draft-file ./reply.txt --dedupe reply:ada:42
+    assent ask --title "Deploy now?" --wait --timeout 600
+    assent answers
+    assent picked-up "$TASK"
+
+    assent attach ./report.pdf --get uuid
+    assent ask --title "Review the report" --item "r1:Quarterly report" --attach r1:./report.pdf
+
+    assent task add --title "Renew the iOS certificate" --why "It expires on Friday" --due 2026-10-15T17:00 --remind "2026-10-15 09:30"
+    assent task update "$TASK" --due 2026-10-16T12:00 --remind none
+    assent note --title "Scan results" --content-file ./results.md --tag jobs
+
+    assent lock acquire deploy:web --ttl 45 --wait 90 && deploy; assent lock release deploy:web
+    assent handoff --to "Release checker" --title "3 builds to verify" --detail ./builds.csv
+
+Run `assent help` for every command and option.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `whoami` | Show the agent this key belongs to. |
+| `run start`, `run progress`, `run finish`, `run defer` | Record a run, show its progress on the phone, finish it with an exit code or status (optionally with a redacted log tail), or show it as deferred until a retry time. |
+| `ask` | Ask the person: approve, todo, pay, login, code or reply. Items, actions, fields, badges, links, attachments, grouping into one decision card, due and reminder times, `--dedupe`, and `--wait` to block until answered. |
+| `attach` | Upload a file (pdf, png, jpeg, gif, webp, txt, md; at most 10 MB) and print its uuid, once the owner turns attachments on for this agent. |
+| `answers`, `picked-up` | List answered asks not picked up yet, and mark one as acted on. |
+| `task add`, `task update`, `task resolve`, `task get`, `task item-result`, `task item-status` | Create and manage tasks, and report per-item outcomes as they finish. `task add --parent <ask-uuid> --parent-item <item-id>` links a to-do to one item of your own ask, so finishing either one finishes both. |
+| `note`, `note update` | Write or update a note. |
+| `link` | Link two items (note, task, run, agent). |
+| `memory get` | Pinned memory notes shared with this agent. |
+| `lock acquire`, `lock release` | Shared locks between agents. |
+| `handoff`, `handoffs`, `handoffs done` | Hand work to another agent and work through hand-offs given to you. |
+| `project get`, `project overview` | Read a project the owner linked this agent to. |
+| `plan create`, `plan get`, `plan sessions` | Create a plan of scheduled sessions and update them. |
+| `rules check`, `rules list`, `rules add --deny`, `rules remove` | Check the person's standing rules before acting, and add deny rules for this agent. |
+| `hook pre-tool-use [--ask]` | Claude Code PreToolUse hook backed by the person's standing rules; with `--ask`, risky calls wait for the person in Assent. |
+| `hook claude-code install`, `hook claude-code uninstall` | Add or remove that hook in Claude Code settings, showing the change first. |
+| `mcp` | A stdio MCP server that forwards every message to the Assent MCP endpoint with this agent key. |
+
+Due and reminder times take a date and time, `2026-10-15T17:00` or `2026-10-15 17:00` (this computer's time zone), or with an offset such as `2026-10-15T17:00:00+01:00`. A bare date such as `2026-10-15` means 09:00 that day in your Assent time zone, and prints a warning on stderr. `--remind` sets when the reminder push goes out: for a to-do (`task add`, or `ask --kind todo`) it is sent at that exact moment, even in quiet hours; for other asks a reminder that falls in quiet hours waits until they end. Without `--remind`, Assent reminds at the due time.
+
+A reply ask carries a draft message (`--draft text`, or `--draft-file path`, or `--draft-file -` for stdin; at most 4000 characters). The person can edit it in Assent and taps Send or Skip; Send answers with `answer.value`, the final text to send.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | OK |
+| 1 | Error |
+| 2 | Usage error |
+| 3 | Conflict: lock held, already answered or expired |
+| 4 | Not found |
+| 5 | Not configured or unauthorised |
+| 6 | `--wait` timed out |
+| 10 | `rules check` found a deny rule |
+| 11 | `rules check` found no rule: ask the person |
+| 69 | Assent unreachable: network failure, timeout, rate limit or a 5xx |
+
+Scripts should treat anything other than 0 (and 3 for locks) as "Assent unavailable, carry on as before".
+
+## Standing rules
+
+The person can answer an approve ask with Always or Never (for 1 day, 7 days, 30 days or with no expiry). That creates a standing rule for the agent that asked and the ask's action. Name what the ask is about so the rule is reusable:
+
+    assent ask --title "Deploy the web app" --rule-action deploy:web --target production --action "go:Deploy:primary" --action "hold:Not now" --wait
+
+A later ask from the same agent with a matching action and target comes back already answered, so `--wait` returns at once. To decide before asking at all:
+
+    assent rules check --action post --target linkedin --summary "Post the weekly update"
+    case $? in 0) post_it ;; 10) echo "not allowed" ;; 11) assent ask --title "Post the weekly update?" --rule-action post --target linkedin ;; *) echo "Assent unavailable" ;; esac
+
+Deny always beats allow; otherwise the most specific rule wins (this agent over every agent, a target over none, the longer pattern). Patterns use `*` as a wildcard and ignore case. Agents can only add deny rules for themselves (`rules add --deny --action Bash --target "git push*" --reason "Pushing deploys" --expires 30d`); allow rules come only from the person.
+
+## Claude Code hook
+
+`assent hook pre-tool-use` reads a Claude Code PreToolUse event on stdin, checks the tool call against the person's standing rules and prints the hook decision. The action is the tool name (`Bash`, `Edit`, `Write`, `WebFetch`, an MCP tool name and so on) and the target is the command, file path, URL or query.
+
+An allow is only honoured when the target is exactly what will run: if a secret had to be redacted, the target is longer than 4000 characters, or a shell command is anything but one simple command (any of `;`, `&`, `|`, `$`, a backtick, `<`, `>`, `(`, `)` or a line break), the hook answers ask instead. A deny is always honoured. The hook fails open to ask: a network error, a timeout, a rate limit, a 5xx, missing config or an unreadable event all answer ask, and it always exits 0.
+
+Add it to `~/.claude/settings.json` (every project) or `.claude/settings.json` (one project), with the key of an agent you created for this assistant:
+
+    {
+      "hooks": {
+        "PreToolUse": [
+          {
+            "matcher": "Bash|Edit|Write|MultiEdit|WebFetch|mcp__.*",
+            "hooks": [{ "type": "command", "command": "ASSENT_CONFIG=$HOME/.assent/claude-code.json assent hook pre-tool-use", "timeout": 10 }]
+          }
+        ]
+      }
+    }
+
+Try it by hand:
+
+    echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | assent hook pre-tool-use
+
+### Asking the person before risky calls
+
+With `--ask`, a call on the ask list goes to the person instead of Claude Code's own prompt. This is a best-effort tripwire, not a sandbox: a command written to dodge the patterns can get past it. Standing rules still come first (deny blocks, an exact allow runs). Otherwise the hook sends an approve ask (Allow or Block) and waits up to `hook.waitSeconds` (default 120), never longer than `--max-wait` (45 seconds when it is not given, inside Claude Code's default hook timeout). Each ask carries a fresh `Idempotency-Key` and `allowDuplicate`, and the hook blocks if Assent hands back a deduped or different ask. The ask detail shows the matched part, the whole command (secrets redacted, hidden and control characters shown as a replacement character) and the working directory; a call longer than 4000 characters is blocked without an ask, and a shell command over 64 KB is blocked before it is even matched. A failed poll withdraws the ask. Allow runs the call; Block, no answer in time (the ask is then withdrawn), an expired or closed ask, Assent being unreachable, no agent key or invalid hook settings all block it. Calls not on the list behave as without `--ask`. An ask for one simple command of at most 500 characters carries the tool and command as its action and target, so Always and Never make reusable rules; any other ask is one-off, with no Always or Never.
+
+The default list is Bash commands matching `git push*`, `git reset --hard*`, `rm -r*`, `rm -fr*`, `*deploy*`, `npm publish*`, `terraform apply*`, `terraform destroy*`, `kubectl delete*` or `docker push*`, checked against the whole command and against every word-tail of each simple command in it, with and without quotes and backslashes, and again after dropping command paths (`/usr/bin/git`), git global options (`-C dir`, `-c k=v`, `--no-pager`) and normalising recursive `rm` flags (`-R`, `-f -r`, `--recursive`). Braces, subshells, `bash -c`, `eval` and shell keywords are covered by the word-tails. Replace it in the config file:
+
+    { "agentKey": "oak_...", "hook": { "ask": [{ "tool": "Bash", "target": "git push*" }, { "tool": "mcp__github__*" }], "waitSeconds": 300 } }
+
+`assent hook claude-code install [--config path] [--settings path] [--yes]` writes the hook into `~/.claude/settings.json` (or `--settings`), as `assent hook pre-tool-use --ask --max-wait <waitSeconds>` with `ASSENT_CONFIG` set to the absolute `--config` path when given, and a Claude Code timeout 30 seconds above the wait. Run it again after raising `waitSeconds`. The settings file is written atomically (a temporary file renamed into place, through a symlink to its target, keeping its mode). It prints the diff on stderr and writes only after you confirm (or with `--yes`). It replaces any earlier Assent hook rather than adding a second. `assent hook claude-code uninstall` removes every Assent hook and leaves the rest of the settings untouched.
+
+## MCP over stdio
+
+`assent mcp` reads MCP JSON-RPC messages, one per line, on stdin, posts each to `<api>/api/v1/mcp` with the agent key, and prints each reply on one line. Requests run side by side, each with a 90 second limit. HTTP and network failures come back as JSON-RPC errors for that request. Without an agent key it exits 5. Use it for MCP clients that start servers as commands:
+
+    { "mcpServers": { "assent": { "command": "assent", "args": ["mcp"], "env": { "ASSENT_CONFIG": "/path/to/agent.json" } } } }
+
+The package also installs the command as `assent-cli`, so `npx assent-cli mcp` works once it is published.
+
+## Safety
+
+`run finish` redacts emails, tokens, keys, phone numbers and home paths from the summary and log tail before sending. `note` and `note update` redact the title and content the same way, and `ask` and `task add` redact the title and detail (a `--url` link and a reply draft are sent as given). The hook redacts secrets from the target before it is sent. Never pass passwords, card or bank details to any command; `pay` and `login` asks carry only a link.

package/dist/args.d.ts

@@ -0,0 +1,29 @@
+export type OptionSpec = Record<string, {
+    type: "string" | "boolean";
+    multiple?: boolean;
+}>;
+export interface Parsed {
+    values: Record<string, string | boolean | string[] | undefined>;
+    positionals: string[];
+}
+export declare function parseCommandArgs(argv: string[], options: OptionSpec): Parsed;
+export declare function parseField(raw: string): Record<string, unknown>;
+export declare function parseBadge(raw: string): {
+    label: string;
+    tone?: string;
+};
+export declare function parseLink(raw: string): {
+    label: string;
+    url: string;
+};
+export declare function readJsonInput(source: string, flag: string, readFile: (path: string) => string | null, stdin: () => Promise<string>): Promise<unknown>;
+export declare function readItemsJson(source: string, readFile: (path: string) => string | null, stdin: () => Promise<string>): Promise<Array<Record<string, unknown>>>;
+export declare function parseGroup(raw: string): {
+    key: string;
+    title: string;
+};
+export declare function parseRules(conflictOn: string[], totalOf: string | undefined, declineAction: string | undefined): {
+    conflictOn?: string[];
+    totalOf?: string;
+    declineAction?: string;
+} | undefined;

package/dist/args.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommandArgs = parseCommandArgs;
+exports.parseField = parseField;
+exports.parseBadge = parseBadge;
+exports.parseLink = parseLink;
+exports.readJsonInput = readJsonInput;
+exports.readItemsJson = readItemsJson;
+exports.parseGroup = parseGroup;
+exports.parseRules = parseRules;
+const node_util_1 = require("node:util");
+const exit_codes_1 = require("./exit-codes");
+function parseCommandArgs(argv, options) {
+    try {
+        const parsed = (0, node_util_1.parseArgs)({ args: argv, options: { ...options, get: { type: "string" } }, allowPositionals: true, strict: true });
+        return { values: parsed.values, positionals: parsed.positionals };
+    }
+    catch (err) {
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, err.message);
+    }
+}
+const FIELD_TYPES = ["text", "money", "date", "datetime", "number", "score"];
+const BADGE_TONES = ["neutral", "ok", "warn", "danger", "note"];
+const MONEY_VALUE = /^([A-Z]{3})\s*(-?\d+(?:\.\d+)?)$/;
+const SCORE_VALUE = /^(\d+(?:\.\d+)?)\/(\d+(?:\.\d+)?)$/;
+function parseField(raw) {
+    const [key, label, ...rest] = raw.split(":");
+    const typed = rest.length > 1 && FIELD_TYPES.includes(rest[0]);
+    const type = typed ? rest[0] : undefined;
+    const value = (typed ? rest.slice(1) : rest).join(":");
+    if (!key || !label || !value)
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--field must look like key:label:value or key:label:type:value");
+    const field = { key, label, ...(type ? { type } : {}), value };
+    const money = type === "money" ? MONEY_VALUE.exec(value) : null;
+    if (money)
+        Object.assign(field, { amount: Number(money[2]), currency: money[1] });
+    if (type === "date" || type === "datetime")
+        field.date = value;
+    if (type === "number") {
+        if (!Number.isFinite(Number(value)))
+            throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--field number values must be numeric");
+        field.number = Number(value);
+    }
+    const score = type === "score" ? SCORE_VALUE.exec(value) : null;
+    if (score)
+        Object.assign(field, { number: Number(score[1]), max: Number(score[2]) });
+    return field;
+}
+function parseBadge(raw) {
+    const at = raw.lastIndexOf(":");
+    const tone = at > 0 ? raw.slice(at + 1) : "";
+    return BADGE_TONES.includes(tone) ? { label: raw.slice(0, at), tone } : { label: raw };
+}
+function parseLink(raw) {
+    const at = raw.indexOf("=");
+    const label = at > 0 ? raw.slice(0, at) : "";
+    const url = at > 0 ? raw.slice(at + 1) : "";
+    if (!label || !/^https?:\/\//.test(url))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--link must look like label=https://...");
+    return { label, url };
+}
+async function readJsonInput(source, flag, readFile, stdin) {
+    const raw = source === "-" ? await stdin() : readFile(source);
+    if (raw === null)
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `Cannot read ${source}`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `--${flag} is not valid JSON`);
+    }
+}
+async function readItemsJson(source, readFile, stdin) {
+    const parsed = await readJsonInput(source, "item-json", readFile, stdin);
+    if (!Array.isArray(parsed))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--item-json must be a JSON array of items");
+    return parsed;
+}
+const GROUP_KEY = /^[A-Za-z0-9._-]{1,80}$/;
+const RULE_FIELD_KEY = /^[a-z0-9_]{1,40}$/;
+const MAX_CONFLICT_FIELDS = 4;
+const MAX_GROUP_TITLE = 120;
+const MAX_ACTION_ID = 60;
+function parseGroup(raw) {
+    const at = raw.indexOf(":");
+    const key = at > 0 ? raw.slice(0, at) : "";
+    const title = at > 0 ? raw.slice(at + 1).trim() : "";
+    if (!GROUP_KEY.test(key) || !title || title.length > MAX_GROUP_TITLE)
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--group must look like key:title, with a key of letters, digits, . _ - (at most 80) and a title of at most 120 characters");
+    return { key, title };
+}
+function parseRules(conflictOn, totalOf, declineAction) {
+    if (conflictOn.length > MAX_CONFLICT_FIELDS)
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `--conflict-on can be given at most ${MAX_CONFLICT_FIELDS} times`);
+    for (const key of [...conflictOn, ...(totalOf === undefined ? [] : [totalOf])]) {
+        if (!RULE_FIELD_KEY.test(key))
+            throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `--conflict-on and --total-of take a field key of lowercase letters, digits and _, got ${key}`);
+    }
+    if (declineAction !== undefined && (declineAction.length < 1 || declineAction.length > MAX_ACTION_ID))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "--decline-action must be an action id of 1 to 60 characters");
+    const rules = { ...(conflictOn.length ? { conflictOn } : {}), ...(totalOf === undefined ? {} : { totalOf }), ...(declineAction === undefined ? {} : { declineAction }) };
+    return Object.keys(rules).length ? rules : undefined;
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_readline_1 = require("node:readline");
+const promises_1 = require("node:readline/promises");
+const cli_1 = require("./cli");
+const config_1 = require("./config");
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const prompt = (0, promises_1.createInterface)({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await prompt.question(question)).trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+(0, cli_1.runCli)(process.argv.slice(2), {
+    env: process.env,
+    home: (0, node_os_1.homedir)(),
+    readFile: config_1.readFileOrNull,
+    readBytes: config_1.readBytesOrNull,
+    writeFile: config_1.writeFileAtomic,
+    removeFile: (path) => (0, node_fs_1.rmSync)(path, { force: true }),
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    readStdin,
+    stdinLines: () => (0, node_readline_1.createInterface)({ input: process.stdin, crlfDelay: Infinity }),
+    confirm,
+    cwd: () => process.cwd(),
+    name: (0, cli_1.commandName)(process.argv[1]),
+}).then((code) => {
+    process.exitCode = code;
+});

package/dist/claude-code.d.ts

@@ -0,0 +1,19 @@
+export interface SetupDeps {
+    env: NodeJS.ProcessEnv;
+    home: string;
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    stdout(line: string): void;
+    stderr(line: string): void;
+    confirm(question: string): Promise<boolean>;
+    cwd(): string;
+}
+type Json = Record<string, unknown>;
+export declare const HOOK_MATCHER = "Bash|Edit|Write|MultiEdit|NotebookEdit|WebFetch|mcp__.*";
+export declare function shellQuote(value: string): string;
+export declare function hookCommand(waitSeconds: number, configPath?: string): string;
+export declare function absoluteConfigPath(path: string, home: string, cwd: string): string;
+export declare function installHook(settings: Json, command: string, timeoutSeconds: number): Json;
+export declare function uninstallHook(settings: Json): Json;
+export declare function runClaudeCodeSetup(argv: string[], deps: SetupDeps): Promise<number>;
+export {};

package/dist/claude-code.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_MATCHER = void 0;
+exports.shellQuote = shellQuote;
+exports.hookCommand = hookCommand;
+exports.absoluteConfigPath = absoluteConfigPath;
+exports.installHook = installHook;
+exports.uninstallHook = uninstallHook;
+exports.runClaudeCodeSetup = runClaudeCodeSetup;
+const node_path_1 = require("node:path");
+const args_1 = require("./args");
+const config_1 = require("./config");
+const diff_1 = require("./diff");
+const exit_codes_1 = require("./exit-codes");
+const hook_ask_1 = require("./hook-ask");
+exports.HOOK_MATCHER = "Bash|Edit|Write|MultiEdit|NotebookEdit|WebFetch|mcp__.*";
+const ASSENT_HOOK = /(?:^|[\s/])(?:assent|ordia) hook pre-tool-use(?:\s|$)/;
+const TIMEOUT_MARGIN_SECONDS = 30;
+const SAFE_WORD = /^[A-Za-z0-9_./~:@%+=,-]+$/;
+const OPTIONS = { settings: { type: "string" }, config: { type: "string" }, yes: { type: "boolean" } };
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function shellQuote(value) {
+    return SAFE_WORD.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+function hookCommand(waitSeconds, configPath) {
+    return `${configPath ? `ASSENT_CONFIG=${shellQuote(configPath)} ` : ""}assent hook pre-tool-use --ask --max-wait ${waitSeconds}`;
+}
+function absoluteConfigPath(path, home, cwd) {
+    const expanded = path === "~" ? home : path.startsWith("~/") ? (0, node_path_1.join)(home, path.slice(2)) : path;
+    return (0, node_path_1.resolve)(cwd, expanded);
+}
+function isAssentHook(hook) {
+    return isObject(hook) && typeof hook.command === "string" && ASSENT_HOOK.test(hook.command);
+}
+function withoutAssent(groups) {
+    return groups.flatMap((group) => {
+        if (!isObject(group) || !Array.isArray(group.hooks))
+            return [group];
+        const hooks = group.hooks.filter((hook) => !isAssentHook(hook));
+        if (hooks.length === group.hooks.length)
+            return [group];
+        return hooks.length ? [{ ...group, hooks }] : [];
+    });
+}
+function hooksOf(settings) {
+    const hooks = settings.hooks ?? {};
+    if (!isObject(hooks))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "The settings \"hooks\" value is not an object, so nothing was changed");
+    const preToolUse = hooks.PreToolUse ?? [];
+    if (!Array.isArray(preToolUse))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "The settings \"hooks.PreToolUse\" value is not a list, so nothing was changed");
+    return { hooks, preToolUse };
+}
+function installHook(settings, command, timeoutSeconds) {
+    const { hooks, preToolUse } = hooksOf(settings);
+    const entry = { matcher: exports.HOOK_MATCHER, hooks: [{ type: "command", command, timeout: timeoutSeconds }] };
+    return { ...settings, hooks: { ...hooks, PreToolUse: [...withoutAssent(preToolUse), entry] } };
+}
+function uninstallHook(settings) {
+    const { hooks, preToolUse } = hooksOf(settings);
+    const remaining = withoutAssent(preToolUse);
+    if (remaining.length === preToolUse.length)
+        return settings;
+    const nextHooks = { ...hooks, PreToolUse: remaining };
+    if (!remaining.length)
+        delete nextHooks.PreToolUse;
+    const next = { ...settings, hooks: nextHooks };
+    if (!Object.keys(nextHooks).length)
+        delete next.hooks;
+    return next;
+}
+function parseSettings(raw, path) {
+    if (raw === null || !raw.trim())
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `${path} is not valid JSON, so nothing was changed`);
+    }
+    if (!isObject(parsed))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `${path} does not hold a JSON object, so nothing was changed`);
+    return parsed;
+}
+function indentOf(raw) {
+    return (raw === null ? undefined : /^([ \t]+)"/m.exec(raw)?.[1]) ?? "  ";
+}
+function sources(deps, configPath) {
+    const env = configPath ? { ...deps.env, ASSENT_CONFIG: configPath } : deps.env;
+    return { env, home: deps.home, readFile: deps.readFile, exists: (path) => deps.readFile(path) !== null };
+}
+function waitSeconds(deps, configPath) {
+    const src = sources(deps, configPath);
+    try {
+        (0, config_1.loadCliConfig)(src);
+    }
+    catch (err) {
+        deps.stderr(`Warning: ${err.message}. Until the hook has an agent key it blocks risky calls and leaves the rest to Claude Code.`);
+    }
+    return (0, hook_ask_1.hookAskSettings)((0, config_1.readConfigFile)(src), src.env).waitSeconds;
+}
+async function setup(verb, argv, deps) {
+    if (verb !== "install" && verb !== "uninstall")
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, "Use hook claude-code install or hook claude-code uninstall");
+    const args = (0, args_1.parseCommandArgs)(argv, OPTIONS);
+    if (args.positionals.length)
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.usage, `Unexpected argument: ${args.positionals[0]}`);
+    const configPath = typeof args.values.config === "string" ? absoluteConfigPath(args.values.config, deps.home, deps.cwd()) : undefined;
+    const path = typeof args.values.settings === "string" ? args.values.settings : (0, node_path_1.join)(deps.home, ".claude", "settings.json");
+    const raw = deps.readFile(path);
+    const before = parseSettings(raw, path);
+    const wait = verb === "install" ? waitSeconds(deps, configPath) : 0;
+    const command = hookCommand(wait, configPath);
+    const after = verb === "install" ? installHook(before, command, wait + TIMEOUT_MARGIN_SECONDS) : uninstallHook(before);
+    if (JSON.stringify(before) === JSON.stringify(after)) {
+        deps.stdout(JSON.stringify({ settings: path, changed: false, written: false }));
+        return exit_codes_1.EXIT.ok;
+    }
+    const afterText = `${JSON.stringify(after, null, indentOf(raw))}\n`;
+    deps.stderr(`Changes to ${path}:`);
+    for (const line of (0, diff_1.lineDiff)(raw ?? "", afterText))
+        deps.stderr(line);
+    const write = args.values.yes === true || (await deps.confirm(`Write this to ${path}? [y/N] `));
+    if (!write) {
+        deps.stdout(JSON.stringify({ settings: path, changed: true, written: false, message: "Nothing written. Run again and confirm, or pass --yes." }));
+        return exit_codes_1.EXIT.ok;
+    }
+    deps.writeFile(path, afterText);
+    deps.stdout(JSON.stringify({ settings: path, changed: true, written: true, ...(verb === "install" ? { command } : {}) }));
+    return exit_codes_1.EXIT.ok;
+}
+async function runClaudeCodeSetup(argv, deps) {
+    try {
+        return await setup(argv[0], argv.slice(1), deps);
+    }
+    catch (err) {
+        const exitCode = err instanceof exit_codes_1.CliError ? err.exitCode : exit_codes_1.EXIT.failure;
+        deps.stderr(JSON.stringify({ error: err.message, exitCode, status: null }));
+        return exitCode;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,38 @@
+import { FetchLike, TaskView } from "./client";
+export interface CliDeps {
+    env: NodeJS.ProcessEnv;
+    home: string;
+    readFile(path: string): string | null;
+    readBytes(path: string): Uint8Array | null;
+    writeFile(path: string, content: string): void;
+    removeFile(path: string): void;
+    stdout(line: string): void;
+    stderr(line: string): void;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    readStdin(): Promise<string>;
+    stdinLines(): AsyncIterable<string>;
+    confirm(question: string): Promise<boolean>;
+    cwd(): string;
+    fetchImpl?: FetchLike;
+    name?: string;
+}
+export declare function parseWhen(raw: string, flag: string, warn: (line: string) => void): string;
+export declare function parseAction(raw: string): {
+    id: string;
+    label: string;
+    style?: string;
+};
+export declare function parseItem(raw: string): {
+    id: string;
+    title: string;
+    selected: boolean;
+};
+export declare function parseRef(raw: string | undefined, flag: string): {
+    type: string;
+    uuid: string;
+};
+export declare function redactedTail(log: string, tailChars: number): string;
+export declare function itemState(task: TaskView, itemId: string): string;
+export declare function commandName(startedAs: string | undefined): string;
+export declare function runCli(argv: string[], deps: CliDeps): Promise<number>;