feat(events): promote lifecycle observation families (#258 v2 s4) (#359)

Author: ScriptedAlchemy

.changeset/promote-lifecycle-observation-events.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Promote the `file/change`, `config/change`, `task/create`, `task/complete`, and `agent/idle` canonical event-route families as Claude-only capabilities with their documented decision channels: `config/change` and `task/create` project deny as a top-level block decision, `agent/idle` projects deny as `continue: false` with a stop reason, while `file/change` and `task/complete` are observation-only with fail-closed errors explaining the host's side-effect-only and exit-code-only control models. Codex, Cursor, and portable carry dated `unavailable` rows per family.

examples/rsc-agent-runtime/README.md

@@ -241,6 +241,11 @@ Host/Origin allowlists mitigate DNS rebinding and cross-origin requests, but the
 | `permission/denied` | Unavailable | `PermissionDenied` (observe-only) | Unavailable |
 | `stop` | Supported | `Stop` | `Stop` |
 | `stop/failure` | Unavailable | `StopFailure` (observe-only) | Unavailable |
+| `file/change` | Unavailable (agent-edit `afterFileEdit` stays a `tool/after` variant) | `FileChanged` (observe-only) | Unavailable |
+| `config/change` | Unavailable | `ConfigChange` (deny) | Unavailable |
+| `task/create` | Unavailable | `TaskCreated` (deny) | Unavailable |
+| `task/complete` | Unavailable | `TaskCompleted` (observe-only; blocking is exit-code-only) | Unavailable |
+| `agent/idle` | Unavailable | `TeammateIdle` (deny via continue:false) | Unavailable |
 | `agent/start` | `subagentStart` | `SubagentStart` | `SubagentStart` |
 | `agent/stop` | `subagentStop` | `SubagentStop` | `SubagentStop` |
 | `workspace/open` | Supported (observe-only; native `pluginPaths` return not modeled) | Unavailable | Unavailable |

packages/agent-bundle/src/adapters/capabilities/claude-2.1.250.json

@@ -23,17 +23,22 @@
       "stop": "Stop"
     },
     "eventRoutes": {
+      "agent/idle": { "nativeEvent": "TeammateIdle", "state": "supported" },
       "agent/start": { "nativeEvent": "SubagentStart", "state": "supported" },
       "agent/stop": { "nativeEvent": "SubagentStop", "state": "supported" },
       "compact/after": { "nativeEvent": "PostCompact", "state": "supported" },
       "compact/before": { "nativeEvent": "PreCompact", "state": "supported" },
+      "config/change": { "nativeEvent": "ConfigChange", "state": "supported" },
+      "file/change": { "nativeEvent": "FileChanged", "state": "supported" },
       "permission/denied": { "nativeEvent": "PermissionDenied", "state": "supported" },
       "permission/request": { "nativeEvent": "PermissionRequest", "state": "supported" },
       "prompt/submit": { "nativeEvent": "UserPromptSubmit", "state": "supported" },
       "session/end": { "nativeEvent": "SessionEnd", "state": "supported" },
       "session/start": { "nativeEvent": "SessionStart", "state": "supported" },
       "stop": { "nativeEvent": "Stop", "state": "supported" },
       "stop/failure": { "nativeEvent": "StopFailure", "state": "supported" },
+      "task/complete": { "nativeEvent": "TaskCompleted", "state": "supported" },
+      "task/create": { "nativeEvent": "TaskCreated", "state": "supported" },
       "tool/after": { "nativeEvent": "PostToolUse", "state": "supported" },
       "tool/before": { "nativeEvent": "PreToolUse", "state": "supported" },
       "tool/failure": { "nativeEvent": "PostToolUseFailure", "state": "supported" },

packages/agent-bundle/src/adapters/capabilities/codex-0.147.0.json

@@ -23,10 +23,22 @@
       "stop": "Stop"
     },
     "eventRoutes": {
+      "agent/idle": {
+        "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no teammate-idle event.",
+        "state": "unavailable"
+      },
       "agent/start": { "nativeEvent": "SubagentStart", "state": "supported" },
       "agent/stop": { "nativeEvent": "SubagentStop", "state": "supported" },
       "compact/after": { "nativeEvent": "PostCompact", "state": "supported" },
       "compact/before": { "nativeEvent": "PreCompact", "state": "supported" },
+      "config/change": {
+        "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no config-change event.",
+        "state": "unavailable"
+      },
+      "file/change": {
+        "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no file-changed event.",
+        "state": "unavailable"
+      },
       "permission/denied": {
         "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no permission-denied event.",
         "state": "unavailable"
@@ -40,6 +52,14 @@
         "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no stop-failure event.",
         "state": "unavailable"
       },
+      "task/complete": {
+        "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no task-completed event.",
+        "state": "unavailable"
+      },
+      "task/create": {
+        "reason": "retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no task-created event.",
+        "state": "unavailable"
+      },
       "tool/after": { "nativeEvent": "PostToolUse", "state": "supported" },
       "tool/before": { "nativeEvent": "PreToolUse", "state": "supported" },
       "tool/failure": {

packages/agent-bundle/src/adapters/capabilities/cursor-2026-08-28.json

@@ -23,13 +23,25 @@
       "stop": "stop"
     },
     "eventRoutes": {
+      "agent/idle": {
+        "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no teammate-idle event.",
+        "state": "unavailable"
+      },
       "agent/start": { "nativeEvent": "subagentStart", "state": "supported" },
       "agent/stop": { "nativeEvent": "subagentStop", "state": "supported" },
       "compact/after": {
         "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no postCompact event.",
         "state": "unavailable"
       },
       "compact/before": { "nativeEvent": "preCompact", "state": "supported" },
+      "config/change": {
+        "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no configChange event.",
+        "state": "unavailable"
+      },
+      "file/change": {
+        "reason": "retrieved 2026-09-02: Cursor documents afterFileEdit as an agent-edit tool variant that overlaps canonical tool/after per the #258 selector rule, not a disk-watch FileChanged equivalent; no dedicated family is inferred without fixture evidence of loss.",
+        "state": "unavailable"
+      },
       "permission/denied": {
         "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no permission-denied event.",
         "state": "unavailable"
@@ -56,6 +68,14 @@
         "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no stop-failure event.",
         "state": "unavailable"
       },
+      "task/complete": {
+        "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no taskCompleted event.",
+        "state": "unavailable"
+      },
+      "task/create": {
+        "reason": "retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no taskCreated event.",
+        "state": "unavailable"
+      },
       "tool/after": { "nativeEvent": "postToolUse", "state": "supported" },
       "tool/before": { "nativeEvent": "preToolUse", "state": "supported" },
       "tool/failure": { "nativeEvent": "postToolUseFailure", "state": "supported" },

packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json

@@ -10,6 +10,10 @@
     "state": "unavailable"
   },
   "eventRoutes": {
+    "agent/idle": {
+      "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TeammateIdle equivalent (https://agent-plugins.org/).",
+      "state": "unavailable"
+    },
     "agent/start": { "reason": "Agent Plugins 1.0.0 does not define hooks.", "state": "unavailable" },
     "agent/stop": { "reason": "Agent Plugins 1.0.0 does not define hooks.", "state": "unavailable" },
     "compact/after": {
@@ -20,6 +24,14 @@
       "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PreCompact/preCompact equivalent (https://agent-plugins.org/).",
       "state": "unavailable"
     },
+    "config/change": {
+      "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native ConfigChange equivalent (https://agent-plugins.org/).",
+      "state": "unavailable"
+    },
+    "file/change": {
+      "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native FileChanged equivalent (https://agent-plugins.org/).",
+      "state": "unavailable"
+    },
     "permission/denied": {
       "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PermissionDenied equivalent (https://agent-plugins.org/).",
       "state": "unavailable"
@@ -42,6 +54,14 @@
       "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native StopFailure equivalent (https://agent-plugins.org/).",
       "state": "unavailable"
     },
+    "task/complete": {
+      "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TaskCompleted equivalent (https://agent-plugins.org/).",
+      "state": "unavailable"
+    },
+    "task/create": {
+      "reason": "2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TaskCreated equivalent (https://agent-plugins.org/).",
+      "state": "unavailable"
+    },
     "tool/after": { "reason": "Agent Plugins 1.0.0 does not define hooks.", "state": "unavailable" },
     "tool/before": { "reason": "Agent Plugins 1.0.0 does not define hooks.", "state": "unavailable" },
     "tool/failure": {

packages/agent-bundle/src/adapters/hook-contract.ts

@@ -255,6 +255,30 @@ export const createNativeEventStarter = (
         last_assistant_message: null,
         stop_hook_active: false,
       });
+    case 'file/change':
+      return deepFreeze({ ...base, file_path: '/tmp/lifecycle-replay-watched.txt' });
+    case 'config/change':
+      return deepFreeze({ ...base, file_path: '/tmp/lifecycle-replay-settings.json', source: 'project_settings' });
+    case 'task/create':
+      return deepFreeze({
+        ...base,
+        task_id: 'lifecycle-replay-task',
+        task_subject: 'Lifecycle replay task.',
+      });
+    case 'task/complete':
+      return deepFreeze({
+        ...base,
+        permission_mode: 'default',
+        task_id: 'lifecycle-replay-task',
+        task_subject: 'Lifecycle replay task.',
+      });
+    case 'agent/idle':
+      return deepFreeze({
+        ...base,
+        permission_mode: 'default',
+        team_name: 'lifecycle-replay-team',
+        teammate_name: 'lifecycle-replay-teammate',
+      });
     case 'workspace/open':
       return deepFreeze(target === 'cursor'
         ? {

packages/agent-bundle/src/config/normalize.ts

@@ -116,6 +116,11 @@ const hookEventForRoute: Readonly<Record<CanonicalAgentEvent, NormalizedHookEven
   'permission/request': 'permissionRequest',
   'permission/denied': 'permissionDenied',
   'stop/failure': 'stopFailure',
+  'file/change': 'fileChange',
+  'config/change': 'configChange',
+  'task/create': 'taskCreate',
+  'task/complete': 'taskComplete',
+  'agent/idle': 'agentIdle',
   'workspace/open': 'workspaceOpen',
 });
 

packages/agent-bundle/src/core/types.ts

@@ -49,6 +49,11 @@ export const eventRouteOnlyHookEvents = Object.freeze([
   'permissionRequest',
   'permissionDenied',
   'stopFailure',
+  'fileChange',
+  'configChange',
+  'taskCreate',
+  'taskComplete',
+  'agentIdle',
 ] as const);
 
 export type EventRouteOnlyHookEvent = (typeof eventRouteOnlyHookEvents)[number];

packages/agent-bundle/src/events/projection.ts

@@ -246,6 +246,24 @@ export const validateNativeEventEnvelope = (
       return nativeEventError('native stop_hook_active must be a boolean');
     }
   }
+  if (canonicalEvent === 'file/change') requireNativeString(native, 'file_path');
+  if (canonicalEvent === 'config/change') {
+    if (!['user_settings', 'project_settings', 'local_settings', 'policy_settings', 'skills'].includes(String(native.source))) {
+      return nativeEventError('native source is invalid');
+    }
+    if (Object.hasOwn(native, 'file_path')) requireNativeString(native, 'file_path');
+  }
+  if (canonicalEvent === 'task/create' || canonicalEvent === 'task/complete') {
+    requireNativeString(native, 'task_id');
+    requireNativeString(native, 'task_subject');
+    for (const field of ['task_description', 'teammate_name', 'team_name']) {
+      if (Object.hasOwn(native, field)) requireNativeString(native, field);
+    }
+  }
+  if (canonicalEvent === 'agent/idle') {
+    requireNativeString(native, 'teammate_name');
+    requireNativeString(native, 'team_name');
+  }
   if (canonicalEvent === 'compact/before' || canonicalEvent === 'compact/after') {
     requireCompactTrigger(native);
     if (target === 'codex') {
@@ -574,6 +592,60 @@ export const projectEventDocument = (
     }
     return undefined;
   }
+  if (event === 'file/change') {
+    if (
+      parsedValue?.outcome === 'deny'
+      || parsedValue?.reason !== undefined
+      || parsedValue?.updatedInput !== undefined
+    ) {
+      throw new TypeError('file/change has no decision control on Claude FileChanged; it is side-effect-only.');
+    }
+    if (additionalContext !== undefined) {
+      throw new TypeError('file/change has no documented context/output channel.');
+    }
+    return undefined;
+  }
+  if (event === 'config/change' || event === 'task/create') {
+    if (parsedValue?.updatedInput !== undefined) {
+      throw new TypeError(`${event} cannot replace native input.`);
+    }
+    if (additionalContext !== undefined) {
+      throw new TypeError(`${event} has no documented additional-context channel.`);
+    }
+    if (parsedValue?.reason !== undefined && parsedValue.outcome !== 'deny') {
+      throw new TypeError(`${event} reason is only valid when outcome is deny.`);
+    }
+    return parsedValue?.outcome === 'deny'
+      ? Object.freeze({ decision: 'block', reason: requireDenyReason() })
+      : undefined;
+  }
+  if (event === 'task/complete') {
+    if (
+      parsedValue?.outcome === 'deny'
+      || parsedValue?.reason !== undefined
+      || parsedValue?.updatedInput !== undefined
+    ) {
+      throw new TypeError('task/complete blocking is exit-code-only on Claude TaskCompleted (JSON continue:false redirects to teammate stop and is ignored for TaskUpdate); it is not projected.');
+    }
+    if (additionalContext !== undefined) {
+      throw new TypeError('task/complete has no documented context/output channel.');
+    }
+    return undefined;
+  }
+  if (event === 'agent/idle') {
+    if (parsedValue?.updatedInput !== undefined) {
+      throw new TypeError('agent/idle cannot replace native input.');
+    }
+    if (additionalContext !== undefined) {
+      throw new TypeError('agent/idle has no documented additional-context channel.');
+    }
+    if (parsedValue?.reason !== undefined && parsedValue.outcome !== 'deny') {
+      throw new TypeError('agent/idle reason is only valid when outcome is deny.');
+    }
+    return parsedValue?.outcome === 'deny'
+      ? Object.freeze({ continue: false, stopReason: requireDenyReason() })
+      : undefined;
+  }
   if (event === 'tool/before') {
     if (target === 'cursor') {
       if (parsedValue?.outcome === 'deny') {