car-runtime 0.52.0 → 0.52.1

package/docs/CLI.md

@@ -2,17 +2,17 @@
 
 > **Generated file — do not hand-edit below the task map.** Produced by
 > `scripts/gen-cli-docs.sh` from `car --help` / `car help <command>` on car
-> 0.51.0 (2026-09-03). Every subcommand the installed binary reports is
+> 0.52.1 (2026-09-04). Every subcommand the installed binary reports is
 > below; a new subcommand cannot ship without appearing here the next time
 > this script runs. To regenerate: `bash scripts/gen-cli-docs.sh`.
 >
-> 66 top-level commands, 98 nested subcommands
+> 68 top-level commands, 101 nested subcommands
 > (one level deep) — counted from the live binary at generation time, not
 > typed by hand.
 
 ## Finding your way around
 
-`car` is one binary with 66 subcommands spanning several different jobs:
+`car` is one binary with 68 subcommands spanning several different jobs:
 running the built-in agent, coding, local model management, OS integrations,
 and installing other people's agents on your machine. This map groups the
 commands people actually reach for; the full alphabetical reference with every
@@ -163,11 +163,13 @@ commands on a cadence via launchd / cron / schtasks).
 | Command | Description |
 |---|---|
 | [`car info`](#car-info) | Show runtime info |
+| [`car capabilities`](#car-capabilities) | Print the deterministic CAR capability manifest |
 | [`car ui`](#car-ui) | Open the browser dashboard served by the daemon |
 | [`car verify`](#car-verify) | Statically verify a proposal |
 | [`car simulate`](#car-simulate) | Simulate a proposal's state effects without executing |
 | [`car optimize`](#car-optimize) | Optimize a proposal (remove phantom dependencies) |
 | [`car replay`](#car-replay) | Replay an event journal and show reconstructed state |
+| [`car run-cancel`](#car-run-cancel) | Cancel one active CAR run and print its deterministic durable receipt |
 | [`car run-task`](#car-run-task) | Run a goal autonomously against stdio MCP tool servers, emitting a JSONL transcript. Headless entry point for external eval harnesses |
 | [`car code-task`](#car-code-task) | Run a coder session headlessly and IN THIS PROCESS: derive or accept an outcome contract, work in a git worktree until the runtime's own re-run of that contract is green, then deliver the result as a pull request |
 | [`car coder-ab`](#car-coder-ab) | A/B-test CAR's coder against an external agent (Codex / Claude Code) over a corpus, and grow that corpus from git history — the productionized dogfooding loop (docs/proposals/coder-ab-dogfood.md) |
@@ -246,6 +248,19 @@ Options:
   -h, --help  Print help
 ```
 
+### car capabilities
+
+```text
+Print the deterministic CAR capability manifest
+
+Usage: car capabilities [OPTIONS]
+
+Options:
+      --json  Emit machine-readable JSON
+      --md    Emit generated Markdown (the default)
+  -h, --help  Print help
+```
+
 ### car ui
 
 ```text
@@ -317,6 +332,23 @@ Options:
   -h, --help  Print help
 ```
 
+### car run-cancel
+
+```text
+Cancel one active CAR run and print its deterministic durable receipt
+
+Usage: car run-cancel [OPTIONS] --run-id <RUN_ID> --idempotency-key <IDEMPOTENCY_KEY> --reason
+<REASON>
+
+Options:
+      --run-id <RUN_ID>
+      --idempotency-key <IDEMPOTENCY_KEY>
+      --reason <REASON>
+      --url <URL>                          [default: ws://127.0.0.1:9100/]
+      --json
+  -h, --help                               Print help
+```
+
 ### car run-task
 
 ```text
@@ -509,7 +541,7 @@ Usage: car coder-ab extract [OPTIONS] --out <OUT>
 Options:
       --repo <REPO>
           Repo to mine (default: current dir)
-          
+
           [default: .]
 
       --out <OUT>
@@ -520,7 +552,7 @@ Options:
           rather than `python3 -m pytest -q`: `python3` does not exist on a standard Windows
           python.org install, and `python` is often absent on macOS/Linux — pytest's console script
           is the portable spelling
-          
+
           [default: "pytest -q"]
 
       --path <PATH>
@@ -528,12 +560,12 @@ Options:
 
       --max <MAX>
           Limit to this many recent commits scanned
-          
+
           [default: 50]
 
       --max-files <MAX_FILES>
           Skip a commit whose changed-file count exceeds this (keep tasks small)
-          
+
           [default: 6]
 
       --full-tree
@@ -543,7 +575,7 @@ Options:
 
       --subject-filter <SUBJECT_FILTER>
           Keep only commits whose subject contains this substring (e.g. `fix(`).
-          
+
           On a Rust repo this is close to required: a `feat` commit's test imports a symbol the
           commit itself adds, so it cannot compile at the pre-fix parent. Such tasks are rejected
           anyway, but only after a full tree materialize + build, which costs 30-200s each.
@@ -583,8 +615,8 @@ from stdin (keeps it out of shell history)
 Usage: car keys set <NAME> [VALUE]
 
 Arguments:
-  <NAME>   
-  [VALUE]  
+  <NAME>
+  [VALUE]
 
 Options:
   -h, --help  Print help
@@ -609,7 +641,7 @@ Remove a stored provider key from the keychain
 Usage: car keys remove <NAME>
 
 Arguments:
-  <NAME>  
+  <NAME>
 
 Options:
   -h, --help  Print help
@@ -724,7 +756,7 @@ Evaluate one local model without downloading or loading it
 Usage: car models preflight [OPTIONS] <MODEL_ID>
 
 Arguments:
-  <MODEL_ID>  
+  <MODEL_ID>
 
 Options:
       --context-tokens <CONTEXT_TOKENS>  [default: 0]
@@ -739,7 +771,7 @@ Adopt an already-usable local artifact into CAR ownership
 Usage: car models adopt <MODEL_ID>
 
 Arguments:
-  <MODEL_ID>  
+  <MODEL_ID>
 
 Options:
   -h, --help  Print help
@@ -1410,7 +1442,7 @@ Options:
           Safety cap on agent turns. This is a backstop, not the expected stop: the loop ends on its
           own when the model finishes (stops calling tools). 12 was too low for whole-project builds
           — it cut real work off mid-task; raise it further for large jobs
-          
+
           [default: 50]
 
       --until <SHELL>
@@ -1426,7 +1458,7 @@ Options:
       --goal-max-iterations <GOAL_MAX_ITERATIONS>
           In goal mode, the hard cap on re-drive iterations (the governor's turn budget). A hard
           bound, not a soft prose clause
-          
+
           [default: 10]
 
       --serve
@@ -1442,6 +1474,45 @@ Options:
           stdout, JSONL progress events on stderr, and no human progress rendering. Needs a goal —
           there is no JSON shape for an interactive REPL. See docs/car-do-json.md
 
+      --response-format <MODE>
+          Constrain the final answer to JSON. Applies to the final answer only; tool turns are
+          unconstrained (a JSON-constrained request suppresses tool use). The loop checks the final
+          answer itself and, if it is not a JSON object, re-asks the model ONCE with no tools and
+          JSON mode on before returning; an answer that already parses costs no extra call.
+          Provider-dependent on that repair turn: OpenAI-protocol and OpenRouter (which forwards it
+          to the upstream provider) enforce it; Anthropic-protocol models reject it. Mutually
+          exclusive with --json-schema. (Unrelated to --json, which shapes car's own output.)
+
+          [possible values: json_object]
+
+      --json-schema <FILE>
+          Constrain the final answer to JSON matching this JSON Schema file. The schema's `title`
+          names it for providers that want one. Applies to the final answer only, with the same
+          one-shot tool-less repair and provider caveats as --response-format; the loop validates
+          the final answer against the schema itself (a valid-JSON answer of the wrong shape is
+          repaired too). Mutually exclusive with --response-format
+
+      --strict-model
+          Use exactly the --model (or CAR_DO_MODEL) named, or fail. Without it `car do` substitutes
+          a usable tool-capable model when the named one is unavailable here (and says so); with it
+          a substitution is a startup error, and the inference layer will not fall back to an
+          on-device model on a remote failure either. Off by default: the substitution is the right
+          call for an interactive run
+
+      --context-window <TOKENS>
+          Bound the running conversation to this many tokens instead of the model's registry window
+          (older middle turns are compacted out to fit, as they are against the real window). Use it
+          to tighten: a value above the model's known window is clamped back down to it, because
+          letting the history overflow the real window is exactly the provider-side truncation
+          compaction exists to prevent
+
+      --max-delegations <N>
+          Run-level cap on `delegate` sub-agent calls. A call past the cap (or past the
+          300-child-turn budget) returns an error result to the assistant instead of spawning, so a
+          delegating run cannot amplify its model calls without bound
+
+          [default: 20]
+
   -h, --help
           Print help (see a summary with '-h')
 ```
@@ -1664,7 +1735,7 @@ Options:
 
       --max-attempts <MAX_ATTEMPTS>
           Max generate→validate→repair attempts per round
-          
+
           [default: 3]
 
   -h, --help
@@ -1765,11 +1836,11 @@ Store a secret. Value is read from --value or piped stdin
 Usage: car secrets put [OPTIONS] <KEY>
 
 Arguments:
-  <KEY>  
+  <KEY>
 
 Options:
-      --service <SERVICE>  
-      --value <VALUE>      
+      --service <SERVICE>
+      --value <VALUE>
   -h, --help               Print help
 ```
 
@@ -1781,10 +1852,10 @@ Retrieve a secret — prints the value on stdout
 Usage: car secrets get [OPTIONS] <KEY>
 
 Arguments:
-  <KEY>  
+  <KEY>
 
 Options:
-      --service <SERVICE>  
+      --service <SERVICE>
   -h, --help               Print help
 ```
 
@@ -1796,10 +1867,10 @@ Delete a secret (idempotent)
 Usage: car secrets delete [OPTIONS] <KEY>
 
 Arguments:
-  <KEY>  
+  <KEY>
 
 Options:
-      --service <SERVICE>  
+      --service <SERVICE>
   -h, --help               Print help
 ```
 
@@ -1811,10 +1882,10 @@ Check whether a secret exists, without returning the value
 Usage: car secrets status [OPTIONS] <KEY>
 
 Arguments:
-  <KEY>  
+  <KEY>
 
 Options:
-      --service <SERVICE>  
+      --service <SERVICE>
   -h, --help               Print help
 ```
 
@@ -2004,7 +2075,7 @@ Report current grant state for a domain
 Usage: car permissions status [OPTIONS] <DOMAIN>
 
 Arguments:
-  <DOMAIN>  
+  <DOMAIN>
 
 Options:
       --target <TARGET>  macOS Automation only: bundle ID of the target app to control. Ignored for
@@ -2020,10 +2091,10 @@ Trigger a native prompt if the OS supports one
 Usage: car permissions request [OPTIONS] <DOMAIN>
 
 Arguments:
-  <DOMAIN>  
+  <DOMAIN>
 
 Options:
-      --target <TARGET>  
+      --target <TARGET>
   -h, --help             Print help
 ```
 
@@ -2035,10 +2106,10 @@ Human-readable explanation and fix suggestion
 Usage: car permissions explain [OPTIONS] <DOMAIN>
 
 Arguments:
-  <DOMAIN>  
+  <DOMAIN>
 
 Options:
-      --target <TARGET>  
+      --target <TARGET>
   -h, --help             Print help
 ```
 
@@ -2105,7 +2176,7 @@ Remove an enrolled voiceprint by label
 Usage: car voice remove --label <LABEL>
 
 Options:
-      --label <LABEL>  
+      --label <LABEL>
   -h, --help           Print help
 ```
 
@@ -2131,10 +2202,14 @@ onboarding step)
 Usage: car approvals <COMMAND>
 
 Commands:
-  default  Set the default approval preset for all agents (`cautious` asks before any
+  default        Set the default approval preset for all agents (`cautious` asks before any
   edit/full-access, `balanced` allows sandboxed edits, `trusting` allows everything without asking)
-  get      Show the current default approval posture
-  help     Print this message or the help of the given subcommand(s)
+  get            Show the current default approval posture
+  set-tool       Set an approval mode for one exact agent and exact tool. `always_allow` requires
+  that agent to be attached with an eligible live callback
+  evaluate-tool  Show whether one exact agent/tool override is active and schema-bound
+  reset-tool     Remove one exact agent/tool approval override
+  help           Print this message or the help of the given subcommand(s)
 
 Options:
   -h, --help  Print help
@@ -2166,6 +2241,53 @@ Options:
   -h, --help  Print help
 ```
 
+#### car approvals set-tool
+
+```text
+Set an approval mode for one exact agent and exact tool. `always_allow` requires that agent to be
+attached with an eligible live callback
+
+Usage: car approvals set-tool <AGENT> <TOOL> <MODE>
+
+Arguments:
+  <AGENT>
+  <TOOL>
+  <MODE>   One of: always_allow | require_approval | deny
+
+Options:
+  -h, --help  Print help
+```
+
+#### car approvals evaluate-tool
+
+```text
+Show whether one exact agent/tool override is active and schema-bound
+
+Usage: car approvals evaluate-tool <AGENT> <TOOL>
+
+Arguments:
+  <AGENT>
+  <TOOL>
+
+Options:
+  -h, --help  Print help
+```
+
+#### car approvals reset-tool
+
+```text
+Remove one exact agent/tool approval override
+
+Usage: car approvals reset-tool <AGENT> <TOOL>
+
+Arguments:
+  <AGENT>
+  <TOOL>
+
+Options:
+  -h, --help  Print help
+```
+
 ### car accounts
 
 ```text
@@ -2201,7 +2323,7 @@ Open the native account-management UI
 Usage: car accounts open [OPTIONS]
 
 Options:
-      --account-id <ACCOUNT_ID>  
+      --account-id <ACCOUNT_ID>
   -h, --help                     Print help
 ```
 
@@ -2281,11 +2403,11 @@ Free-text contact search
 Usage: car contacts find [OPTIONS] <QUERY>
 
 Arguments:
-  <QUERY>  
+  <QUERY>
 
 Options:
       --limit <LIMIT>            [default: 50]
-      --containers <CONTAINERS>  
+      --containers <CONTAINERS>
   -h, --help                     Print help
 ```
 
@@ -2330,7 +2452,7 @@ Inbox summaries per account
 Usage: car mail inbox [OPTIONS]
 
 Options:
-      --accounts <ACCOUNTS>  
+      --accounts <ACCOUNTS>
   -h, --help                 Print help
 ```
 
@@ -2343,7 +2465,7 @@ bounded: depth 8, 64 requests)
 Usage: car mail mailboxes [OPTIONS]
 
 Options:
-      --accounts <ACCOUNTS>  
+      --accounts <ACCOUNTS>
   -h, --help                 Print help
 ```
 
@@ -2356,7 +2478,7 @@ account, then concatenated)
 Usage: car mail messages [OPTIONS]
 
 Options:
-      --accounts <ACCOUNTS>  
+      --accounts <ACCOUNTS>
       --mailbox <MAILBOX>    Mailbox selector — a `full_name` from `car mail mailboxes`, or a bare
       leaf name like "Travel". Defaults to INBOX
       --limit <LIMIT>        [default: 50]
@@ -2373,7 +2495,7 @@ Fetch one message body by the `id` from `car mail messages`
 Usage: car mail body <ID>
 
 Arguments:
-  <ID>  
+  <ID>
 
 Options:
   -h, --help  Print help
@@ -2476,7 +2598,7 @@ Free-text note search
 Usage: car notes find [OPTIONS] <QUERY>
 
 Arguments:
-  <QUERY>  
+  <QUERY>
 
 Options:
       --limit <LIMIT>  [default: 50]
@@ -2664,8 +2786,8 @@ Sleep windows in an ISO-8601 time range
 Usage: car health sleep --start <START> --end <END>
 
 Options:
-      --start <START>  
-      --end <END>      
+      --start <START>
+      --end <END>
   -h, --help           Print help
 ```
 
@@ -2677,8 +2799,8 @@ Workouts in an ISO-8601 time range
 Usage: car health workouts --start <START> --end <END>
 
 Options:
-      --start <START>  
-      --end <END>      
+      --start <START>
+      --end <END>
   -h, --help           Print help
 ```
 
@@ -2690,8 +2812,8 @@ Daily activity summaries across a date range (YYYY-MM-DD)
 Usage: car health activity --start <START> --end <END>
 
 Options:
-      --start <START>  
-      --end <END>      
+      --start <START>
+      --end <END>
   -h, --help           Print help
 ```
 
@@ -2720,12 +2842,12 @@ Options:
           Registry source for `<namespace>/<name>` references: an `http(s)://…/index.json` URL or a
           LOCAL registry directory (or `file://` URL). Defaults to the public mirror. The private
           source needs a token — set `CAR_REGISTRY_TOKEN`
-          
+
           [default: https://raw.githubusercontent.com/Parslee-ai/car-releases/main/index.json]
 
       --url <URL>
           WebSocket URL of the running car-server daemon
-          
+
           [default: ws://127.0.0.1:9100/]
 
       --json

package/index.d.ts

@@ -1498,6 +1498,23 @@ export class CarRuntime {
    * `cost_overage` alert. */
   metricsAlerts(thresholdsJson?: string): Promise<string>;
 
+  /** Watch-only self-heal detector status as JSON: cadence, last tick, source
+   * `route`, validated `source_checkout` or `refusal_reason`, detector IDs,
+   * active/dismissed counts, and `filing_mode: "watch-only"`. */
+  selfhealStatus(): Promise<string>;
+
+  /** List active (not dismissed) self-heal detections as JSON. Each includes
+   * `route` and an optional `local_issue_path`. `queryJson` optionally carries
+   * `kind`, `severity`, `since`, `offset`, and `limit` (bounded to 500). */
+  selfhealDetections(queryJson?: string): Promise<string>;
+
+  /** Append a dismissal marker for a stable detection dedup key. This does not
+   * delete history, file an issue, use network, or remediate anything. */
+  selfhealDismiss(dedupKey: string): Promise<string>;
+
+  /** Run one non-overlapping watch-only detection tick immediately. */
+  selfhealRun(): Promise<string>;
+
   /** Execution log counts and approximate retained native bytes. Returns JSON. */
   eventLogStats(): Promise<string>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",