@reunionstudio/airlock-mcp 0.1.7 → 0.1.9

package/.agents/skills/airlock-mcp/SKILL.md

@@ -229,6 +229,38 @@ Airlock:
 - `airlock.admin.*` performs administrative changes and operational mutations.
 - `airlock.agent.*` performs governed user or agent work in the actor's scope.
 
+Installed Airlock may also expose separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. They are distinct from this local
+spec-workbench MCP server. Administrators manage them with
+`admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`. Their fixed allowlists contain five agent tools
+(`airlock_my_access_context`, work, safe spec description, spec states, and file
+state) and four observer tools (specs, work, spec states, and file state). They
+never expose mutation, governed payload rows, restricted-reference reads, or
+attachment bytes. Each client must authenticate as its own Snowflake principal;
+workspace identity is not Airlock authority.
+
+Treat every mutating human or automated agent as an attributable Snowflake
+principal. Direct work uses that principal's Airlock assignments. Work for
+another principal requires explicit Airlock delegation and
+`on_behalf_of_user`; pass `delegation_id` only when Airlock reports more than
+one matching active grant. Snowflake user type and agent-session metadata are
+informational, not authority. Never map workspace roles, channel membership,
+reactions, or chat approval into Airlock permissions.
+A `DELEGATED_ACTION` event records the authorized attempt and actor/principal
+identity; the mutation result and normal file, attachment, or workflow events
+provide commitment evidence.
+
+Stored-procedure events may expose
+`EVENT_CONTEXT.snowflake_agent_active` as informational provenance. Never use
+that marker to grant access, infer delegation, classify billing, or replace the
+authenticated Snowflake principal.
+
+A read-only channel may use a dedicated observer principal with
+`app_observer`, a distinct Airlock role/assignment, and explicit per-spec
+`observer_access`. Do not reuse that observer principal for mutation, and do
+not share one mutating principal across human or automated actors.
+
 Use `agent.list_my_work` as the actor's single operational inbox for workflow,
 watcher, deadline, overdue, and exception work. Use `observe.work` for the
 read-only account-wide current-work projection and `observe.activity` for event
@@ -243,6 +275,19 @@ workflow, attachment, and exact-reference changes. Use `observe.spec_state` and
 `observe.file_state` only with observer/admin authority for account-wide state.
 Do not substitute global observer tokens for an agent's scoped token.
 
+After every supported `agent.*` or intentional `admin.*` mutation, preserve a
+bounded `airlock.commitment-receipt/v1` in the external workspace history.
+Record the procedure and authenticated Snowflake principal; derive any
+represented principal and delegation id from the actual procedure arguments.
+Retain the target spec/path/filename, returned status/code/message and issues,
+and timestamp. After a successful direct file mutation, call `agent.file_state`
+with the returned target and retain its `UPLOAD_ID`, `FILE_STATE_ID`, workflow
+state, attachment count, and reference count. Do not make that direct actor
+state read after delegated work; leave `committed_state` null unless the actor
+performs a separate independently authorized observation. Keep a denied
+mutation as a receipt with no committed state. Never use a chat display name as
+the Snowflake actor or describe workspace approval as an Airlock commitment.
+
 Required source references are exact governed evidence, not filename fields.
 When an active downstream-to-source link has `min_count > 0`, load the
 downstream file into Draft, discover eligible sources with
@@ -394,6 +439,8 @@ human decisions remain.
 
 - Local checks are not Airlock authority.
 - Installed Airlock procedures remain the execution contract.
+- Every mutating actor keeps an attributable Snowflake principal; shared
+  integration identities and workspace roles are not authorization shortcuts.
 - Do not write directly to Airlock-owned tables, stages, generated views, or
   generated tables.
 - Do not put Airlock workflow state, reviewer comments, approval status, or

package/.cortex-plugin/activation.md

@@ -0,0 +1,20 @@
+# Airlock MCP activation
+
+Use the bundled Airlock skill when a task concerns Airlock specs, governed
+Snowflake work, read-only governance observation, delegation, expectations,
+attachments, workflow, state polling, or commitment receipts.
+
+Before acting, preserve the authenticated Snowflake principal. Workspace roles
+and chat identity are not Airlock authority. Use `airlock.agent.*` for governed
+work, `airlock.observe.*` for read-only observation, and `airlock.admin.*` only
+for intentional administration. Use explicit Airlock delegation when the
+connected principal acts for another principal.
+
+Do not confuse this local spec-workbench MCP server with the optional
+Snowflake-managed MCP endpoints exposed by an installed Airlock Native App.
+Those role-separated agent and observer endpoints preserve Snowflake identity
+and expose only fixed read-only tools; they do not expose mutation or governed
+payload rows.
+
+Never store credentials in this plugin or its workspace files. Configure the
+Airlock MCP connection through the supported environment or connection setup.

package/.cortex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "airlock-mcp",
+  "description": "Governed Airlock spec, observation, and commitment guidance for Snowflake principals.",
+  "version": "0.1.9",
+  "author": {
+    "name": "Reunion Studio",
+    "url": "https://github.com/reunionstudio/airlock-mcp"
+  },
+  "skills": [
+    "./.agents/skills"
+  ],
+  "mcpServers": {
+    "airlock": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@reunionstudio/airlock-mcp@0.1.9",
+        "server"
+      ]
+    }
+  }
+}

package/README.md

@@ -28,15 +28,25 @@ Airlock MCP gives agents four kinds of Airlock help:
    procedures to inspect setup, access, activity, billing events, health,
    context packets, and governance maps before deciding what an app or agent
    should do.
+5. Workspace interoperability: preserve principal identity, poll scoped state,
+   commit only through installed procedures, and retain portable Airlock
+   receipts in external workspace history.
 
 ## Installed Airlock Contract
 
 Current Airlock separates procedure intent:
 
 - `airlock.observe.*` is the read-only governance observation surface. It is
-  available to `app_admin` and `app_observer` and is the preferred path for
-  discovery, health checks, access explanation, governance maps, activity,
-  billing event context, and list/detail context packets.
+  available at the Snowflake object layer to `app_admin` and `app_observer`.
+  Airlock assignments and per-spec `observer_access` rules scope ordinary
+  observers; account-wide surfaces require `app_admin` or the locked Airlock
+  role `global_observer`. That reserved role is observation-only: it cannot own
+  specs, receive guest/reviewer grants, or manage child roles.
+  Account-wide auditors should use `airlock.observe.observers(...)` for a flat
+  user, assignment, observer-role, spec/path/workflow, and license inventory.
+  `active_seat_observer_only` means the identity is observer-only now but still
+  has a billable seat that must be explicitly unassigned; role changes never
+  silently rewrite billing history.
 - `airlock.admin.*` is for admin changes and operational actions such as
   creating specs, changing roles, loading OKF bundles, rerunning setup, or
   deleting purge candidates.
@@ -44,22 +54,93 @@ Current Airlock separates procedure intent:
   specs, validating/loading data, workflow actions, attachments, delegations,
   and references.
 
+Installed Airlock can also expose a deliberately small read-only subset through
+separate Snowflake-managed Native App MCP servers for `app_agent` and
+`app_observer`. They are opt-in, preserve the authenticated Snowflake principal,
+and do not replace the public procedure API or this package's local workbench.
+See [Native App managed MCP](docs/native-app-managed-mcp.md) for the fixed tool
+allowlists, setup calls, identity proof, and security boundary.
+
+Every mutating human or automated agent should connect as its own attributable
+Snowflake principal. When it acts for another principal, use explicit Airlock
+delegation. Snowflake user type, chat identity, channel membership, workspace
+roles, and reactions do not create Airlock authority. A read-only channel may
+use a distinct scoped observer principal, but that principal must not be reused
+for mutation.
+
+Stored-procedure activity includes the informational
+`EVENT_CONTEXT.snowflake_agent_active` marker when Snowflake exposes it. The
+marker identifies execution context for observation; it never changes Airlock
+access, workflow, expectations, billing, or receipt identity.
+A `DELEGATED_ACTION` event records an authorized attempt, not proof that its
+mutation committed. Commitment receipts derive delegation identity from the
+actual call arguments, and only successful direct file mutations are hydrated
+through `agent.file_state`; delegated work leaves `committed_state` null unless
+the actor performs a separate independently authorized observation.
+
 Use `airlock.agent.list_my_work(...)` for the current actor's unified workflow,
-watcher, deadline, overdue, and exception inbox. Use `airlock.observe.work(...)`
-for the read-only account-wide projection of current work, and
+read-only observation, deadline, overdue, and exception inbox. Use
+`airlock.observe.work(...)` for the read-only assignment-scoped projection of
+current work, and
 `airlock.observe.activity(...)` for historical events. The older split work
 procedures are retired.
 
-Watcher agents should poll `airlock.agent.spec_state(...)` before retrieving a
-complete descriptor, file list, or governed dataset. Cache the
-authorization-scoped `STATE_TOKEN` and perform the heavier read only when it
-changes. Poll `airlock.agent.list_my_work(...)` independently because deadlines
-and expectation windows can change with time without rotating a spec token.
+Polling agents should call `airlock.agent.spec_state(...)` for one known spec,
+or `airlock.agent.spec_states(...)` for up to 100 known specs under one role
+lens, before retrieving complete descriptors, file lists, or governed datasets.
+Cache each authorization-scoped `STATE_TOKEN` and perform the heavier read only
+when it changes. Poll `airlock.agent.list_my_work(...)` independently because
+deadlines and expectation windows can change with time without rotating a spec
+token.
 After selecting a logical file, compare
 `airlock.agent.file_state(...).FILE_STATE_ID`; that UUID rotates when its data,
-workflow, attachments, or exact source references change. Observer clients use
-the account-wide read-only `observe.spec_state(...)` and
-`observe.file_state(...)` equivalents.
+workflow, attachments, exact source references, or retained version history
+change. Observer clients use
+the authorization-scoped, read-only `observe.spec_state(...)`,
+`observe.spec_states(...)`, and `observe.file_state(...)` equivalents. Missing
+or inaccessible specs are omitted from a batched result without disclosing the
+cause; that omitted row is the terminal polling signal. Authorized query
+failures remain procedure errors.
+
+### Observer Access And Seats
+
+An observe-only integration does not claim or consume a named Airlock seat.
+`airlock.agent.*` and the built-in Streamlit app remain seat-gated. Moving an
+existing identity to observe-only does not silently remove a seat that was
+previously assigned or claimed; an administrator should explicitly call
+`airlock.admin.unassign_license(...)` after confirming the identity no longer
+uses those surfaces.
+
+Specs grant read-only visibility with canonical `observer_access` config:
+
+```json
+{
+  "observer_access": {
+    "enabled": true,
+    "observer_roles": [
+      {
+        "role_name": "finance_observer",
+        "path_filter": "finance",
+        "workflow_states": ["Approved"]
+      }
+    ]
+  }
+}
+```
+
+Grant the integration Snowflake application role `app_observer`, create or
+reuse the Airlock observer role, and assign the integration's Snowflake
+username to it. Use a distinct observer principal per channel so attribution,
+scope, and revocation remain independent. Observe procedures return governance
+metadata only, never governed payload rows or attachment bytes.
+
+Set up an observer in four explicit steps: grant the observer principal's Snowflake role
+`<APP_NAME>.app_observer`, create and assign a distinct Airlock role, publish
+that role in each intended spec's `observer_access`, then verify the result with
+`observe.observers(...)`. Audit assignment creation, changes, and removal with
+`observe.admin_activity(..., action_family => 'assignments')`; its structured
+event context includes before/after state. See [docs/workflows.md](docs/workflows.md)
+for the operating checklist and billing cleanup boundary.
 
 When building an app or workflow, prefer `observe.*` for read-only setup and
 monitoring questions, `agent.*` for governed submissions in the actor's scope,
@@ -115,6 +196,19 @@ Install from npm:
 npx @reunionstudio/airlock-mcp install
 ```
 
+Install the bundled Cortex Code plugin from GitHub:
+
+```bash
+cortex plugin install reunionstudio/airlock-mcp
+```
+
+The `.cortex-plugin/plugin.json` manifest loads the same Airlock skill and pins
+the stdio MCP server to this package version. Keep Snowflake and MCP credentials
+outside the manifest. When the Cortex Code CLI is available locally, validate a
+checkout with `cortex plugin validate` before distributing it. Account-local
+Cortex Extension sharing remains subject to Snowflake's current preview and
+RBAC requirements.
+
 Today this package is a small installer and MCP launcher. For Codex, install
 registers a local stdio server with:
 
@@ -133,6 +227,10 @@ person through process discovery, and entering the bundled spec-building
 workbench when a first spec is ready to draft. It also guides agents building
 apps or workflows that use specs the user already has access to.
 
+See [principal and workspace interoperability](docs/principal-workspace-interoperability.md)
+for the identity matrix, state-polling contract, and portable commitment
+receipt.
+
 Workspace summaries are structured spec cards. They present the current spec
 core, file rules, attachment policy, guest access, column rules, sample record
 shape, note-file status, and local check status so Codex can reflect the draft
@@ -273,8 +371,8 @@ before designing direct SQL helpers. These payloads are intended to be useful
 to agents as well as humans.
 
 For operational queues, call `agent.list_my_work` in the actor's scope. An
-observer may call `observe.work` for all current work; historical questions
-belong to `observe.activity`.
+observer may call `observe.work` for current work in its assigned scope;
+historical questions belong to `observe.activity`.
 
 Required source references are a governed submission contract. When a
 downstream spec has an active source link with `min_count > 0`, load the file

package/SECURITY.md

@@ -12,8 +12,25 @@ operation surface.
 - Validates MCP server names before passing them to `codex mcp add`.
 - Passes npm or GitHub package specs as argv entries, never through a shell.
 - Rejects package specs with whitespace or control characters.
-- Exposes guidance only; it does not read local secrets, call Snowflake, mutate
-  files, or contact network services.
+- Does not read local secrets, call Snowflake, or contact network services.
+  Workbench tools write only the project files explicitly requested by the
+  caller.
+
+## Installed Native App MCP
+
+Installed Airlock can separately expose opt-in Snowflake-managed MCP endpoints.
+They are not hosted by this npm package and do not inherit local workspace
+identity. Their fixed agent and observer allowlists expose only read-only access
+context, work, safe spec discovery, and compact spec/file state. They exclude
+administrative or governed mutation, governed payload rows, restricted-reference
+reads, and attachment bytes.
+
+Each client must authenticate as its own Snowflake principal with a role that
+holds the matching Airlock application role and can use the configured
+warehouse. The endpoint adapters call Airlock's existing handlers, so procedure
+authorization, role lenses, observer scope, and license policy remain the
+security boundary. Only fixed adapters in the role-accessible versioned `mcp`
+schema are granted; Airlock's private `internal` schema remains ungranted.
 
 ## Production Rules
 

package/docs/architecture.md

@@ -36,10 +36,23 @@ product surface.
 
 ## MCP Surface
 
+There are two complementary MCP surfaces:
+
+- This package is a local bootstrap and spec-workbench server. It does not call
+  Snowflake or become an Airlock authorization layer.
+- Installed Airlock may expose optional Snowflake-managed Native App MCP
+  servers over nine fixed read-only adapters. Those endpoints execute inside
+  Snowflake as the authenticated principal and retain the existing `agent.*`
+  and `observe.*` policy checks.
+
+See [Native App managed MCP](native-app-managed-mcp.md) for the installed
+surface. The remainder of this section describes this package's local server.
+
 The bootstrap server exposes:
 
 - prompt: `airlock-start`
 - resource: `airlock://getting-started`
+- resource: `airlock://native-app-managed-mcp`
 - orientation tool: `airlock_start`
 - workbench tools: `airlock_doctor`, `airlock_init_repo`,
   `airlock_init_app_context`, `airlock_list_patterns`,

package/docs/native-app-managed-mcp.md

@@ -0,0 +1,67 @@
+# Native App Managed MCP
+
+Installed Airlock can optionally expose separate Snowflake-managed MCP servers
+for agent-scoped and observer-scoped reads. The stored procedures remain the
+authoritative API; MCP is a small transport adapter over existing policy checks.
+
+This is distinct from the local `airlock-mcp` package. The package helps agents
+design specs and build Airlock-aware software. It does not automatically query
+Snowflake. The Native App endpoints run in the consumer account and require an
+independently authenticated Snowflake principal.
+
+## Enablement
+
+Airlock does not create MCP objects during installation. An app administrator
+must opt in and name a usable warehouse:
+
+```sql
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH');
+CALL airlock.admin.enable_mcp_server('observer', 'OBSERVER_WH');
+CALL airlock.observe.mcp_servers();
+```
+
+Use `validate_only => TRUE` to check the fixed plan without DDL. Disable an
+endpoint with `airlock.admin.disable_mcp_server('agent')` or `'observer'`.
+Disable and re-enable to change its warehouse or refresh its specification
+after an Airlock upgrade.
+
+The authenticated Snowflake role needs warehouse access and the matching
+Airlock application role. Each mutating human or automated agent must retain
+its own Snowflake principal; never use a shared MCP credential as a
+meta-permission layer.
+
+## Fixed Read-Only Tools
+
+The agent endpoint exposes:
+
+- `airlock_my_access_context`
+- `airlock_list_my_work`
+- `airlock_describe_spec`
+- `airlock_spec_states`
+- `airlock_file_state`
+
+The observer endpoint exposes:
+
+- `airlock_observe_specs`
+- `airlock_observe_work`
+- `airlock_observe_spec_states`
+- `airlock_observe_file_state`
+
+Neither endpoint exposes mutation, `admin.*`, governed row reads,
+restricted-reference reads, or attachment bytes. Agent calls retain ordinary
+assignment, role-lens, and named-license checks. Observer calls retain
+assignment-scoped observer access and do not claim a named license.
+
+Snowflake's managed SQL transport requires scalar `VARIANT` results, so the
+servers target fixed adapters in Airlock's versioned `mcp` schema. Those
+adapters invoke the same handlers as the public read procedures. Only the fixed
+adapters are granted; Airlock's private `internal` schema remains ungranted.
+
+## Principal Proof
+
+Before relying on a new PAT-based client, run Airlock's
+`scripts/run_batch62_mcp_identity_probe.py` with two independently issued,
+role-restricted Snowflake programmatic access tokens. The proof must return two
+distinct matching `USER_ID` values from `airlock_my_access_context`. External
+workspace, channel, bot, or public-key identifiers are provenance only and
+never confer Airlock authority.

package/docs/principal-workspace-interoperability.md

@@ -0,0 +1,106 @@
+# Principal and workspace interoperability
+
+Airlock treats a workspace as a place for discussion, drafts, monitoring, and
+automation. It does not treat workspace roles, channel membership, reactions,
+or chat approvals as Snowflake authority.
+
+## Required identity model
+
+- Every mutating human or automated agent connects as its own attributable
+  Snowflake principal.
+- Direct work uses that principal's Airlock assignments.
+- Work for another principal uses an explicit Airlock delegation and
+  `on_behalf_of_user`; pass `delegation_id` only when Airlock reports multiple
+  matching active grants.
+- Snowflake user type and agent-session metadata are informational. They do not
+  create Airlock authority or change policy, workflow, expectations, or
+  billing.
+- Stored-procedure activity exposes `event_context.snowflake_agent_active` when
+  Snowflake supplies the execution-context marker. Use it for observation only;
+  the authenticated principal remains the authoritative actor.
+- A read-only channel may use a dedicated observer principal with
+  `<APP_NAME>.app_observer` and explicit per-spec `observer_access`. Never reuse
+  that principal for mutation.
+
+## Polling
+
+Use state tokens before larger reads:
+
+- `agent.spec_state(...).STATE_TOKEN` for one actor-visible spec, or
+  `agent.spec_states(...)` for up to 100 known specs under one role lens;
+- `agent.file_state(...).FILE_STATE_ID` for one visible file's data, workflow,
+  attachment, reference, and retained-version state;
+- `observe.spec_state`, `observe.spec_states`, and `observe.file_state` for a
+  scoped observer principal; and
+- `agent.list_my_work` or `observe.work` on a separate cadence for deadlines
+  and current work.
+
+A missing state row is the terminal result for that cursor. Return to discovery
+instead of inferring whether the object was deleted, retired, or became
+inaccessible.
+
+Plural spec polling preserves first-request order after case-insensitive
+deduplication and omits missing or inaccessible targets without identifying the
+cause. Use it for one logical multi-spec polling cycle; keep the singular call
+for one target.
+
+## Commitment receipts
+
+After every supported `agent.*` or intentional `admin.*` mutation, store a
+bounded receipt in the workspace event history:
+
+```json
+{
+  "schema": "airlock.commitment-receipt/v1",
+  "procedure": "airlock.agent.load_data",
+  "actor": {
+    "snowflake_principal": "CSMITH",
+    "on_behalf_of": "ASMITH",
+    "delegation_id": null
+  },
+  "target": {
+    "spec_name": "reimbursements",
+    "path": "asmith",
+    "filename": "expense_2026_08_08"
+  },
+  "outcome": {
+    "status": "ok",
+    "code": "LOADED",
+    "message": null,
+    "issues": []
+  },
+  "committed_state": null,
+  "operation_identity": {},
+  "recorded_at": "2026-08-08T12:00:00Z"
+}
+```
+
+Bind `actor.snowflake_principal` to the authenticated connection identity, not
+a chat display name. Preserve the procedure's stable status, code, message,
+and issues. Derive `on_behalf_of` and `delegation_id` from the actual procedure
+arguments and reject conflicting receipt metadata.
+
+After a successful direct file mutation, call `agent.file_state` with the
+returned spec, path, and filename to populate `committed_state`. Do not make
+that direct actor state read after delegated work because `agent.file_state`
+has no delegated call shape. Leave `committed_state` null unless the actor
+performs a separate independently authorized observation. For attachment
+mutations, retain the returned `ATTACHMENT_ID` in `operation_identity`.
+
+A `DELEGATED_ACTION` event records the authorized delegated attempt and its
+actor/principal identity. It does not by itself prove that the requested
+mutation committed; use the procedure outcome and normal mutation events as
+commitment evidence.
+
+Denied mutations are receipts too. Preserve the denial code and issues, omit
+committed state, and never describe workspace approval as an Airlock
+commitment.
+
+## Cortex Code plugin
+
+This repository includes `.cortex-plugin/plugin.json`, which loads the bundled
+Airlock skill and starts the pinned Airlock MCP package over stdio. Install from
+the Git repository with Cortex Code's plugin command, inspect the version, and
+keep credentials outside the plugin manifest. Account-local Cortex Extension
+sharing may be used where enabled; follow Snowflake's current preview and RBAC
+requirements.

package/docs/workflows.md

@@ -175,19 +175,76 @@ Use the installed Airlock procedure grammar:
 - `airlock.admin.*` is for administrative mutation and operational changes.
 
 For work discovery, use `agent.list_my_work` as the current actor's unified
-inbox. Observers use `observe.work` for account-wide current work and
-`observe.activity` for historical events. Do not recreate separate workflow
-and expectation inbox calls in app code.
-
-Watcher loops should call `agent.spec_state` before larger reads. Cache its
-authorization-scoped `STATE_TOKEN` and retrieve descriptors, file lists, or
-governed data only when it changes. Poll `agent.list_my_work` independently
-because deadlines and expectation windows can change without rotating the spec
-token. Once the app tracks one logical file,
+inbox. Observers use `observe.work` for current work within their assignment and
+spec scope, and `observe.activity` for scoped historical events. `app_admin`
+and the locked Airlock role `global_observer` receive the account-wide forms.
+Do not recreate separate workflow and expectation inbox calls in app code.
+
+For an account-wide observer audit, call `observe.observers(...)`. It flattens
+the current user assignment, effective observer role, spec/path/workflow scope,
+and named-license posture. Treat `active_seat_observer_only` as an explicit
+administrative cleanup state: observer calls are free, but a previously claimed
+seat remains billable until `admin.unassign_license(...)` is called.
+
+When asked to set up an observer principal for a channel, keep these controls
+separate and apply them in order:
+
+1. Grant a dedicated Snowflake account role the installed app's
+   `<APP_NAME>.app_observer` application role.
+2. Create a distinct Airlock role with `admin.create_roles(...)`, then assign
+   the observer principal's Snowflake username with
+   `admin.create_assignments(...)`.
+3. Add that role to each intended spec's `observer_access.observer_roles`, using
+   `path_filter` and `workflow_states` when narrower visibility is required.
+4. As `app_admin` or `global_observer`, verify the result with
+   `observe.observers(...)` and audit the setup through
+   `observe.admin_activity(procedure_name => 'create_assignments', action_family
+   => 'assignments', ...)`.
+
+Assignment create, alter, and drop activity includes structured
+`EVENT_CONTEXT.before`, `EVENT_CONTEXT.after`, and
+`EVENT_CONTEXT.changed_fields`. Expect `free_observer_only` when the principal
+has no agent access or active seat. If it reports `active_seat_observer_only`,
+confirm the principal no longer needs `agent.*` or Streamlit before calling
+`admin.unassign_license(...)`. Never share one Snowflake username across
+channels merely to simplify setup; that collapses attribution and revocation.
+
+Watcher loops should call `agent.spec_state` for one known spec or
+`agent.spec_states` for up to 100 known specs under one role lens before larger
+reads. Cache each authorization-scoped `STATE_TOKEN` and retrieve descriptors,
+file lists, or governed data only when it changes. Poll `agent.list_my_work`
+independently because deadlines and expectation windows can change without
+rotating a spec token. Once the app tracks one logical file,
 compare `agent.file_state(...).FILE_STATE_ID` to detect data replacement,
-workflow movement, attachment changes, or exact-reference changes. Observer
-services may use the global read-only `observe.spec_state` and
-`observe.file_state` equivalents.
+workflow movement, attachment changes, exact-reference changes, or retained
+version-history changes. Observer principals use the authorization-scoped,
+read-only `observe.spec_state`, `observe.spec_states`, and `observe.file_state`
+equivalents. Missing or inaccessible specs are omitted from a plural result as
+the terminal polling signal; authorized query failures remain procedure errors.
+
+Every mutating human or automated agent should connect as an attributable
+Snowflake principal. When it acts for another principal, use explicit Airlock
+delegation and `on_behalf_of_user`; pass `delegation_id` only when multiple
+active grants match. Workspace roles, channel membership, reactions, and chat
+approvals remain collaboration context, not Airlock authority.
+A `DELEGATED_ACTION` event records the authorized attempt and actor/principal
+identity; it does not by itself prove that the requested mutation committed.
+
+When activity includes `EVENT_CONTEXT.snowflake_agent_active`, treat it as
+informational execution provenance. It does not grant authority, prove
+delegation, or change policy and billing.
+
+After each supported `agent.*` or intentional `admin.*` mutation, store an
+`airlock.commitment-receipt/v1` in workspace history. Preserve the authenticated
+Snowflake actor and derive any represented principal and delegation id from the
+actual call arguments. Retain the target, stable status/code/message/issues,
+and timestamp. For a successful direct file mutation, follow with
+`agent.file_state` and retain `UPLOAD_ID`, `FILE_STATE_ID`, workflow state,
+attachment count, and reference count. Do not make that direct actor state read
+after delegated work; leave `committed_state` null unless the actor performs a
+separate independently authorized observation. A denied call is still a
+receipt, but it has no committed state. See
+`docs/principal-workspace-interoperability.md` for the complete shape.
 
 For downstream work that requires governed source evidence, use the installed
 source-reference sequence: load the downstream Draft, call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {
@@ -30,6 +30,7 @@
     "src/*.mjs",
     "src/airlock_mcp/*.py",
     ".agents",
+    ".cortex-plugin",
     "patterns",
     "schemas",
     "workspaces",

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.7",
+    version="0.1.9",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"

package/src/airlock_mcp/app_context.py

@@ -42,6 +42,14 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Installed Airlock may separately expose opt-in Snowflake-managed MCP endpoints
+for `app_agent` and `app_observer`. They use fixed read-only tool allowlists,
+preserve each client's authenticated Snowflake principal, and never expose
+mutation, governed payload rows, restricted-reference reads, or attachment
+bytes. They are distinct from the local Airlock MCP spec workbench. Manage them
+with `admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`.
+
 Use `agent.list_my_work` for the actor's unified current-work inbox,
 `observe.work` for account-wide current work, and `observe.activity` for
 historical events. The older split workflow/expectation work calls are retired.
@@ -139,6 +147,12 @@ Installed Airlock procedure grammar:
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
 
+An installed Airlock app may also provide separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. Their fixed tools are read-only,
+retain the authenticated Snowflake principal, and exclude mutation and governed
+payload reads. Do not confuse those endpoints with the local Airlock MCP spec
+workbench or treat workspace identity as Airlock authority.
+
 Use `agent.list_my_work` for the current actor's unified work inbox. Use
 `observe.work` for account-wide current work and `observe.activity` for event
 history.
@@ -224,6 +238,7 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
             "required_source_references": "load Draft, list eligible sources, pin exact manifest rows, then advance; SOURCE_REFERENCE_REQUIRED blocks missing evidence",
             "spec_migration": "immutable two-version lifecycle; list with observe.spec_migrations, run bounded admin migration batches, inspect observe.spec_migration evidence, cancel only before activation, and retire only after the source is drained",
             "admin": "administrative mutation and operational changes",
+            "native_mcp": "optional role-separated Snowflake-managed read-only endpoints; fixed agent and observer tools preserve Snowflake principal identity and never expose mutation or governed payload rows",
             "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
             "attachment_preview": "governed Streamlit preview emits metadata-only ATTACHMENT_PREVIEW; MCP clients do not get direct stage access",
             "application_surface": "built-in Streamlit is a generic operating/fallback surface; purpose-built apps own domain UI and use Airlock as the governed backend",

package/src/airlock_mcp/bootstrap.py

@@ -126,6 +126,15 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Installed Airlock may also expose separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. They are distinct from this local
+spec-workbench MCP server and contain only fixed read-only tools for access
+context, work, safe spec discovery, and compact spec/file state. They preserve
+the authenticated Snowflake principal and never expose mutation, governed
+payload rows, restricted-reference reads, or attachment bytes. Administrators
+manage them through `admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`.
+
 Use `agent.list_my_work` for the actor's unified current-work inbox,
 `observe.work` for account-wide current work, and `observe.activity` for
 historical events. The older split workflow/expectation work calls are retired.

package/src/mcp.mjs

@@ -1,9 +1,15 @@
 import readline from "node:readline";
 
-import { PROTOCOL_VERSION, airlockPrompt, gettingStartedText } from "./text.mjs";
+import {
+  PROTOCOL_VERSION,
+  airlockPrompt,
+  gettingStartedText,
+  nativeAppManagedMcpText,
+} from "./text.mjs";
 import { WORKBENCH_TOOLS, callWorkbenchTool } from "./workbench.mjs";
 
 const GETTING_STARTED_URI = "airlock://getting-started";
+const NATIVE_APP_MANAGED_MCP_URI = "airlock://native-app-managed-mcp";
 
 const START_TOOL = {
   name: "airlock_start",
@@ -44,10 +50,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.7",
+        version: "0.1.9",
       },
       instructions:
-        "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
+        "Airlock MCP is the local spec workbench and app-context bootstrap server. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs. Installed Airlock can separately expose opt-in Snowflake-managed read-only MCP endpoints; read airlock://native-app-managed-mcp for their fixed tools and security boundary.",
     });
   }
 
@@ -122,20 +128,30 @@ export function handleMcpRequest(message) {
           description: "How to start building and using Airlock specs with Codex.",
           mimeType: "text/markdown",
         },
+        {
+          uri: NATIVE_APP_MANAGED_MCP_URI,
+          name: "Installed Airlock Native App MCP",
+          description: "Opt-in Snowflake-managed read-only endpoints exposed by an installed Airlock Native App.",
+          mimeType: "text/markdown",
+        },
       ],
     });
   }
 
   if (method === "resources/read") {
-    if (params?.uri !== GETTING_STARTED_URI) {
+    if (params?.uri !== GETTING_STARTED_URI && params?.uri !== NATIVE_APP_MANAGED_MCP_URI) {
       return makeError(id, -32602, `unknown resource: ${params?.uri || ""}`);
     }
+    const text =
+      params.uri === NATIVE_APP_MANAGED_MCP_URI
+        ? nativeAppManagedMcpText()
+        : gettingStartedText("Home");
     return makeResponse(id, {
       contents: [
         {
           uri: params.uri,
           mimeType: "text/markdown",
-          text: gettingStartedText("Home"),
+          text,
         },
       ],
     });

package/src/text.mjs

@@ -56,20 +56,61 @@ access, which specs are read sources, which spec records decisions or actions,
 and where the app should run. Teach the installed Airlock procedure split:
 \`airlock.observe.*\` is read-only governance observation,
 \`airlock.agent.*\` is governed agent work, and \`airlock.admin.*\` is
-administrative mutation. Prefer observe payloads such as
+administrative mutation. Installed Airlock may also expose separate opt-in
+Snowflake-managed MCP endpoints for the agent and observer application roles.
+Those endpoints have fixed read-only tool allowlists and preserve the
+authenticated Snowflake principal; they are not this local spec-workbench MCP
+server. They never expose mutation, governed payload rows, restricted-reference
+reads, or attachment bytes. Prefer observe payloads such as
 \`observe.procedures\`, \`observe.specs\`, \`observe.spec\`,
 \`observe.governance_map\`, \`observe.explain_access\`, \`observe.health\`,
 \`observe.activity\`, \`observe.admin_activity\`, \`observe.spec_admin_activity\`,
 and \`observe.billing_events\` before inventing custom read paths. For \`alter_spec\`
 activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
-before fetching version snapshots. For watcher loops, cache the role-scoped
-\`agent.spec_state(...).STATE_TOKEN\` and do larger reads only when it changes.
+before fetching version snapshots. For polling loops, use
+\`agent.spec_state(...).STATE_TOKEN\` for one known spec or
+\`agent.spec_states(...)\` for up to 100 known specs under one role lens, and
+do larger reads only when a token changes.
 After selecting one logical file, compare
 \`agent.file_state(...).FILE_STATE_ID\` to detect data, workflow, attachment,
-or exact-reference changes. Observer services may use the account-wide
-\`observe.spec_state\` and \`observe.file_state\` equivalents. Offer to run \`airlock-mcp init-app-context\`
+exact-reference, or retained version-history changes. Observer principals may use
+the authorization-scoped \`observe.spec_state\`, \`observe.spec_states\`, and
+\`observe.file_state\` equivalents. Missing or inaccessible specs are omitted
+from a plural result without disclosing the cause; that omitted row is the
+terminal polling signal. Authorized query failures remain errors. Holding
+\`app_observer\` opens only the read-only procedure family; Airlock
+assignments plus \`observer_access.observer_roles\` determine spec visibility,
+and account-wide observation requires \`app_admin\` or the locked Airlock role
+\`global_observer\`. That reserved role cannot own specs, receive guest/reviewer
+grants, or manage child roles. Observe-only calls do not consume a named seat, while
+\`agent.*\` and Streamlit remain seat-gated. Use a distinct Snowflake username
+per observer channel principal. For account-wide audits, call
+\`observe.observers(...)\` to join observer assignment/scope with agent-access
+and license posture. \`active_seat_observer_only\` means the identity remains
+billable until an administrator explicitly calls \`admin.unassign_license\`;
+never infer billing from role names alone. When asked to configure an observer
+principal, apply four explicit controls: grant its dedicated Snowflake role
+\`<APP_NAME>.app_observer\`, create and assign a distinct Airlock role, publish
+that role through each spec's \`observer_access\`, then verify scope and billing
+with \`observe.observers(...)\`. Audit assignment create, alter, and drop
+through \`observe.admin_activity(..., action_family => 'assignments')\`; use
+the structured \`EVENT_CONTEXT.before\`, \`after\`, and \`changed_fields\`
+instead of parsing descriptions. Offer to run \`airlock-mcp init-app-context\`
 in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
 generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+Treat every mutating human or automated agent as an attributable Snowflake
+principal. Direct work uses that principal's assignments; work for another
+principal uses explicit Airlock delegation and \`on_behalf_of_user\`. Workspace
+roles, channel membership, reactions, and chat identity do not create Airlock
+authority. Treat \`EVENT_CONTEXT.snowflake_agent_active\` as informational
+provenance only. A \`DELEGATED_ACTION\` event records an authorized attempt, not
+proof that its mutation committed. After each supported mutation, retain an
+\`airlock.commitment-receipt/v1\` with the authenticated actor, delegation
+identity derived from the actual call arguments, target, stable result, and
+timestamp. Hydrate successful direct file mutations with \`agent.file_state\` so
+the receipt includes \`UPLOAD_ID\`, \`FILE_STATE_ID\`, and current workflow state.
+Leave delegated \`committed_state\` null unless the actor performs a separate
+independently authorized observation.
 Treat Airlock's built-in Streamlit app as a generic operating and fallback
 surface, not a universal domain app. When a repeated, high-value decision needs
 domain-specific summaries, calculations, evidence layout, terminology, or
@@ -131,7 +172,8 @@ Airlock MCP will offer:
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
   - read-only observe procedures for governance maps, health, access explanation, activity, billing events, and context packets
-  - scoped spec and file state tokens for efficient watcher polling
+  - the optional role-separated Snowflake-managed MCP endpoints exposed by installed Airlock
+  - scoped spec and file state tokens for efficient polling
   - app context seeding with spec snapshots and manifests
   - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
@@ -142,6 +184,78 @@ Airlock MCP will offer:
   - airlock-specs library patterns as starting points, checked against current artifacts`;
 }
 
+export function nativeAppManagedMcpText() {
+  return `# Installed Airlock Native App MCP
+
+This npm package runs a local spec workbench and app-context bootstrap MCP
+server. An installed Airlock Native App can separately expose two opt-in,
+Snowflake-managed MCP endpoints for governed operational discovery. Enabling
+those endpoints does not turn this local server into a Snowflake client.
+
+## Enable And Inspect
+
+An Airlock administrator selects a warehouse and enables each interface
+explicitly. Replace \`airlock\` with the installed application object name when
+it differs:
+
+\`\`\`sql
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH', TRUE);
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH');
+CALL airlock.admin.enable_mcp_server('observer', 'OBSERVER_WH');
+CALL airlock.observe.mcp_servers();
+\`\`\`
+
+The first call is validate-only. Use
+\`airlock.admin.disable_mcp_server('agent')\` or \`'observer'\` to remove an
+endpoint. Disable and re-enable an endpoint to change its warehouse or refresh
+its fixed tool specification after an Airlock upgrade. The client principal's
+Snowflake role must be able to use the selected warehouse and hold the matching
+Airlock application role.
+
+## Fixed Tool Allowlists
+
+The agent endpoint, \`core.airlock_agent_mcp\`, exposes only:
+
+- \`airlock_my_access_context\`
+- \`airlock_list_my_work\`
+- \`airlock_describe_spec\`
+- \`airlock_spec_states\`
+- \`airlock_file_state\`
+
+The observer endpoint, \`core.airlock_observer_mcp\`, exposes only:
+
+- \`airlock_observe_specs\`
+- \`airlock_observe_work\`
+- \`airlock_observe_spec_states\`
+- \`airlock_observe_file_state\`
+
+Neither endpoint exposes \`admin.*\`, governed or administrative mutation,
+governed payload rows, restricted-reference reads, or attachment bytes. Existing
+Airlock procedure authorization remains the policy boundary. Except for the
+non-claiming \`airlock_my_access_context\` tool, agent tools retain ordinary
+named-license enforcement and may auto-assign a license when consumer policy
+allows it. Observer tools neither require nor assign a named license.
+
+## Identity And Transport Boundary
+
+Every MCP client should authenticate as its own Snowflake principal. A shared
+token, workspace role, channel identity, or external agent id does not create
+Airlock authority. Treat external identity metadata as provenance only; use
+Airlock delegation when one authenticated principal acts for another.
+
+The endpoint specifications target scalar \`VARIANT\` adapters in Airlock's
+role-accessible, versioned \`mcp\` transport schema because Snowflake's managed
+MCP SQL API consumes JSONV2 rather than Arrow table results. The adapters call
+the same read-only handlers and retain the same authorization, role-lens,
+observer-scope, and license checks as the public procedures. Only the fixed
+adapters are granted from \`mcp\`; Airlock's private \`internal\` schema remains
+ungranted.
+
+Use \`airlock_my_access_context\` first when validating a new agent connection,
+and require that independently issued credentials return their exact distinct
+\`USER_ID\` values.`;
+}
+
 export function gettingStartedText(project) {
   return `# Airlock MCP
 
@@ -165,6 +279,13 @@ Airlock MCP gives agents four kinds of Airlock help:
    context packets, and governance maps before deciding what an app or agent
    should do.
 
+Installed Airlock can also expose separate opt-in, role-separated,
+Snowflake-managed read-only MCP endpoints. They preserve the authenticated
+Snowflake principal and use fixed agent and observer tool allowlists. They are
+distinct from this local spec-workbench server. Read
+\`airlock://native-app-managed-mcp\` for the exact tools, lifecycle procedures,
+licensing behavior, and security boundary.
+
 Start in a Git-backed specs repo such as ${specsRepoName(project)}. GitHub is
 the recommended default when the user has it set up, but any normal repository
 works. If Codex is creating the repo, ask where the directory should live before
@@ -225,11 +346,41 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 \`observe.explain_access\`, \`observe.health\`, \`observe.activity\`,
 \`observe.admin_activity\`, \`observe.spec_admin_activity\`, and \`observe.billing_events\`;
 for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
-triage what changed before fetching version snapshots. For watcher loops, poll
-\`agent.spec_state\` and compare its scoped \`STATE_TOKEN\` before larger reads;
+triage what changed before fetching version snapshots. For polling loops, use
+\`agent.spec_state\` for one known spec or \`agent.spec_states\` for up to 100
+known specs under one role lens, and compare scoped \`STATE_TOKEN\` values before
+larger reads;
 compare \`agent.file_state(...).FILE_STATE_ID\` for one selected file. Observer
-services use \`observe.spec_state\` and \`observe.file_state\` for account-wide
-read-only state. Do not use retired admin
+principals use \`observe.spec_state\`, \`observe.spec_states\`, and
+\`observe.file_state\` for authorization-scoped read-only state. File-state
+UUIDs include retained version-history changes. Missing or inaccessible specs
+are omitted from a plural result as the terminal polling signal; authorized
+query failures remain errors.
+\`app_observer\` grants access to the
+read-only procedure family; Airlock assignments and
+\`observer_access.observer_roles\` grant spec visibility. Observe-only calls do
+not consume a named seat. Account-wide access requires \`app_admin\` or the
+locked \`global_observer\` Airlock role, which cannot own specs, receive
+guest/reviewer grants, or manage child roles. Account-wide auditors should call
+\`observe.observers(...)\` for flattened observer scope and license posture;
+\`active_seat_observer_only\` requires explicit \`admin.unassign_license\` to
+stop future seat billing. Observer setup should use a dedicated Snowflake
+username and account role, the \`<APP_NAME>.app_observer\` application role, a
+distinct Airlock role/assignment, and explicit per-spec \`observer_access\`.
+Verify it with \`observe.observers\` and audit structured assignment before/after
+evidence with \`observe.admin_activity(..., action_family => 'assignments')\`.
+Every mutating human or automated agent must keep an attributable Snowflake
+principal. Use explicit Airlock delegation when it acts for someone else; never
+turn workspace membership or chat approval into Airlock authority. Treat
+\`EVENT_CONTEXT.snowflake_agent_active\` as informational provenance only. A
+\`DELEGATED_ACTION\` event records an authorized attempt, not proof of commitment.
+Store each supported mutation as an \`airlock.commitment-receipt/v1\`, preserving
+the authenticated actor, delegation identity derived from the actual call
+arguments, stable status/code/issues, target, and timestamp. Follow successful
+direct file mutations with \`agent.file_state\` to retain \`UPLOAD_ID\`,
+\`FILE_STATE_ID\`, and workflow state. Leave delegated \`committed_state\` null
+unless the actor performs a separate independently authorized observation.
+Do not use retired admin
 read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
 \`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
 \`reference_config.restricted_reference\`, do not enumerate the protected