New · July 2026

RicherHook Event Types

Plexon hooks now fire on six lifecycle events instead of two (including user-prompt expansion, tool failure, config change, and pre-compact) and support a new agent hook type that dispatches the event to a sub-agent. Personas can bundle their own hooks, configured once at install, and a post-session hook can gate on a phrase in the assistant's final reply. Wire automation onto every meaningful moment in the agent's lifecycle without writing orchestration glue, and author your hooks by hand or straight from chat.

Download
The Hooks panel with its built-in help: what a hook is, when it fires, and how the AI writes one for you.
The Hooks panel listing hooks by lifecycle event

Six Lifecycle Events, Not Two

Plexon hooks now fire on six moments instead of two. Pre-Tool Use and Post-Tool Use keep their existing modify/block contract; four new events (User Prompt Expansion, Post-Tool Use Failure, Config Change, and Pre-Compact) observe the agent's lifecycle and let you wire automation onto every meaningful transition.

  • Post-Tool Use Failure fires only on tool errors. No more conditional logic in every Post-Tool hook
  • User Prompt Expansion fires after @file / @symbol / @agent rewriting. See and rewrite the final prompt
  • Config Change fires after every settings save. Mirror to Slack, audit changes, replicate across machines
  • Pre-Compact fires before context compaction. Snapshot state or dump to long-term memory
The hook editor: name the hook, choose its lifecycle event, pick a Command, HTTP, or Agent action, and set tool matchers

Agent-Typed Hooks: Spawn a Sub-Agent on Any Event

Beyond Command and HTTP executors, hooks now support an Agent type. Pick any installed Plexon sub-agent (code-reviewer, release-coordinator, your own custom one) and dispatch the event payload to it as a seed prompt. Verifier sub-agents on tool failure, automated PR review on config drift, summarizer agents on pre-compact: composition without writing glue code.

  • Configure an Agent hook in two clicks: pick agent, optionally override mode and seed prompt
  • Sub-agent receives the event payload as fenced JSON so it treats it as data, not commands
  • Agent hooks never block. They run alongside the daemon and surface as tiles in the UI
  • Built on the existing parallel-agents infrastructure. No new orchestration layer

Workflow-Typed Hooks: Run a Whole Flow on an Event

When the reaction is a procedure rather than a judgment call, point the hook at a Dynamic Workflow. The event becomes the trigger for the run, and the flow does the rest: read the finished session, write the notes, print the PDF, notify. You watch it on a canvas instead of reading a log.

  • Pick any workflow as the action, global or per-project
  • The payload arrives as the trigger, so the flow reads the session id, the tool name, the project
  • Never blocks, and the session does not wait for the run to finish
  • The same pairing from the other side: a workflow can carry a Plexon event as its own trigger

Two Pipelines, Right Semantics

Under the hood, the dispatcher splits into a ToolHookPipeline (gates with modify/block semantics) and a LifecycleHookPipeline (informational events that can never wedge the agent). Both are nil-safe and rebuilt atomically when you save a hook, so reloading is instantaneous and a misbehaving lifecycle hook can never block your session.

  • Tool pipeline carries the existing prerequisite gates and threshold gates unchanged
  • Lifecycle pipeline runs in registration order; errors are swallowed (status field surfaces them)
  • Hook reload is atomic. The UI save replaces both pipelines together
  • Existing pre_tool_use / post_tool_use hooks need zero changes

Author Hooks From Chat

Ask the assistant to set up a hook and it does it for you. The plexon_hook tool lets it create, list, edit, enable, disable, and test hooks in plain language, writing to the same store the Hooks panel reads. A hook made from chat shows up in the panel right away and reloads live, exactly like one you built by hand.

  • "Add a hook that runs my notify script after every file write" becomes a real, saved hook
  • List, enable, disable, or dry-run existing hooks by asking
  • Plugin-provided hooks stay protected: the assistant refuses to delete them
  • Same validation and live reload as the panel, with no parallel storage

Guided Authoring: Templates and Create with AI

You do not need to code to ship a hook. The panel opens with a Create with AI button that hands your plain-language request to the assistant, which writes the script file, registers the hook, and tests it. Starter templates cover all seven events; the ones that need a script route to the AI, the rest open the builder pre-filled. And the builder itself now explains the contract: what your hook receives and what its answer can do, with the exact sample payload one click away.

  • Create with AI writes the script, registers the hook, and tests it from one request
  • Eight starter templates: guards, audit webhooks, reminders, failure reviewers, reply follow-ups
  • The builder shows the per-event payload and output contract as you change event and type
  • Test results open with a plain verdict, and a blocked pre-tool hook reads as what it is: working

Claude Code Imports Round-Trip

When you import settings from Claude Code, Plexon now recognizes UserPromptSubmit / UserPromptExpansion, PostToolUseFailure, ConfigChange, PreCompact, the Stop hook, and the agent hook type, instead of silently dropping them. Claude's prompt-typed hooks (which are shell commands at the runtime level) import as Plexon command hooks; agent-typed hooks import as Plexon agent hooks with the prompt template preserved.

  • UserPromptSubmit / UserPromptExpansion → user_prompt_expansion
  • PostToolUseFailure → post_tool_use_failure (gated on result.IsError)
  • ConfigChange / PreCompact → mapped 1:1
  • Stop → post_session, with any $CLAUDE_PROJECT_DIR path filled in for you
  • agent type → agent type (with status_message → agent_name, prompt → seed template)

Personas Bring Their Own Hooks

A persona can now ship hooks the same way it ships skills and agents: installed together, active only while that persona is active. Configure the persona's hooks once at install time (folders, formats, thresholds, whatever fields the author exposed with sane defaults), and they run in the background without a single manual setup step in the Hooks panel.

  • Hooks live inside the persona bundle and switch on and off with the persona
  • Install-time fields carry defaults, so most people never touch a setting
  • Fields stay editable later from the Hooks panel, same as a hand-built hook
  • No global hook clutter: a persona you never installed adds nothing to your pipeline

Post-Session Hooks Can Gate on What the Assistant Said

A post_session hook can now check the assistant's final reply for a phrase before it fires, instead of running after every single turn. Wire a hook to a closing line like "consultation complete" and it stays quiet through the rest of the conversation, then triggers exactly once the model signals the work is done.

  • Matchers scan the assistant's last message for a phrase or pattern
  • No matcher configured keeps the old behavior: fires on every session end
  • Pairs naturally with an agent-typed hook for a clean "do X when the session says Y" recipe
  • Same live reload and validation as every other hook type

Hook-Spawned Agents Can Read the Finished Transcript

A new plexon_read_session tool lets an agent dispatched from a hook read back the session it was spawned from, in full. That closes the loop for note-taking and summarizer agents: the hook fires after the conversation ends, and the agent it spawns reads exactly what was said before writing anything to disk.

  • Scoped to the session that triggered the hook, not the whole history
  • Built for post-session agents: notes, summaries, structured extracts
  • No transcript hunting or ad hoc file plumbing to wire up
  • Composes with the existing agent hook type and seed-prompt dispatch

Why the New Events Matter

Failure-Only Automation

post_tool_use_failure fires only when a tool errored. Wire alerting, retry triggers, or a verifier sub-agent without checking is_error in every Post-Tool hook.

Rewrite Prompts In-Flight

user_prompt_expansion fires after @-mention rewriting; hooks see the final text the model is about to receive and may rewrite it. Redact secrets, inject reminders, normalize formatting.

Config Drift Visibility

config_change fires after every successful settings save. Mirror to a chat channel, audit history, or trigger a release-coordinator agent when release files are touched.

Pre-Compaction Snapshots

pre_compact fires before context-window condensation runs. Snapshot state, dump key decisions to long-term memory, or run a summarizer agent before the original messages are rewritten.

Agent-Typed Hooks

Pick any installed sub-agent and dispatch the event payload as its seed prompt. Verifier on tool failure, code reviewer on config change, summarizer on pre-compact: composition without glue code.

Workflow-Typed Hooks

Point a hook at a Dynamic Workflow and the event starts the run. For the reactions with steps: file the notes, export the PDF, then tell me. A workflow can also carry the event as its own trigger.

Feed Context Back to the Model

A Post-Tool Use hook can return additionalContext and Plexon appends it to the tool result the assistant reads. Nudge the next step, flag a policy, or add a reminder right after an edit or command.

Author From Chat

Ask the assistant to add, edit, enable, disable, or test a hook and the plexon_hook tool sets it up in the same store the Hooks panel reads, live and validated.

Hooks Follow the Persona

A persona can bundle its own hooks alongside its skills and agents. They activate with the persona, configure at install with sane defaults, and stay editable later from the Hooks panel.

Read the Finished Transcript

plexon_read_session gives a hook-spawned agent the full transcript of the session that triggered it, so a post-session note-taker or summarizer works from what was actually said.

Backwards Compatible

Existing pre_tool_use / post_tool_use hooks need zero changes. Claude Code imports now round-trip prompt, agent, and Stop hook types instead of silently dropping them.