@zackbart/connecta 0.31.0 → 0.32.0

package/documentation/code-mode.md

@@ -48,7 +48,7 @@ QuickJS subpath:
 import { createConnecta } from "@zackbart/connecta";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
 
-createConnecta({ executor: quickJsExecutor() /* connectors, auth, storage… */ });
+createConnecta({ executor: quickJsExecutor(), readOnly: false /* connectors, auth, storage… */ });
 ```
 
 `quickJsExecutor()` runs each program in a disposable child process, with CPU,
@@ -61,7 +61,7 @@ On Workers the Worker Loader is the sandbox; Dynamic Workers require the Paid pl
 ```ts
 import { workerExecutor } from "@zackbart/connecta/worker";
 
-createConnecta({ executor: workerExecutor({ loader: env.LOADER }) });
+createConnecta({ executor: workerExecutor({ loader: env.LOADER }), readOnly: false /* … */ });
 ```
 
 The adapter uses only `loader` and an optional `timeout`. Its admission defaults
@@ -283,7 +283,10 @@ signature is byte-identical to the one `search_tools` returns.
 integration is ambiguous. `safety: "readOnly"` selects stored read verdicts;
 `"approvalRequired"` selects stored write verdicts; omitted or `"all"` selects
 both. Search and describe rows carry `classification`. These filters grant no
-authority and change no pool trust or call admission decision.
+authority and change no call admission decision. On a read-only endpoint,
+search and describe omit write tools (`W12`): a write is absent from every
+filter, and describing one is `unknown_tool`. `connecta.skill` guides are not
+filtered and may name such a write; calling it is still refused.
 
 **S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`
 (declared properties only), and `outputKeys`: the names the rendered schema
@@ -394,10 +397,10 @@ and a 32 KiB bridge ceiling. `page` is zero-based and mutually exclusive with
 are at least four bytes wide and align both edges to UTF-8 boundaries.
 Follow `nextOffset`, reassemble inside the program, and return a reduced value.
 Before returning a page, the host rechecks current authentication, connector/tool
-grants, pool membership, and endpoint trust against both the original and current
-tool classification. A read-only endpoint cannot page a write result, so a
-direct write there returns an inline truncation notice without stashing the
-result or advertising a paging action. Binding
+grants, pool membership, and whether the endpoint is read-only against both the
+original and current tool classification. A read-only endpoint cannot page a
+write result; it never runs a write, so any write result it is asked for came
+from a writable endpoint. Binding
 mismatches, revoked access, and old entries without bindings are `not_found`, as
 are unknown or expired ids; a storage failure is `unavailable`. IDs are random UUIDs.
 The `get_result` meta-tool is removed.
@@ -477,7 +480,7 @@ Connecta passes an admitted decoded URI as an opaque MCP `resources/read`
 argument to the configured endpoint. It never fetches that
 URI or creates a connector from it.
 
-Resources are protocol reads in both `read-only` and `trusted` pools. A read
+Resources are protocol reads on read-only and writable endpoints alike. A read
 requires a grant to the whole connector through the endpoint/pool and identity
 intersection. Exact-tool grants, including guarded grants, authorize no
 resources. An absent, hidden, tool-restricted or resource-incapable connector
@@ -553,27 +556,27 @@ URL-elicitation hosts retain their existing flow.
 may do. A provider maps each downstream failure to the code that tells the
 caller what to do next, and never invents a cause it was not told.
 
-| Code                                 | Raised when                                                                                                                                                                                           | `retryable`   |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `unknown_address`                    | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
-| `unknown_tool`                       | the connector has no such tool                                                                                                                                                                        | false         |
-| `destructive_tool_requires_approval` | a program in a read-only pool attempted a write (`E4`)                                                                                                                                                | false         |
-| `auth_required`                      | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
-| `invalid_args`                       | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
-| `not_found`                          | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap                      | false         |
-| `conflict`                           | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false         |
-| `input_required_unsupported`         | a downstream asked for input; use `nextAction` for the equivalent direct call                                                                                                                         | false         |
-| `rate_limited`                       | the downstream reported a rate limit                                                                                                                                                                  | true          |
-| `unavailable`                        | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose                     | true          |
-| `timeout`                            | a call or sandbox deadline expired; details name operation, stage, elapsedMs, and deadlineMs                                                                                                          | per operation |
-| `program_error`                      | guest JavaScript failed; `details.name`, `line`, and a fixed repair hint describe it                                                                                                                  | false         |
-| `cancelled`                          | the run ended while this call was in flight (`E5`)                                                                                                                                                    | false         |
-| `connector_call_failed`              | anything else the connector threw                                                                                                                                                                     | per message   |
-| `catalog_lookup_failed`              | the connector's catalog could not be loaded                                                                                                                                                           | per cause     |
-| `result_processing_failed`           | the result could not be prepared                                                                                                                                                                      | per message   |
-| `result_too_large`                   | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
-| `budget_exceeded`                    | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
-| `write_outcome_unknown`              | a trusted-pool write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                  | false         |
+| Code                         | Raised when                                                                                                                                                                                           | `retryable`   |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `unknown_address`            | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
+| `unknown_tool`               | the connector has no such tool                                                                                                                                                                        | false         |
+| `read_only_endpoint`         | a program on a read-only endpoint attempted a write (`E4`)                                                                                                                                            | false         |
+| `auth_required`              | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
+| `invalid_args`               | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
+| `not_found`                  | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap                      | false         |
+| `conflict`                   | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false         |
+| `input_required_unsupported` | a downstream asked for input; use `nextAction` for the equivalent direct call                                                                                                                         | false         |
+| `rate_limited`               | the downstream reported a rate limit                                                                                                                                                                  | true          |
+| `unavailable`                | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose                     | true          |
+| `timeout`                    | a call or sandbox deadline expired; details name operation, stage, elapsedMs, and deadlineMs                                                                                                          | per operation |
+| `program_error`              | guest JavaScript failed; `details.name`, `line`, and a fixed repair hint describe it                                                                                                                  | false         |
+| `cancelled`                  | the run ended while this call was in flight (`E5`)                                                                                                                                                    | false         |
+| `connector_call_failed`      | anything else the connector threw                                                                                                                                                                     | per message   |
+| `catalog_lookup_failed`      | the connector's catalog could not be loaded                                                                                                                                                           | per cause     |
+| `result_processing_failed`   | the result could not be prepared                                                                                                                                                                      | per message   |
+| `result_too_large`           | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
+| `budget_exceeded`            | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
+| `write_outcome_unknown`      | a program write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                       | false         |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -581,16 +584,13 @@ caller what to do next, and never invents a cause it was not told.
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** A tool classified as a write never runs in a
-program unless the pool is trusted (`W12`). It is refused with
-`destructive_tool_requires_approval` before validation and before anything is
-sent, `nextAction` carrying its canonical address to `call_destructive_tool`
-and a schema-filtered snapshot within the 512-byte echo budget. `argsRedacted`
-marks partial or withheld arguments; use the original arguments if this flag is
-set or `args` is absent. Snapshots are never clipped. The host's prompt on that
-call is the approval, and the only one: generated code can neither mint the
-capability nor approve its own write, and the model's short `reason` grants no
-authority and never goes downstream.
+**E4.** A tool classified as a write never runs on a read-only endpoint
+(`W12`). A program's call is refused with `read_only_endpoint` before
+validation and before anything is sent. The refusal carries no `nextAction` and
+echoes no arguments: no route on that endpoint writes, so the program reports
+it rather than retrying. Generated code can neither mint the capability nor
+change the endpoint; on a writable endpoint, approval of the program as a write
+belongs to the client.
 
 **E5.** Failures of the _execution_, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
@@ -631,7 +631,7 @@ Program diagnostic fields are bounded before transport, including escaped text;
 a large custom error name cannot turn a failure into a truncated success.
 
 **E7.** `retryable` for `unknown_address`, `unknown_tool`, and
-`destructive_tool_requires_approval` is pinned false, never inferred from an
+`read_only_endpoint` is pinned false, never inferred from an
 address containing `503`, `429`, or `temporar`. The first two carry
 `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }`
 — scoped discovery keyed to the surface the caller has, since a program cannot
@@ -686,7 +686,7 @@ Caught call failures retain that connector visibility when catalog loading or
 tool resolution fails. Recovery messages listing configured connectors or
 local guides retain visibility of those contributors too.
 Each page rechecks current auth,
-grants, pool membership, and trust. Reading a stash inside a program carries
+grants, pool membership, and the endpoint's `readOnly`. Reading a stash inside a program carries
 its dependencies forward to any new return stash. The page cap is the smallest
 of the deployment cap and contributing connectors' effective `maxResultBytes`.
 Read-only endpoints cannot page write results. A UUID is a handle, never a grant.
@@ -882,17 +882,17 @@ deadline past the ceiling means raising the ceiling too.
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
 
-| Bound                                                                         | Value                                                                                                        |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Host calls per execution, shared by `search`, `describe`, `call`, and `read`  | 20 by default, `execute.maxHostCalls`                                                                        |
-| Trusted-pool writes per run, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
-| Deadline per host call                                                        | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
-| Discovery page                                                                | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
-| `describe` addresses                                                          | ≤ 100                                                                                                        |
-| `describe` nearby suggestions                                                 | ≤ 3 canonical addresses per failed entry                                                                     |
-| Caller text echoed by `describe` recovery                                     | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
-| Result                                                                        | 24,000 serialized characters                                                                                 |
-| Logs presented to the model                                                   | 4,000 characters                                                                                             |
+| Bound                                                                                   | Value                                                                                                        |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Host calls per execution, shared by `search`, `describe`, `call`, and `read`            | 20 by default, `execute.maxHostCalls`                                                                        |
+| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
+| Deadline per host call                                                                  | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
+| Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
+| `describe` addresses                                                                    | ≤ 100                                                                                                        |
+| `describe` nearby suggestions                                                           | ≤ 3 canonical addresses per failed entry                                                                     |
+| Caller text echoed by `describe` recovery                                               | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
+| Result                                                                                  | 24,000 serialized characters                                                                                 |
+| Logs presented to the model                                                             | 4,000 characters                                                                                             |
 
 Every `call`, `read`, `search`, and `describe` spends one host call on entry, before
 resolution, validation, or dispatch. Catching a local refusal refunds nothing.
@@ -901,7 +901,7 @@ The first call beyond the budget ends the host run with one non-retryable
 `try/catch` cannot swallow it. Later host access, including `emit`, stops; pending
 replies are withheld. The refusal reaches no connector, returns no partial result,
 and discards accepted emits (`M4`). Calls still resolving or awaiting admission
-are cancelled, including trusted-pool writes past their gate. Dispatched trusted-pool writes
+are cancelled, including writes past their gate. Dispatched writes
 drain under `W9`; unknown outcomes retain precedence. The lease then releases:
 QuickJS terminates its child, and the Worker adapter disposes RPC and loader
 handles independently of the guest deadline. Workers guest computation may
@@ -1003,22 +1003,22 @@ payload-free _by construction_ means the event has nowhere to put a payload.
 distinctive output is the program source — exactly what a payload-free history
 must never keep.
 
-**V5.** A trusted-pool write a program issues after it has already returned is not
+**V5.** A write a program issues after it has already returned is not
 sent and records nothing: it was never an attempt (`W9`).
 
 ## Writes
 
-Pool trust belongs to deployment code. The default `/mcp` endpoint uses
-`trust: "read-only"`; each named pool has its own `trust`, also defaulting to
-`"read-only"`. A trusted default endpoint does not make named pools trusted.
-The default preserves refusal of ordinary program writes. A deployment must opt into program writes explicitly.
+Whether an endpoint writes belongs to deployment code. Every deployment sets
+`readOnly` for `/mcp` explicitly; construction fails without it. Each named pool inherits
+the deployment's `readOnly` unless it sets its own, in either direction. The
+client owns approval; Connecta answers one question per endpoint: can it write.
 
 ```ts
 createConnecta({
   connectors, executor,
-  trust: "read-only",
+  readOnly: false, // required: false writes, true refuses every write call
   pools: {
-    automation: { tools: ["posthog"], trust: "trusted", grant },
+    reporting: { tools: ["posthog"], readOnly: true, grant },
   },
   classification: {
     posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
@@ -1027,6 +1027,9 @@ createConnecta({
 });
 ```
 
+The removed `trust` option, on the deployment or a pool, fails construction
+with a message naming `readOnly` (`INV-11`).
+
 The registry computes one `classifyTool` verdict on each request-scoped
 published catalog entry. It caches and persists only raw downstream facts.
 Every caller consumes that stored verdict. Config cannot classify an individual
@@ -1044,7 +1047,7 @@ fail construction; unknown remote tool keys fail publication of the whole
 catalog. Overrides are exact tool names, including names containing dots.
 They are never inferred from descriptions or arguments.
 
-**W9.** Programs in trusted pools may write. A dispatched write is awaited even
+**W9.** Programs on a writable endpoint may write. A dispatched write is awaited even
 if the program does not await it, bounded by its host-call deadline. A write
 that reaches accounting after the program settles is not sent. An unanswered
 write makes the run fail `write_outcome_unknown` with
@@ -1054,7 +1057,7 @@ write is automatically retried, including an ambiguous timeout. A downstream
 refusal or a tool's `isError` can establish failure; a timeout or an unanswered
 transport failure leaves the outcome unknown.
 
-**W10.** `execute.maxWrites`, default 10, bounds writes in trusted programs in
+**W10.** `execute.maxWrites`, default 10, bounds a program's writes in
 addition to the host-call budget. It is checked after argument validation and
 before admission, so an over-budget write spends no permit.
 
@@ -1067,14 +1070,20 @@ reconciliation. Any new call must use the original arguments when its echo is
 partial or absent. A returned `writes` count cannot make a run safe to repeat.
 See [argument echo rules](./meta-tools.md#echo-budgets) for supported schema shapes.
 
-**W12.** `trusted` endpoints annotate `execute_code` as a write and permit
-program writes. `read-only` endpoints annotate it as read-only and refuse
-program writes before validation, with `call_destructive_tool` as the recovery.
-`call_tool` accepts only reads in either tier; `call_destructive_tool` may send
-writes in either tier. Approval belongs to the host. Trust grants no tool or
-connector access and cannot be set by guest code, request arguments, or a
-downstream catalog. `execute.approval`, `Connector.approval`, and per-tool
-approval exemptions are removed. `W1`–`W8` and `W11` remain retired.
+**W12.** Writable endpoints annotate `execute_code` as a write
+(`readOnlyHint: false, destructiveHint: true`) and permit program writes and
+`call_destructive_tool`; `call_tool` still accepts only reads and refuses a write
+with `destructive_tool_requires_approval`. Read-only endpoints annotate
+`execute_code` as read-only (`readOnlyHint: true, destructiveHint: false`),
+omit write tools from `search_tools`, `connecta.search`, and
+`connecta.describe`, and refuse every write call through `call_tool`,
+`call_destructive_tool`, and programs with `read_only_endpoint` before
+validation or dispatch. Guides and skills are documentation and may still name
+those tools. `tools/list` is the same six tools on both. Approval belongs to the client.
+`readOnly` grants no tool or connector access and cannot be set by guest code,
+request arguments, or a downstream catalog. `execute.approval`,
+`Connector.approval`, per-tool approval exemptions, and pool `trust` are
+removed. `W1`–`W8` and `W11` remain retired.
 
 ## Executor exceptions
 
@@ -1225,8 +1234,8 @@ rejection, and branded adapter acceptance across module copies.
 | `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
 | `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/d1-storage.node.test.ts` (shared stash transfers), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                        |
 | `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/operator-view.test.ts`, `test/sql-storage-contract.ts`, run by `test/d1-storage.node.test.ts` and `test/sqlite-storage.node.test.ts` (historical pause and approval rows still render and round-trip)                              |
-| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited trusted-pool write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                |
-| `W10`, `W12`           | `test/program-writes.test.ts` (a trusted-pool write runs and every other write keeps `E4`, the write budget, pool trust and override precedence, `call_tool` still refusing, search and describe verdicts, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                                                             |
+| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited program write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                     |
+| `W10`, `W12`           | `test/program-writes.test.ts` (a writable endpoint's program write runs, a read-only endpoint omits writes from search and describe and refuses every write call on every path, including a write its guide names, a required deployment `readOnly`, the write budget, `readOnly` inheritance and overrides, `call_tool` still refusing, search and describe verdicts, construction refusals including retired `trust`), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                       |
 | `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                   |
 | `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
 | `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |

package/documentation/deploying.md

@@ -64,7 +64,7 @@ through to `fetch`. The example owns those details and
 
 ## Compose capabilities and access
 
-Both configurations use `defineConfig((env) => …)` and a required executor.
+Both configurations use `defineConfig((env) => …)`, a required executor, and a required `readOnly` choice.
 [Integrating services](./integrating.md) explains the `connectors` array.
 Configuration selects optional factories through explicit slots:
 
@@ -96,10 +96,15 @@ personal connection, token management, and activity access explicit.
 [Clerk setup](./auth.md#clerk-oauth-tokens-and-operator-sessions) owns resource-bound
 tokens and `aud_claim_enabled`. A person's operator session is not an MCP token.
 
-Root and named pools default to `read-only`. A `trusted` pool allows writes
-inside programs and marks `execute_code` as a write. Host approval remains the
-host's decision. Pool membership intersects the caller's grants; it never
-widens them. See [pools](./auth.md#pools) before changing trust.
+Every deployment must set `readOnly` in its configuration; startup fails without
+it, and the template and Worker example set `readOnly: false`. Each named pool
+inherits that value unless it sets its own. A writable endpoint (`false`) allows
+writes through `call_destructive_tool` and programs and marks `execute_code` as
+a write; the client decides what to approve. A read-only endpoint (`true`) omits
+write tools from search and describe and refuses every write call; provider
+guides may still name those tools. Pool membership intersects
+the caller's grants; it never widens them. See [pools](./auth.md#pools) before
+changing `readOnly`.
 
 ## Verify and diagnose
 

package/documentation/integrating.md

@@ -35,7 +35,7 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from Connecta pool trust. Read the
+read scope. That is separate from a Connecta `readOnly` endpoint. Read the
 [Linear skill](https://github.com/zackbart/connecta/blob/main/src/providers/linear/SKILL.md)
 and [factory options](https://github.com/zackbart/connecta/blob/main/src/providers/linear/index.ts)
 for API-key framing, workspace instructions, and admission choices.
@@ -49,6 +49,15 @@ mapping from admitted identity to the downstream account; a request must not
 choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
+Wispr Flow uses OAuth only through `wisprFlow()` from
+`@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
+Notetaker content, with personal and work accounts holding separate data.
+Its [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/wispr-flow/SKILL.md)
+owns account access, search limits, transcript permissions and paging. The
+reviewed classification includes task writes listed in Claude's directory even
+though Wispr's public help describes read-only access; discover the account's
+actual tools before assuming those writes exist.
+
 Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
 server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
 with an operator-managed key. Notion requires `auth` the same way:
@@ -66,6 +75,48 @@ MCP clients to its hosted server, an operational gate outside Connecta. See the
 To use both implementations of one provider, configure two connector ids with
 independent credentials.
 
+Planning Center's `excludeApps` removes whole products from a connection, for
+example `planningCenter("pco", { purpose, excludeApps: ["giving"] })` for a
+deployment that keeps agents away from donor and financial data. Excluded
+products lose their named tools, guide text, and version pins, and the
+`pco_api_get` and `pco_api_mutate` hatches refuse their paths before sending.
+The check reads the exact URL the transport would fetch, and while any product
+is excluded a hatch path must be literal: dot segments, empty segments,
+backslashes, whitespace, and percent-encoded `/`, `\`, `?`, `#`, or `%` are
+refused rather than normalized.
+
+Exclusion also closes the routes through which the excluded product's data is
+reachable through another product. While any product is excluded the connection removes
+`list_lists`, `list_list_people`, and `run_list` and refuses every People list,
+list result, rule, and condition, by path or `include`, because a list's
+conditions can draw on any product, such as a donor list built from Giving
+donations, and lists can depend on other lists. Planning Center publishes a
+list's conditions, but a reliable check would have to follow every nested list,
+so the connection does not attempt one. It refuses webhook event and delivery
+payloads, since a payload can carry any product's records, and every change to
+an existing webhook subscription by id, since the id does not name its product.
+A new subscription must name a reachable product's event. People cannot be
+excluded.
+
+What exclusion guarantees is that agents reach none of the excluded product's
+endpoints, no live cross-product query such as a People list, and no webhook
+payload or change to an existing subscription. It does not hide records that the church's own
+automations or staff have copied into a reachable product. A
+[Giving automation](https://help.planningcenter.com/en/144355-automations-in-giving.html)
+can add first-time donors to a People workflow, and those workflow cards stay
+readable, as do donor details recorded in notes, custom fields, or form
+answers. Those are People data once written, so the connection does not refuse
+them by guessing at their origin.
+
+For a hard boundary, give the connection a personal access token belonging to a
+Planning Center user with No Access in the excluded product. Planning Center
+sets permissions per product for each user, does not grant Giving to
+organization administrators automatically, and lets People workflows be shared
+per workflow; a token carries its user's permissions, so Planning Center itself
+refuses what that user cannot see. `excludeApps` is defense in depth on top of
+that boundary: it narrows what Connecta exposes, not what the token can do
+elsewhere.
+
 ## Another remote MCP server
 
 Declare its endpoint and intended auth mode. This fragment uses a server-stored
@@ -137,9 +188,10 @@ which binds the grant to configured API origins and manages authentication.
 [Downstream OAuth on api()](./auth.md#downstream-oauth-on-api) owns a concrete
 HTTP example and the client setup contract.
 
-Mark every side-effecting tool `readOnlyHint: false`. On read-only endpoints
-writes use `call_destructive_tool`; trusted programs may write within their
-grants. Host approval is independent of tool definition. Use declared output
+Mark every side-effecting tool `readOnlyHint: false`. On a writable endpoint
+writes use `call_destructive_tool` or a program, within the caller's grants; a
+`readOnly` endpoint refuses them and omits them from search. Client approval is independent of
+tool definition. Use declared output
 schemas when known; runtime observations cannot replace them.
 
 ## Separate ownership from visibility

package/documentation/meta-tools.md

@@ -2,7 +2,7 @@
 
 Connecta keeps one small tool surface in model context and resolves downstream
 tools behind it. `search_tools` finds addresses, the call tools enforce the
-stored classification, `execute_code` runs programs under pool trust, and `connecta.result` inside programs
+stored classification, `execute_code` runs programs on a writable or read-only endpoint, and `connecta.result` inside programs
 pages bounded results.
 
 This guide is the contract an MCP client sees. The in-program `connecta.*` API
@@ -31,10 +31,13 @@ configuration adds a seventh or removes one, so a client's cached tool list
 never depends on the storage behind the deployment. There was an eighth,
 `resume_execution`, while programs paused at writes; it left with pausing
 ([#672](https://github.com/zackbart/connecta/issues/672)). `execute_code`
-is annotated `readOnlyHint: true, destructiveHint: false` on a `read-only`
-endpoint, and `readOnlyHint: false, destructiveHint: true` on a `trusted`
-endpoint. Approval belongs to the host. Pool trust never changes connector
-visibility or tool grants. The four tools with structured-only success results
+is annotated `readOnlyHint: true, destructiveHint: false` on a read-only
+endpoint, and `readOnlyHint: false, destructiveHint: true` on a writable one.
+Approval belongs to the client. A read-only endpoint keeps all six tools, omits
+write tools from `search_tools` results and describe, and refuses every write
+call; `readOnly` never changes connector visibility or read grants. Guides
+(`queryAnalysis.guideSummary`, `skills`, `connecta.skill`, skill
+`resources/read`) are documentation and may name tools the endpoint refuses. The four tools with structured-only success results
 advertise `outputSchema`. The two direct-call tools omit it because their default
 mode returns native `content`. Default-mode successes declare
 `_meta["dev.connecta/format"]: "json" | "text"`; value mode places the value in
@@ -70,9 +73,11 @@ credentials, logs, or raw error text.
 
 Connecta's discovery tools carry read-only hints. `authorize_connector`
 requests interactive authentication changes; `call_destructive_tool` sends
-writes and is annotated destructive. `execute_code` reports the selected pool's
-trust in its description and annotations. Its host may approve the whole
-program on a trusted endpoint. `call_destructive_tool.reason` is dropped before
+writes and is annotated destructive. `execute_code` states whether the endpoint
+is read-only or writable in its description and annotations. On a writable
+endpoint the client may approve the whole program as a write. On a read-only
+endpoint, the `call_tool`, `call_destructive_tool`, and `search_tools`
+descriptions say so too; `call_destructive_tool` still runs reads there. `call_destructive_tool.reason` is dropped before
 anything runs.
 
 ## Routing between the call surfaces
@@ -93,12 +98,16 @@ page the completed direct-call result or oversized program return with
 `connecta.result` after the write runs once. Sampling or slicing a write's output
 inside the program can still discard the answer.
 
-A `trusted` pool lets the same program discover and dispatch writes.
-A `read-only` pool refuses writes before validation or dispatch with
-`destructive_tool_requires_approval` and a `nextAction` naming
-`call_destructive_tool` and the canonical address. Each write then uses its
-own top-level call. Connecta never pauses, replays, or approves a program.
-Top-level discovery remains available for catalog inspection and write routing.
+On a writable endpoint the same program discovers and dispatches writes, capped
+by `execute.maxWrites`, and `call_destructive_tool` sends one known write. On a
+read-only endpoint nothing writes: `search_tools`, `connecta.search`, and
+`connecta.describe` omit write tools as if the connector lacked them, and
+every write call through `call_tool`, `call_destructive_tool`, or a program is
+refused before validation or dispatch with `read_only_endpoint`,
+`retryable: false`, and no `nextAction`. Connector guides are not filtered and
+may still name such a write. No route on that endpoint writes; the agent
+reports it. Connecta
+never pauses, replays, or approves a program.
 
 Both search routes return the flat page specified under
 [lexical discovery](#lexical-discovery), using the catalog's shared output schema.
@@ -129,14 +138,14 @@ Read-only lookup belongs in `connecta.search` inside the program; top-level
 `search_tools` stays for explicit catalog inspection and approval-required
 discovery. Both take the same arguments.
 
-| Argument           | What it does                                                                                                                                                                                                                                                            |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `query`            | two to four action/object terms; empty or whitespace-only browses                                                                                                                                                                                                       |
-| `connector`        | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous                                                                        |
-| `safety`           | `"readOnly"` selects stored `read` verdicts; `"approvalRequired"` selects stored `write` verdicts; omitted or `"all"` selects both. Each row carries `classification: "read" \| "write"`. These legacy filter names do not describe host approval policy or pool trust. |
-| `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small                                                                                                                                                                            |
-| `includeSchemas`   | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures))                                                                                                                     |
-| `fullDescriptions` | unabridged tool purposes, at the obvious cost                                                                                                                                                                                                                           |
+| Argument           | What it does                                                                                                                                                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`            | two to four action/object terms; empty or whitespace-only browses                                                                                                                                                                                                                                   |
+| `connector`        | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous                                                                                                    |
+| `safety`           | `"readOnly"` selects stored `read` verdicts; `"approvalRequired"` selects stored `write` verdicts; omitted or `"all"` selects both. Each row carries `classification: "read" \| "write"`. These legacy filter names do not describe client approval policy; a read-only endpoint has no write rows. |
+| `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small                                                                                                                                                                                                        |
+| `includeSchemas`   | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures))                                                                                                                                                 |
+| `fullDescriptions` | unabridged tool purposes, at the obvious cost                                                                                                                                                                                                                                                       |
 
 Neither `connector` nor `safety` grants authority or changes invocation
 admission; they select what discovery shows and nothing else.
@@ -381,7 +390,7 @@ caught catalog-load errors, unknown-tool failures, and recovery messages that
 list visible connectors or local guides. Returns with no downstream calls still
 require matching identity, origin and endpoint, current auth, and pool membership. A page must
 match those bindings and pass current auth, connector/tool grants, pool membership,
-and trust checks. Old entries lacking bindings fail closed. A random UUID is a
+and read-only checks. Old entries lacking bindings fail closed. A random UUID is a
 handle, never an access grant.
 
 New entries store UTF-8 bytes in a base64 envelope split across storage keys,
@@ -512,13 +521,10 @@ format: "text", text }`. The page size is clamped to the original call's inline
 cap and a 32 KiB program bridge ceiling, with UTF-8 alignment and forward progress. Reassemble inside the sandbox;
 returning pages unchanged can hit the program result cap. The admitted subject
 and principal, endpoint/pool, request origin, connector, and tool bindings must
-match. The host rechecks current access and trust before returning each page; a
-read-only endpoint cannot read a write stash. Caller arguments select no partition.
-
-A write on a read-only endpoint returns an inline truncation notice and any
-usable bounded preview. It says paging is unavailable and the write already
-ran; it carries no result handle or recovery action and stores no unreachable
-stash. Write paging remains available on trusted endpoints.
+match. The host rechecks current access and whether the endpoint is read-only
+before returning each page; a read-only endpoint cannot read a write stash.
+Caller arguments select no partition. A read-only endpoint never runs a write,
+so every write result it could page came from a writable endpoint.
 
 A refused stash write cannot undo a downstream success. Direct calls and program returns produce
 a paging-unavailable notice, without a handle or recovery action. A write's
@@ -820,10 +826,11 @@ attempted tool name; an unknown tool scopes the same query to the connector that
 answered. The suggested route follows the route the caller took:
 `tool: "search_tools"` for a top-level call, `function: "connecta.search"` with
 the same arguments when the miss happened inside `execute_code`, which has no
-way to call a tool. `call_tool` reaching an unannotated, write-capable, or
-destructive tool returns `nextAction` for `call_destructive_tool` with the
-canonical address, and so does the same call inside a program, unless config
-marks that pool trusted. Nothing is executed by these records.
+way to call a tool. On a writable endpoint, `call_tool` reaching an unannotated,
+write-capable, or destructive tool returns `destructive_tool_requires_approval`
+with `nextAction` for `call_destructive_tool` and the canonical address. On a
+read-only endpoint every write path returns `read_only_endpoint` with no
+`nextAction`. Nothing is executed by these records.
 
 `connecta.describe` keeps its failures inline instead, so one miss cannot
 discard the other schemas; each failed entry carries a human `error`, typed
@@ -932,12 +939,12 @@ original arguments cannot repeat the write while the vendor retains the key
 (Stripe may prune v1 keys after 24 hours). After that, look the object up before
 retrying. When a connector recorded such facts, any other dispatched write whose
 outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
-with them under its own code, and trusted-program write accounting keeps it. `args` may be partial reconciliation context
+with them under its own code, and program write accounting keeps it. `args` may be partial reconciliation context
 with `argsRedacted: true`. A withheld echo or arguments over the 512-byte budget
 carry `argsOmitted: true`; sensitive or unresolved schemas also carry
 `argsRedacted: true`. When `args` is absent or redacted, use the original
-arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`. Trusted
-program write accounting keeps this detail even if the guest catches the
+arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`.
+Program write accounting keeps this detail even if the guest catches the
 failure or returns early. Multiple uncertain writes use `uncertainCalls`,
 bounded to ten calls with `uncertainCallsTruncated` when more exist.