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
Enablemeerkat-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.
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 withAgentFactory::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:
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’sAgentFactory, 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.
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.kindis the closed refusal kind:reprepare_required,deniedormalformed_facts.data.tool_invokedisfalseonly 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.
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 anOperationRefusalObserver on its factory (or with
AgentBuilder::with_operation_refusal_observer):
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-ownedweb_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), isToolOperationTarget::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 namedweb_searchfrom 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()isNone). Every governedweb_searchcall carries this target under every grant basis, so an owner that refuses targets it does not map refusesweb_searchuntil it maps it. - Its helper (
AuthorizationOperation::Model, usageInference, always theOperationpurpose).binding.delegate_attribution()names the call:parent_binding()is the call’s binding with the target above, androle()isToolDelegateRole::HostedSearchInference. The facts are the helper’s own: identity, credential, backend, endpoint, wire model, andhosted_capabilitiesof[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.
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
UseFactoryAgentBuilder 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’ssession-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.
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.
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:
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 setSessionBuildOptions.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 actualmachine 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:
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 aSessionAgentMandate: 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_observedandresolve_lineage_ceiling_observedresolve a lineage inside the caller’s own observation of the publication and returnLineageResolutionRefusal::Changedwhen an owner change published during the resolution (classify it as a stale read) orRefusedwith the refusal the standalone resolution reports. A caller with no enclosing observation whose answer can say “ask again” uses them too and classifiesChangedas a change of policy, as native admission does. A standaloneLocalGrantAuthority::resolve_lineagestill reports a concurrent change asGrantRefusal::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 withReprepareRequired, which the runtime driver reports asRuntimeDriverError::ControllerReadinessUnavailablewithControllerReadinessFailure::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) andrequire_source_original_livecalled outside an exclusion of owner changes answer a change one of those reads meets with readinessPolicyChangedas 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 mirrorsWorkAuthorization::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 answerPolicyChanged. A host that submits again waits first, outside its own locks, with a boundedOwnerChangeChurn::wait_after_stale_read, then resubmits once. A review read, which reads its material once by design, refuses as stale (ToolError::AuthorizationRefusedwithReprepareRequired) instead of an unavailable review context, and a fresh attempt reads it again.AgentInstallationGrantreports a change it meets while reading the agent’s lineage asMcpAttachmentRefusal::NotCurrent. A poisoned publication still answersUnavailableand is never retried. Failed durable grant custody and a clock failure still answerUnavailable, except one met while an owner change publishes, which is discarded with that stale read; a preparation’s one rebuild then answersUnavailableif the failure persists. meerkat_core::authorization::OwnerChangeChurn(withOwnerChangeWaitandOwnerChangeInProgress) is one bounded wait, for a site that rebuilds afterReprepareRequired, until an owner change in progress on the work’s own publication completes:OWNER_CHANGE_WAIT_BOUND(2 s) andOWNER_CHANGE_FREE_REBUILDS(3 rebuilds that do not spend the operation’s own).WorkAuthorization::owner_change_in_progress(provided, defaultNone) reports such a change as a waiting hint, never a permission;LocalAuthorizationPublication::change_in_progressnames a published change of the local owners, the native work owner’sowner_change_in_progressalso 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_changetakes 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_churngives a delegate operation of a tool call, such as theweb_searchhelper’s model request, the waiting state that reports as that call’s.OwnerChangeChurn::wait_after_stale_readis the wait for a host’s pure observation of the work’s own publication (one that reads owners and runs no effect, such asLocalAuthorizationPublication::observearoundresolve_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.Settledmeans 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 bodyToolDispatchContext::remaining_tool_time), which its first wait arms. Take a fresh churn for each decision point (ToolDispatchContext::owner_change_churnin 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 genuineUnavailablenever wait. OneUnavailableis 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). AnUnavailablean 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_searchhelper’s model request (bounded byToolDispatchContext::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, iswait_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 itsEntryrecord, 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 asreview_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_withinandissue_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 answersRefused(ReprepareRequired), with nothing run or appended, and names the hold as a change in progress until it ends; a poisoned, retired or exhausted publication staysUnavailable. In core the dispatch steps then answerAuthorizationRefused(ReprepareRequired). Their waiting forms,GovernedDispatchOperation::run_if_current_within_after_owner_changeandissue_child_if_current_within_after_owner_changeand the same two onEnteredDispatchOperation(async), wait after each such refusal with a freshOwnerChangeChurnthat 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 (sitetool_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 answersreview_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, likeOwnerChangeChurn: no machine input changes. - A governed helper admission fence and a helper child issuance answer
Unavailableinstead ofDeniedwhen 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 stayDenied.GovernedHelperChildIssuance::issue_or_recover_after_owner_changewaits first on the dispatch and entered paths (through the waiting dispatch steps) and answersUnavailableonly past the bounds; its prepared path never waits. Once the dispatch path spent an R2 or R3 review, issuing again through it answersDenied(the review is spent): a caller that may issue again enters once and issues throughGovernedHelperChildIssuance::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
Unavailablewith 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 idempotentcreate_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 iswait_after_stale_readof oneOwnerChangeChurnper call (2 s and three free rebuilds, clamped to the budget, in a tool bodyToolDispatchContext::remaining_tool_time). A fence built withfrom_dispatchwaits 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,Deniedand every otherUnavailable(a refusal to rebuild inside the prepared path’s own exclusion, clock or custody unavailable, a poisoned publication) at once, and the lastUnavailableonce 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_authorizationnames the entered operation’s work, whoseowner_change_in_progressit waits on. OwnerChangeWait::tracerecords each wait as onedebugevent of targetmeerkat::authz::owner_change_waitwithsite(model_request,compaction_summary,tool_dispatch,tool_entry,tool_policy_entry,tool_step,tool_child_issuance,helper_admissionorweb_search_delegate, or the site a host passes),operation_id,waited_msandsettled. Each refused attempt keeps its own audit record.
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 withToolDispatchContext::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) orUnavailable(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 answersAuthorizationRefusedwith no not-dispatched certificate, orOperationAuthorizationUnavailable, 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_changeandGovernedHelperAdmissionFence::create_idempotent_after_owner_changewait 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_withinis 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_dispatchstays R1-only (no review runs under the graph lock), andGovernedHelperChildIssuance::from_dispatchis the dispatch’s single consuming entry, so a reviewed call issues one child there. Both answerDeniedwhen 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:OperationRefusalObservationexposessession_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 }orAuthorityUnavailable) anddisposition()(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::dispatchreturns aRefusalDispatch(NotDispatched,Unknown; non-exhaustive). The fenced dispatch (and the retained consent attempt) certifiesNotDispatchedfor 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, isUnknown, which makes no claim.OperationRefusedequality compares both facts, so a certified refusal no longer equalsOperationRefused::new(kind)of the same kind: comparekind()anddispatch().- The payload’s message,
Display,Debugand 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 asoperation_authorization_unavailableinstead ofoperation_refusedwithmalformed_facts: it is no verdict the peer gave.
Read where a refusal was decided
Since 0.9.4AuditObservation::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. Asource 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:
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::Appliedrecords successful application.Refusedrecords an actual native permission refusal before entry.OperationAuthorizationUnavailablerecords 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 throughLocalGrantAuthority 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:
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
Enablemeerkat-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 withlocal-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-localOperationAuthorizationError::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.