workpilot 0.35.2__tar.gz → 0.37.0__tar.gz

{workpilot-0.35.2 → workpilot-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workpilot
-Version: 0.35.2
+Version: 0.37.0
 Summary: Enterprise AI assistant — internal preview only
 Project-URL: Homepage, https://aka.ms/workpilot
 Project-URL: Documentation, https://gim-home.github.io/WorkPilot/
@@ -12,7 +12,7 @@ Requires-Dist: apscheduler>=3.11
 Requires-Dist: beautifulsoup4>=4.14
 Requires-Dist: fastapi>=0.135
 Requires-Dist: filelock>=3.32.5
-Requires-Dist: github-copilot-sdk>=1.0
+Requires-Dist: github-copilot-sdk<2,>=1.0.16
 Requires-Dist: httptools>=0.8.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: jsonschema>=4.20
@@ -22,13 +22,14 @@ Requires-Dist: markdownify>=1.2
 Requires-Dist: mcp<3,>=2.1.1
 Requires-Dist: msal>=1.35.1; sys_platform == 'linux' and platform_machine == 'aarch64'
 Requires-Dist: msal[broker]>=1.35.1; sys_platform != 'linux' or platform_machine != 'aarch64'
-Requires-Dist: playwright>=1.58
+Requires-Dist: playwright>=1.59
 Requires-Dist: prompt-toolkit>=3.0
-Requires-Dist: pydantic-monty==0.0.23
+Requires-Dist: pydantic-monty==1.0.0
 Requires-Dist: pydantic<3,>=2.12
 Requires-Dist: pyjwt[crypto]>=2.8
 Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: referencing>=0.36
 Requires-Dist: rich>=14.3
 Requires-Dist: tiktoken>=0.9
 Requires-Dist: typer>=0.24

{workpilot-0.35.2 → workpilot-0.37.0}/browser_agent/actions.py

@@ -38,11 +38,15 @@ class BrowserLocator(BaseModel):
     by: Literal["css", "role", "label", "text", "test_id"]
     value: str = Field(min_length=1, max_length=300)
     name: str | None = Field(default=None, max_length=300)
+    exact: bool = False
+    nth: int | None = Field(default=None, ge=0)
 
     @model_validator(mode="after")
     def compatible_name(self) -> Self:
         if self.by != "role" and "name" in self.model_fields_set:
             raise ValueError("only role locators accept a name")
+        if self.by not in {"role", "label", "text"} and "exact" in self.model_fields_set:
+            raise ValueError("only role, label and text locators accept exact")
         return self
 
 

{workpilot-0.35.2 → workpilot-0.37.0}/docs/agents/bridge-mode.md

@@ -4,6 +4,19 @@
 
 Bridge mode lets you drop out of WorkPilot's own agent loop for a session and talk directly to Claude Code or the GitHub Copilot CLI instead, while keeping the same terminal, channel, and audit trail.
 
+## Switch to a persistent WorkPilot agent
+
+After creating an agent in the local/desktop **Agents** page, use `/bridge research` to
+continue its independent conversation. Use `/bridge off` to return to the main assistant.
+`@research message` is the one-shot equivalent and leaves the current bridge selection
+unchanged, including when another internal or external agent is selected.
+
+Internal agents still execute through WorkPilot's normal tools, skills and approvals.
+The external-CLI permission behavior below applies only to `claude` and `copilot`.
+`/pause`, `/resume`, `/stop` and `/status` control a selected internal agent; prefix them
+with `@name` for a one-shot control, for example `@research /stop`.
+See [Persistent agents](overview.md#persistent-agents).
+
 ## Why use it
 
 Normally, WorkPilot's agent loop reasons about your request and calls tools, including the
@@ -19,6 +32,7 @@ From the `you>` prompt:
 ```text
 /bridge claude      # bridge to Claude Code
 /bridge copilot     # bridge to the GitHub Copilot CLI
+/bridge copilot --fresh  # create a distinct native conversation, even while bridged
 /bridge off         # exit bridge mode, return to the normal agent loop
 ```
 
@@ -42,19 +56,47 @@ itself or session-level behavior rather than the underlying tool:
 - `/reset` — reset E-stop
 - `/exit`, `/quit`, or `/bye` — aliases for `/bridge off`
 
+## Copilot conversation and output
+
+`/bridge copilot resume=<id>` resumes a specific native conversation. Ordinary re-entry
+can resume the last conversation from the Bridge transcript. A fresh entry creates a
+unique native ID without deleting previous history. WorkPilot starts fresh automatically
+only when native metadata confirms the requested history is missing, not when discovery
+or resume fails.
+
+`/model <name>` switches the live native model while preserving history. `/model default`
+clears WorkPilot's pin but leaves a live or resumed Copilot conversation on its current
+native selection. Use a fresh, unpinned conversation to select the CLI default.
+Unavailable discovery is shown explicitly; static model suggestions are not claims of
+current availability.
+
+Streaming surfaces receive ordered, credential-redacted root assistant text. Subagent
+output, reasoning, and raw tool arguments are not forwarded. Every turn still has an
+authoritative final response; Teams receives only that buffered response.
+
+Cancelling a Copilot turn requests native `abort()` before finishing local cleanup.
+`/bg` leaves the active Copilot turn running and keeps its conversation reserved until
+completion; resume that conversation after it finishes. E-stop and shutdown also cancel
+detached Bridge turns. Runtime shutdown closes discovery-only SDK clients as well.
+If native abort fails, WorkPilot reports that work may still be running and retains the
+conversation reservation until a confirmed stop or runtime shutdown.
+
 ## Requirements
 
 - **Claude Code bridge**: requires WorkPilot installed with the optional `all` extra — see
   [Install](../getting-started/install.md) and [Claude Code tasks](claude-code.md).
-- **Copilot bridge**: requires a GitHub Copilot subscription and a configured GitHub token — see [Copilot tasks](../agents/github-copilot.md).
+- **Copilot bridge**: requires a GitHub Copilot subscription and native GitHub authentication
+  or a configured token — see [Copilot tasks](github-copilot.md).
 
 ## Security
 
 Entering Bridge mode is itself risk-gated and audited. While bridged, WorkPilot's normal
 tool registry and per-tool approval pipeline are not orchestrating the external CLI; the
-bridge integration instead bypasses Claude permission prompts and automatically approves
-Copilot permission requests. Treat the risk approval for entering Bridge mode as authorization
-for the bridged CLI to use its tools without further WorkPilot or external per-tool prompts.
+bridge integration instead bypasses Claude permission prompts and approves ordinary unresolved
+Copilot permission requests. Native Copilot rules still apply, and enterprise-managed
+requests requiring human approval are never auto-approved. Treat the risk approval for
+entering Bridge mode as authorization for ordinary native tool use, not a bypass of
+managed policy.
 WorkPilot still enforces channel authentication, credential redaction, outbound safety hooks,
 and E-stop. Session history records the bridge timeline, while the per-turn audit event stores
 metadata and a prompt hash rather than the prompt body. See

{workpilot-0.35.2 → workpilot-0.37.0}/docs/agents/claude-code.md

@@ -16,7 +16,7 @@ workpilot_search:
 
 > [中文版](../zh-cn/agents/claude-code.md)
 
-WorkPilot can delegate coding tasks to Claude Code using the `claude_code` tool family. This lets the agent run code, review, test, research, and refactor tasks in the background using Anthropic's Claude models via the Claude Agent SDK.
+WorkPilot can delegate coding tasks to Claude Code using the `claude_code` tool. This lets the agent run code, review, test, research, and refactor tasks in the background using Anthropic's Claude models via the Claude Agent SDK.
 
 ::: tip Ask WorkPilot
 ```text
@@ -39,7 +39,7 @@ available before WorkPilot can delegate.
 - Claude Code enabled in config (`tools.claude_code.enabled: true`, the default)
 
 This is the **only** part of WorkPilot gated behind an optional install extra — the base
-install works without it. The `claude_code` tools register only when both the SDK and CLI
+install works without it. The `claude_code` tool registers only when both the SDK and CLI
 binary are available.
 
 ## How it works
@@ -60,11 +60,13 @@ failed, preserving any partial result that was already received.
 
 ### claude_code
 
-Submits a task to Claude Code.
+Submits tasks and checks their status. Omit `action` to submit a task.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `task` | string | Description of what to do |
+| `action` | string | `submit` (default) or `status` (read-only) |
+| `task_id` | string | For `status`: task ID to check; omit to list all tasks |
+| `task` | string | Description of what to do; required only for `submit` |
 | `task_type` | string | `code` (default), `review`, `test`, `refactor`, or `research` |
 | `files` | list | Files relevant to the task (optional) |
 | `mode` | string | `background` (default) or `wait` |
@@ -78,13 +80,15 @@ Submits a task to Claude Code.
 | `agent` | string | Claude sub-agent name to invoke |
 | `effort` | string | Reasoning effort override |
 
-### claude_code_status
+### Status queries
 
-Check the status of a running or completed task.
+Use `claude_code(action="status", task_id="...")` to check a running or completed task.
+Omit `task_id` to list all tasks. Status queries need no `task` description, score 0, and
+do not require approval.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `task_id` | string | Task ID to check (optional — lists all tasks if omitted) |
+The separate `claude_code_status` tool is no longer registered. Update old calls and
+tool-name configuration references explicitly; status-only permissions are not
+automatically widened to allow task submission.
 
 ## Task types
 

{workpilot-0.35.2 → workpilot-0.37.0}/docs/agents/github-copilot.md

@@ -2,7 +2,7 @@
 
 > [中文版](../zh-cn/agents/github-copilot.md)
 
-WorkPilot can delegate coding tasks to GitHub Copilot using the `github_copilot` tool family. This lets the agent run code, review, test, and refactor tasks in the background while you continue working.
+WorkPilot can delegate coding tasks to GitHub Copilot using the `github_copilot` tool. This lets the agent run code, review, test, and refactor tasks in the background while you continue working.
 
 These are **local CLI/SDK tasks**, not GitHub-hosted cloud-agent tasks. For Issue
 triage, cloud agents, and delivery tracking, see
@@ -26,6 +26,8 @@ WorkPilot cannot create the subscription or enter credentials for you.
 
 - A GitHub Copilot subscription
 - GitHub authentication through a configured token or `gh auth login`
+- WorkPilot's supported `github-copilot-sdk>=1.0.16,<2` dependency; the SDK provisions
+  its local runtime unless `tools.copilot.cli_path` selects an installed CLI
 
 ## How it works
 
@@ -34,36 +36,51 @@ When you ask WorkPilot to implement a feature, write tests, or review code, it c
 Tasks can run in the background (you get a task ID and check back later) or in wait mode.
 Wait mode has a soft cap (`tools.copilot.wait_timeout`, default 900 seconds); after the cap,
 the Copilot session continues in the background and delivers its result later.
+Interrupting the WorkPilot waiter also detaches it; E-stop, runtime shutdown, and the
+hard task timeout request native cancellation instead. `task_timeout: 0` retains a
+one-hour hard cap, including time spent sending the request.
 
 ## Tool reference
 
 ### github_copilot
 
-Submits a task to GitHub Copilot.
+One tool supports three actions. `submit` is the default when `action` is omitted;
+`status` and `models` are read-only queries and do not require a task description.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `task` | string | Description of what to do |
+| `action` | string | `submit` (default), `status`, or `models` |
+| `task_id` | string | For `status`: task to inspect; omit to list live and historical tasks |
+| `task` | string | Required for `submit`: description of what to do |
 | `task_type` | string | `code`, `review`, `test`, or `refactor` |
 | `files` | list | Files relevant to the task (optional) |
 | `workdir` | string | Working directory override; paths outside the workspace raise risk |
 | `mode` | string | `background` (default) or `wait` |
 | `model` | string | Model to use (optional, defaults to per-type policy) |
 | `resume_task_id` | string | Resume a previous task (optional) |
-| `agent` | string | Copilot custom-agent name |
+| `agent` | string | Copilot custom-agent name, passed through the SDK's native agent option |
 | `auto_approve` | bool/null | Per-task preference for unresolved grey-area tool requests; it can tighten, never loosen, operator configuration |
 
-### github_copilot_status
+### Check status
 
-Check the status of a running or completed task.
+Use `github_copilot(action="status", task_id="...")` to inspect a task, or omit
+`task_id` to list tasks. Output includes the WorkPilot task ID, native Copilot session
+ID, working directory, and known run state. After a restart, a saved binding is
+labelled historical rather than reported as an actively monitored run.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `task_id` | string | Task ID to check (optional — lists all tasks if omitted) |
+### List models
 
-### github_copilot_models
+Use `github_copilot(action="models")` to list models available to the current
+authentication, with context/prompt limits and billing multipliers. Discovery errors
+are reported explicitly rather than disguised as an empty list.
 
-Lists available GitHub Copilot models and their context limits. No parameters required.
+### Old tool names
+
+`github_copilot_status` and `github_copilot_models` are removed. Replace calls with the
+corresponding actions. Existing configuration references are automatically normalized
+to `github_copilot` with a deprecation warning, using the standard tool-name alias
+mechanism. Configuration applies to the unified tool; submission and query actions
+keep their existing risk and approval rules.
 
 ## Task types
 
@@ -83,6 +100,10 @@ Lists available GitHub Copilot models and their context limits. No parameters re
 | test | claude-haiku-4.5 |
 | refactor | claude-sonnet-4.6 |
 
+An explicit `model` overrides this policy. An unset per-type policy leaves model
+selection to the native CLI; resuming an unpinned conversation preserves its native
+selection.
+
 ## Examples
 
 ```text
@@ -98,6 +119,22 @@ WorkPilot decides whether to use `github_copilot` based on the task, unless you
 ## Concurrent tasks
 
 Up to 5 Copilot tasks can run concurrently by default. Additional requests queue until a slot is available.
+Different native conversations can run in parallel, but an active or detached task
+retains its conversation until completion or confirmed cancellation. A competing
+continuation or Bridge attachment is rejected instead of replacing its live handle.
+Status and model queries do not consume delegation slots.
+
+## Continue a task
+
+Use `resume_task_id` with a previous WorkPilot task ID. Each continuation has a new
+task ID but keeps the actual native Copilot conversation ID, including when continuing
+a continuation. WorkPilot saves these bindings and their working directories locally;
+Copilot retains the conversation history.
+
+When no `files` or `workdir` is supplied, continuation inherits the saved directory
+before risk assessment. For older tasks with no saved binding, query status to recover
+native metadata or supply an explicit directory. WorkPilot does not guess the workspace
+after a restart, automatically replay old tasks, or restore their live notifications.
 
 ## Permission-request safety
 
@@ -106,6 +143,9 @@ native `~/.copilot/` allow/deny rules and other native configuration. WorkPilot
 the unresolved grey-area requests. For those requests, a per-task `false` can tighten a
 permissive `tools.copilot.hooks.auto_approve` setting to deny; a per-task `true` can never loosen
 an operator setting of `false`.
+Native tool exclusions remain effective on create and resume. Enterprise-managed
+requests requiring human approval are not automatically approved; this integration
+reports that human confirmation is unavailable.
 
 ## Configuration
 
@@ -133,6 +173,9 @@ tools:
     enabled: false
 ```
 
+This disables delegation, not [Bridge mode](bridge-mode.md). Root delegation,
+Bridge, and discovery share one lazy SDK runtime; their policies remain separate.
+
 ## See also
 
 - [Claude Code tasks](claude-code.md) — delegate tasks to Claude Code (Anthropic Agent SDK) instead

{workpilot-0.35.2 → workpilot-0.37.0}/docs/agents/overview.md

@@ -18,6 +18,48 @@ Explain which Agent is handling this task and why.
 ```
 :::
 
+## Persistent agents
+
+For a recurring responsibility, create an agent in **Agents** in the local Web UI or desktop
+app. Give it a calling name, instructions, model, tools, skills, and workspace. Leaving the
+workspace blank assigns a separate working directory. Agent definitions used for delegation
+remain reusable templates; creating a persistent member gives it its own durable identity.
+
+```text
+@research Find the release notes.
+@research Continue with the same sources.
+/bridge research
+/bridge off
+```
+
+`@name` addresses only that message. `/bridge name` switches the current conversation until
+`/bridge off`; a one-shot mention while bridged does not change that selection. These commands
+work through the existing CLI, local Web, and cloud chat channels. Use the local/desktop app
+to manage members; cloud chat does not require a new gateway version.
+
+Each member has its own main session, MEMORY.md, HISTORY.md, and SQLite search index. It
+returns to standby after task completion and associated memory processing, with no periodic
+model calls. Pause finishes the current tool batch first. Stop preserves data; continue in
+chat with `@name /resume`. After a restart, interrupted tasks are not automatically retried:
+send a new message or explicitly continue. Bridge selection itself is not restored.
+The same resume command works in a single invocation: `workpilot run "@research /resume"`.
+
+Open a member to inspect its session, edit or clear its memory, search history, or rebuild
+its history index without using a model. Clear memory keeps history and sessions. Stop active
+work before changing configuration, memory, or indexes. Optional skills are selected by name;
+an empty list selects none. The normal security policy still applies: independent data and
+workspaces are not a process or container isolation boundary.
+
+Viewing memory, history, and sessions reads saved data without initializing the member's
+execution environment. Missing optional skills therefore do not prevent inspecting prior work.
+
+If cleanup fails, the remaining cleanup steps and other members are still attempted. The failed
+member retains its data and reports incomplete cleanup; use **Stop** again to retry.
+
+Automatic team creation, automatic collaboration, and team-shared memory are not part of this
+first version. Scheduled-job and Event management remain with the main assistant.
+See [Bridge mode](bridge-mode.md) and [Local data](../storage/overview.md).
+
 ## Built-in agents
 
 | Agent | Purpose |

workpilot-0.37.0/docs/automation/events.md

@@ -0,0 +1,254 @@
+---
+description: Fixed-code condition checks, explicit fingerprint grants, isolated tests, and separate scheduled tasks.
+workpilot_search:
+  keywords:
+    - Event fixed main context boolean monitor condition automation
+    - expected false fresh check scoped approval isolated test
+    - Events Web approval API key Entra
+---
+
+# Events
+
+> [中文版](../zh-cn/automation/events.md)
+
+An Event checks a condition with fixed Python code, without an agent reasoning on every poll.
+A separate [scheduled task](scheduling.md) decides what to do. The four contracts are
+`EventDefinition`, `EventContext`, `EventRun`, and `EventConditions`; live tool schemas are authoritative.
+
+::: tip Ask WorkPilot
+“Monitor the build every minute and summarize it when complete.”
+“At 9 AM, check afresh and prepare only if the build is still running.”
+:::
+
+## Availability and manual setup
+
+Events default to `events.enabled: false`. An operator must enable it and keep
+`tools.code_mode.enabled` enabled (its default).
+Clocks also require `cron.enabled` and a running scheduler host; manual checks do not require cron.
+Do not silently enable dependencies. See [scheduler setup](scheduling.md#enable-the-scheduler-manually).
+Global defaults are `max_concurrent_checks: 5`, `max_pending_checks: 200`, and
+`history_retention_days: 30` under `events`. Checks are bounded and serialized per Event;
+overload and output truncation are explicit. See the [configuration reference](../configuration/schema.md).
+Nested checks report `blocked` / `overloaded` rather than waiting for busy execution capacity
+or another run of the same Event; ordinary callers can still wait within the pending-check limit.
+
+### Web-host authentication prerequisite
+
+Web chat and Event approval transports must be authenticated through Entra or an effective API key.
+The gateway's existing temporary generated key is valid; a permanently configured key is not required.
+CLI or standalone Cloud use does not itself require Web configuration. See
+[Local gateway authentication](../gateways/local.md#authentication-and-network-exposure).
+
+## From a request to an enabled check
+
+1. Agree on true, false, unknown/error, printed evidence, and a separate task and destination.
+2. Inspect existing definitions/history. Load `tools(name="event-automation", action="skill")`;
+   describe `events`, `cron`, and source tools before using their actual schemas.
+3. Save a disabled draft. Static `validate` checks schema/entrypoint without host calls and reports
+   `type_checked: false`; native type checking happens during execution.
+4. Request explicit human [authorization](#authorization) for that Event ID and fingerprint;
+   saving is not approval.
+5. Run an authorized, isolated `test` when appropriate and inspect its result and real effects.
+6. Create/link the follow-up task before enabling its listener and the Event plan. Enabling does
+   not check immediately or replay cached observations; use **Check now** for an explicit
+   production check. Verify history rather than inferring execution from a successful save.
+
+### Events in the Web UI
+
+Events configuration and management entry points are temporarily hidden throughout the Web UI:
+navigation, command palette, Event pages, Scheduled condition controls, and configuration editors.
+Old Event page URLs return to Chat. Existing definitions, task conditions, runtime behavior, and
+HTTP/tool APIs are unchanged. Scheduled details retain read-only check evidence without Event
+management links, and editing a task preserves its saved conditions. Chat and Security approval
+cards remain available for explicit human authorization.
+
+Use the conversational tools for Event changes and operator-managed configuration files for
+capability setup. `test` uses real tools but does not trigger tasks; `run` can trigger enabled linked
+tasks. Once accepted, the host owns the check: closing the client or losing the connection does
+not cancel it. The same request ID resolves to the same retained run; reconnect queries it
+instead of automatically resubmitting. A host restart marks unfinished checks interrupted,
+without replay. Request lookup is bounded by check-history retention.
+HTTP request IDs must be 1-128 characters forming one URL path segment, excluding `/`, `.` and `..`.
+An empty approval `changes` object is equivalent to omitting it and still requires explicit authorization.
+
+## Author a fixed checker
+
+Use `async def main(context)` for tool calls or `def main(context)` for computation. The runtime
+invokes it in a fresh code-mode sandbox. The checker engine needs no model; tools may use one.
+Read-only queries are recommended, not enforced: other granted tools are eligible. Checkers cannot
+call `agent`, `spawn`, or `run_code`, directly or through `call_tool`. They can inspect cron tasks
+but cannot add, enable, or run them; task actions are separate.
+A tool-free comparison, with `actual` and `expected` supplied in `params`, is:
+
+```python
+def main(context):
+    return context["params"]["actual"] == context["params"]["expected"]
+```
+
+Example disabled `create` payload (not a YAML import file); discover `read_file` first:
+
+```yaml
+id: build-ready
+description: Check whether the build has completed
+enabled: false
+params: {path: build-status.txt}
+pre_trigger: {schedule: 60}
+code: |
+  async def main(context):
+      text = await read_file(path=context["params"]["path"])
+      print(text[:1000])
+      complete = "status=complete" in text
+      running = "status=running" in text
+      if complete == running:
+          raise ValueError("Expected one recognized build status")
+      return complete
+```
+
+`timeout_seconds` defaults to 60. Use optional `expires_at` for bounded monitoring.
+Keep credentials in existing tool configuration, not code, params, or printed details.
+
+Prefer booleans on successful paths. Python truthiness remains compatible, with coercion diagnostics:
+`None` and empty values are false, but the string `"false"` is true. Do not disguise errors as false.
+Errors, blocked, cancelled, interrupted checks, and missing/expired observations have no boolean.
+`print` is bounded supplementary data, separate from the result and diagnostics.
+Run history uses one `source`: `manual`, `time`, or `test`. Test runs never become production
+observations.
+
+Context is a copied snapshot containing `event`, `run`, `params`, `input`, and `last_success`.
+`last_success` is the previous successful production check for this revision, including false,
+or `null`; tests/failures do not replace it. There is no writable `context.state` or mutation
+writeback. Input cannot replace host identity, params, or authority.
+
+## Authorization
+
+Authorization approves an entire fixed Event by **`event_id` + `fingerprint`**, within the
+current workspace. The fingerprint is the SHA-256 hash of its ID, code and parameters,
+not a credential or proof of approval.
+Event IDs are unique within a workspace, not globally. Conversations share its definitions,
+grants, observations and clocks; the originating conversation is provenance, not an access
+boundary. Deleting or switching a chat does not retire its Events.
+Legacy databases with duplicate workspace IDs report
+`workspace_id_conflict` rather than choosing one definition or grant; reconcile those records
+from a backup before starting the workspace-wide runtime.
+`create`, `get`, and `list` expose the current `fingerprint`. Pass it with `event_id` to `authorize`;
+optional `expires_at` limits the grant. There are no per-tool or per-argument grant rules:
+approval covers the otherwise permitted tool calls made by that fixed Event.
+Code/parameter changes request explicit approval **before** applying. The old version continues
+while approval is pending; approval and applying the matching new grant are one operation.
+The enabled/paused state is preserved, without an extra check or another enable step. Rejection,
+timeout or a stale editing baseline leaves the active version unchanged. The Web editor shows
+the current and proposed definitions; conversational updates use the same approval path.
+
+Polling, timeout, Event expiry, description and notifications are ordinary configuration edits
+that preserve the grant. Editing Event expiry does not extend a separate grant expiry.
+Web reauthorization preserves the current grant expiry unless you explicitly change or clear it.
+`update` takes `changes`, `expected_revision`, and optional `expected_version`; Web edits require
+the independent editing version, including for changes that keep the execution revision.
+Existing tool ceilings, hard denies, E-stop, audit, and postflight remain.
+Description and error-notification edits keep the execution revision, grant, observations and timer;
+they do not interrupt an active check. They remain editable after a one-shot time or expiry has
+passed; these edits do not rearm the check or extend its authorization. New executable settings
+must still satisfy schedule and expiry validation.
+Approval cards show the complete checker and JSON authorization scope: Event ID/fingerprint,
+workspace, parameters, runtime configuration, and expiry. Review both before
+approving unattended execution; the Security approval queue shows the same checker and scope.
+When they are too large for a Teams card, the card points to the Security approval queue instead.
+
+Inspect the saved Event, use the full fingerprint returned by `get`, wait for the human
+decision, then test:
+
+```python
+events(action="get", event_id="build-ready")
+events(action="authorize", event_id="build-ready",
+       fingerprint="<fingerprint returned by get>")
+events(action="test", event_id="build-ready")
+```
+
+Tests execute granted real tools; inspect earlier effects before repeating them. Nested checks
+inherit isolation: no production observations or task triggering. Production `run` may trigger tasks.
+Checker grants never transfer to actions; those retain ordinary [approvals](../security/approvals.md).
+
+## Combine time and conditions
+
+Event timers poll independently; clocked tasks **check fresh at each tick** rather than using cache.
+Event-only tasks use committed `event.checked` observations without recursive checks. `cron` examples:
+
+```yaml
+name: build-summary
+schedule: event.checked
+event_conditions:
+  mode: all
+  items: [{event_id: build-ready, equals: true, max_age_seconds: 120}]
+event_policy: {mode: enter_match, cooldown_seconds: 300}
+prompt: Summarize the completed build using the attached check details.
+```
+
+```yaml
+name: morning-preparation
+schedule: "0 9 * * *"
+timezone: Asia/Shanghai
+event_conditions:
+  mode: all
+  items: [{event_id: build-ready, equals: false}]
+prompt: Prepare the build follow-up while the build is still running.
+```
+
+`all` requires every match; `any` needs one known match. Unknown is never false.
+`max_age_seconds` bounds observation age and is rechecked before dispatch, including after waiting
+for task capacity. `each_match` dispatches on matching results;
+`enter_match` on entry into a match, including the first known match. Cooldown is not exactly-once delivery.
+Unknown observations do not reset entry state. `busy_policy: skip` suppresses a busy task's
+action without discarding valid condition transitions or replaying it later. `continue` uses
+ordinary session handling: reuse a persistent conversation or create a new isolated session.
+This policy is only supported for tasks with Event conditions.
+Timed triggers honor the same policy within `cron.max_concurrent_jobs`; `skip` retains the
+single-instance limit, while `continue` can admit overlapping ticks within that capacity.
+Continued Event-bus triggers use the same limit for admitted task activations across jobs.
+Excess matching triggers record `capacity_full` without dispatch or replay; nonmatching
+observations still update condition transitions.
+There are no separate parallel/sequential Event modes.
+Persistent conversations finish the active turn before starting the next trigger as its own
+turn, with its own permissions and check evidence. Waiting for that conversation does not occupy
+global task capacity. Conditions and authority are rechecked before dispatch; an expired or
+invalidated trigger is explicitly skipped, not recorded as completed or replayed later.
+One-shot pre-triggers retain their resolved occurrence across restart and consume it atomically
+with check reservation. Unknown started checks are not automatically replayed.
+Approved code or parameter edits preserve that occurrence and its consumed state; only an
+explicit check-plan change reschedules or rearms it.
+For absolute `at:` timestamps without an offset, `pre_trigger.timezone` selects the wall-clock
+timezone (local timezone when omitted). An explicit timestamp offset takes precedence;
+relative `at:+seconds` delays are unchanged.
+
+## Handoff and management
+
+Existing cron owns execution, overlap, capacity, and history; no separate task queue or replay exists.
+Ordinary message/prompt/tool actions retain their instructions and arguments. Printed details stay
+fenced as untrusted data, including in `events` tool results, and are never interpolated into tool
+arguments. Bound tasks can use `events(action="context")`. Existing tools can address idle owned
+agents, but Events do not automatically wait for busy agents or silently resume stopped/paused ones.
+Use the default `completion_mode="wait"` for one-shot tasks so delegated work finishes before retirement.
+
+The task context contains `task_id`, `reason`, and bounded `events` evidence. Ownership,
+authorization, trigger bookkeeping and causation stay in the host; they are not read back
+from the task's data. The same true/false/unknown condition rules apply during evaluation
+and immediately before dispatch.
+
+Failures remain in history, with grouped error/recovery notices by default (`on_error: {notify: true}`).
+No automatic retries or repair proposals. Agree who retires finished monitors and verify Event/task history.
+Disable an Event to pause it. Deletion retires its workspace ID; retained check history follows
+normal retention, and the workspace cannot reuse the ID for a different definition.
+
+Task execution history retains the latest 100 dispatched outcomes. Routine skips do not evict
+those runs: each task persists only its **latest linkage decision**, including time, reason and
+related check IDs/revisions. Older skips are not individually retained. Links use retained
+correlations, never timestamp guesses; an empty reverse lookup does not prove no action occurred.
+
+V1 operations: `list`, `get`, `history`, `create`, `update`, `enable`, `disable`, `delete`,
+`validate`, `authorize`, `revoke`, `run`, `test`, `context`. The authenticated `/api/events`
+surface supports workspace management, revision-checked configuration edits, approval requests,
+test/production admission and querying retained runs. Decisions use the same `/api/approvals`
+transport and authenticated approval identity as Security. The Schedule HTTP API also manages
+Event-conditioned tasks. No webhook or YAML import endpoint is introduced.
+Removing an Event-bound task requires its Event runtime so the protected binding is removed
+with the job. Use Scheduled or the live conversational `cron` tool; standalone `wp cron remove`
+refuses these jobs.