[plugin sdk] Add host-hook examples and recipes (#72287 follow-up) by 100yenadmin · Pull Request #72333 · openclaw/openclaw

100yenadmin · 2026-04-26T19:04:49Z

Summary

Docs follow-up for the host-hook stack. This PR adds worked recipes, Mermaid diagrams, and maintainer-facing explanations for how the generic host-hook seams compose across plugin archetypes.

This PR is docs-only. The foundation contracts land in #72287, workflow seams in #72383, and executable fixtures in #72384. This page is intended to make the stack reviewable by explaining what each hook does, which plugin classes it enables, and how hooks compose without adding Plan Mode product behavior to core.

Current update: the earlier detailed maintainer explanation was accidentally compressed during stack cleanup. This body restores/reconstructs the detailed docs narrative and keeps current stack/check status in comments.

Expansion note: This docs PR expanded to become the maintainer map for the stack after the implementation spread across foundation, workflow seams, fixtures, and examples. It is intentionally stack-dependent documentation and should land after, or be retargeted with, the implementation PRs.

Stack Position

flowchart LR
  A["#72287 foundation contracts"] --> B["#72383 workflow seams"]
  B --> C["#72384 executable fixtures"]
  C --> D["#72333 recipes and diagrams"]

Because this is a docs PR for APIs landing in the stack, it should be reviewed as a companion to #72287/#72383/#72384 rather than as an independent claim that main already exposes every referenced method.

Reader Map

flowchart TB
  State["Session state"] --> Approval["approval cards"]
  State --> Wizard["setup wizard"]
  Queue["Next-turn injection"] --> Review["review assistant retries"]
  Queue --> Resume["approval continuation"]
  Policy["Trusted policy"] --> Compliance["budget/compliance gates"]
  UI["Control UI descriptors/actions"] --> Dashboards["data-only status cards"]
  Events["Agent events + run context"] --> Monitor["incident/SLA monitors"]
  Scheduler["Scheduler jobs"] --> Followup["quiet-hours and follow-up wakeups"]
  Attach["Session attachments"] --> Reports["reports and audit exports"]

What The Docs Explain

Topic	Why maintainers need it	Example plugin classes
Session extensions	Shows how plugins own durable state without core-specific fields.	Approval workflow, setup wizard, budget tracker.
Next-turn injections	Shows how action results or external events become exactly-once prompt context.	Review retry, deploy approval, support-ticket update.
Trusted policy	Explains bundled-only safety policy before normal plugin hooks.	Compliance gate, workspace boundary, production freeze.
Tool metadata	Shows how plugins annotate risk/tags for catalog and effective inventory consumers.	Security UI, audit plugin, cloud action grouping.
Control UI descriptors/actions	Explains data-only UI contribution without arbitrary browser JS.	Approval card, onboarding panel, incident timeline.
Agent events and run context	Shows how monitors correlate run events without global ad hoc maps.	SLA watcher, billing exporter, incident commander.
Scheduler jobs	Explains plugin-owned future work and cleanup ownership.	Quiet-hours resume, stale review reminder, deploy timeout watcher.
Attachments	Shows host-mediated artifact delivery without channel-specific coupling.	Report sender, audit export, patch bundle delivery.
Finalize retry	Explains bounded final repair without product-specific runner patches.	Review assistant, release checklist verifier, incident summary repair.

Diagrammed End-To-End Recipes

sequenceDiagram
  autonumber
  participant Operator
  participant UI as Control UI
  participant Gateway
  participant Plugin
  participant Queue as Next-turn Queue
  participant Runner

  Plugin->>Gateway: register descriptor/action/session extension
  Gateway->>UI: expose data-only descriptor
  Operator->>UI: approve or choose action
  UI->>Gateway: plugins.sessionAction / sessions.pluginPatch
  Gateway->>Plugin: validate and update plugin-owned state
  Plugin->>Queue: enqueue continuation context
  Runner->>Queue: drain before prompt hooks
  Runner->>Plugin: agent_turn_prepare receives queued context

The recipes are intentionally not Plan Mode-specific. They show the reusable shapes that Plan Mode, deploy approvals, compliance gates, SLA monitors, onboarding flows, review assistants, and artifact publishers can all build on.

Review Cleanup In This PR

Clarifies that the APIs land in [plugin sdk] Add generic plugin host-hook contracts #72287/[plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383 and this PR is docs-only.
Adds stack diagrams so maintainers can see how the PRs fit together.
Fixes the recipe count and Mintlify-fragile heading punctuation.
Fixes the SLA Watcher example so its startedAt map is populated and cleared.
Uses stable idempotency keys in examples.
References reserved-command behavior through the implemented command contract instead of stale helper names.
Aligns deploy params to version consistently.
Uses explicit sessionKey in examples that need persisted state.
Uses safe canonical path checks in policy examples instead of personal/local paths.
Fixes Markdown table syntax.

Non-Scope

This PR does not add runtime code and does not implement Plan Mode product behavior. It should not introduce:

Plan Mode prompts
/plan command behavior
Telegram-specific behavior
Plan Mode cards/CSS
installer patching

The docs are meant to help maintainers and plugin authors understand the generic host-hook contracts and the companion fixture proof.

Validation

pnpm docs:list
git diff --check

greptile-apps · 2026-04-26T19:06:38Z

Greptile Summary

This PR adds a 2,426-line recipe book (docs/plugins/host-hooks-examples.md) for the generic host-hook contracts introduced in #72287, registers it in the docs nav, and adds zh-CN glossary entries. The doc itself is well-structured and thorough, but one of the 14 single-contract examples contains a logic bug: the SLA Watcher's heartbeat_prompt_contribution handler reads from an in-memory Map that is never populated (the event subscription writes to run context instead), so the heartbeat nudge never fires as written.

Confidence Score: 4/5

Safe to merge after fixing the SLA Watcher example logic bug and the five/six parts prose inconsistency.

One P1 logic bug in a code example (the startedAt Map is never populated, making Recipe 5's real-world example completely non-functional as written) and one P2 prose inconsistency. No source changes are included; all changes are documentation-only.

docs/plugins/host-hooks-examples.md — specifically the SLA Watcher real-world example (Recipe 5, lines 628–659) and the 'How to read this doc' section (line 31).

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/plugins/host-hooks-examples.md
Line: 31

Comment:
**"Five parts" says five, lists six**

The prose says "Each recipe has the same **five** parts:" but the numbered list below it runs from 1 through 6. This will confuse readers who count along.

```suggestion
Each recipe has the same six parts:
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: docs/plugins/host-hooks-examples.md
Line: 633-658

Comment:
**SLA Watcher example: `startedAt` Map is never populated**

The `startedAt: Map<string, number>` declared on line 633 is never written to. When `run_started` fires, the subscription stores the timestamp in *run context* via `ctx.setRunContext("sla", { startedAt: Date.now() })`, but the `heartbeat_prompt_contribution` handler reads from the Map (`startedAt.get(event.sessionKey)`), which is always empty. The heartbeat handler will therefore always return early and never emit an SLA nudge.

The Recipe C (Incident Commander) archetype later in the doc correctly uses `api.getRunContext()` inside the heartbeat handler. The fix here is the same pattern — read from run context rather than the unpopulated Map, and remove the unused `startedAt` Map declaration.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "docs(plugins): add host-hook examples an..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 31da93f992

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a new “recipe book” documentation page for the upcoming generic plugin host-hook contracts, and wires it into the docs navigation and zh-CN glossary so it appears in the “Building plugins” section and passes i18n glossary checks.

Changes:

Add docs/plugins/host-hooks-examples.md: a large worked-examples/recipes guide covering host-hook contracts and composition archetypes.
Register the new page in docs/docs.json under “Building plugins”.
Add zh-CN glossary entries for the new page title/sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/plugins/host-hooks-examples.md	New host-hook examples/recipes page with contract snippets, diagrams, and archetype walkthroughs.
docs/docs.json	Adds the new doc page to the “Building plugins” navigation group.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary translations for the new page title and sidebar title.

Copilot

Pull request overview

Adds a new “recipe book” documentation page for the (stacked) generic plugin host-hook contracts introduced in #72287, and wires it into the docs navigation + zh-CN glossary so it shows up in the sidebar and passes i18n glossary checks.

Changes:

Add docs/plugins/host-hooks-examples.md with worked examples, composition recipes, diagrams, and testing patterns for host-hook contracts.
Add the new page to the “Building plugins” docs nav.
Add zh-CN glossary entries for the new page title and sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
docs/plugins/host-hooks-examples.md	New long-form recipe page with examples/diagrams/testing guidance for host hooks.
docs/docs.json	Adds the new page to the plugins documentation navigation group.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN translations for the new doc title/sidebar label.

clawsweeper · 2026-04-27T03:22:34Z

Codex automated review: keeping this open.

Keep this PR open. Current main has the lower-stack generic host-hook foundation, but it does not contain this PR's recipe page/glossary additions or the higher-level workflow/fixture stack that the PR explicitly depends on. The provided discussion also shows active same-author companion PRs #72383 and #72384, so this is still useful stacked docs work rather than conservative cleanup.

Best possible solution:

Keep this PR open as the stacked host-hook recipe documentation. Review or land #72383 and #72384 first, then align the recipe page and glossary with the final shipped API names, docs nav placement, and resolved review comments before merging.

What I checked:

Current main reviewed: The checkout is clean and at ad57a6d, matching the provided current main SHA. (ad57a6d61658)
Proposed recipe page is not on main: Current docs navigation lists the Tools & Plugins / Plugins pages, including plugins/hooks and plugins/sdk-overview, but no plugins/host-hooks-examples entry. A targeted search for host-hooks-examples and Host-hook examples in docs and docs/.i18n returned no matches. Public docs: docs/docs.json. (docs/docs.json:1177, ad57a6d61658)
Main has reference docs, not the recipe book: sdk-overview documents a compact host-hook method table for workflow plugins. That is useful foundation documentation, but it is not equivalent to this PR's long worked recipe book with diagrams, archetypes, and examples. Public docs: docs/plugins/sdk-overview.md. (docs/plugins/sdk-overview.md:113, ad57a6d61658)
Foundation host-hook APIs exist: OpenClawPluginApi on main exposes foundation seams such as registerSessionExtension, enqueueNextTurnInjection, registerTrustedToolPolicy, registerControlUiDescriptor, run-context helpers, and registerSessionSchedulerJob. Contract fixtures exercise those foundation hooks. (src/plugins/types.ts:2337, ad57a6d61658)
Higher workflow seams are not on main: Targeted searches found no current-main implementation of the workflow follow-up surfaces described by this PR and [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383/[plugin sdk] Add advanced workflow plugin contract fixtures #72384, including plugins.sessionAction, sendSessionAttachment, scheduleSessionTurn, registerSessionAction, SessionAttachment, or advanced-workflow-fixtures. (ad57a6d61658)
Open same-author stack dependencies: The provided PR body and timeline say this docs PR is a companion to [plugin sdk] Add generic plugin host-hook contracts #72287, [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383, and [plugin sdk] Add advanced workflow plugin contract fixtures #72384. Provided related-item context shows [plugin sdk] Add generic plugin host-hook contracts #72287 merged, while [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383 and [plugin sdk] Add advanced workflow plugin contract fixtures #72384 remain open same-author PRs. The cleanup rule says not to close one half of paired open same-author work.

Remaining risk / open question:

Merging this docs PR before [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383/[plugin sdk] Add advanced workflow plugin contract fixtures #72384 land or before it is retargeted could publish recipes for APIs or fixtures that current main does not expose.
The recipe examples cover trusted policy, workspace boundaries, scheduling, attachments, and finalize retry, so stale or incorrect examples could mislead plugin authors even though the PR is docs-only.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against ad57a6d61658.

Copilot

Pull request overview

Adds a new “Host-hook examples and recipes” documentation page to complement the generic plugin host-hook contracts work (stacked on #72287), plus navigation and zh-CN glossary updates so the page is discoverable and passes i18n checks.

Changes:

Add docs/plugins/host-hooks-examples.md: a large recipe book with contract snippets, examples, diagrams, and composition archetypes.
Add the new page to the “Building plugins” docs nav group.
Add zh-CN glossary entries for the new page title/sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/plugins/host-hooks-examples.md	New recipe book covering host-hook contract usage patterns, pitfalls, and composition archetypes.
docs/docs.json	Adds the new page to the “Building plugins” navigation group.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary entries for the new page’s title and sidebar title.

chatgpt-codex-connector · 2026-04-27T07:55:45Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Copilot

Pull request overview

Adds a new “host-hook recipe book” documentation page to help plugin authors apply the generic host-hook contracts introduced in #72287, and wires the page into the docs navigation and zh-CN glossary.

Changes:

Add docs/plugins/host-hooks-examples.md with worked examples, composition recipes, diagrams, and testing guidance for host-hook contracts.
Add the new page to the “Building plugins” docs nav group.
Add zh-CN glossary entries for the new page title and sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/plugins/host-hooks-examples.md	New long-form recipe/reference page with examples, diagrams, and testing recipes for host-hook contracts.
docs/docs.json	Adds the new host-hook examples page to the “Building plugins” navigation group.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary entries for the new doc’s title/sidebar label to satisfy i18n glossary checks.

chatgpt-codex-connector · 2026-04-27T08:12:19Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Copilot

Pull request overview

Adds a new docs “recipe book” page for plugin host-hook composition patterns, and wires it into the docs navigation + zh-CN glossary to make it discoverable and translatable.

Changes:

Introduces docs/plugins/host-hooks-examples.md with worked recipes, diagrams, and archetype compositions for host-hook-style plugin workflows.
Adds the new page to the plugins docs sidebar/navigation.
Adds zh-CN glossary entries for the new page title/sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/plugins/host-hooks-examples.md	New long-form recipes/examples page (contracts, diagrams, archetypes, testing guidance).
docs/docs.json	Adds the new page to the plugins docs nav list.
docs/.i18n/glossary.zh-CN.json	Adds glossary translations for the new page title and sidebar label.

Copilot

Pull request overview

Adds a new docs page intended to serve as a “recipe book” for composing the proposed generic plugin host-hook contracts (with worked examples, Mermaid diagrams, and archetype recipes), and wires it into the docs navigation and zh-CN glossary.

Changes:

Add docs/plugins/host-hooks-examples.md with extensive host-hook recipes and diagrams.
Add the new page to the plugins docs nav in docs/docs.json.
Add zh-CN glossary entries for the new page titles.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
docs/plugins/host-hooks-examples.md	New host-hook recipes/examples page (contracts, end-to-end flows, Mermaid diagrams).
docs/docs.json	Adds the new page into the published plugins navigation.
docs/.i18n/glossary.zh-CN.json	Adds glossary translations for the new page titles.

Copilot

Pull request overview

Adds a new documentation page that acts as a “recipe book” for composing plugin host-hook contracts (with worked examples and Mermaid diagrams), and wires it into the docs navigation and CN glossary.

Changes:

Add docs/plugins/host-hooks-examples.md with end-to-end recipes and composition archetypes for host-hook usage.
Add the new page to docs/docs.json so it appears in the plugins docs nav.
Add glossary entries for the new page title/sidebar label in docs/.i18n/glossary.zh-CN.json.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
docs/plugins/host-hooks-examples.md	New “host-hook recipes” doc page with examples, diagrams, and guidance.
docs/docs.json	Adds the new page to the docs sidebar/nav.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary translations for the new page labels.

Copilot

Pull request overview

Adds a new “Host-hook examples and recipes” documentation page intended to be a worked companion to the host-hook contract stack, plus glossary entries for localized navigation titles.

Changes:

Adds docs/plugins/host-hooks-examples.md with end-to-end recipes, diagrams, and composition archetypes for host-hook usage.
Updates docs/.i18n/glossary.zh-CN.json with translations for the new doc title/sidebar title.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/plugins/host-hooks-examples.md	New recipe/diagram-heavy doc explaining how to compose host-hook contracts into common plugin archetypes.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary entries for the new page title strings.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a3709e2203

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0d90a0d3c0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a new documentation page that explains how the (stack-dependent) generic plugin host-hook contracts compose into common workflow/plugin archetypes, plus a small i18n glossary update for the new page title(s).

Changes:

Added docs/plugins/host-hooks-examples.md with worked recipes, Mermaid diagrams, and end-to-end composition patterns for host hooks.
Added zh-CN glossary entries for the new page title and sidebar title.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/plugins/host-hooks-examples.md	New long-form recipe/guide covering host-hook composition patterns, examples, diagrams, and testing guidance.
docs/.i18n/glossary.zh-CN.json	Adds translations for the new doc page title/sidebar title strings.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 383bb2484b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-27T16:10:15Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Adds docs/plugins/host-hooks-examples.md, a 2,400-line recipe book covering the generic plugin host-hook contracts introduced in openclaw#72287: session extensions, sessions.pluginPatch, next-turn injections, agent_turn_prepare, heartbeat_prompt_contribution, trusted tool policy, tool metadata, scoped commands with continueAgent, Control UI descriptors, agent event subscriptions, run context, session scheduler jobs, runtime lifecycle cleanup, and the cleanup matrix. Each recipe pairs a real TypeScript signature from src/plugins/types.ts or src/plugins/host-hooks.ts with a minimal example, a mermaid diagram, a real-world plugin entry, and common pitfalls. Composition recipes walk through five end-to-end archetypes (approval workflow, workspace policy gate, background lifecycle monitor, setup wizard, review assistant). Closes the gap between the SDK reference and the kind of plugin authors will actually want to build on these surfaces. Adds the page to the Building plugins nav group in docs/docs.json and zh-CN glossary entries for the new title and sidebar label.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0272587410

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df1f761837

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 148cc536a2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a28bb435a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb1a4d8bfd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-28T07:21:17Z

+  name: "Workspace Policy",
+  description: "Block writes outside the configured workspace root",
+  register(api) {
+    const workspaceRoot = String(api.pluginConfig.root ?? "");


Fail closed when workspace root is unset in policy recipe

This recipe initializes workspaceRoot as String(api.pluginConfig.root ?? "") and then treats a path as valid when it starts with workspaceRoot + "/"; when root is missing, that becomes "/", so absolute paths are incorrectly considered in-bounds and the trusted policy can allow out-of-workspace operations. Because this section is a security policy pattern, it should explicitly reject empty/missing roots (and preferably canonicalize the root) before checking tool paths.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-28T07:21:17Z

+      targetPath = await fs.realpath(String(event.params?.path ?? ""));
+    } catch {


Avoid realpath checks that reject new in-workspace files

The trusted-policy example resolves event.params?.path with fs.realpath, which throws for targets that do not yet exist; in common write flows this blocks legitimate creates inside the workspace and returns allow:false even though the destination is valid. The recipe should validate against a resolved parent directory (or a normalized absolute path) so new file writes inside the workspace are not denied by default.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-28T07:21:17Z

+- **Don't drop other plugins' injections.** Filter to your own `pluginId`
+  before consuming. The host defaults already handle every plugin's items —
+  if you replace the default, do it for _your_ injections only.
+- **`agent_turn_prepare` runs only on user-initiated turns.** For


Correct agent_turn_prepare trigger scope in pitfalls note

This note says agent_turn_prepare runs only on user-initiated turns, but the runtime path calls runAgentTurnPrepare without a trigger check (src/agents/pi-embedded-runner/run/attempt.prompt-helpers.ts), while heartbeat turns still execute the same prompt-build flow. That mismatch can mislead plugin authors into skipping heartbeat-safe handling even though their agent_turn_prepare hooks can still run during heartbeat-driven prompt builds.

Useful? React with 👍 / 👎.

electricsheepops · 2026-04-28T07:41:39Z

Superseded by #73384 now that #72287 has merged.\n\nThe host-hook examples/recipes docs are included in the consolidated follow-up alongside the workflow implementation and fixture proofs, and the docs nav note has been updated for the new single-PR landing shape. Please review the docs in #73384 rather than this docs-only branch.

Copilot AI review requested due to automatic review settings April 26, 2026 19:04

openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Apr 26, 2026

Copilot started reviewing on behalf of 100yenadmin April 26, 2026 19:05 View session

greptile-apps Bot reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

chatgpt-codex-connector Bot reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Copilot AI reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

100yenadmin requested a review from Copilot April 26, 2026 19:22

Copilot started reviewing on behalf of 100yenadmin April 26, 2026 19:23 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

clawsweeper Bot mentioned this pull request Apr 26, 2026

[plugin sdk] Add generic plugin host-hook contracts #72287

Merged

100yenadmin requested a review from Copilot April 27, 2026 07:16

Copilot started reviewing on behalf of 100yenadmin April 27, 2026 07:17 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

100yenadmin requested a review from Copilot April 27, 2026 07:56

Copilot started reviewing on behalf of 100yenadmin April 27, 2026 07:56 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

100yenadmin requested a review from Copilot April 27, 2026 08:07

Copilot started reviewing on behalf of 100yenadmin April 27, 2026 08:08 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin requested a review from Copilot April 27, 2026 08:20

Copilot started reviewing on behalf of 100yenadmin April 27, 2026 08:20 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

100yenadmin requested a review from Copilot April 27, 2026 08:35

Copilot AI reviewed Apr 27, 2026

View reviewed changes

100yenadmin mentioned this pull request Apr 27, 2026

[plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383

Closed

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

chatgpt-codex-connector Bot reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

chatgpt-codex-connector Bot reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin requested a review from Copilot April 27, 2026 14:47

Copilot started reviewing on behalf of 100yenadmin April 27, 2026 14:47 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md

chatgpt-codex-connector Bot reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

Eva added 5 commits April 28, 2026 12:24

docs(plugin-sdk): clarify host-hook recipe stack

685c4fb

docs(plugin-sdk): address host-hook recipe review

38dbf0f

docs(plugin-sdk): hide host-hook recipes from nav until APIs land

d27e709

docs(plugin-sdk): guard session-bound command examples

0272587

100yenadmin force-pushed the docs/plugin-host-hooks-examples branch from 879aec8 to 0272587 Compare April 28, 2026 05:30

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

docs(plugin-sdk): align host hook examples with contracts

df1f761

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

docs(plugin-sdk): keep policy recipe path generic

148cc53

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

docs(plugin-sdk): use agent event payload shape in examples

3a28bb4

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

docs(plugin-sdk): keep metadata recipe plugin-owned

cb1a4d8

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

clawsweeper Bot mentioned this pull request Apr 28, 2026

[plugin sdk] docs: plugin host hook RFC #71731

Closed

15 tasks

100yenadmin mentioned this pull request Apr 28, 2026

[plugin sdk] Consolidate workflow seams and fixtures #73384

Closed

100yenadmin closed this Apr 28, 2026

		targetPath = await fs.realpath(String(event.params?.path ?? ""));
		} catch {

Uh oh!

Conversation

100yenadmin commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack Position

Reader Map

What The Docs Explain

Diagrammed End-To-End Recipes

Review Cleanup In This PR

Non-Scope

Validation

Uh oh!

greptile-apps Bot commented Apr 26, 2026

Greptile Summary

Confidence Score: 4/5

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clawsweeper Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Apr 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Apr 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

100yenadmin commented Apr 26, 2026 •

edited

Loading

clawsweeper Bot commented Apr 27, 2026 •

edited

Loading