title: Plugin hook lifecycle contracts

scenario:
  id: plugin-hook-contracts
  surface: automation
  category: automation.automation-hooks
  coverage:
    primary:
      - automation.api-on-registration
      - automation.tool-call-policy-hooks
      - automation.message-hooks
      - automation.session-lifecycle-hooks
      - automation.plugin-approval-requests
      - automation.cron-changed
  objective: Verify a real fixture plugin registers and executes typed policy, message, session, approval, and cron hooks through production boundaries.
  successCriteria:
    - The production plugin loader executes api.on registrations for all six typed hook families.
    - Message receive and send hooks observe and modify real hook-runner events.
    - Session start and end hooks receive their lifecycle events from the loaded registry.
    - A cron_changed hook receives the durable job snapshot and scheduling metadata.
    - The before_tool_call policy adjusts parameters and creates an attributed plugin approval request.
    - The embedded approval broker resolves the request and the policy chain returns the approved parameters.
  docsRefs:
    - docs/automation/hooks.md
    - docs/plugins/hooks.md
    - docs/plugins/plugin-permission-requests.md
  codeRefs:
    - src/plugins/loader.ts
    - src/plugins/registry-registrars-tools-hooks.ts
    - src/plugins/hooks.ts
    - src/plugins/hook-runner-global.ts
    - src/agents/agent-tools.before-tool-call.ts
    - src/infra/embedded-plugin-approval-broker.ts
    - src/hooks/plugin-hooks.e2e.test.ts
  execution:
    kind: vitest
    path: src/hooks/plugin-hooks.e2e.test.ts
    summary: Load a real fixture plugin, execute its typed hook boundaries, and resolve its approval request.