[Feature] Add execution hooks for observability and integrations

[bitloi]

Feature Request: Execution Hooks

Summary

Add a hooks system that lets users run custom logic at key points during program execution—without modifying their .prose programs or adding external tooling.

Problem

Right now, there's no clean way to:

• Log what's happening during a run
• Track costs and token usage
• Send notifications when things complete or fail
• Add custom validation before sessions spawn
• Clean up resources after a run finishes

Users either have to manually add logging sessions throughout their programs, or build external monitoring that doesn't understand OpenProse's execution model.

Proposed Solution

Define a hooks.md specification that describes hook points the VM recognizes. Users create a .prose/hooks.prose file with handlers for the events they care about.

Hook Points

Hook	When it fires
on_run_start	Before the program begins executing
on_run_end	After the program finishes (success or failure)
on_session_start	Before spawning each subagent
on_session_end	After a subagent returns
on_error	When an unhandled error occurs
on_parallel_join	When parallel branches complete

Example

# .prose/hooks.prose

on_session_start:
  session "Log to monitoring service"
    context: { agent, prompt, model }

on_run_end:
  if **run failed**:
    session "Send Slack alert about failure"
      context: { error, program_name }
  else:
    session "Post success summary"
      context: { outputs, duration }

How It Works

1. VM checks for .prose/hooks.prose at run start
2. When a hook event occurs, VM executes the matching handler
3. Hook handlers have access to event-specific context (agent name, error details, etc.)
4. Hooks run in the same execution context as the main program
5. Hook failures can be configured to fail the run or just log warnings

Why This Matters

For production use: Teams need visibility into what their programs are doing. Hooks provide that without cluttering the actual workflow logic.

For cost management: An on_session_end hook can track token usage across every session, giving accurate cost data.

For integrations: Hooks are the natural place to connect OpenProse to Slack, PagerDuty, logging services, or custom dashboards.

For debugging: An on_error hook can capture context and state when things go wrong, making issues easier to diagnose.

Design Considerations

Stays LLM-Native

Hooks are defined in .prose syntax, not external code. The LLM reads the hook specification and executes handlers just like any other OpenProse code. No Python, no JavaScript, no external runtime.

Opt-In

Programs work exactly the same without hooks. Users add them when they need observability or integrations.

Composable

Hook handlers can use all normal OpenProse features—agents, parallel blocks, conditionals. A hook could even call imported programs from the registry.

Open Questions

1. Hook execution order: If multiple hooks are defined for the same event, what order do they run?
2. Hook timeouts: Should hooks have a maximum execution time to prevent blocking?
3. Nested hooks: If a hook spawns a session, does that trigger on_session_start again? (Probably not—hooks should be excluded from triggering other hooks.)
4. Global vs local hooks: Should there be user-level hooks in ~/.prose/hooks.prose that apply to all programs?

Implementation

This requires:

1. A new skills/open-prose/hooks.md specification document
2. Updates to prose.md to describe hook loading and execution
3. Possibly new syntax for hook definitions (or reuse existing block syntax)

No external tooling or code changes needed—just markdown specifications that the LLM reads.

@irl-dan Please review the issue and let me know if I can open a PR for the feature.