@calliopelabs/cli 3.6.0 → 3.8.0

package/docs/delegation-ledger.md

@@ -49,10 +49,24 @@ servers reject that token version; current raw-ledger endpoints reject its revie
 authority binding. Child credentials retain that binding. A sibling owner endpoint
 cannot accept the token, and reservations, settlements and revocations enforce the
 selected subtree. Each new request also checks the target account's native admission,
-stop/escalation state and the host's output cap. Existing requests can still settle
+stop/escalation state, explicit reviewed provider/model choices and the host's
+output cap. Smart agents also enforce their reviewed initial pool. Task-bound
+hosts derive escalation eligibility from that task's retained native failed-check
+evidence; account-only hosts cannot select an escalation pool. Explicit reviewed
+pins retain the same precedence as local Smart routing. The provider/model check
+uses the current admitted graph and runs
+again under the ledger writer lock before a new reservation commits. Existing requests can still settle
 after owner cancellation; grant revocation and token expiry retain their existing
 semantics.
 
+Reviewed host capabilities additionally advertise `endpointBinding: 1`. Hosting
+captures the owner's configured provider target hashes in the native budget approval
+and token audience. New reservations must match that target for their provider;
+changing an owner's endpoint fences existing hosts and changes newly issued tokens.
+Restarting with unchanged endpoint configuration preserves credentials and allowance.
+API key rotation does not change target identity. Child-side endpoint overrides cannot
+widen this authority. Target hashes contain no API keys or raw endpoint strings.
+
 The HTTP grant operation only returns credentials for an **exact, already admitted**
 native child grant. It cannot create a proposal, approve children, bypass native
 depth/count limits or promote an interrupted ledger grant into the execution graph.
@@ -67,10 +81,48 @@ that history requires verified restoration or an explicit owner-managed credenti
 rotation; opening it never silently treats missing revocations as an empty history.
 
 This is reviewed ledger hosting, not automatic Cykick/Astrolift enrollment. Remote
-workspace identity, dispatcher credential delivery, task-attempt ownership, transport
+workspace identity, dispatcher credential delivery, exclusive task ownership, transport
 reachability and any narrower Cykick file-mutation policy still need their native
 bindings. A loopback listener does not make a desktop reachable from a remote pod.
 
+## Serve one active native task attempt
+
+```sh
+calliope ledger serve-task --run RUN_ID --task TASK_ID --attempt 1 \
+  --max-output-tokens 1024 --project /path/to/project \
+  --token-file /private/task.token
+```
+
+`prepareReviewedTaskLedger(cwd, runId, taskId, attempt, maxOutputTokens, options)`
+derives the agent, session, immutable start-event ID/hash and native owner from
+the current attributed `task_started` journal event. Pending, legacy unattributed,
+stopped, completed and stale attempts cannot open this host. The private token's
+audience binds that task, owner and output cap as well as the reviewed run.
+Another task, changed owner, different cap or account-only host rejects the token.
+This endpoint advertises reviewed capability version 2 with `taskBinding: 1`.
+
+Its operations are only `hello`, `journal`, `task-execution`, `reserve` and `settle`.
+There is no legacy `execution` fallback or child-grant mutation. Current clients
+negotiate `task-execution`, validate its version 2 binding and automatically carry
+the exact attribution and output cap into the shared execution guard. Older clients
+refuse the missing legacy operation before inference. Each new reservation verifies
+the attribution, agent, output cap and still-active native owner/attempt, including
+under the ledger writer lock. Existing admissions may replay or settle after the
+attempt ends; the original token expiry and accounting still apply.
+
+Task-bound sessions retain version 2 restrictions with the start-event provenance.
+A different task/attempt or an account-only connection cannot resume them. Reopening
+the same active attempt preserves its token, allowance, history and deadline.
+This does not dispatch work, acquire an exclusive process lease, implement Astrolift enrollment. A trusted scheduler still
+owns those actions and the delivery of the private credential.
+
+Run `CALLIOPE_REVIEWED_HOST_TASKS=1 npm run test:reviewed-host` for the real-process
+task-host qualification. It checks two concurrent headless children, native ACP
+session binding, exact request attribution, host restart, completed-attempt refusal, an active sibling
+and run cancellation against a local deterministic provider with no paid requests.
+The current reverse exec tunnel retains its child-grant contract; this task-host
+mode is qualified through direct native HTTP transport.
+
 ## Run a delegated child
 
 A host (Cy, an Astrolift task) grants the child, writes its scoped token to a private file and
@@ -100,6 +152,7 @@ undelegated fallback.
 | `hello` | any | protocol and operations |
 | `journal` | any | the full hash-chained history (`manifest`, `events`) |
 | `execution` | account owner | verify `{agentId, project: {root, key}}` against the retained owner grant and return its native workspace binding |
+| `task-execution` | task owner, task endpoint only | verify the account/workspace and return the immutable native start provenance and output cap |
 | `reserve` | owner of `reservation.agentId` | charge before dispatch; same id replays the original admission |
 | `settle` | owner of the reserved request | record usage or an outcome; same settlement replays |
 | `grant` | parent, or a child for its own accounts | allocate child accounts; returns the child's scoped token |
@@ -321,7 +374,7 @@ The executable reports its tested artifact type and invariant results as JSON.
 This is a local HTTP host example, not a deployed Astrolift acceptance test.
 Use `delegation-ledger/v1`, reviewed host capability version 1 and the headless
 capability tuple above; a matching package version alone is insufficient.
-The current CLI entry point requests a 4096-token output limit, so the reviewed
+The account-only CLI entry point requests a 4096-token output limit, so the reviewed
 host and discovered model must both permit that bound. Lower output caps are
 available to library callers through `DelegatedExecutionOptions.maxOutputTokens`.
 The existing ledger, workspace and session suites cover nested grants, lost

package/docs/improvement-cycles.md

@@ -0,0 +1,309 @@
+# Bounded improvement cycles
+
+Version-4 [supervised runs](continuous-supervision.md) record each final `retry`,
+`replan` or `decompose` decision as an improvement cycle. The controller optimizes
+for the reviewed principle (`speed`, `robustness`, `stability`, `security`,
+`performance` or `cost`), reviews executor evidence, and receives the latest four
+cycles' measured outcomes. A reviewer, when configured, owns the final decision;
+its controller draft is not a second improvement.
+
+## Host capability discovery
+
+`calliope improve host-capabilities --contract-version 1 --json` returns the
+additive version-1 `improvement.host-capabilities` contract. It inventories the
+native execution, review-request, task-outcome and source-change interfaces with
+their independent versions. Discovery uses CLI JSON; operations use the native
+library APIs described below. This declaration does not create remote RPC methods.
+Unknown requested versions and run/approval/mutation selectors are refused.
+
+`implementation` identifies the installed package version, artifact form and
+build metadata status. Source metadata records the build's Git commit and dirty
+state when available; builds outside their own source repository retain `null`.
+The query never runs Git in the caller's project. Missing, malformed or mismatched
+metadata cannot establish source identity. Even clean metadata is self-reported:
+verify npm integrity and publisher provenance, or standalone release checksums
+and binary attestations, against the same release tag and source commit before
+trusting it. The query explicitly reports `external-attestation-required`.
+
+Legacy execution discovery remains unchanged:
+
+`calliope improve capabilities --json` returns a version-1 `improvement` envelope
+whose action is `capabilities` and whose data kind is `improvement.capabilities`.
+The data contract is version 2; its `hostAdmission` field advertises the native
+`expectedExecutionRevision` option for propose/run and binding to the controller's
+own committed reset event. Version-1 declarations do not promise this admission
+contract. The outer CLI response envelope remains version 1.
+This read-only query does not select a project/run, call a model, import feedback,
+or grant execution authority. Run selectors, approval hashes and mutation flags
+are rejected for this action. Hosts must negotiate this declaration instead of
+inferring learning support from the package version or command names.
+
+The current declaration advertises native recursive task-strategy improvement,
+history schema versions, operation effects, exact-proposal approval, inherited
+limits and withdrawal semantics. External feedback import, cross-run learned
+strategy selection and model training are explicitly unavailable. Project brain
+memory remains a separate interface. A supported operation still requires the
+exact native run's current state and policy; this declaration is not evidence
+that an installed run can execute it. Unknown contract versions are not compatible
+by implication. This is the capability-discovery part of #413, not a completed
+external feedback or reinforcement-learning interface.
+
+## Host review requests
+
+Explicit host contract version 2 additionally exposes the
+[reviewed task feedback](task-feedback.md) record/inspect/history API. Version 1
+discovery remains unchanged. Feedback receipts do not award rewards or enable
+cross-run learning.
+
+The separately negotiated `improvementReviewCapabilities()` API (version 1,
+`improvement.review-capabilities`) advertises `requestImprovementReview`,
+`inspectImprovementReviews` and `dismissImprovementReview`. It is request-only;
+existing version-2 execution capabilities are unchanged. Hosts must negotiate
+this API separately before exposing a model request tool. Hosts supply the model-tool and human-review UI adapters. This API increment
+does not add a CLI subcommand.
+
+Requests carry version 1, `action` (`propose`, `run`, `rollback`), the exact
+`executionRevision`, `cycleId` and `proposalHash` (both null for `propose`), and a
+nonempty untrusted `reason` of at most 1,024 characters. Recording requires an
+inactive approved supervised run and native policy/confirmation. It calls no
+model, starts no worker, approves no proposal, and changes neither task state nor
+budget. Run/withdrawal requests bind the native proposal hash; a new proposal
+request needs retained task outcomes and remaining original controller time and
+round capacity. Withdrawal requests can outlive the original deadline.
+
+Version-9 events append to the existing private execution journal. Each request
+is bound to the immediately preceding revision. Only one request can be current;
+identical retries after a lost acknowledgement return that same request ID after
+rechecking policy and run approval. A competing changed request fails. Native
+ownership, revision and revocation checks run again before commit. At most 64
+requests are retained per run, within the existing journal byte/event bounds.
+Replay independently validates requests and never derives execution authority
+from them. Older readers that do not support event version 9 must refuse these
+journals; do not downgrade a run's owner after recording a request.
+
+Inspection projects `pending`, `expired`, `stale` or `dismissed` from native
+events. Any later execution/control event makes the old request stale, not
+approved or completed. Human execution must use a fresh native inspection and
+the existing proposal/run/withdrawal APIs with their normal review and policy.
+Dismissal requires the exact current request ID/revision and a separate native
+confirmation; it retains all history and does not withdraw the strategy. The
+request reason remains untrusted display data, never an instruction or reward.
+
+## Controls
+
+```sh
+calliope improve history --run RUN_ID --json
+calliope improve propose --run RUN_ID --allow-mutations --json
+calliope improve run CYCLE_ID --run RUN_ID --approve PROPOSAL_HASH --allow-mutations --json
+calliope improve rollback CYCLE_ID --run RUN_ID --allow-mutations --json
+```
+
+The REPL exposes the same arguments under `/improve`. Without a subcommand it
+shows history; without `--run` it inspects the latest run in the active project.
+Headless mutations require `--allow-mutations` or an approval callback, and still
+pass project policy. REPL approvals use the existing scope preview and audit log.
+
+`propose` reviews an inactive supervised run's retained outcomes, or returns its
+existing pending proposal without another model call. Explicit recovery of a
+halted controller retains its original rounds, task attempts, reservations and
+deadline. It starts no workers and applies no proposed changes. It needs recorded
+outcomes and remaining controller authority; a completed run or a `continue` or
+`stop` decision can produce no improvement proposal. Inspect that decision before
+resuming ordinary execution.
+
+A recorded proposal hold survives restart. `run` requires its exact review hash;
+ordinary `run resume` cannot bypass that hold. Approval is recorded in the same
+execution journal before application, and checked again under coordinator
+ownership. All subsequent decisions remain subject to the original reviewed
+supervision policy. To inspect and retire a strategy, stop the coordinator first.
+
+Native hosts can pass `expectedExecutionRevision` to `proposeImprovement` and
+`runImprovement`. It must match the execution revision from their reviewed
+inspection. Malformed, missing-history and stale bindings are refused before
+execution approval. The coordinator rechecks after asynchronous authorization,
+under its ownership lease and inside the journal append lock before starting
+work. The execution permission request includes that bound `executionRevision`.
+An explicit controller reset advances the binding only to its own committed
+reset event; another writer's revision is never silently adopted. Existing
+callers that omit the option bind to the history inspected by the improvement
+action. This host API does not add a CLI flag; hosts negotiate the version-2 data
+contract before relying on it. It does not authorize execution, change proposal hashes, or replenish
+the original budget or deadline.
+
+`rollback` **withdraws the execution strategy**. For a replan it restores the
+previous unwithdrawn applied strategy; for decomposition it stops the admitted
+child agents and their descendants. It stops controller continuation and preserves
+the task graph, allocations, attempts, checks, candidate worktrees and artifacts.
+It does not apply an inverse patch to source: this loop edits isolated candidates,
+and never automatically applies them to the source checkout. Inspect the retained
+base commit and patch artifacts to compare or recover a candidate. A different
+pending decision must be resolved before withdrawing an older cycle. Withdrawing
+an expired cycle is allowed because it reduces authority; it cannot revive the
+clock or refund spend.
+
+## Evidence and schema
+
+History is a deterministic projection of the existing private, hash-chained
+journals, not a second mutable database. Legacy histories and cycles retain
+`version: 1`; runs with [request attribution](request-attribution.md) use version 2
+and identify the observed budget revision. Cycles whose review events carry
+sanitized [provider-health evidence](provider-health.md) use version 3 and retain
+the controller snapshot plus the reviewer snapshot when that separate role is
+configured. This records the aggregate operational evidence available to each
+decision without importing credentials, endpoint strings, provider text or new
+execution authority. Each cycle's immutable ID is its final decision event ID. It
+includes:
+
+- Trigger event IDs/hashes, principle, proposed hypothesis/change/metric.
+- Parent decomposition and previous attempt links, target tasks, original run
+  deadline and limits, scoped worker/controller/reviewer accounts and ancestors.
+- Review hold, explicit approval, application and withdrawal event references;
+  original plan approval and separate production approval (`not-approved`).
+- Baseline and direct next-attempt outcomes, checks, artifact hashes, observed
+  duration/tool results, unresolved risks, isolation image and rollback references.
+- Original manifest hash and the inspected execution revision.
+- Controller and optional reviewer provider-health snapshots, their observation
+  times, relevant-event counts and history hashes.
+
+Inspection validates journal ancestry, current artifact read permissions, retained
+artifact bytes and the pinned worktree base. Evidence reads are bounded to 64 MiB
+per inspection; histories retain the execution store's existing event/size bounds.
+No inspection calls a model or replays a tool. Recorded run replay reproduces the
+same cycles without execution. Keep history private: task evidence can contain
+project information even though API keys are not part of the cycle contract.
+
+A cycle measures its **direct next attempts**. If a decomposed child fails and a
+nested replan fixes it, the parent cycle retains that first failed result and the
+nested cycle records the verified retry. This preserves the failure instead of
+retroactively claiming every experiment succeeded. `verified` means the recorded
+targets completed their acceptance process, not that every optimization claim was
+proved. Human acceptance remains distinguishable by its source event.
+
+## Measurements and limitations
+
+| Measurement | Definition | Comparison requirement |
+|---|---|---|
+| `acceptance-check-pass-rate` | Passed recorded acceptance checks / all recorded checks | Same tasks and check definitions |
+| `attempt-duration` | Sum of task-start to task-finish event durations, milliseconds | Same complete task population |
+| `tool-failure-rate` | Failed completed tool calls / completed tool calls | Same complete task population |
+| `provider-accounted-cost` | Accounted provider charges for the recorded worker attempts, integer nano-dollars | Same complete task population, bound request provenance and fully settled usage |
+
+Missing measurements are `null`, never zero. New task populations and changed
+check definitions are explicitly non-comparable. These observations do not prove
+causality or provide an automatic security/performance certification. Requested
+metrics remain proposed even when checks pass. The duration is summed task time,
+not workflow wall time; acceptance checks are not the individual assertions inside
+a test process. The cost measurement excludes planning and controller/reviewer
+overhead, and is not whole-goal cost per successful task or an invoice. Those
+roles retain separate request attribution in run diagnostics. Unknown or pending
+requests retain their conservative charge, but prevent a comparable cost delta.
+Legacy/missing bindings yield unavailable costs rather than fabricated zeroes;
+the shared run/project ledgers continue enforcing their original reservations.
+
+For linked goals, [whole-goal metrics](goal-accounting.md) separately include
+planning and review overhead and inspect final artifacts before reporting cost
+per verified task. This total is not a comparable before/after cycle metric.
+
+The HUD adds the latest cycle's status, comparable check rate and comparable
+worker-attempt cost. Explicit Brain run ingestion cites the budget revision and
+stores a separate snapshot when accounting changes; hypotheses remain proposed.
+Headless output
+uses `version: 1`, `type: improvement` for results and `type: improvement.event`
+for streamed execution events; enclosed events keep their own schema version.
+Execution exit codes remain 0 success, 4 partial, 3 policy denial, 130 cancellation
+and 1 failure; malformed command arguments exit 2. History is local-only JSON and
+can be redirected for diagnostics. There is no import of execution authority.
+
+## Safety and recovery
+
+The loop cannot edit permissions, expand budgets/depth/count, reset deadlines,
+erase evidence, publish, merge, deploy or send external messages. Every file/tool
+mutation uses the shared runtime gates; child admission rechecks inherited scope
+and grants. All coding attempts use retained Git worktrees and reviewed isolated
+verification. Unknown requests retain their reservation, and interrupted calls
+require explicit recovery. A cancelled or denied experiment keeps its partial
+results; a new run is not an automatic escape from its allowance.
+
+This implements recursive, evidence-driven **task strategy improvement**. It does
+not automatically patch Calliope itself or promote knowledge to accepted fact.
+The [project Brain](project-brain.md) can explicitly ingest verified run evidence;
+improvement hypotheses remain proposed. [Opt-in agent retrieval](agent-knowledge.md)
+lets planners and workers read that knowledge within their inherited source scopes.
+
+## Reviewed source proposals
+
+The native `sourceChangeCapabilities`, `previewSourceChange`,
+`proposeSourceChange`, `inspectSourceChange` and `listSourceChanges` APIs let a host offer verified
+source changes for human review. A source-owned skill or interface uses the Git
+repository that owns its files. Installed skills keep their separate installation
+and trust lifecycle.
+
+The selection binds the original run, execution revision, verified cycle, task
+and executor-collected patch hash. Preview checks the original approval, task
+write scope, pinned source commit and repository-local author. It returns the
+patch, affected paths and a review hash without creating Git objects or refs.
+Creating a proposal requires the exact `orchestration_source_proposal` permission
+and rechecks those inputs under the execution lease.
+
+The writer creates one commit and one local branch under
+`refs/heads/calliope-proposals/<run>/<review hash>` using a temporary private
+index. It leaves the source checkout/index and execution journal unchanged.
+Immutable intent and candidate records support retry after cancellation or a lost
+response; repeated publication recovers the same branch instead of overwriting
+it. Inspection reports `prepared` when the branch is absent and `proposed` when
+the exact recorded commit is present. Absence alone does not establish whether
+someone previously removed the branch. A moved branch is a conflict.
+Listing retains original review identities across restart and source HEAD changes;
+it reads the same native intent/candidate records and checks each branch.
+
+This API does not install skills, merge, push, release or invoke a model. A host
+must explicitly support the separate versioned source-change capability before
+offering the action. Desktop integration and platform qualification are separate
+from native API validation.
+
+## Ordinary task evidence
+
+`taskOutcomeCapabilities()` and `inspectTaskOutcome(project, runId, selection,
+options)` expose the same native evidence for an ordinary task outside an
+improvement cycle. Select `{taskId, attempt, executionRevision}` from an inactive
+run. The reader replays the journal at that attempt's start, retains its task,
+agent and strategy configuration hash, and revalidates each artifact's bytes
+under the native read policy. It refuses active ownership, stale selections and
+changed or missing evidence. In particular, a historical live project file that
+a later retry overwrote cannot be freshly verified; retained run artifacts allow
+independent inspection of both attempts.
+
+The returned `{value, hash}` separates executor status from native human task
+acceptance, includes original event/check/artifact references, and attributes
+charges to the exact start event using the reservation ledger. Missing or
+unsettled costs remain `null`; reservations are not reported as settled cost.
+Duration, tool calls and failures are recorded observations. An interrupted
+attempt without a finish remains unknown. The accounting snapshot carries its
+own ledger revision and may advance independently of the execution journal.
+
+This read-only API performs no inference, artifact execution, ledger writes,
+user assessment, feedback import or reward assignment. A host may separately
+propose a human assessment for memory review; doing so does not change the
+executor evidence. Ordinary-task UI and memory feedback require their own host
+qualification.
+
+## Native validation
+
+The [native Brain-loop receipt](docs/evidence/native-brain-loop-smoke.json) records a
+Fable planner/controller and a Haiku worker on a public clamp fixture. All 12 paid
+requests used the native provider after live discovery. Planning recovered from
+one output cutoff within its original allowance. After exact-plan review, the
+worker submitted a deliberately unchanged baseline, the real Docker check failed,
+the controller replanned, and a one-line repair passed the same unchanged tests.
+The live HUD showed both agents, attempts, controller rounds and remaining budgets.
+
+Planner and worker Brain reads left its journal unchanged. A fresh process resumed
+and replayed the completed run without model calls or execution/budget changes.
+Explicit run ingestion then preserved both failed and passed checks as observations
+and the improvement hypothesis as proposed knowledge. All artifact hashes were
+verified, and the source checkout remained unchanged.
+
+The probe retained $3.068752 of conservative reservations, including the cutoff,
+within a $5 cap. This demonstrates one staged repair cycle; it does not establish
+general coding reliability, causal improvement, or native nested decomposition.
+Provider conformance and signing remain separate release gates.

package/docs/releases/3.7.0.md

@@ -0,0 +1,53 @@
+# Calliope CLI 3.7.0
+
+This release adds durable ACP session controls, tightens reviewed inference
+admission, and publishes a versioned discovery contract for native improvement
+hosts. It retains the LiteLLM retirement and Hugging Face support from 3.6.0.
+
+## ACP session controls
+
+ACP clients can change Work/Plan mode through `session/set_mode` and choose a
+model through `session/set_config_option`. Model choices come from live provider
+discovery. Saved controls survive process restart; stale or concurrent updates
+refuse instead of overwriting another client. Plan mode denies mutating tools.
+Delegated sessions retain their parent's model authority.
+
+The stable ACP wire protocol and `--version --json` remain unchanged. Clients
+must negotiate `_meta.calliopeSessionControls.version: 1`; an older CLI does not
+promise these controls. See the [ACP contract](../acp.md).
+
+## Reviewed inference authority
+
+New remote-ledger reservations must match the current admitted agent's explicit
+provider/model choices. The host rechecks those constraints under the ledger
+writer lock, including for newly admitted descendants. Rejected choices leave
+the parent's allowance unchanged; already-admitted requests retain their replay
+and settlement semantics.
+
+The Node and standalone qualifications use real child and ledger processes with
+deterministic local inference. Task/attempt and endpoint authority, Smart routing
+stage binding and actual disposable Astrolift parent/child acceptance remain in
+[#415](https://github.com/calliopeai/calliope-cli/issues/415). This release does not
+claim those deployment requirements are complete.
+
+## Native improvement host discovery
+
+`calliope improve host-capabilities --contract-version 1 --json` reports the
+installed native execution, review-request, task-outcome and source-proposal
+interfaces with independent versions. It does not open the caller's project or
+grant execution authority. Unsupported versions and execution selectors refuse;
+the existing `improve capabilities` response remains compatible.
+
+The declaration includes the installed package version and build source metadata
+when available. Metadata is self-reported, not proof of authenticity: verify npm
+integrity and provenance, or native checksums and attestations, against the release
+tag and source commit. Missing, dirty or invalid metadata cannot establish a
+released build. See the [improvement host contract](../improvement-cycles.md).
+
+External feedback import, cross-run learned strategy selection and model-weight
+training remain unavailable. SDK 7 recapture work remains separate from this
+release; xAI live qualification remains deferred.
+
+Refs: [#444](https://github.com/calliopeai/calliope-cli/issues/444),
+[#415](https://github.com/calliopeai/calliope-cli/issues/415),
+[#413](https://github.com/calliopeai/calliope-cli/issues/413).

package/docs/releases/3.8.0.md

@@ -0,0 +1,65 @@
+# Calliope CLI 3.8.0
+
+This release adds explicit subscription access, native task-bound delegation and
+reviewed feedback. It also tightens reviewed inference authority and reads
+Mimwell portable knowledge graphs.
+
+## Experimental subscription access
+
+`calliope auth chatgpt login` selects ChatGPT-plan access for the OpenAI provider.
+Account selection, private credential storage, refresh/revocation and live model
+discovery are separate from API-key access. Streamed Responses and tool calls use
+Calliope's existing permission loop. Expired sessions stop; quota exhaustion can
+use an explicitly configured paid API-key fallback. Subscription requests refuse output-token
+and USD enforcement that the service cannot provide; USD totals exclude this
+consumption. See [ChatGPT plan access](../chatgpt-plan.md).
+
+Quota and rate-limit circuits persist across processes. Opt-in API-key fallback
+reserves every paid request against a shared project ceiling, preserves public
+conversation/tool context and strips encrypted subscription state. Paid sessions
+stay on their selected model; partial output, cancellation, logout and reviewed
+execution stop automatic transitions. A depleted API account stops without
+retrying or switching back. Missing live/reviewed billing bounds refuse payment.
+
+`calliope claude -- <prompt>` delegates a complete session to the installed,
+authenticated official Claude Code CLI. `calliope claude status` checks that local
+setup. Claude owns permissions, tools, sessions and plan usage; Calliope's native
+sandbox and budgets do not govern the delegated session. See
+[local Claude plan delegation](../claude-plan.md).
+
+These integrations ship as opt-in experimental features. Tests use synthetic
+authentication and response fixtures; live account eligibility and subscription
+prompt/tool round trips remain unqualified. Complete the user-operated checks in
+the linked guides before relying on either route for unattended work.
+
+## Reviewed task authority and feedback
+
+Delegated headless and ACP execution can bind to an exact native task attempt,
+including its owner, output cap and original accounting across host restarts.
+Completed or mismatched attempts refuse new inference. Reviewed Smart routing
+pools and provider endpoints now constrain new reservations; an endpoint change
+requires new review, while prior admissions retain replay and settlement.
+See [delegation ledger](../delegation-ledger.md).
+
+Version-2 improvement host discovery exposes reviewed task feedback. Receipts bind
+an assessment to the exact observed completed attempt and retain private journal
+evidence. They neither mark a task accepted nor activate a learned policy. See
+[task feedback](../task-feedback.md). External placement and disposable remote
+parent/child acceptance remain tracked in #415; cross-run learned strategy
+selection remains tracked in #413.
+
+## Compatibility and runtime
+
+- `brain import` accepts `mimwell-kg/v1` alongside existing graph formats; exports
+  continue using `calliope-kg/v1`.
+- OpenAI SDK 7 stream capture handling now recognizes delivered completion events.
+  Runtime SDKs, Conf, Ink and supporting dependencies are updated; container builds
+  include the metadata builder.
+- Node 24 or later is required. The stable ACP wire protocol remains version 1.
+- Mistral/Hugging Face SDK 7 live qualification follow-up remains in #457; xAI is
+  explicitly deferred by the existing publication gate.
+
+Performance budgets from #210 remain enforced for cold start, keystroke rendering
+and retained-session heap growth. See [performance measurements](../performance.md).
+
+Refs: #474, #467, #468, #415, #455, #463, #457.

package/docs/reviewed-provider-metadata.md

@@ -0,0 +1,84 @@
+# Reviewed metadata for bounded provider calls
+
+Some providers discover model IDs without publishing capabilities, limits or
+prices through their models API. An operator can supply the missing evidence for
+bounded execution in a private billing file. This does not enable Smart routing,
+change a provider/model pin, or add models to discovery. The selected model and
+endpoint must still match recent live discovery.
+
+Use `~/.calliope-cli/billing.json` or `CALLIOPE_BILLING_FILE`, outside the worker
+project. Protect it with `chmod 600`. The existing reader rejects aliases,
+symlinks, hardlinks, group/world write access, files over 128 KiB and more than
+64 profiles. Profiles are operator authority; workers must never generate or
+install them from their outputs.
+
+```json
+{
+  "version": 2,
+  "profiles": [{
+    "version": 2,
+    "provider": "deepseek",
+    "model": "<exact live-discovered model ID>",
+    "target": "<configured providerTarget(provider).key digest>",
+    "checkedAt": 0,
+    "expiresAt": 0,
+    "sources": ["https://api-docs.deepseek.com/quick_start/pricing/"],
+    "prices": {"input": 0, "output": 0},
+    "capabilities": {"chat": true, "tools": true, "streaming": true},
+    "limits": {"contextLength": 0, "maxOutputTokens": 0},
+    "admission": "reviewed-full-context-v1"
+  }]
+}
+```
+
+The placeholders are intentionally invalid. Set positive token limits from
+current provider documentation and epoch-millisecond timestamps, with expiry at
+most seven days after review. Review the exact endpoint's billing terms: a
+gateway may charge differently from its upstream provider. Prices are USD per
+million tokens and must upper-bound applicable cache, reasoning and time/tier
+rates on the adapter path. URL presence alone does not verify metadata. Include
+no keys, private prompts or response content; source URLs must be HTTPS without
+credentials, queries or fragments. Every configured provider can use this schema;
+the CLI bundles no model or pricing catalogue.
+
+## Conservative admission
+
+Each request reserves the larger of reviewed and live input capacity, plus its
+requested maximum output. This is a full-capacity allowance, not a tokenizer
+estimate or consumed tokens. A tiny prompt to a large-context model may therefore
+need substantial token headroom before dispatch; do not reduce the reviewed
+capacity to make a budget fit. Successful usage reporting settles the reservation
+to reported usage at the reserved rates. Failures, cancellation and missing usage
+retain the reservation, and overruns stop subsequent requests.
+
+The output maximum is the smaller of the reviewed and live limits. Prices use
+the larger rate for each input/output direction. Reviewed capabilities fill only
+unknown live fields; a live rejection always vetoes the request. Unknown required
+capabilities in both sources fail closed. Live routing metadata remains unchanged,
+including unknown prices used by Smart ranking. This profile does not request
+Anthropic token counting, accept supplied input counts or admit multimodal input.
+
+The provider/model/endpoint binding, original run/agent/project budgets, policy,
+deadlines and cancellation checks still apply. The profile is re-read before
+reservation and before dispatch; deletion, edits or expiry revoke admission.
+Revocation after a durable reservation retains that reservation conservatively.
+No automatic paid probe or retry can replenish the original allowance.
+
+## Versioning and recovery
+
+Version-2 billing files can contain these profiles together with unchanged
+[legacy counted profiles](counted-admission.md). Version-1 files retain their
+original format and hashes; no file or historical journal is migrated.
+
+New quotes carry `quoteEvidence.version = 2`, including the reviewed profile and
+digest, quote time, live observations and required capabilities. Execution
+reservations carrying that proof use reservation event version 4, also supporting
+existing request attribution. Replay reconstructs the conservative bounds from
+the recorded proof and rejects inconsistent prices, limits or event versions.
+Historical replay checks validity at quote time, without fetching metadata or
+requiring a now-expired profile to be renewed.
+
+Ordinary project-capped turns include the same proof in their existing hash-linked
+policy audit event. Execution journals retain it with the reservation. Neither
+contains prompt bytes, tool arguments or credentials. The outer headless JSON
+envelope and existing ledger projections retain their versions.