Skip to main content
This guide starts with explicitly configured, storeless native Rust sessions and describes native persistent composition, including SQLite execution custody. The embedding application is trusted code: it authenticates callers, supplies current policy owners, and attaches the actual controller and executor. Merely enabling a Cargo feature or calling agent.run(...) does not establish this integration.
Explicit native embedding supports storeless sessions and persistent sessions over the in-memory or SQLite runtime store. After a completed turn, a SQLite session reopens in a new process under the host’s current grants, configured provider binding and credential owner. Stock CLI, REST, RPC and MCP paths do not acquire governed activation from this API: the stock rkat CLI and rkat-rpc open a governed realm through their own stock composition (see Governance settings), and the stock REST and MCP servers refuse to start on one. The meerkat_rpc::governed_jsonl entry, under meerkat-rpc’s default local-authorization feature, provides a fixed-host, single-connection profile and does not activate ordinary RPC constructors; a connection not commissioned for live MCP attachment needs a build without the mcp feature (see below). Console projection does not activate native governance. Provider login and Console access administration do not grant native operation permission.

Install the real owners before sharing the machine

Enable meerkat-runtime’s local-authorization feature in the matching checkout or dependency release. Compose NativeGrantWorkConfiguration from these owners: The policy callbacks read current local owner facts without I/O. Relevant owner mutations participate in the grant authority’s publication. Preserve correlated principal/action/resource rules; independent lists must not grant extra pairs.
For a storeless machine, install before wrapping it in Arc, cloning it, or registering sessions. Already shared or populated machines refuse installation. For persistence, select governed mode during construction as shown below. The fluent installer does not upgrade a persistent machine. The backend must supply exclusive execution custody; setup refusal must propagate before publishing a service or provider-auth handle.

Configure native shell confinement on the factory

For automatically composed shell tools, install the trusted host requirement with AgentFactory::with_shell_confinement. Keep using the native owners above to authorize each exact shell operation. Confinement controls the process’s mechanical access after authorization; it does not authenticate input or grant permission to a command. This native Rust excerpt assumes existing, canonical absolute paths named work_root and sessions_path. It grants application filesystem access to the work tree plus the declared command-runtime baseline and denies IP networking:
Use this builder in the native service composition below. Each agent build creates its own shell dispatcher and shared job manager, retaining the same immutable host requirement for foreground, background and monitor launches. The application need not inject a shared shell dispatcher or a second policy evaluator. When the factory also has a runtime root and session identity, it settles earlier process custody and binds that session’s durable process owner before publishing the dispatcher. Without a runtime root, shell containment is in process; background jobs still require their separate durable job runtime. Required enforces the complete supported requirement or refuses that launch; there is no unrestricted fallback. The current backend uses macOS Seatbelt. Non-macOS hosts, exact IP endpoint grants and required termination of descendants that escape their process group are unsupported. Invalid requirements or an unavailable executor also refuse before the requested command runs. Required launches use the configured cwd and exact explicit environment, with no ambient environment inheritance. Select a directly executable shell allowed by the requirement; the example uses /bin/bash to avoid macOS /bin/sh’s mutable selector outside the work grant. TrustedHost is the default shell compatibility mode and inherits the host environment. It is independent of local-governed authorization: installing native grant owners does not select Required, and selecting Required does not install those owners. If the application grants only its local tools, disable provider-hosted capabilities it does not authorize in the existing Config before constructing the builder. For example, Anthropic web search defaults to enabled on supported models; the shell E1 fixture uses the explicit disable shown above. It is an application capability choice rather than a requirement for every shell host. This selects requested provider capabilities. It does not replace the native controller or operation owner checks, and a capability kept enabled still needs its own current authorization. Under required shell confinement, a command that enters and then attempts a denied filesystem write receives a nonzero exit with stderr; the outside file remains unchanged, a permitted sibling executes, and the same run continues to its next model turn. That is returned shell feedback from an entered process. A backend or launch refusal happens before the command runs. Shell dispatch preserves its exact mechanical cause as confinement_refused tool feedback, including foreground, background and monitor recovery paths. Ordinary IO and custody failures retain their execution error class. The member upcall bridge preserves the exact confinement cause and settlement companions in tool feedback; malformed causes become an ordinary execution failure rather than a fabricated mechanical refusal. Required confinement has backends on macOS and Linux; on other platforms a required launch refuses. The core pre-tool path also accepts a typed HookEngineError::LaunchRefused from an injected hook engine. It skips that tool and returns the exact confinement_refused or ordinary execution_failed feedback; permitted siblings and the next model turn continue. HookLaunchRefused retains the attempted tool call ID without emitting hook start or completion events. An explicit pre-tool hook decision likewise refuses only its attempted call, using hook_denied feedback with the exact hook ID, point, reason code and optional JSON payload. An absent payload and a present JSON null remain distinct, including across the member upcall bridge. The entered deciding hook retains its start, completion and denial events; its decision is not a launch failure. AgentFactory::with_command_hook_confinement (or with_host_confinement for a stock host’s resolved requirements) applies required confinement to automatically composed command hooks: the final command, argv, cwd and explicit environment are bound before launch, and ambient environment is not inherited. Missing native custody or an unsupported requirement refuses the launch and never falls back. A pre-tool launch refusal blocks its tool and becomes local feedback; other hook points keep their existing failure disposition. hook_engine_override cannot be combined with this requirement.

Install a bounded model reviewer for R2 tools

Install review on the trusted host’s AgentFactory, before constructing the FactoryAgentBuilder. Your OperationPolicyOwner still selects the required LocalPolicyAllowance.review_tier for each exact operation. Installing a model neither changes that tier nor grants permission. R1 keeps its normal native authorization checks and makes no reviewer call. This excerpt uses your configured factory and config. Set reviewer_model to an explicit model name supported by your configured OpenAI backend, and reviewer_auth_binding to its existing AuthBindingRef. These are host configuration, not values taken from the proposed tool call. Reuse the host’s ApprovalService as approvals.
Here, 256 is the output-token limit and eight seconds is the absolute review deadline, including context reads and the model request. Keep it below the effective tool timeout, including any config.tools.tool_timeouts override. An allow expires at that same deadline and is checked again at effect entry. The adapter makes one tool-free request, with no retry or fallback; it does not accept per-session provider parameter overrides in the reviewer identity. NativeOperationReviewContextSource reads through the candidate’s retained native work owner. Each original source read and the reviewer’s own inference need independent current authorization under that work. The tool’s permission does not grant either. If those prerequisites also require review, this adapter refuses rather than approving them recursively. A missing context reader, denied source or model route, expired deadline, or unsupported reviewed entry produces local unavailable feedback; there is no transcript or ungoverned-model fallback. For an R2 tool, model deny or escalate returns local review_unsatisfied feedback, and review unavailability returns review_unavailable. The attempted effect does not run; permitted siblings can continue. An allow still needs the same candidate and current native permission at entry. Failure to stage the candidate’s protected audit link prevents reviewer entry. That failure, source observation failure and reviewer-model observation failure retain the typed operation_observation_unavailable outcome. The engine preserves completed sibling results before reporting that infrastructure failure for the affected attempt. Fresh work requires new native admission. R3 returns human-consent-required feedback: this adapter provides no automatic human route, and a model allow cannot satisfy R3. Custom OperationReviewer and OperationReviewContextSource implementations return ReviewerFailure::Unavailable for ordinary unavailability and preserve ReviewerFailure::ObservationUnavailable for protected observation failures. Existing unit constructors or patterns using ReviewerFailure must migrate to ReviewerFailure::Unavailable. The protected input-row audit records the candidate-to-attempt link and each source/model operation’s authorization observations. It follows the existing input commit and store durability rules. Optional BoundOperationReview::with_observer events are live notifications, not durable consent records. Neither those events nor recovered audit IDs recreate a live allowance, and review approval is not evidence that the tool executed. Since 0.9.4 a single owner change does not fail an R2 call. When one owner publication change lands during the review, at its verdict’s commit, or at the dispatch’s own entry staging before the tool’s dispatcher runs, and the operation is still permitted at R2 with the same review material, the fenced dispatch re-prepares it and reviews it once more from the start as a second attempt for the same tool_call_id; the earlier verdict is never used. Deciding to review again reads the successor’s material once (review_operation_context); when the material is unchanged, that read is the one the second attempt is shown. A with_observer observer can therefore see a ContextChanged retirement followed by the second attempt: do not treat the retirement as the call’s final outcome. At most one re-review runs per call, only after an allow or a reviewer failure and only with enough tool time left for a whole review deadline. A second change, a denial or escalation, an expired review, a changed tier (human consent included), changed or unreadable material, and a change once the dispatcher runs settle as before. A change still in progress when the verdict is checked is waited out within the attempt’s review deadline (2 s at most). The re-review adds no record type: the audit shows a second ReviewAttemptStarted after the successor’s Prepared record, and a change at the entry staging leaves that staging’s Entry record twice. Per tool call the waits stay bounded: at most 3 wait states, 9 free rebuilds and 6 s of waiting, inside the tool’s timeout.

What the model reads on a refused tool call

A tool call that its operation’s owners refuse returns an error result with a uniform payload:
  • data.kind is the closed refusal kind: reprepare_required, denied or malformed_facts.
  • data.tool_invoked is false only when Core refused the call before the tool’s body ran: before it invoked the tool’s dispatcher, or at the tool’s own effect entry (ToolDispatchContext::enter_reviewed_effect) while no effect of the call had entered. Both read the same, wherever the owner change that refused the call landed. It is "unknown" when the refusal came back from the tool after an effect of the call entered (the tool may have had an effect before a later governed step refused), from the tool’s own code, or from a mob member’s upcall.
  • Neither field is a permission or evidence of one. They name no owner, policy, principal or audit record; a refusal never grants a replay, and a new call is a new operation with fresh admission.
Owners that could not decide return operation_authorization_unavailable, with no data. A dispatcher layer that runs tool code before it delegates must not forward an inner tool_invoked: false: it returns OperationRefused::new(refusal.kind()) instead, which reads "unknown". A leaf that runs an effect of its own before its effect entry is such a layer.

Observe refusal dispositions

A refused or unavailable governed operation reaches the model only as uniform feedback that carries no private fact. The host that composed the agent can see which typed refusal Core met and what Core did with it by installing an OperationRefusalObserver on its factory (or with AgentBuilder::with_operation_refusal_observer):
Each OperationRefusalObservation names the session, the run and the refused operation (the id its authorization audit records), the surface (the model request, a tool call by its tool-use id, or a compaction summary), the outcome (the closed refusal kind with its RefusalDispatch, read from the same refusal the model payload renders, or owners that could not decide) and the disposition: a bounded wait for an owner change (how long, and whether the change settled), the one rebuild, the controller feedback request, the tool result, a skipped compaction or the failed run. Observations are diagnostics at decision time, not durable records: they are not exactly-once across a crash, and an operation reported as waiting or rebuilding can still fail later. None of it enters the event stream, a wire type or any model context. The observer covers the agent’s own governed operations: its model requests, its tool calls (a decided consent’s retained attempt included, once the attempt has resolved its candidate), the owner-change waits of a tool’s delegate operations that wait with the call’s ToolDispatchContext::owner_change_churn, and its compaction summaries. Refusals decided elsewhere are not observed: the exact-control refusals of MCP attachments, tool applications and context controls, a consent attempt refused before it resolved its candidate, and review outcomes, which are not operation refusals.

Authorize the builtin web_search and its helper

Since 0.9.2 the Meerkat-owned web_search builtin is two governed operations. Your OperationPolicyOwner maps both from typed facts, never from the tool name:
  • The call (AuthorizationOperation::Tool). Its plan’s single owner target, single_tool_operation_target(plan), is ToolOperationTarget::BuiltinOperation { operation: BuiltinToolOperation::WebSearch }. The composite dispatcher that registered the builtin states it and revalidates it at dispatch against its exact registration; a plan that carries its witness runs only on that builtin, even after another owner takes the name. A tool merely named web_search from any other owner (your own dispatcher, a registered bundle) has no such target unless that owner states it itself: an in-process dispatcher can, so the target is the dispatching owner’s statement, never proof that the Meerkat builtin runs. The call acts with no account of its own (target.account() is None). Every governed web_search call carries this target under every grant basis, so an owner that refuses targets it does not map refuses web_search until it maps it.
  • Its helper (AuthorizationOperation::Model, usage Inference, always the Operation purpose). binding.delegate_attribution() names the call: parent_binding() is the call’s binding with the target above, and role() is ToolDelegateRole::HostedSearchInference. The facts are the helper’s own: identity, credential, backend, endpoint, wire model, and hosted_capabilities of [WebSearch] (OpenAI, Anthropic) or [GoogleSearch] (Gemini). Return the inference on that route and one tuple per hosted capability, never the controller’s tuple. An inference without an attribution is still an ordinary alternate-model operation.
With a TargetedGrantLineages basis, select GrantTarget::BuiltinToolOperation { operation: WebSearch } for the call and GrantTarget::DelegatedHostedSearch { route, capability } for each approved helper route, where route is ControllerModelFacts::new(selection, endpoint, wire_model).route_key() of the helper’s resolved route. Neither uses the base, the catalog or the controller lineage: the base is neither a substitute nor an implicit intersecting ceiling, and every contributing original must select the same keys with its own current ceiling. A single GrantLineage basis covers both like any other operation. Choosing a target does not erase a restriction: issue those lineages, and every contributor’s ceiling, with the original time, operation (including read-only), resource domain, processor and audience (private-data) restrictions, because the base no longer bounds them. Read-only is an action set: ExecutionRestrictions has no read-only flag, so a read-only lineage is one whose actions are only read actions. A typed public-search target or a read-only declaration does not mean that private information cannot leave through a query; do not infer it. A resource-domain restriction (DomainRestriction) is unrestricted, a set of exact domains, or every domain whose typed authority is one of a non-empty set of owners (DomainRestriction::owned_by). An owner bound matches a domain by its authority alone; a namespace is never a pattern. This lets a parent grant fix the application while each child names its exact session domain: issue the parent with owned_by([application]) and each session’s child with DomainRestriction::exact of the application’s domain for that session. The child’s effective bound is then exactly that domain, and a child that names another authority’s domain permits nothing. The bound isolates applications only as far as each application’s domains carry an authority that no other application shares. An owner bound records no MCP connector approval: only an exact connector domain or connector action records one. Since 0.9.4 ExecutionRestrictions.resource_domains is a DomainRestriction (it was ExactRestriction<ResourceDomain>). Build it with DomainRestriction::{unrestricted, exact, owned_by, unresolved} and read it through bound(), which returns the #[non_exhaustive] DomainBound (Unrestricted, Exact, OwnedBy). A reader that cannot interpret a bound kind must treat it as naming nothing. Conjunction is the exact intersection of both match sets: an owner bound meets exact domains as the owners’ own domains, two owner sets meet as their intersection, and no owner is the empty exact set. Namespaces stay opaque. Review text states an owner bound as “owned by” and its owners. Unrestricted and exact bounds keep their earlier wire bytes in both directions, and the shared restriction conformance corpus moves to contract 1.1 with owner-scoped vectors (the 1.0 vectors are unchanged). A 0.9.3 binary refuses to restore a grant owner whose journal holds an owner-scoped restriction (RestartRequired); a journal that holds none stays readable by 0.9.3. An input row that carries an owner-scoped restriction is written at stored input state 7, and a row stamped before 7 that carries one is rejected. The attribution keys the selection and the protected audit record (AuditDelegateAttribution, with the call’s operation id and the role); it grants nothing. The helper’s own decision and its authorization refusal are recorded under its own operation, also when it is refused before its provider send. A helper the owner rates R2 or R3 settles at its model entry as unsupported_entry (R2) or human_consent_required (R3), whether or not a reviewer exists, because a model request carries no operation review, and nothing is sent. The web_search executor of every provider keeps that typed settlement, so the model sees the same review_unavailable (R2) or review_unsatisfied (R3) tool feedback, carrying only its kind, as for any other tool’s review refusal; an owner that cannot decide the helper now still gives operation_authorization_unavailable. No audit row records that review refusal (a limit of every model request, not only this helper), so the audit shows only its preparation. One attribution can prepare helper requests until its run ends, and each request is its own operation that needs its own current lineage. Behaviour contract for a call that already entered: revoking the call’s own lineage refuses later calls, but it does not cancel an invocation that already entered, and that invocation may still make its authorized helper request. The helper passes its own current work, contributor, route, capability and final entry checks; it inherits no grant, review result or controller authority of its call, and no further authorization or review cycle of the call runs. Revoking the helper’s own lineage, or a contributor’s, before the helper’s send prevents the send, also after the helper’s request was prepared. Cancelling an entered invocation on the call’s revocation would be a different contract that needs a live dependency on the call’s currentness; the stored attribution does not provide one. Neither contract undoes a provider effect that already began or turns a local refusal into the end of the run: a refusal reaches the model as typed tool feedback, and the run continues. The composite rejects stale, wrong-owner and tampered plans within trusted Rust composition. Witness constructors and accessors are public, so this is not cryptographic resistance to hostile in-process Rust code. Operation review of web_search is an unsupported slice, not review coverage: the builtin has no reviewed entry point, so a review its owner requires settles as local feedback and the search never runs. R2 is reviewer_missing without a reviewer and unsupported_entry with one; R3 is human_consent_required without a human consent route and unsupported_entry with one. Serving R2 or R3 for it needs the consuming review entry first. Stock is unsupported for this route too: the stock governed realm issues neither grant and maps neither operation, so a product that takes this route through stock policy needs the full stock path first.

Attach and pin the controller before submitting work

Storeless sessions

Use FactoryAgentBuilder and EphemeralSessionService, then meerkat::surface::materialize_ephemeral_runtime_session to attach the session to that same machine. Start with InitialTurnPolicy::Defer and DeferredPromptPolicy::Discard; the first prompt will enter through native admission.

In-memory persistent sessions

Enable the facade’s session-store, memory-store and local-authorization features. The following excerpt assumes owners from above, a configured FactoryAgentBuilder named builder, a session capacity max_sessions, and an application-selected PathBuf for the existing reconfigure configuration. The configuration path is not the session storage location.
This returns the stock PersistentSessionService and the bundle’s same MeerkatMachine. The service retains the actual session actor; the bundle’s RuntimeStore holds the committed Session document and store-issued revision. The native runtime owns accepted inputs, original authority associations and attached audit, persisted in that same store. These memory stores retain records for the lifetime of the process; they do not provide restart durability.

SQLite persistent sessions

A SQLite composition keeps sessions, accepted inputs, original authority associations and protected audit across a process restart. After a completed turn, closing the service and reopening the same database reconstructs the session actor from its stored Session document under the host’s current owners. Stored effects are not replayed; fresh work needs current grants, ingress authentication and a fresh controller pin.
The facade’s session-store feature already enables its built-in SQLite stores; keep local-authorization enabled for governed construction. Use the actual SQLite session and WholeBlob runtime backends as co-tenants of the same database. This excerpt assumes an application-selected PathBuf named database_path and the application’s existing Arc<dyn BlobStore> named blob_store, alongside owners, builder, max_sessions and reconfigure_config_path from above:
The backend binds row I/O and execution custody to the same canonical regular database file. The trusted host must keep the database and lock namespace stable. Its two dedicated lock files coordinate lifetime claims and short claim admission through the operating system; SQLite transaction locks alone do not supply execution custody. Ordinary backend opening creates no execution lock files. Acquiring a claim requires access to that writable lock namespace. The physical-lock owner uses descriptor-scoped operating system locks on macOS, Linux and Windows; other platforms refuse. An ordinary execution owner requests shared custody; a governed owner requests exclusive custody before recovering provider authority or publishing handles. Conflicting claims refuse locally through the existing Busy class. Unsupported scope and operational acquisition failures remain explicit setup refusals. SQLite’s special :memory: path cannot supply physical file custody and is refused. Use the actual InMemoryRuntimeStore for a process-local in-memory composition. Retained native drivers and exported authorization handles retain their same actual claim. An upgrade from shared to governed custody excludes new admissions while it releases and reacquires the lifetime lock. Contention restores shared custody before returning Busy; an uncertain unlock or restoration failure retains the admission gate and returns Unavailable until the failed claim’s last owner drops. A failed claim does not become governed authority. Controller grant administration over this store holds the store’s writer through the change; see Remove a permission without removing the controller. To reopen after a completed turn, drop the original service and all backend claims before opening new stores; the actor is then reconstructed from the stored Session document with the host’s actual trusted owners. Historical serialized authority associations remain audit data. They never bootstrap current grant, ingress or controller authority. Keep the host’s actual token store: its marked credential is restored through the existing lifecycle owner, while an unrelated empty store requests credential release and does not reconstruct the current provider authority. Fresh work after reopening uses current host grants, ingress authentication and a fresh controller pin, and does not replay the old work. An input carrying an earlier process’s grant association passes current ingress authentication but is refused by current grant authority before model, tool or durable input entry; the original transcript prefix, input row and protected audit stay unchanged. The low-level equivalent is MeerkatMachine::persistent_with_local_grant_authorization(runtime_store, Some(blob_store), owners)?. Ordinary MeerkatMachine::persistent, persistent_without_blobs, and the session-store variants of PersistenceBundle::new and its related constructors also return Result. They request shared custody when the backend supports it; governed construction requires exclusive custody directly, without dropping and reacquiring a claim. Ordinary custom backends without custody support remain usable; governed construction rejects them with UnsupportedScope. For an existing Rust integration, persistent(store, blob_store) and persistent_without_blobs(store) now return Result<Self, RuntimeDriverError>. Handle the result before wrapping the machine in Arc, for example Arc::new(MeerkatMachine::persistent(store, blob_store)?). Reuse the bundle’s machine when composing another surface. Built-in mob session services accept it through acquire_runtime_adapter(Some(machine.clone()))?. A clone of the same underlying machine owner is valid. A different live owner is refused with ControllerReadinessFailure::AuthorityChanged, even when it uses the same store. A store mismatch is UnsupportedScope; custody contention is Busy. Ok(None) remains an explicit optional-runtime outcome for custom services, not a substitute for a failed persistent acquisition. Builders and archive paths propagate acquisition errors before performing their operation. With the runtime-adapter feature, replace the old MobSessionService::runtime_adapter() getter with acquire_runtime_adapter(None)?, or pass the intended shared machine as Some(machine.clone()). The method returns Result<Option<Arc<MeerkatMachine>>, RuntimeDriverError>. A wrapper must forward that candidate and result to its underlying service instead of creating another machine. Both built-in services’ canonical_runtime_adapter() methods now return Result<Arc<MeerkatMachine>, RuntimeDriverError>. PersistentSessionService::with_canonical_runtime_adapter remains an infallible builder binding; acquisition still rejects a retained owner for a foreign store. Direct acquisition uses RuntimeDriverError::ControllerReadinessUnavailable { reason }; mob composition preserves the reason in MobError::SessionError(SessionError::RuntimeUnavailable { reason }). These failures describe runtime readiness, not permission denial. Exported auth lifecycle and OAuth capabilities retain the acquired backend custody, including generated/raw lifecycle clones and nested credential or device poll handles. Dropping only the machine does not make a conflicting governed owner available while those capabilities survive. This retains backend custody, not the machine or a runnable controller after restart. Keep using the installed authority for credential updates; persistent registry replacement is refused, while requesting the already installed owner is a no-op. Reserve creation with service.reserve_create_session_admission().await?, then use meerkat::surface::materialize_session_with_reserved_admission_and_actor_slot with the same deferred/discard initial-turn options. Its executor factory must construct meerkat::surface::PersistentRuntimeExecutor::new(service, machine, session_id) and pass the supplied actor slot to .with_publication_actor_slot(actor_slot). Clone the same service and machine into that factory and await materialization before pinning the controller. This executor forwards store-boundary acknowledgements to the actual persistent service owner. Do not combine EphemeralSessionService with a persistent machine. In the tested snapshot, materialize_ephemeral_runtime_session rejects that pairing with a wrapped SessionError::Unsupported before constructing an actor or registering native work. Migrating to persistence requires the stock service and executor above; an ephemeral executor cannot acknowledge the persistent owner’s committed data.

Pin the selected controller

When supplying a registry-selected client override, also set SessionBuildOptions.auth_binding from that client’s actual ControllerModelSelection::auth_binding(). For a storeless service, obtain the actor with live_session_actor_witness and its real client with pin_controller_client_for_actor. For a persistent service, acquire acquire_live_session_actor_turn_boundary_lease, pin that exact actor with pin_controller_client_for_actor, then drop the boundary lease before native submission. A copied model name is not a pinned client. The selected credential must be usable in this machine’s generated auth owner; use the normal credential lifecycle, not a fabricated Ready flag. Since 0.9.4 a controller on the environment’s default key (no recorded auth binding, the env_default credential; ControllerModelSelection::uses_synthetic_env_default_credential) holds no credential lease under governed admission, as for an authless route. Its live client must still report exactly the pinned selection, and your controller policy still decides whether that route runs.

Remove a permission without removing the controller

Use the native custody accessor before grant revocation, on a storeless machine or one over the actual InMemory or SQLite runtime store. This excerpt assumes the same actual machine and grants owner, an authenticated administrative PrincipalRef named administrator, and the exact issued GrantLineageRef named grant_to_remove. Propagate both typed custody and grant errors:
Keep the guard through this synchronous mutation. The accessor tries the actual machine locks once; ordinary operation checks do not use this administration path. GrantRefusal::ControllerInUse means an unfinished controller retains the grant or one of its ancestors. Separate controller and operation permissions into appropriately narrowed leaves so removing an operation permission need not remove the controller. A terminal input can still belong to an unfinished run; its original contributor continues to protect that controller. Busy or unsupported custody is public ControllerCustodyRefusal::Unavailable, without a permission verdict. Over an InMemory or SQLite runtime store the custody also retains the store’s writer and observes stored inputs as well as every attached native driver through the change; stored authority it cannot decode refuses the mutation until recovery. Do not replace the guard with a catalog listing, serialized association or a caller-owned assertion of no unfinished work. A host sharing grants with another machine or detached owner must include that additional scope in actual custody. Explicit credential publication and removal use that administrative custody. Ordinary credential acquisition, refresh and cached command reads do not scan historical work. Continue to use the credential owner’s normal API rather than editing its backing files or reconstructing readiness from stored identity. The Console Access panel changes Meta’s console ABAC rules; it is not a native grant editor. Native permission repair belongs to the embedding’s authorized grant/resource owners. Keep local refusals as affected-call feedback while permitted work continues; audit availability and launch failures require their own infrastructure repair. No CLI grant command or universal Console permission control is supplied by this API.

Bind a session agent’s MCP servers

A trusted host that selected the agent a registered session acts as binds that selection to the session’s registration before the agent is built, as a SessionAgentMandate: the qualified executor, the exact worker grant lineage selected for each MCP server the agent may use, and the represented subject the mandate applies to. Since 0.9.4 SessionAgentMandate::new(executor, servers, represented_subject) takes no catalog argument and refuses an empty server selection (AgentMandateError::NoSelection). SessionAgentMandate::catalog_lineage and the stock realm’s AgentGrantRefs::catalog_lineage are removed: the agent’s tool catalog is base work, whose lineage the work’s authority basis selects (AgentGrantRefs::prompt_selection still places the catalog grant there). A stock selection that grants only the catalog therefore binds no session agent; every configured MCP server stays unavailable, as before, and the registration stays free for a server mandate.

Survive owner changes in progress

Every owner mutation passes through the grant authority’s publication. While a change is being published, observations refuse to rebuild (OperationRefusalKind::ReprepareRequired): a stale read, not a verdict. Since 0.9.4 the runtime classifies that consistently and waits it out within fixed bounds.
  • LocalGrantAuthority::resolve_lineage_observed, resolve_controller_lineage_observed and resolve_lineage_ceiling_observed resolve a lineage inside the caller’s own observation of the publication and return LineageResolutionRefusal::Changed when an owner change published during the resolution (classify it as a stale read) or Refused with the refusal the standalone resolution reports. A caller with no enclosing observation whose answer can say “ask again” uses them too and classifies Changed as a change of policy, as native admission does. A standalone LocalGrantAuthority::resolve_lineage still reports a concurrent change as GrantRefusal::Unavailable.
  • In the native runtime that stale read is ReprepareRequired. A grant-backed preparation rebuilds once, for the work’s own grant and for the contributor ceilings of work that names other originals (a helper’s source). Controller admission refuses with ReprepareRequired, which the runtime driver reports as RuntimeDriverError::ControllerReadinessUnavailable with ControllerReadinessFailure::PolicyChanged. Native admission of a scoped original (ScopedOriginalIngress, which reads the admitted original’s own grant-lineage mandate and the liveness of each contributor it names), the retained-resume check (ScopedRetainedResume) and require_source_original_live called outside an exclusion of owner changes answer a change one of those reads meets with readiness PolicyChanged as well. Each of these admission reads, controller admission’s included, is first made once more in place when the change it met has completed: LocalGrantAuthority::owner_change_in_progress (a waiting hint that mirrors WorkAuthorization::owner_change_in_progress, never a permission) names none. Admission never waits, because it runs inside the session’s ingress transaction, so a change still in progress, or back-to-back changes, still answer PolicyChanged. A host that submits again waits first, outside its own locks, with a bounded OwnerChangeChurn::wait_after_stale_read, then resubmits once. A review read, which reads its material once by design, refuses as stale (ToolError::AuthorizationRefused with ReprepareRequired) instead of an unavailable review context, and a fresh attempt reads it again. AgentInstallationGrant reports a change it meets while reading the agent’s lineage as McpAttachmentRefusal::NotCurrent. A poisoned publication still answers Unavailable and is never retried. Failed durable grant custody and a clock failure still answer Unavailable, except one met while an owner change publishes, which is discarded with that stale read; a preparation’s one rebuild then answers Unavailable if the failure persists.
  • meerkat_core::authorization::OwnerChangeChurn (with OwnerChangeWait and OwnerChangeInProgress) is one bounded wait, for a site that rebuilds after ReprepareRequired, until an owner change in progress on the work’s own publication completes: OWNER_CHANGE_WAIT_BOUND (2 s) and OWNER_CHANGE_FREE_REBUILDS (3 rebuilds that do not spend the operation’s own). WorkAuthorization::owner_change_in_progress (provided, default None) reports such a change as a waiting hint, never a permission; LocalAuthorizationPublication::change_in_progress names a published change of the local owners, the native work owner’s owner_change_in_progress also names a reservation of the publication’s writer held now (published or not), and the native run and audit wrappers forward it. OwnerChangeChurn::wait_for_settled_change takes the wait’s trace site and operation: it records the debug event below and reports the wait to the host’s operation refusal observer. ToolDispatchContext::owner_change_churn gives a delegate operation of a tool call, such as the web_search helper’s model request, the waiting state that reports as that call’s.
  • OwnerChangeChurn::wait_after_stale_read is the wait for a host’s pure observation of the work’s own publication (one that reads owners and runs no effect, such as LocalAuthorizationPublication::observe around resolve_lineage_observed) that still answered stale after its one rebuild (PublicationError::Changed, LineageResolutionRefusal::Changed). Such a read can be invalidated by a change it never sees in progress: a grant issuance holds the grant owner’s mutex across its acknowledged append, with the publication’s writer reserved and unpublished, so a lineage read that reaches that mutex waits there and ends stale only once the issuance published, often after it completed. The wait waits for any change in progress, an unpublished reservation included, and with none in progress as it starts it pauses 1 ms first. Settled means make the same observation once more, afresh; NotSettled (past the deadline, or every free rebuild spent) means stop and answer the read as stale, never as unavailable. Each settled wait is one of the churn’s three free rebuilds, within its one deadline (2 s, clamped to the budget passed: in a tool body ToolDispatchContext::remaining_tool_time), which its first wait arms. Take a fresh churn for each decision point (ToolDispatchContext::owner_change_churn in a tool body), hold nothing across the wait (no publication guard or exclusion, no owner or host lock, no store transaction), and never wait around an effect: read, claim or record an effect once, after the observation answered. A current answer, a denial and a genuine Unavailable never wait. One Unavailable is contention instead, and a host retries it: a governed helper admission fence’s refusal while another writer holds the publication (see the helper fence below). An Unavailable an owner answers for itself is genuine: an installed owner never answers its own transient lock contention that way, because at a controller’s model request that answer ends the run. Dropping the wait cancels it, with nothing to release. The waiting forms of the governed steps below take the same wait after a step refused to rebuild.
  • The runtime waits at a model request (one deadline per model call, set at its first wait to 2 s or to the remaining run budget if less; the budget is checked after every wait), at a governed tool dispatch’s prepared entry, body entry and call-level policy gate (inside the tool’s timeout; a streaming tool’s gate wait also counts against its inactivity window), at the web_search helper’s model request (bounded by ToolDispatchContext::remaining_tool_time, the tool time a fenced dispatch has left) and at a compaction summary (past the bounds the refusal still fails its compaction). A free rebuild runs only once no change is in progress. Every one of these waits, those of the dispatch’s root staging and a dispatch issuance’s staging, and a review’s currentness check after its verdict, is wait_after_stale_read: a refusal to rebuild there is a stale read of the work’s own publication that ran nothing, so when the change that made it stale had already completed they pause 1 ms and rebuild, as one of the same free rebuilds. When the body entry or the gate’s staging waits out a change after recording its Entry record, it records another for the decision checked after the wait. The gate’s check point runs on the decision checked after its wait, but the gate’s own code already ran: a reviewed tool whose decision changed while the gate waited settles as review_unsatisfied (context_changed) and is not reviewed again.
  • A governed step takes the work owners’ exclusion without waiting (WorkAuthorization::run_if_current_within, run_entered_if_current_within and issue_child_if_current_within). When another actor holds it (an issuance with its acknowledged append, another operation’s final entry, a host’s owner change or held exclusion), the native work owner answers Refused(ReprepareRequired), with nothing run or appended, and names the hold as a change in progress until it ends; a poisoned, retired or exhausted publication stays Unavailable. In core the dispatch steps then answer AuthorizationRefused (ReprepareRequired). Their waiting forms, GovernedDispatchOperation::run_if_current_within_after_owner_change and issue_child_if_current_within_after_owner_change and the same two on EnteredDispatchOperation (async), wait after each such refusal with a fresh OwnerChangeChurn that reports as the call’s, within the call’s remaining tool time, and take the step again; with no change in progress at that read (the holder may have finished in between) they pause 1 ms and take it again. Every retry is one of the churn’s free rebuilds, within its one deadline. Every attempt is the synchronous step, decided afresh, and releases the exclusion, the owner locks, the run’s custody read and the review owner’s step admission before any wait. An attempt whose operation ran is the step’s answer. The dispatch issuance makes its single consuming entry once, its staging waiting out a change in progress within the dispatch attempt’s own bounds (site tool_entry, sharing the attempt’s churn with its other stagings and its review’s post-verdict check). It then issues once under that entry, as the synchronous form does: the entering decision and no step admission, so an approval read or another holder of the review owner cannot refuse it after the spend. Only after a refusal to rebuild does it wait and issue again through the entry’s witness, whose steps are each admitted by the review owner: a review or consent is spent exactly once. Unlike the root staging, the issuance’s staging never reviews again: at R2 a change it meets supersedes the reviewed decision, and the call answers review_unsatisfied (context_changed) once the change completes; R1 goes on, and so does an R3 consent, which its spend re-adjudicates. Past the bounds the last attempt’s typed refusal is returned. A streaming tool’s inactivity window is not part of the remaining tool time: a wait longer than the window left ends as the tool’s inactivity timeout, as a gate wait does. This is shell synchronization, like OwnerChangeChurn: no machine input changes.
  • A governed helper admission fence and a helper child issuance answer Unavailable instead of Denied when their check refuses to rebuild, on the prepared and dispatch paths alike: under the owner-change exclusion they cannot wait, and a refusal to rebuild is no verdict, so a later attempt may succeed. A denial and malformed facts stay Denied. GovernedHelperChildIssuance::issue_or_recover_after_owner_change waits first on the dispatch and entered paths (through the waiting dispatch steps) and answers Unavailable only past the bounds; its prepared path never waits. Once the dispatch path spent an R2 or R3 review, issuing again through it answers Denied (the review is spent): a caller that may issue again enters once and issues through GovernedHelperChildIssuance::from_entered, whose steps never spend. The fence runs inside the WorkGraph store callback and never waits.
  • The fence’s contention is retryable at the host level. While another writer holds the publication its check excludes owner changes on (a reservation of the writer that has not published), or an owner change is in progress there, it refuses as Unavailable with nothing run or committed. GovernedHelperAdmissionFence::create_idempotent_after_owner_change, given the WorkGraph service, the key, the request and a budget, makes the keyed create through a new fence for each attempt (a fence serves one attempt), always the same idempotent create_idempotent_with_fence. It waits, outside every lock and store transaction, and tries again after an attempt that refused for one of these: on the prepared path, an exclusion refused while the publication named such a change or hold; on the dispatch and entered paths, a refusal to rebuild (ReprepareRequired), which it waits out as the waiting step forms above do (for a change or hold in progress, or after a 1 ms pause when none is named). Every wait is wait_after_stale_read of one OwnerChangeChurn per call (2 s and three free rebuilds, clamped to the budget, in a tool body ToolDispatchContext::remaining_tool_time). A fence built with from_dispatch waits with that dispatch context’s own churn (ToolDispatchContext::owner_change_churn), so its waits also report to the host’s operation refusal observer on the call’s surface, without an operation id; prepared and entered fences trace their waits only. Read the budget right before the call (the deadline is armed after the first attempt), and await the call holding no lock or store transaction of your own: its waits run inside it. It answers success, Denied and every other Unavailable (a refusal to rebuild inside the prepared path’s own exclusion, clock or custody unavailable, a poisoned publication) at once, and the last Unavailable once a wait is not settled; refusal() on the fence it was called on then reads the answered attempt’s reason. That fence serves this one admission. Dropping the future commits nothing an attempt did not commit itself. EnteredDispatchOperation::work_authorization names the entered operation’s work, whose owner_change_in_progress it waits on.
  • OwnerChangeWait::trace records each wait as one debug event of target meerkat::authz::owner_change_wait with site (model_request, compaction_summary, tool_dispatch, tool_entry, tool_policy_entry, tool_step, tool_child_issuance, helper_admission or web_search_delegate, or the site a host passes), operation_id, waited_ms and settled. Each refused attempt keeps its own audit record.
A host’s pure check in a tool body, with the wait after a stale read:

Continue a reviewed call with governed helper steps

A governed tool call whose operation requires review (R2, a model review; R3, human consent) spends that review once, at the entry of its effect. A call that then takes further governed steps of the same operation (a governed helper WorkGraph admission, governed helper child grant issuances) makes that entry with ToolDispatchContext::enter_governed_operation(call), which returns the typed witness EnteredDispatchOperation. A leaf that already entered with enter_reviewed_effect_held or ReviewedEntryTicket::enter (for example on a worker) mints it with GovernedDispatchOperation::into_entered(custody), passing the custody its own entry returned. The operation may come from the dispatch’s context or from the refreshed context the entry returned (when its staging re-prepared the decision): every clone of a dispatch context shares the dispatch’s one review entry, so both convert the same custody, and the witness’s entered tier and window are those of the decision the entry spent. Each step decides against the operation’s current decision, re-prepared from current owners when the one it starts from is stale.
  • One witness serves the fence and every issuance of the call. Each step is decided afresh by the dispatch’s own work owners under their single non-waiting exclusion, with every own, named and further original re-read; none spends again, runs a review or requests consent, so a step may run inside the WorkGraph store callback. Retrying an issued intent answers Recovered.
  • A step runs only while the current decision requires no more review than the call entered (EnteredDispatchOperation::entered_tier), within the entered decision’s validity window. A decision re-prepared since the entry runs at the same or a lower tier.
  • For a reviewed entry the review owner admits a step only while the admitting dispatch is live. A step admitted before the dispatch ended (returned, cancelled or timed out) runs to completion, and the review stays in use until the last such step has finished; a step that starts later is refused. An unreviewed (R1) entry spends nothing and, like the plain R1 path, is bounded by its run, not its dispatch.
  • A refused step answers Denied (an ended dispatch, a source cancelled, revoked or no longer retained, a decision needing more review than was entered, an expired window) or Unavailable (contention, a rebuild request, owners that cannot answer now), and speaks only for its own step: earlier steps keep their effects, and the call’s result is the host’s to compose. In core a step answers AuthorizationRefused with no not-dispatched certificate, or OperationAuthorizationUnavailable, never a review settlement. Another actor’s hold of the work owners’ exclusion is a refusal to rebuild there (ReprepareRequired), which the witness’s waiting forms (run_if_current_within_after_owner_change, issue_child_if_current_within_after_owner_change), GovernedHelperChildIssuance::issue_or_recover_after_owner_change and GovernedHelperAdmissionFence::create_idempotent_after_owner_change wait out before they answer.
  • The witness is the capability of exactly the call that entered; use it only for that call’s own steps. WorkAuthorization::run_entered_if_current_within is a provided method whose default answers unavailable: a work owner, or a wrapper, that does not implement or forward it refuses every entered step. The native owner and its audit and run-custody wrappers do.
  • The plain dispatch paths are unchanged: GovernedHelperAdmissionFence::from_dispatch stays R1-only (no review runs under the graph lock), and GovernedHelperChildIssuance::from_dispatch is the dispatch’s single consuming entry, so a reviewed call issues one child there. Both answer Denied when the dispatch’s review settles the step, since 0.9.7 (before, Unavailable).

Refusal observation and dispatch types

What the model reads on a refused tool call and Observe refusal dispositions describe the payload and the observer. The typed API behind them:
  • OperationRefusalObservation exposes session_id(), run_id(), operation_id(), surface() (OperationRefusalSurface::ModelRequest, ToolCall { tool_use_id } for the call or a delegate operation of it, Compaction), outcome() (OperationRefusalOutcome::Refused { kind, dispatch } or AuthorityUnavailable) and disposition() (OperationRefusalDisposition::WaitedForOwnerChange { waited_ms, settled }, Rebuilt, ControllerFeedback, ToolResult, CompactionSkipped, RunFailed). The three enums are #[non_exhaustive].
  • Core calls the observer synchronously on the deciding task and holds no lock shared with another operation while it does; the observer must not block. A panicking observer is a host bug, and the panic propagates.
  • OperationRefused::dispatch returns a RefusalDispatch (NotDispatched, Unknown; non-exhaustive). The fenced dispatch (and the retained consent attempt) certifies NotDispatched for every operation refusal it meets before it invokes the dispatcher, and the execution policy gate for every one it meets before it invokes its inner dispatcher. Every other refusal, one a dispatcher returns included, is Unknown, which makes no claim. OperationRefused equality compares both facts, so a certified refusal no longer equals OperationRefused::new(kind) of the same kind: compare kind() and dispatch().
  • The payload’s message, Display, Debug and tracing stay uniform. A mob member upcall keeps carrying the bare kind, so a 0.9.3 peer decodes it as before and the receiving side’s model reads "unknown". An upcall refusal whose data is absent or names no known kind decodes as operation_authorization_unavailable instead of operation_refused with malformed_facts: it is no verdict the peer gave.

Read where a refusal was decided

Since 0.9.4 AuditObservation::Refused carries read: Option<AuditRefusalRead> with observed_at_ms, basis, publication_sequence, live_sequence and publication_instance. AuditRefusalBasis::OwnerAnswer means the owners answered at one coherent publication (a refusal from a prepared decision’s own validity window is such an answer); PublicationChanged means the publication changed after the sequence the attempt read and the change completed; ChangeInProgress means an owner change was still in progress when the attempt ended. A refusal to rebuild that a prepared decision observes at its check reads as a changed publication against the live sequence. AuditPolicyRead gains publication_instance, since sequences of different instances do not compare. Both are process-local diagnostics, not permissions or cross-process freshness proofs. Rows carry them at stored input state version 7; a row stamped before version 7 that carries either is refused, and records written earlier read with neither. AuditObservation is now #[non_exhaustive]: matches outside the crate need a wildcard arm, Refused patterns without .. need the read field, and AuditPolicyRead struct literals need publication_instance.

Append external context under current permissions

External context needs authority for the exact source and destination as well as permission to invoke the control. A source annotation, session ID or previous run is insufficient. The trusted producer supplies a process-only receipt from its actual owner, alongside ContextControlFacts for the authenticated requester, executor, realm, source and destination. Implement AdmittedWorkPolicyOwner::authorize_context_control to validate that receipt and the current invocation or service mandate. Implement OperationPolicyOwner::authorize_context_control for the exact source hydration and destination publication checks. Their defaults return unavailable. Both participate in the same local publication ordering as other native policy reads. With the actual receipt and facts already obtained from those owners, submit through SessionServiceControlExt:
The constructor binds data; it does not authenticate a producer or grant access. The installed native owner prepares the checks, and the Session owner rechecks them after actor or staging waits, immediately before mutation. This operation adds no input and borrows no current run. For a control already prepared by that same native owner, append_authorized_system_context preserves its exact binding. Reusing the same process control cannot settle another attempt. A fresh attempt needs a fresh control; the request’s normal idempotency key still detects an already appended message after current authorization succeeds. Handle SessionControlError::Authorization by its typed variant. Refused returns local feedback without appending the content. Unavailable means no usable authorization was established. ObservationUnavailable is a separate audit failure and does not prove that an earlier effect never happened. A raw append_system_context call supplies no authenticated receipt, so in a governed session it answers authorization unavailable. Meerkat’s own raw appenders do the same there: JSON-RPC session/inject_context (rkat-rpc’s typed append, which its durable delivery also uses) and the mob operator’s mob/append_system_context (MobMcpState::mob_append_system_context). LiveResponses outcomes use the authenticated append when a native work authorization host is installed. The Session retains protected control observations with its existing commit. They do not enter model context or public history, and they cannot authorize a retry. A persistent service commits the refusal observation before returning it; a persistence failure remains infrastructure failure. Preserve the actual result and any settlement error rather than inferring delivery from a log line.

Settle job delivery recipients independently

JobRuntimeDeliveryApplier derives the complete recipient manifest from the unchanged committed producer payload, including legacy/default-origin targets. Each RuntimeDeliveryRecipient binds a subscription ID to its exact subscription and target. Before any recipient enters, RuntimeDeliveryInbox::bind_recipients re-reads the committed row and retains the supplied manifest. The producer owns complete manifest extraction; the generic inbox does not parse opaque payloads or confer execution authority. Enrollment supports only JobTerminal and JobNotification; single-target continuations use their own admission path. Enrollment retains the existing payload and writes authority envelope v3, which older readers refuse. A runtime authority without recipient enrollment retains v1, or v2 when it contains whole-row refusals. Use settle_recipient with the actual local result:
  • RuntimeDeliveryRecipientOutcome::Applied records successful application.
  • Refused records an actual native permission refusal before entry.
  • OperationAuthorizationUnavailable records the native owner’s explicit unavailable-authorization result.
JobDeliveryApplyError::Infrastructure and authorization ObservationUnavailable leave the recipient pending and the pass blocked. They are not local permission verdicts, and neither proves that an effect did not occur. Retry reads retained settlements and skips every settled recipient; permission repair does not revive a previously refused recipient. Call finish_recipients only after every bound recipient has settled. The call advances the ordered cursor and returns RuntimeDeliveryRecipientGroupOutcome. Read the parent RuntimeDeliveryStatus through delivery_status: Completed groups remain settled across reopen under the store’s durability guarantees; retry neither replays successful siblings nor revives refused ones. RuntimeJobDeliveryDrain::applied contains rows with established applied results, including already acknowledged effects; locally_settled contains other completed groups. Paging counts both lists so a page of local refusals cannot strand later work, while RuntimeDeliveryPass::applied counts only the applied list. A recipient refusal does not change the producer job’s completed result. The sink effect and its settlement commit are separate. A crash or error between them can leave an uncertain effect with no committed settlement. This API does not provide effect/commit atomicity or exactly-once execution, and a missing settlement is not evidence that replay is safe.

Bind the final input to authenticated ingress

Issue the controller and operation grants through LocalGrantAuthority and construct the InputAuthorityAssociation for the actual runtime, identities, mandate, grant references and pinned selection. It remains a claim until the installed owners validate it. The following excerpt assumes the host already has those values and pin from the attached actor. Authenticate requester, ingress_actor, realm and authentication outside the request body. Set any idempotency key before binding:
Inspect the AcceptOutcome and optional completion handle. Finalizing this context does not itself admit work. Do not mutate the bound payload, manufacture a WorkAuthorizationContext, or reuse one from a prior turn; the native owner builds it from the admitted contributors.

Serve one fixed governed JSONL connection

Enable meerkat-rpc with default-features = false and local-authorization. This profile takes an in-memory PersistenceBundle constructed with new_with_local_grant_authorization above, a selected LlmClient, one fixed Config, and a nonempty Vec<ToolDef> of callback tools. Initialize the selected credential through that bundle’s installed auth lifecycle before serving. The entry checks that governance is already installed and uses that same owner; it does not install or upgrade persistent governance. The retained client does not bypass configuration validation. Its actual ControllerModelSelection::auth_binding() must name a binding in config.realm[binding.realm]. Populate that realm’s binding, backend and auth maps with the corresponding ProviderBindingConfig, BackendProfileConfig and AuthProfileConfig. The binding must resolve through resolve_explicit_auth_binding_target to the selected credential identity, and its provider/backend/auth combination must be supported by ProviderRuntimeCatalog. Keep the actual endpoint and credential account consistent with the selected client. The binding realm must equal the connection realm, and config.agent.model must equal the selected model. Authenticate the connection in trusted host code. Construct qualified requester, ingress actor and optional represented-subject identities there, with their realm and historical authentication evidence. Supply an Arc<InputAssociationProducer>: it receives the final merged Input, actual runtime ID and pinned ControllerModelClient, and returns an InputAuthorityAssociation referencing real issued grants. These are historical claims, not permission or proof of the semantic provenance of prompt text. The installed native owners still validate them and current permissions before admission. This excerpt assumes those host-owned values, the fresh bundle, and one JSONL reader/writer pair:
mcp_attachment_identity_key_custody: None fits this callback-only recipe. A host separately commissioned for live MCP attachment supplies Some persistence from its selected persistent backend’s open_with_refresh_authority(), and reopens the same backend after a restart. That custody protects attachment identity only: the governed profile gains no provider or MCP credential from it. With None, an attachment whose target carries command arguments or URL credentials is recorded unbound and restores as renewal-required. When persistence is supplied, failure to create or read its identity key refuses that attachment admission before anything is recorded or staged, and a restore only loads the realm’s existing key. Constructing the persistence does not check filesystem access. The entry constructs AgentFactory::minimal() internally and owns one private runtime, config store and callback connection. It installs the host’s catalog once and supplies the same fixed definitions as inline session tools. Wire requests cannot replace that registry or choose principals, grants, model or credentials. Core catalog controls such as tool_catalog_search and tool_catalog_load may still be advertised. They remain subject to native operation policy and cannot register tools or expand this fixed callback registry; dynamic tools/register is unsupported. After initialization, use session/create with initial_turn: "deferred", then turn/start. Both accept prompt and optional injected_context; the turn also identifies its session. The entry merges the deferred seed and contexts before binding native ingress, retaining the actual actor and controller across an input permission refusal. The client must handle server tool/execute requests and return their results on that same connection. A refused tool operation becomes safe model feedback without entering that callback; permitted sibling operations can continue. Input refusal, readiness, infrastructure failure and post-effect settlement remain distinct, as described below. A later cleanup or settlement failure does not authorize repeating an effect. This profile supports deferred create, turn execution, callback replies and necessary initialization/cancellation protocol. Dynamic tool registration, configuration changes, cold/restarted sessions, public history/observation and MCP setup are outside it. For this uncommissioned recipe the constructor rejects an MCP-enabled build: it admits one only for a connection commissioned for live MCP attachment, and setting the identity-key custody does not commission one. It also rejects configurations enabling skills, hooks, built-in tools, shell, comms, mobs, scheduling, workgraphs, model fallback or a system-prompt file.

Submit governed work from a Console host

Console access controls (Meta’s console ABAC) do not commission native owners, and neither does a native dependency with local-authorization enabled. A host that submits governed work from its own UI keeps the governed bundle, session service, machine and attached controller described above. It carries the host-qualified requester, ingress actor, represented subject and authentication evidence from its authenticated send check to the final native input through NativeIngressContext, as GovernedConnection does for JSONL. The browser cannot supply these facts, and missing or mismatched facts must refuse before model or tool entry. After a native input refusal or readiness failure, settle the reserved interaction without reporting that nothing was accepted. Keep operation refusal separate from input readiness, and outcome-audit failure separate from the actual effect; neither infrastructure failure authorizes replaying an effect.

Preserve the result and test the actual effect

An operation-local OperationAuthorizationError::Refused can become safe model feedback while permitted work continues. Unavailable and ObservationUnavailable are distinct infrastructure outcomes, not permission denials. Native input refusal is retained as RuntimeDriverError::InputRefused; admission readiness is reported separately through RuntimeDriverError::ControllerReadinessUnavailable. The facade’s native_admission_error_detail projects these to finite WireInputAdmissionErrorDetail values: ErrorCode::InputRefused (-32030) or ErrorCode::InputNotReady (-32031). Preserve that distinction and handle serialization failure; a readiness result does not prescribe automatic retry. Session operations that cannot acquire runtime authority instead return SessionError::RuntimeUnavailable { reason }. Its audience-safe projection uses ErrorCode::SessionRuntimeUnavailable (-32032, HTTP 503, CLI exit 52), preserving the typed readiness reason. It is separate from an attempted operation’s local permission feedback and does not terminate retained work. ErrorCode is publicly exhaustive, so downstream Rust matches must handle these added variants. This Rust/JSONL projection does not imply new typed SDK decoders. Retain settlement_failures alongside the physical result. A diagnostic after a successful effect does not authorize repeating it. Use native input audit records for this process-lifetime path. With the persistent composition, the normal session/input commits retain the original association and ordered audit alongside the committed transcript. Keep authorization checks local and persist observations through these existing commit boundaries. Route controller grant/policy removal and credential maintenance through their custody-aware owners so unfinished work retains its controller. The repository fixture crates/meerkat-authorization/tests/native_governed_loop/e1_policy_control.rs shows the complete factory, native admission, loopback HTTP and tool path. Its cases distinguish refusal before body entry from diagnostics after an effect and cover resource-specific permissions, queued work and requester revocation; the e1_policy_control/stock_persistent.rs child uses the stock bundle/service/executor with a committed Session document, native input and audit readback. For an application, require zero forbidden body entries, one permitted effect, the same admitted run’s feedback and normal completion. Read the broader integration contract and authorization concepts before extending the protected operation inventory.