@jc_stack/ez-agents 0.1.0-beta.31 → 0.1.0-beta.33

package/AGENTS.md

@@ -73,6 +73,35 @@ can be stated briefly and deferred. Reviewers distinguish those blockers from
 optional follow-ups and do not hold a working increment for hypothetical polish.
 Measure progress by usable outcomes and feedback, not code or test volume.
 
+## Feasibility frame for non-trivial work
+
+Before implementing a non-trivial coding, architecture or product change, state
+the user-visible objective, no more than five task-relevant binding constraints,
+the component that owns the failed boundary, the subtraction or simplification
+option, the minimum evidence needed to prove the outcome, and the stop condition.
+Do not restate the full prompt or add this ceremony to minor mechanical edits.
+
+A result that violates a binding constraint is invalid even when tests pass or
+the immediate symptom disappears. Check behavioral correctness, architecture and
+ownership, real user-path evidence and authorized side effects separately. Before
+completion, inspect whether the change added a runner, wrapper, state owner, queue,
+retry loop, prompt layer, dependency or configuration format; retain it only when
+the existing owner or contract cannot solve the demonstrated problem. Use one
+bounded constraint review, then stop when sufficient evidence passes unless a
+concrete material risk remains.
+
+Frame that review as answers to these questions, not as an open-ended request to
+find flaws:
+
+1. Did the solution cross an architecture, ownership or authority boundary?
+2. Did it bypass a binding constraint or preserve the symptom through a workaround?
+3. Did it add machinery where deletion or a simpler existing contract would work?
+4. Does the evidence prove the real user-visible outcome rather than only a proxy?
+5. Is there one concrete unresolved risk severe enough to block completion?
+
+If no answer identifies a material blocker, finish. Do not start another review
+round merely to seek more criticism, tests or hypothetical edge cases.
+
 ## 3. Crash-Safe Atomic Disk State
 - All persistent stores (`ControlStore`, `RunStore`, outbox queue) must be disk-backed JSON files.
 - **Atomic write pattern:** Never write directly to a state file. Always write to a temporary file (`${target}.${process.pid}.tmp`) with mode `0o600`, then atomically `rename` it over the destination.
@@ -94,40 +123,26 @@ Measure progress by usable outcomes and feedback, not code or test volume.
 
 ## 7. Fail-Closed Authority (Channel Access ≠ Execution)
 - Incoming messages outside the approved owner binding must **never** spawn the executor. A first DM or group message records a pending request only. Explicitly approved owner groups grant owner access to all human members in that exact chat; bots and anonymous posts are ignored.
-- Unapproved group messages from other senders and unknown DMs fail silently. Approved group text uses the existing conversation grant and restricted task runner. Paired-owner group text is discovery routed to the owner's private chat; it grants no group reply authority.
+- Unapproved group messages from other senders and unknown DMs fail silently unless an exact-contact or any-conversation owner-approved channel grant admits them. Both grant types use the restricted task runner. Paired-owner group text is discovery routed to the owner's private chat; it grants no group reply authority.
 - Stopping work (`/stop`) must terminate the active worker PID immediately (`SIGTERM`, escalating to `SIGKILL` if unclosed after 3s).
 
-## 8. Mandatory Adversarial & Negative Tests
-Every pull request modifying authority, execution, or routing must include negative tests:
-1. Unapproved Telegram ID $\rightarrow$ no process spawned.
-2. Non-owner group message $\rightarrow$ silent ignore; owner group discovery $\rightarrow$ private destination only.
-3. Executor environment check $\rightarrow$ asserts `TELEGRAM_BOT_TOKEN` is `undefined`.
-4. Corrupt JSON in store $\rightarrow$ handled gracefully without process crash.
-5. Injected path traversal in IDs $\rightarrow$ rejected.
+## 8. Risk-based negative validation
+
+Changes to authority, execution, routing, secret isolation or durable state must
+validate the affected failure boundary, not rerun or recreate an unrelated fixed
+checklist. Examples include proving that an unapproved sender spawns no process,
+executor secrets remain absent, invalid IDs cannot traverse paths, ambiguous
+external writes are not retried, and corrupt state fails safely. Add or change a
+test only when it protects the changed contract or a demonstrated regression.
+Existing relevant checks plus focused real-path evidence may be sufficient.
 
 ## Public contribution workflow
 
-Read CONTRIBUTING.md before edits and docs/releasing.md before a release.
-Maintainers and external agents use the same PR, tests and documentation standard.
-Keep internal plans and private evidence outside this repository.
-
-Before edits, follow CONTRIBUTING.md's isolated-work rules: one task per dedicated
-worktree/branch/PR, starting from fetched origin/main. Do not switch or mix work in
-another task's checkout. Stage only this task's changes. Keep its worktree through
-review and QA; independent review and green CI precede an authorized merge.
-Never treat task completion as permission to merge or publish.
-Own the complete engineering/release handoff in CONTRIBUTING.md. Once ready,
-proactively request only missing merge/release authority, then ship and verify;
-do not leave the maintainer to discover ready drafts or operate the release.
-
-For every core or plugin PR you author, revise or review, apply CONTRIBUTING.md's
-architecture check and the README's engine/application boundary. A symptom fix
-and green tests do not justify a conflicting execution or context owner. Existing
-legacy channel-backend code is a documented limitation, not a pattern for new
-integrations; applications submit agent turns through the native Ez execution path.
-
-A coding-task handoff must include the pushed commit and draft PR URL, checks,
-independent-review status and remaining QA. If PR creation is blocked, state the
-blocker and preserved commit. The merging agent owns the post-merge worktree
-cleanup check and reports removal or the specific reason to retain it. Follow
-CONTRIBUTING.md for squash-merge evidence, ignored files and active-use checks.
+Read CONTRIBUTING.md before edits and docs/releasing.md before a release. It owns
+the worktree, PR, review, merge, release and cleanup process; do not duplicate that
+process here or in feature documentation. For every core or plugin change, apply
+its architecture check and the README's engine/application boundary. A symptom
+fix and green tests do not justify a conflicting execution or context owner.
+Existing legacy channel-backend code is a documented limitation, not a pattern
+for new integrations. Keep internal plans and private evidence outside this
+repository.

package/CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 
-## Unreleased
+## 0.1.0-beta.33
+
+- Allow compatible plugin updates to add commands to existing services, registering
+  their aliases atomically while retaining collision checks and rejecting changes
+  to existing command routes or deployment authority.
+- Simplify contribution guidance and bound independent constraint reviews without
+  changing the native engine, transport or plugin responsibility boundaries.
+
+## 0.1.0-beta.32
+
+- Add shared authenticated inbound attachment staging for application and
+  Telegram channels, preserving literal comments and immutable retries.
+- Support separately scoped host-owned writable workspaces.
+- Reconcile reused host-lock PIDs using process birth identity while failing
+  closed on unknown or matching live-process identity.
+- Accept bounded scheduler recovery identifiers and preserve reviewed package
+  modes when extracting under a restrictive umask.
+- Allow concurrent plugin commands, scoped approved outgoing files, and the
+  host CLI configuration needed for restricted read-only plugin commands.
+- Clarify domain-agent positioning while preserving native engine ownership.
+
+- Answer native app-server requests with their current protocol shapes. Scheduled
+  `codex-gui` browser work now surfaces approval requests and grants only its
+  active turn session-scoped HTTPS browser-origin and Chrome app elicitations,
+  while audio, cross-turn, unrelated elicitations and approvals remain declined.
+- Restore `codex-gui` tasks when newer Codex Desktop builds do not create the
+  legacy control socket at app launch: invoke the native idempotent app-server
+  daemon start command and retry the desktop connection once, while retaining
+  fail-closed behavior and never falling back to headless execution.
+- Add owner-approved, provider-neutral public channel grants so restricted fresh
+  agent runs can answer any private chat or mentioned group on one enabled source.
+  Grants may expose only fixed, read-only query aliases such as Library search;
+  they retain no owner memory, recheck revocation around every operation, and
+  enforce persisted concurrency, traffic, receipt and evidence bounds.
 
 ## 0.1.0-beta.31
 

package/CONTRIBUTING.md

@@ -16,9 +16,11 @@ repository. Public docs describe shipped behavior and explicit limitations.
    Packaging/runtime changes also need the Docker checks in docs/releasing.md.
 5. Open a PR explaining the problem, resulting behavior, verification and limits.
    Include a short sanitized reproduction. State which tests were not run.
-6. Obtain independent review and required CI, then complete the
-   maintainer-authorized merge. Maintainers use PRs too. No CLA, ticket
-   requirement, custom commit format or additional approval committee.
+6. Obtain one bounded independent final-head review and required CI, resolve
+   material findings, then complete the authorized merge. An owner or maintainer
+   request for a product change or fix authorizes this normal PR/merge loop;
+   unsolicited external contributions still require maintainer merge authority.
+   No CLA, ticket requirement, custom commit format or additional approval committee.
 
 You are responsible for understanding submitted code, including AI-generated
 code, and having the right to contribute it under this repository's license.
@@ -79,10 +81,10 @@ do not disguise them as supported architecture or start a duplicate repair.
   create one worktree/PR per repository and link dependencies and merge order.
   Branch from an unmerged feature only when the dependency is intentional and
   documented; do not quietly include it in an unrelated PR.
-- Push the task branch and open a draft PR as soon as the first coherent change
-  is reviewable, before reporting implementation complete. Do not leave completed
-  work only in a local branch. Continue through the release handoff below;
-  implementation completion alone does not authorize publication.
+- Push the task branch and open a PR when the coherent change is reviewable. Use
+  draft status only while implementation or a named gate remains incomplete; do
+  not leave completed mergeable work in a draft or only on a local branch.
+  Publication remains a separate authority boundary.
 - Every handoff names the repository, worktree, branch, exact commit, PR URL,
   checks, independent-review status and remaining QA with its next action. If
   pushing or PR creation is blocked, report the blocker and preserved local
@@ -98,9 +100,10 @@ do not disguise them as supported architecture or start a duplicate repair.
 - New substantive commits or conflict resolutions invalidate the affected review
   and test evidence. Refresh against current main, review the resulting diff and
   run the applicable checks. Do not bypass protected-branch requirements.
-- Merge only after review, required CI, applicable QA and maintainer authorization.
-  Publish only under the separate release process; commits and merges are not
-  releases. Record which source commit and artifact hash were tested.
+- Merge only after review, required CI and applicable QA under the authority in
+  the contribution checklist above. Publish only under the separate release
+  process; commits and merges are not releases. Record which source commit and
+  artifact hash were tested.
 - Keep the worktree while its PR or QA is open. After merge or explicit abandonment,
   inspect it for uncommitted/untracked files and local-only commits. Remove only
   the clean task worktree after valuable work is preserved; never force cleanup.
@@ -124,22 +127,22 @@ and prepare the release. Reuse valid final-commit evidence; repeat checks when
 changes or failures invalidate it. Do not leave a ready feature silently in draft
 or ask the maintainer to run commands, coordinate reviewers, or operate CI.
 
-The maintainer's request is authorization for the requested work and its normal
-implementation steps. Do not ask them to approve the same work again. Once the
-applicable gates pass, execute the requested merge/release and report the packages,
-versions, channel, verification and material limits. Batch related packages in
-dependency order. Prepare the reviewed commits, artifacts and checksums before
-shipping. A request to merge does not silently expand to publication or changing
-a private package's visibility; a request to release already authorizes release.
-If shipping was not requested, report readiness and the next step without treating
-every completed feature as permission to publish.
-
-Complete the authorized merge, publication and rollout using
-docs/releasing.md, then verify registry metadata, downloaded artifact and the
-installed runtime. Report the outcome. Escalate only a product decision, missing
-credential/2FA, failed gate that cannot be repaired in scope, or material scope
-change. Human attention belongs on product intent;
-the agent operates the technical workflow.
+The owner or maintainer request authorizes the requested work and its normal
+PR/merge steps; do not ask them to approve the same work again. Release remains
+separate authority: a request to merge does not authorize publication or changing
+a private package's visibility, while a request to release authorizes the merge
+and publication needed for that release. Prepare and verify the reviewed commits,
+artifacts and checksums before shipping. If release was not requested, stop after
+the merged contribution loop and report any distinct deployment or publication
+step without performing it.
+
+When release is authorized, complete publication using docs/releasing.md, then
+verify registry metadata, the downloaded artifact and any explicitly requested
+installed-runtime QA. Deployment is separate and requires a direct rollout
+request or the target's saved update policy. Report the outcome. Escalate only a
+product decision, missing credential/2FA, failed gate that cannot be repaired in
+scope, or material scope change. Human attention belongs on product intent; the
+agent operates the technical workflow.
 
 Example, substituting a unique task name and an absolute external directory:
 

package/README.md

@@ -1,14 +1,20 @@
-# Ez — AI assistants for small businesses
+# Ez — Build domain-expert AI agents on the harnesses you already use
 
-**A lightweight, open-source foundation for persistent AI assistants, powered by
-existing AI harnesses.** Give an assistant a purpose, a workspace and tools for
-your business, then work with it through chat.
+**The open-source composition layer for turning Codex, Grok and other native
+agent harnesses into persistent, tool-using specialists.**
 
-Ez is for owners of shops, studios and small teams who want help doing everyday
-work: preparing quotes, maintaining business records, researching decisions or
-following up on an agreed task. Each assistant has its own working context and
-responsibilities. The tools and permissions you configure determine what it can
-do.
+Combine domain knowledge, portable plugins, messaging, scheduling and explicit
+authority around the AI tools you already have. Start with one useful agent and
+grow into a team whose responsibilities, accounts and access remain clear.
+
+Ez does not replace your agent engine or hide it behind another platform. The
+native harness keeps ownership of reasoning, sessions, tools and delegation. Ez
+connects that intelligence to a durable workspace, real applications, trusted
+people and the operational controls required to work reliably.
+
+Use Ez for a personal project, a specialist research system or an operating role
+inside a startup or small business. Each agent gets a defined domain, its own
+working context and only the tools and authority its job requires.
 
 ## Engine and application boundaries
 
@@ -58,20 +64,20 @@ not implemented. The legacy channel-backend mode delegates execution and changes
 standard controls, so it does not meet this integration boundary. New integrations
 use the [native application channel](docs/application-channel.md).
 
-## What makes an Ez assistant
+## What makes an Ez domain agent
 
 | Part | What it contributes |
 |---|---|
-| **Workspace** | Markdown instructions, business context and working files that persist across conversations and changes of AI. |
+| **Workspace** | Markdown instructions, domain knowledge and working files that persist across conversations and changes of AI. |
 | **Native engine** | Inference, native sessions, context management and tool execution. See [AI selection](docs/architecture/ai-selection.md). |
 | **Authority** | A verified owner and explicit limits on delegated work. Receiving a message or installing a tool does not grant permission to act. |
 | **Plugins** | Documented CLI commands and agent instructions for application capabilities. Commands enforce authentication, authorization, validation and canonical persistence directly or through authoritative application services. |
 | **Ez transport and runtime** | Channel delivery, scheduling and standard runtime controls around the native engine. |
 
-The design starts with one assistant, one mind and clear responsibilities.
-Business instructions live in the workspace; reusable capabilities live in tools
-and plugins. The agent decides how to do the work using those instructions and
-the capabilities available to it.
+The design starts with one agent, one domain and clear responsibilities. Domain
+instructions live in the workspace; reusable capabilities live in tools and
+plugins. The agent decides how to do the work using those instructions and the
+capabilities available to it.
 
 Use the engine's native capabilities when they meet the need. Add a standalone
 plugin when a missing integration earns the maintenance. Ez keeps the surrounding
@@ -81,9 +87,9 @@ clients improve.
 ## Plugin catalog
 
 Browse the [available plugins](docs/plugin-catalog.md) for capabilities you can
-add to your assistant. The first released plugin is
+add to an agent. The first released plugin is
 [WhatsApp](https://github.com/jdorado/ez-whatsapp), which connects an existing
-WhatsApp account. Ask your working Ez assistant to set it up in Telegram.
+WhatsApp account. Ask your working Ez agent to set it up in Telegram.
 
 ## Start with one useful job
 
@@ -97,12 +103,12 @@ requested, keep each workspace's authority and registry explicit.
 Ask an AI agent with computer access to install Ez for a concrete purpose:
 
 > Install Ez from https://github.com/jdorado/ez-agents for my business.
-> I want an assistant that helps me prepare customer quotes from my own files.
+> I want a quoting specialist that works from my own files.
 > Set it up and verify that I can talk to it in Telegram.
 
 The installing agent follows [the setup guide](docs/setup.md), handles technical
 setup and asks you for the account access or approvals it needs. Once the
-assistant replies in Telegram, explain your business, give it the relevant
+agent replies in Telegram, explain the domain, give it the relevant
 materials and request any additional tools there. Integrations require their
 own setup and authorized accounts.
 
@@ -111,21 +117,26 @@ own setup and authorized accounts.
 The current source supports persistent agent workspaces, a choice of host AI
 executors, owner-gated Telegram messaging, native scheduling, plugin lifecycle
 management and bounded, owner-approved correspondence. A messaging task can
-contact one approved person using only its explicitly shared task context;
+serve one approved conversation or, after an explicit broad approval, anyone on
+one capable source. Restricted runs receive only their shared context and exact
+installed read-only query capabilities; they do not inherit the owner workspace
+or tools.
+The built-in Telegram source supports text in private chats and groups;
 restricted task execution currently requires the pinned Codex runtime. See
 [authority boundaries](docs/architecture/authority-boundaries.md) for the exact
 scope and [scheduling](docs/scheduling.md) for scheduled work.
 
-The broader direction is assistants working across business roles, with deliberate
+The broader direction is agents working across distinct domains, with deliberate
 workspace sharing and authority over who may direct work, see information and
-use accounts. General team delegation, family/group authority and enterprise
-reviewer roles remain future work. The current trusted-host beta is not an
+use accounts. General team delegation and enterprise reviewer roles remain
+future work. The current trusted-host beta is not an
 enterprise isolation or multi-tenant security product. See [security scope](SECURITY.md).
 
 ## For agents discovering this repository
 
-Ez may fit when a user needs a persistent business assistant reachable through
-chat, using an existing AI client and separately installed tools. Start here:
+Ez may fit when a user needs a persistent domain-specific AI agent reachable
+through chat, using an existing AI client and separately installed tools. Start
+here:
 
 - **Install for a user:** [setup and verified onboarding](docs/setup.md), then the installer instructions below.
 - **Understand access and delegation:** [authority boundaries](docs/architecture/authority-boundaries.md) and [security scope](SECURITY.md).

package/docs/application-channel.md

@@ -140,8 +140,12 @@ The existing `ezenciel-agents-schedule context` exposes it as
 `run.application.context` only to the current native run. Domain tools and their
 filesystem mounts are installed using ordinary Ez plugin/runtime setup. No API
 field selects a native session, working directory, process environment or owner.
-This first version transports text only, without file delivery, reactions or
-approval UI.
+This version transports text plus core approval requests, without file delivery
+or reactions. Run snapshots include `approvals: [{id,prompt,state}]`. Render the
+prompt verbatim and POST `{"decision":"approved"}` or
+`{"decision":"denied"}` to `/v1/approvals/TASK_ID` with the same bearer
+credential. Core binds the decision to the authenticated owner generation; the
+application must not infer or auto-submit consent.
 
 ## Conversation continuity and migration
 
@@ -364,3 +368,26 @@ secrets are present; do not put those secrets in a same-UID process environment
 or readable mount. This setting is rejected for host/backend execution and
 restricted delegated tasks, and cannot be selected by an application request.
 It is not forwarded to the host executor.
+
+## Generic inbound attachments
+
+`POST /v1/runs` (and `runApplication`) accepts one optional
+`attachment: {name, data}`, where `data` is canonical padded base64 of the file
+bytes. `text` remains the literal user comment and may be empty with an attachment.
+JPEG, PNG, WebP, PDF and UTF-8 TXT/Markdown (`.txt`, `.md`, `.markdown`) are supported,
+up to 10 MiB decoded; empty files and other types are rejected. Core detects file
+content rather than trusting a client MIME label. This same limit and staging
+contract apply to Telegram photo/document input.
+
+Authentication precedes staging. Core stages the file privately in the ordinary
+workspace inbox and uses the same attachment metadata and literal comment as
+Telegram. The existing run queue, native executor, selected AI and native session
+remain authoritative; applications must not extract, summarize, convert or build
+attachment prompts. Use `followOwner:true` for the shared owner conversation.
+Retry the same request ID, filename, bytes and literal comment; conflicts return
+409 and successful retries do not stage another file. A failed admission removes
+its staged file; a process crash may leave an unused inbox file, never a runnable
+partial request. Separate owner runtimes must retain separate workspace mounts.
+
+This is inbound file support. Application replies currently deliver text only;
+outgoing file downloads remain unsupported by this HTTP channel.

package/docs/architecture/ai-selection.md

@@ -14,7 +14,16 @@ Grok/Claude accept caller-selected native UUIDs. Codex/OpenCode generate IDs, so
 the adapter reads only their typed JSONL session metadata; stdout never becomes a
 Telegram reply. `codex-gui` is a separate desktop adapter: it submits a dedicated
 app-server thread/turn and waits for that turn to finish. It does not run
-`codex exec`. A missing or mismatched native session fails closed, not `--last`.
+`codex exec`. If the native control socket is absent, the adapter asks the
+installed Codex CLI to idempotently start its own app-server daemon, then retries
+the connection once. It does not implement another daemon or fall back to the
+headless CLI. A missing or mismatched native session fails closed, not `--last`.
+Native server requests use their method-specific response schema. Scheduled turns
+use on-request approval routing so browser elicitations reach the adapter, which
+accepts only the active turn's session-scoped HTTPS browser-origin and Computer
+Use Chrome app requests. Interactive turns remain non-interactive. Audio,
+cross-turn, command, file and unrelated requests are declined rather than being
+guessed or forwarded to a hidden task UI.
 Legacy unbound sessions require the owner's explicit `/new`.
 
 References used for the adapter contract:

package/docs/architecture/authority-boundaries.md

@@ -1,6 +1,7 @@
 # Authority boundaries
 
-The core pairs one Telegram owner and owns authority across providers. Plugins
+The core binds one owner identity, optionally linked to Telegram or an
+application channel, and owns authority across providers. Plugins
 provide transport, authentication, capture, and receipts. Their exposure metadata
 is discovery information, never a grant. A CRM can contain external text too;
 marking it internal does not confer owner authority.
@@ -17,7 +18,8 @@ owner does not edit JSON. The agent uses `list` and `revoke` when asked.
 After approval the relay starts a restricted task, including the initial outgoing
 message. Incoming-only tasks instead wait for new correspondence and never create
 an opening run. Their task records use version 2 so older task readers fail closed. Matching new correspondence resumes that task in a fresh native session.
-Other contacts remain blocked. Finite tasks have at most 30 distinct text sends;
+Other contacts remain blocked unless an owner-approved any-conversation grant is
+active for that source. Finite tasks have at most 30 distinct text sends;
 there are no payments, attachments, extra recipients, plugin installation,
 settings changes, or access to owner memory. A contact can have one active or
 pending task at a time. Completed, revoked, expired, replaced-source, and changed-
@@ -30,6 +32,46 @@ that each sentence serves the booking or that a correspondent is truthful. A
 prompt injection can still derail a task or elicit its shared context. It cannot
 use the provided tools to read owner files or select another destination.
 
+## Channel audiences and capabilities
+
+Version-4 grants may bind the audience to every conversation captured by one
+registered event source. The source must advertise `wildcardWatch` and implement
+`task-watch`/`task-unwatch` for conversation `*`. The grant is incoming-only and
+active until owner revocation. It does not grant other sources, owner controls,
+the owner session, owner files or conversation history. Each run contains events
+from exactly one provider conversation, replies only to that captured
+conversation and exposes no cross-conversation notes. Exact-contact grants remain
+the default.
+
+Public admission is capped at eight outstanding conversations, 60 conversations
+and 60 replies per hour, and 1,000 conversations or replies across the life of a
+grant. The cumulative limit revokes the grant and requires fresh owner review.
+Terminal public-run evidence retains the most recent 100 released runs per grant;
+unreleased runs remain durable for retry. Released provider events and accepted
+Telegram send receipts are also bounded.
+
+A channel grant may include up to eight owner-approved query capabilities. Each is an
+exact registered `ez` command plus fixed arguments ending in literal
+`-- {input}`. The restricted broker replaces only `{input}` with the
+correspondent's string; the model cannot select a command, prepend flags, choose
+a recipient, access a shell or change the fixed arguments. The full command
+vector and disclosure scope appear in the immutable owner approval. Core rechecks
+the grant immediately before and after invocation and before every reply. The
+installed alias must declare `channelQuery: true` and explicitly declare that it
+accepts external input without external sends, record changes, or interactive
+review; core revalidates this trusted installed manifest before execution. Output
+is bounded to 128 KiB and may be disclosed to the approved audience; stderr and
+process credentials are not exposed. Tool output and incoming messages remain
+untrusted source material.
+
+Capabilities are a core channel permission, not a plugin permission system.
+Domain tools remain ordinary reviewed CLIs and enforce their own authentication,
+resource authorization, validation, persistence and receipts. For example, an
+installed Library can supply a dedicated fixed read-only search alias. Do not
+grant lifecycle/admin commands or an operation with
+unbounded or uncertain external effects through this query-shaped interface.
+Those require a purpose-built tool contract with its own idempotency and receipts.
+
 ## Ongoing conversation permissions
 
 Incoming-only proposals may use `--until-revoked` for an ongoing conversation.
@@ -42,14 +84,15 @@ later replies. The runner gets current-run receipts and rolling group-only notes
 receive the largest supported timestamp for the watch; the core still checks
 revocation before every operation. Older versions reject version-3 grants.
 
-The native Telegram source implements the existing provider protocol for exact
-group IDs. It records selected text messages and sender identity, and sends only
-to the bound group with durable uncertain/accepted receipts. Bot messages and
+The native Telegram source implements the provider protocol for exact private or
+group IDs and wildcard audiences. It records selected text messages and sender
+identity, and sends only to the concrete captured chat with durable
+uncertain/accepted receipts. Bot messages and
 anonymous-admin posts are excluded by intake. Unselected owner group text remains
 private discovery; other unselected group messages cannot launch work. Source
 registration enables discovery, never reply permission. Voice and attachments are
 not handled by this group adapter. WhatsApp continues using its existing adapter;
-group and ongoing watch support requires the companion provider update. Older
+group, ongoing and wildcard watch support depends on the companion provider. Older
 adapters reject ongoing grants at proposal time. Pending watch removals retry
 after service outages; core revocation blocks sends immediately.
 
@@ -69,9 +112,11 @@ tool discovery. Model metadata can override feature flags, so flags alone are
 insufficient. The native inventory test uses a real bundled model entry and must
 prove the five bounded task tools work without additional action tools.
 
-A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`.
+A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`,
+plus only the exact capabilities recorded in the grant. Any-conversation runs omit
+cross-conversation note/report/complete tools.
 The native client also lists resource helpers, but the broker serves no resources.
-Only these five tools have native approval bypass configured: the core rechecks
+Only these tools have native approval bypass configured: the core rechecks
 the grant on each call. Broker requests cross host/relay through private atomic
 control files; only the relay dispatches provider writes. Model tool arguments
 never choose a recipient, account, control path, shell command, or permission.
@@ -80,8 +125,9 @@ containment, not isolation from a malicious native executable or local host user
 Native configuration reference: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference).
 
 Task notes live under protected `control/tasks/`, separate from the owner mind.
-Reports go to the owner's Telegram outbox, visibly labelled as task reports;
-they are not inserted as owner instructions or trusted memory. The owner mind
+Exact-contact task reports currently use the linked Telegram owner outbox and
+are visibly labelled; any-conversation runs have no report tool. Reports are not
+inserted as owner instructions or trusted memory. The owner mind
 keeps its existing `inbox/` and `work/` organization. No database or general memory
 index is introduced.
 
@@ -92,6 +138,8 @@ stable string `accountId` in `events-head`. The core calls `task-watch` with tha
 account, exact `conversationId`, and expiry to request bounded capture attention.
 The existing events/events-check protocol supplies incoming messages. This
 subscription grants attention only; execution still requires the core grant.
+Sources that support an any-conversation grant additionally advertise
+`wildcardWatch: true` and accept `*` only for watch/unwatch, never as a send target.
 
 For sends the core supplies `task-send` with those same bound IDs, text, and a
 core-prefixed idempotency key. The adapter checks account consistency immediately
@@ -116,7 +164,9 @@ records, but cannot launch task work.
 Unmatched events retain terminal `cancelled` plus
 `external-execution-unavailable`. Task runs use record version 2; older readers
 reject/skip them instead of executing them with owner access. Existing version-1
-owner runs remain readable. Package state schema stays 1, but rollback suspends
+owner runs remain readable. Older task readers reject version-4 wildcard grants;
+approval prompt changes also fail closed if a capability-bearing older record is
+read after rollback. Package state schema stays 1, but rollback suspends
 task processing until a task-aware version returns; rollback does not replay
 messages or erase task receipts. Update host and relay together. A missing or
 outdated host fails task launch closed.
@@ -124,9 +174,9 @@ outdated host fails task launch closed.
 The installing host user remains trusted and can modify local control state.
 Owner runs can use the plugin manager and Docker administration; content read
 inside owner work still depends on native protections and agent judgment. This
-is not a public multi-tenant execution service. Family delegation, payments,
-enterprise reviewer agents, arbitrary file sharing, and other restricted native
-executors are deferred.
+is an owner-configured channel service, not a general multi-tenant execution
+platform. Payments, enterprise reviewer agents, arbitrary file sharing and
+unrestricted delegated executors are deferred.
 
 Verify with `pnpm verify`, Docker test/runtime targets and smoke fixtures.
 `EZ_TEST_NATIVE_TASKS=1 pnpm exec tsx --test test/task-native.test.ts` checks the

package/docs/architecture/event-sources.md

@@ -31,9 +31,16 @@ creation; it does not promise exactly-once external actions after executor failu
 
 Before starting queued work, recheck binding, owner and provider eligibility.
 Unavailable sources keep work queued; removed subscriptions cancel empty runs.
-No check can retract work already started. Eligible external runs are now recorded
-as blocked (`external-execution-unavailable`), with no executor launch. They do
-not borrow the owner workspace, session or tools. The existing source cursor and
-deduplication remain intact; blocked work does not retry automatically. Work status
-shows the blocked count. No provider SDK or provider-specific authority is imported.
+Events matching exactly one active core task launch its restricted fresh-session
+runner; unmatched events are recorded as blocked (`external-execution-unavailable`)
+with no executor launch. Neither borrows the owner workspace, session or tools.
+Any-conversation tasks admit at most one outstanding run per conversation and
+eight across the public source queue, with persisted limits of 60 conversations
+and 60 replies per hour and 1,000 across a grant. The cumulative limit revokes
+the grant. Owner work is preferred and preempts an active public run. Terminal
+history retains the latest 100 released runs per public grant; providers supporting
+`releaseEvents` are told to discard terminal source events. Release completion is
+persisted, and a failed release is retried before that run can be pruned. The source cursor and
+deterministic run IDs preserve replay. No provider SDK or provider-specific
+authority is imported into core.
 See [authority boundaries](authority-boundaries.md).

package/docs/architecture/telegram-intake.md

@@ -2,7 +2,7 @@
 
 One owner, one bot, one relay writer per control directory. No database, extra agent, or executor loop.
 
-1. Gate the sender and private chat before accepting work. Text from the paired owner in a group is recorded only for discovery and routed to the owner's private chat; other group senders are ignored. Group controls, anonymous administrators and group replies are unsupported.
+1. Gate the sender and chat before accepting work. Text from the paired owner in an unbound group is recorded only for discovery and routed to the owner's private chat. Other private/group senders are ignored unless the built-in source has an active exact or wildcard core grant. Group controls and anonymous administrators remain unsupported.
 2. Atomically save the raw update and deduplicate its Telegram update ID in `EZ_CONTROL_DIR/inbox.json`.
 3. Collect a short burst before downloading/transcribing. Seal batch membership on disk, then normalize in receive order. Captions, album IDs and quoted context travel with the media.
 4. Create one durable run using the batch's stable ID. A restart between run creation and intake completion finds that same run; it does not create a second job.

package/docs/host-service.md

@@ -89,6 +89,9 @@ preserving it rather than reverting to a different or expired host login.
 An agent binding may set `sharedWorkspace` to an absolute canonical application
 repository. The host resolves its canonical path, adds that directory to Codex
 write permissions for chat and scheduled jobs, including symlink aliases.
+If the agent needs more than one separately scoped writable directory, keep the
+canonical application in `sharedWorkspace` and list the others as absolute paths
+in `additionalWorkspaces`; do not grant a broader common parent.
 The host claims requests independently; a running job does not block another
 request sharing its workspace. The selected engine owns execution concurrency.
 Task sessions and artifacts remain isolated. The binding is host-owned and cannot

package/docs/plugin-contributions.md

@@ -18,6 +18,8 @@ Before the first PR, provide:
 - Per-command exposure declarations for external reads, external sends, record
   changes and requested review; see [plugin metadata](plugins.md#exposure-declarations).
   These are self-reported capabilities, never permission grants or safety certificates.
+  A dedicated query-only alias may opt into restricted channel use with
+  `channelQuery: true` and the required explicit non-writing exposure fields.
 - Private state locations, start/stop/status, backup, migration/rollback limits,
   data-preserving uninstall and separate account revocation instructions.
 - Offline contract/negative tests and CI. Verify snapshot installation and CLI
@@ -26,7 +28,10 @@ Before the first PR, provide:
 
 Copy CONTRIBUTING.md, SECURITY.md structure, PR template and docs/releasing.md
 from a released Ez repository; adapt commands and security facts to your plugin.
-Do not copy private QA, company policy, proposed features or unsupported claims.
+Add a short AGENTS.md that states the plugin's ownership boundary and applies the
+same compact feasibility frame and risk-based validation policy; do not copy
+core-only Telegram, state or dependency invariants. Do not copy private QA,
+company policy, proposed features or unsupported claims.
 Public instructions must work without the maintainer's parent workspace. Use
 reviewed local source and its inspected content hash; registry installation is
 inert. Installation is complete only after account onboarding and verified use.