car-runtime 0.52.0 → 0.53.0

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-06). 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
+> 69 top-level commands, 106 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 69 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,15 +163,18 @@ 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) |
 | [`car keys`](#car-keys) | Store cloud-provider API keys in the OS keychain, so a native-app user never sets an environment variable (docs/proposals/native-secrets-no-env.md). The key is read env-first, keychain-fallback by the runtime |
+| [`car selfheal`](#car-selfheal) | Inspect and operate the daemon's deterministic self-healing detector |
 | [`car daemon`](#car-daemon) | Start the daemon server (delegates to car-server binary) |
 | [`car models`](#car-models) | Manage local inference models |
 | [`car setup`](#car-setup) | Set up the right model for this machine — detect hardware, recommend, and install. Run with no flags for an interactive walkthrough |
@@ -246,6 +249,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 +333,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 +542,7 @@ Usage: car coder-ab extract [OPTIONS] --out <OUT>
 Options:
       --repo <REPO>
           Repo to mine (default: current dir)
-          
+
           [default: .]
 
       --out <OUT>
@@ -520,7 +553,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 +561,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 +576,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 +616,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 +642,91 @@ Remove a stored provider key from the keychain
 Usage: car keys remove <NAME>
 
 Arguments:
-  <NAME>  
+  <NAME>
+
+Options:
+  -h, --help  Print help
+```
+
+### car selfheal
+
+```text
+Inspect and operate the daemon's deterministic self-healing detector
+
+Usage: car selfheal <COMMAND>
+
+Commands:
+  status   Show cadence, active counts, and the route resolved by the last tick
+  list     List active detections, optionally filtered by kind, severity, or time
+  show     Print the trusted local issue document for one detection
+  dismiss  Dismiss one active detection by dedup key
+  run      Run one deterministic detection tick now
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal status
+
+```text
+Show cadence, active counts, and the route resolved by the last tick
+
+Usage: car selfheal status
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal list
+
+```text
+List active detections, optionally filtered by kind, severity, or time
+
+Usage: car selfheal list [OPTIONS]
+
+Options:
+      --kind <KIND>          Detection kind (metrics_alert, agent_gave_up, agent_log_error,
+      agent_silently_idle, recurring_tool_failure, capability_miss)
+      --severity <SEVERITY>  Severity (warning or critical)
+      --since <SINCE>        Only detections observed at or after this RFC3339 timestamp
+  -h, --help                 Print help
+```
+
+#### car selfheal show
+
+```text
+Print the trusted local issue document for one detection
+
+Usage: car selfheal show <DEDUP_KEY>
+
+Arguments:
+  <DEDUP_KEY>  Detection SHA-256 dedup key
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal dismiss
+
+```text
+Dismiss one active detection by dedup key
+
+Usage: car selfheal dismiss <DEDUP_KEY>
+
+Arguments:
+  <DEDUP_KEY>  Detection SHA-256 dedup key
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal run
+
+```text
+Run one deterministic detection tick now
+
+Usage: car selfheal run
 
 Options:
   -h, --help  Print help
@@ -724,7 +841,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 +856,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 +1527,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 +1543,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 +1559,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 +1820,7 @@ Options:
 
       --max-attempts <MAX_ATTEMPTS>
           Max generate→validate→repair attempts per round
-          
+
           [default: 3]
 
   -h, --help
@@ -1765,11 +1921,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 +1937,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 +1952,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 +1967,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 +2160,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 +2176,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 +2191,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 +2261,7 @@ Remove an enrolled voiceprint by label
 Usage: car voice remove --label <LABEL>
 
 Options:
-      --label <LABEL>  
+      --label <LABEL>
   -h, --help           Print help
 ```
 
@@ -2131,10 +2287,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 +2326,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 +2408,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 +2488,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 +2537,7 @@ Inbox summaries per account
 Usage: car mail inbox [OPTIONS]
 
 Options:
-      --accounts <ACCOUNTS>  
+      --accounts <ACCOUNTS>
   -h, --help                 Print help
 ```
 
@@ -2343,7 +2550,7 @@ bounded: depth 8, 64 requests)
 Usage: car mail mailboxes [OPTIONS]
 
 Options:
-      --accounts <ACCOUNTS>  
+      --accounts <ACCOUNTS>
   -h, --help                 Print help
 ```
 
@@ -2356,7 +2563,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 +2580,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 +2683,7 @@ Free-text note search
 Usage: car notes find [OPTIONS] <QUERY>
 
 Arguments:
-  <QUERY>  
+  <QUERY>
 
 Options:
       --limit <LIMIT>  [default: 50]
@@ -2664,8 +2871,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 +2884,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 +2897,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 +2927,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/docs/agent-ir-spec.md

@@ -181,6 +181,35 @@ Proposed → Validated → Executing → Succeeded
 
 `ActionStatus` is observable through the event log, not part of the input contract.
 
+#### Execution outcome event data
+
+Every per-action `ActionFailed` event carries:
+
+- `params_digest`: lowercase SHA-256 of the RFC 8785/JCS-canonicalized action
+  `parameters` object. The event never copies raw parameters; consumers join
+  through `proposal_id` + `action_id` to the authoritative `ProposalReceived`
+  record and can use the digest to detect a mismatch.
+- `expected_effects`: the action's declared expected-effects object, unchanged.
+- `error_class`: one of `timeout`, `rejected_by_policy`, `tool_error`,
+  `validation`, or `unknown`.
+
+`ActionSucceeded` carries `params_digest` and `expected_effects` too, making the
+success/failure join symmetric without adding an error classification to a
+successful call.
+
+The normalized error mapping is intentionally low-cardinality:
+
+| `error_class` | Mapping |
+|---|---|
+| `timeout` | the engine's action deadline expired, or the daemon-to-host tool callback reported its own timeout |
+| `rejected_by_policy` | a dispatch-time tool guard returned the stable `denied by policy:` or `rejected by policy:` prefix |
+| `validation` | post-dispatch output or callback-state JCS/I-JSON, state-key-set, or serialization validation failed |
+| `tool_error` | any other error returned while dispatching a tool action |
+| `unknown` | a post-dispatch failure on an action with no tool |
+
+Normal action/schema/policy admission failures happen before execution and are
+`ActionRejected`, not `ActionFailed`, so this mapping does not reclassify them.
+
 ---
 
 ## Precondition
@@ -220,6 +249,7 @@ Registered when a tool is added to the runtime. Carries everything the runtime n
 ```jsonc
 {
   "name": "deploy",
+  "source": "user_defined",
   "description": "Deploys an artifact to a target environment.",
   "parameters": {
     "type": "object",
@@ -238,6 +268,7 @@ Registered when a tool is added to the runtime. Carries everything the runtime n
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `name` | string | **yes** | — | unique within a runtime |
+| `source` | `builtin \| user_defined \| subprocess \| mcp` | no | `user_defined` | stable origin category assigned by the runtime; MCP server detail remains registry-private |
 | `description` | string | no | `""` | human-readable; included in tool catalog |
 | `parameters` | JSON Schema | no | `{}` | validated by the runtime before dispatch |
 | `returns` | JSON Schema | no | none | validated against tool return value when set |
@@ -562,15 +593,21 @@ allow = ["staging", "preview"]   # any other target — or none at all — is de
 | `allow` | no | permitted values; defaults to empty, which denies every call |
 
 #### `deny_tool_param_matching`
-The content counterpart to `deny_tool_param`, for prohibitions no fixed substring expresses — credential shapes, account numbers, an address family. `matches` is a regex over the string-coerced parameter value. The match is **unanchored**, so the pattern fires anywhere in the value; anchor it with `^`/`$` when that matters. Like `deny_tool_param`, an absent parameter is not a violation — use `allow_tool_param` when absence itself must be refused.
+The content counterpart to `deny_tool_param`, for conditions no fixed substring expresses — credential shapes, account numbers, an address family, or an open-ended trusted prefix. `matches` is a regex over the string-coerced parameter value. The match is **unanchored**, so the pattern fires anywhere in the value; anchor it with `^`/`$` when that matters.
 
-The pattern is compiled once when the rule set is applied, not per action. A pattern that fails to compile **denies every call to that tool** rather than disappearing, matching the loader's loud-error posture.
+By default a regex match denies and an absent parameter does not. Set `negate = true` for the "unless" form: a mismatch denies, and an absent parameter also denies because nothing proves the required pattern. The pattern is compiled once when the rule set is applied, not per action. A pattern that fails to compile **denies every call to that tool** rather than disappearing, matching the loader's loud-error posture.
 
 ```toml
 [[deny_tool_param_matching]]
 tool    = "http_request"
 param   = "body"
 matches = "sk-[A-Za-z0-9]{20,}"   # never let an API-key-shaped string leave in a body
+
+[[deny_tool_param_matching]]
+tool    = "docker.rm"
+param   = "name"
+matches = "^parslee-"
+negate  = true                     # deny unless the name has the trusted prefix
 ```
 
 | Param | Required | Notes |
@@ -578,6 +615,7 @@ matches = "sk-[A-Za-z0-9]{20,}"   # never let an API-key-shaped string leave in
 | `tool` | yes | tool name the rule applies to |
 | `param` | yes | parameter key inspected on the action |
 | `matches` | yes | regex source; unanchored; an uncompilable pattern denies the tool outright |
+| `negate` | no | defaults to `false`; when `true`, deny mismatch or absence instead of match |
 
 #### `rate_limit_tool`
 A sliding-window cap on how often `tool` may be called. The call is denied when admitting it would make it the `max_calls + 1`-th call to `tool` within the trailing `interval_secs`. `max_calls = 0` denies every call. This bounds how much of a side effect an agent can produce in a stretch of wall-clock time, independently of whether any single call is legitimate.