fix(cursor): require every documented subagent envelope field and validate author.email with the pinned format

Addresses the second Codex review round on #375:
- subagentStart: parent_conversation_id, tool_call_id, subagent_model, and
  is_parallel_worker are required (only git_branch is documented optional) in
  both the route envelope validator and the generated wrapper validator.
- subagentStop: task, description, summary, duration_ms, message_count,
  tool_call_count, modified_files, and agent_transcript_path (string|null) are
  required to match the documented input, which marks no field optional.
- Simulation encoders carry neutral values for the mandatory fields canonical
  input lacks so hook simulation still passes the tightened validators.
- author.email goes through the pinned schema's format: email checker so
  values like dev@example..com fail closed as cursor.manifest.author.email.invalid.

Author: ScriptedAlchemy

packages/agent-bundle/src/adapters/cursor.ts

@@ -111,11 +111,13 @@ const validateMcp = validator.compile(mcpSchema);
 const validateHooks = validator.compile(hooksSchema);
 const validateMarketplace = validator.compile(marketplaceSchema);
 /**
- * The exact `format: "uri"` check the pinned plugin schema applies to
- * `homepage`/`repository`, so metadata is validated as the string that will
- * be emitted rather than as the normalized form `new URL()` would accept.
+ * The exact `format: "uri"` / `format: "email"` checks the pinned plugin
+ * schema applies to `homepage`/`repository` and `author.email`, so metadata is
+ * validated as the string that will be emitted rather than through a looser
+ * local approximation (`new URL()` normalizes; a hand regex admits `a@b..c`).
  */
 const validateSchemaUri = validator.compile({ type: 'string', format: 'uri' });
+const validateSchemaEmail = validator.compile({ type: 'string', format: 'email' });
 
 /** The pinned Cursor document validators, shared with the unified bundle adapter. */
 export const cursorPluginValidator = validatePlugin;
@@ -310,7 +312,7 @@ const isAbsoluteUrl = (value: unknown): value is string => {
 };
 
 const isEmail = (value: unknown): value is string =>
-  isNonemptyString(value) && /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(value);
+  isNonemptyString(value) && validateSchemaEmail(value) === true;
 
 const isNonemptyStringArray = (value: unknown): value is readonly string[] =>
   Array.isArray(value) && value.every(isNonemptyString);
@@ -387,7 +389,7 @@ export const planCursorManifestMetadata = (
         diagnostics.push(errorDiagnostic(`${codePrefix}.manifest.author.name.invalid`, 'Cursor author.name must be a nonempty string.'));
       }
       if (author['email'] !== undefined && !isEmail(author['email'])) {
-        diagnostics.push(errorDiagnostic(`${codePrefix}.manifest.author.email.invalid`, 'Cursor author.email must be a valid email address.'));
+        diagnostics.push(errorDiagnostic(`${codePrefix}.manifest.author.email.invalid`, "Cursor author.email must be an email address the pinned schema's email format admits."));
       }
       if (extra.length === 0 && isNonemptyString(author['name']) && (author['email'] === undefined || isEmail(author['email']))) {
         document['author'] = Object.freeze({

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

@@ -534,21 +534,32 @@ export const encodeCursorPlaygroundInput = (
   // 2026-09-02): Cursor names the subagent fields subagent_* and reports the
   // completion summary and follow-up loop count instead of Claude's
   // last_assistant_message / stop_hook_active pair.
+  // Every documented field except git_branch is required, so the simulated
+  // envelope carries neutral values for the ones canonical input lacks.
   ...(nativeEvent === 'subagentStart'
     ? {
+        is_parallel_worker: false,
+        parent_conversation_id: input.sessionId,
         subagent_id: input.agentId,
+        subagent_model: input.model ?? '',
         subagent_type: input.agentType,
         task: '',
-        tool_call_id: input.toolUseId,
+        tool_call_id: input.toolUseId ?? '',
       }
     : {}),
   ...(nativeEvent === 'subagentStop'
     ? {
         agent_transcript_path: input.agentTranscriptPath ?? null,
+        description: '',
+        duration_ms: 0,
         loop_count: input.stopHookActive === true ? 1 : 0,
+        message_count: 0,
+        modified_files: [],
         status: 'completed',
         subagent_type: input.agentType,
-        summary: input.lastAssistantMessage,
+        summary: input.lastAssistantMessage ?? '',
+        task: '',
+        tool_call_count: 0,
       }
     : {}),
   session_id: input.sessionId,
@@ -771,8 +782,8 @@ export const cursorHookWrapperSource = (entry: TargetHookWrapper): string => [
   '  cwd: canonicalInput.cwd,',
   '  hook_event_name: nativeEvent,',
   '  ...(canonicalEvent === "stop" ? { loop_count: canonicalInput.stopHookActive === true ? 1 : 0, status: "completed" } : {}),',
-  '  ...(canonicalEvent === "agentStart" ? { subagent_id: canonicalInput.agentId, subagent_type: canonicalInput.agentType, task: "", tool_call_id: canonicalInput.toolUseId } : {}),',
-  '  ...(canonicalEvent === "agentStop" ? { agent_transcript_path: canonicalInput.agentTranscriptPath ?? null, loop_count: canonicalInput.stopHookActive === true ? 1 : 0, status: "completed", subagent_type: canonicalInput.agentType, summary: canonicalInput.lastAssistantMessage } : {}),',
+  '  ...(canonicalEvent === "agentStart" ? { is_parallel_worker: false, parent_conversation_id: canonicalInput.sessionId, subagent_id: canonicalInput.agentId, subagent_model: canonicalInput.model ?? "", subagent_type: canonicalInput.agentType, task: "", tool_call_id: canonicalInput.toolUseId ?? "" } : {}),',
+  '  ...(canonicalEvent === "agentStop" ? { agent_transcript_path: canonicalInput.agentTranscriptPath ?? null, description: "", duration_ms: 0, loop_count: canonicalInput.stopHookActive === true ? 1 : 0, message_count: 0, modified_files: [], status: "completed", subagent_type: canonicalInput.agentType, summary: canonicalInput.lastAssistantMessage ?? "", task: "", tool_call_count: 0 } : {}),',
   '  session_id: canonicalInput.sessionId,',
   '  ...(subagentEvent ? {} : { tool_input: canonicalInput.toolInput, tool_name: canonicalInput.toolName, tool_use_id: canonicalInput.toolUseId }),',
   '  ...(canonicalEvent === "afterTool" && canonicalInput.toolResponse !== undefined ? { tool_output: JSON.stringify(canonicalInput.toolResponse) } : {}),',
@@ -833,15 +844,19 @@ export const cursorHookWrapperSource = (entry: TargetHookWrapper): string => [
   '    return;',
   '  }',
   '  if (canonicalEvent === "agentStart") {',
-  '    requireString(input, "subagent_id");',
-  '    requireString(input, "subagent_type");',
-  '    requireString(input, "task");',
+  '    for (const field of ["subagent_id", "subagent_type", "task", "parent_conversation_id", "tool_call_id", "subagent_model"]) requireString(input, field);',
+  '    if (typeof input.is_parallel_worker !== "boolean") fail("native is_parallel_worker must be a boolean");',
+  '    if (input.git_branch !== undefined) requireString(input, "git_branch");',
   '    return;',
   '  }',
   '  if (canonicalEvent === "agentStop") {',
-  '    requireString(input, "subagent_type");',
+  '    for (const field of ["subagent_type", "task", "description", "summary"]) requireString(input, field);',
   '    if (!["completed", "error", "aborted"].includes(input.status)) fail("native subagentStop status is invalid");',
-  '    if (typeof input.loop_count !== "number") fail("native subagentStop loop_count must be a number");',
+  '    for (const field of ["duration_ms", "message_count", "tool_call_count", "loop_count"]) {',
+  '      if (typeof input[field] !== "number") fail(`native subagentStop ${field} must be a number`);',
+  '    }',
+  '    if (!Array.isArray(input.modified_files) || !input.modified_files.every((file) => typeof file === "string")) fail("native modified_files must be an array of strings");',
+  '    if (input.agent_transcript_path !== null && typeof input.agent_transcript_path !== "string") fail("native agent_transcript_path must be a string or null");',
   '    return;',
   '  }',
   '  if (typeof input.loop_count !== "number") fail("native stop loop_count must be a number");',

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

@@ -185,37 +185,37 @@ export const validateNativeEventEnvelope = (
     }
     if (canonicalEvent === 'agent/start') {
       // https://cursor.com/docs/hooks#subagentstart (retrieved 2026-09-02).
+      // Only git_branch is documented "(optional)"; every other field is required.
       requireNativeString(native, 'subagent_id');
       requireNativeString(native, 'subagent_type');
       requireNativeStringValue(native, 'task');
-      for (const field of ['parent_conversation_id', 'tool_call_id', 'subagent_model', 'git_branch']) {
-        if (Object.hasOwn(native, field)) requireNativeStringValue(native, field);
-      }
-      if (Object.hasOwn(native, 'is_parallel_worker')) requireNativeBoolean(native, 'is_parallel_worker');
+      requireNativeString(native, 'parent_conversation_id');
+      requireNativeString(native, 'tool_call_id');
+      requireNativeStringValue(native, 'subagent_model');
+      requireNativeBoolean(native, 'is_parallel_worker');
+      if (Object.hasOwn(native, 'git_branch')) requireNativeStringValue(native, 'git_branch');
     }
     if (canonicalEvent === 'agent/stop') {
       // https://cursor.com/docs/hooks#subagentstop (retrieved 2026-09-02).
       requireNativeString(native, 'subagent_type');
       if (!['completed', 'error', 'aborted'].includes(String(native.status))) {
         return nativeEventError('native status is invalid');
       }
+      // The documented subagentStop input marks no field optional;
+      // agent_transcript_path is `string | null`.
       for (const field of ['task', 'description', 'summary']) {
-        if (Object.hasOwn(native, field)) requireNativeStringValue(native, field);
+        requireNativeStringValue(native, field);
       }
       for (const field of ['duration_ms', 'message_count', 'tool_call_count']) {
-        if (Object.hasOwn(native, field)) requireNativeNumber(native, field);
+        requireNativeNumber(native, field);
       }
       requireNativeNumber(native, 'loop_count');
-      if (
-        Object.hasOwn(native, 'modified_files')
-        && (!Array.isArray(native.modified_files) || !native.modified_files.every((file) => typeof file === 'string'))
-      ) {
+      if (!Array.isArray(native.modified_files) || !native.modified_files.every((file) => typeof file === 'string')) {
         return nativeEventError('native modified_files must be an array of strings');
       }
       if (
-        Object.hasOwn(native, 'agent_transcript_path')
-        && native.agent_transcript_path !== null
-        && typeof native.agent_transcript_path !== 'string'
+        !Object.hasOwn(native, 'agent_transcript_path')
+        || (native.agent_transcript_path !== null && typeof native.agent_transcript_path !== 'string')
       ) {
         return nativeEventError('native agent_transcript_path must be a string or null');
       }

packages/agent-bundle/tests/cursor-adapter.test.ts

@@ -276,13 +276,22 @@ it('rejects cursor URLs that new URL() would normalize but the pinned uri format
     expect(manifest).not.toHaveProperty('homepage');
     expect(manifest).not.toHaveProperty('repository');
   }
+  // author.email goes through the same pinned `format: "email"` checker; a
+  // hand regex would admit the doubled dot and defer the failure to the
+  // generic schema pass.
+  const doubledDot = withCursorConfig({ author: { email: 'dev@example..com', name: 'Example' } });
+  expect(cursorAdapter.plan(doubledDot).diagnostics.map((diagnostic) => diagnostic.code))
+    .toEqual(['cursor.manifest.author.email.invalid']);
+  expect(JSON.parse(writeContents(doubledDot)['.cursor-plugin/plugin.json']!)).not.toHaveProperty('author');
   const exact = withCursorConfig({
+    author: { email: 'dev@example.com', name: 'Example' },
     homepage: 'https://example.test',
     repository: 'https://EXAMPLE.test/a%2Fb?ref=main#readme',
   });
   const plan = cursorAdapter.plan(exact);
   expect(plan.diagnostics).toEqual([]);
   const manifest = JSON.parse(writeContents(exact)['.cursor-plugin/plugin.json']!) as Record<string, unknown>;
+  expect(manifest['author']).toEqual({ email: 'dev@example.com', name: 'Example' });
   expect(manifest['homepage']).toBe('https://example.test');
   expect(manifest['repository']).toBe('https://EXAMPLE.test/a%2Fb?ref=main#readme');
 });

packages/agent-bundle/tests/event-project.test.ts

@@ -132,6 +132,19 @@ it('validates the documented Cursor subagentStart and subagentStop envelopes fai
     .toThrow(/native subagent_id must be a nonempty string/u);
   expect(() => validateNativeEventEnvelope({ ...start, is_parallel_worker: 'no' }, startOptions))
     .toThrow(/native is_parallel_worker must be a boolean/u);
+  // Only git_branch is documented "(optional)"; every other field must be present.
+  const { git_branch: _gitBranch, ...withoutGitBranch } = start;
+  expect(validateNativeEventEnvelope(withoutGitBranch, startOptions)).toBe(withoutGitBranch);
+  for (const [field, message] of [
+    ['parent_conversation_id', 'native parent_conversation_id must be a nonempty string'],
+    ['tool_call_id', 'native tool_call_id must be a nonempty string'],
+    ['subagent_model', 'native subagent_model must be a string'],
+    ['is_parallel_worker', 'native is_parallel_worker must be a boolean'],
+    ['task', 'native task must be a string'],
+  ] as const) {
+    const { [field]: _omitted, ...missing } = start;
+    expect(() => validateNativeEventEnvelope(missing, startOptions)).toThrow(message);
+  }
   // Claude's agent_id/agent_type spelling is not the Cursor envelope.
   expect(() => validateNativeEventEnvelope({
     agent_id: 'abc-123',
@@ -166,6 +179,20 @@ it('validates the documented Cursor subagentStart and subagentStop envelopes fai
     .toThrow(/native modified_files must be an array of strings/u);
   expect(() => validateNativeEventEnvelope({ ...stop, agent_transcript_path: 7 }, stopOptions))
     .toThrow(/native agent_transcript_path must be a string or null/u);
+  // The documented subagentStop input marks no field optional.
+  for (const [field, message] of [
+    ['task', 'native task must be a string'],
+    ['description', 'native description must be a string'],
+    ['summary', 'native summary must be a string'],
+    ['duration_ms', 'native duration_ms must be a number'],
+    ['message_count', 'native message_count must be a number'],
+    ['tool_call_count', 'native tool_call_count must be a number'],
+    ['modified_files', 'native modified_files must be an array of strings'],
+    ['agent_transcript_path', 'native agent_transcript_path must be a string or null'],
+  ] as const) {
+    const { [field]: _omitted, ...missing } = stop;
+    expect(() => validateNativeEventEnvelope(missing, stopOptions)).toThrow(message);
+  }
 });
 
 it('validates prompt/submit and session/end host envelopes fail closed', () => {

packages/agent-bundle/tests/hooks.test.ts

@@ -1323,10 +1323,41 @@ it('round-trips the documented Cursor subagent envelopes through published Curso
       stderr: 'Agent Bundle hook error: native subagentStop status is invalid\n',
       stdout: '',
     });
+    // Every documented field except git_branch is mandatory: a malformed
+    // envelope must fail closed before the handler runs with undefined fields.
+    const { git_branch: _gitBranch, ...startWithoutGitBranch } = startInput;
+    await expect(runNativeHook(join(outputRoot, 'cursor', 'hooks', 'subagent-start.mjs'), startWithoutGitBranch))
+      .resolves.toMatchObject({ code: 0, stderr: '' });
+    for (const [field, message] of [
+      ['tool_call_id', 'native tool_call_id must be a string'],
+      ['parent_conversation_id', 'native parent_conversation_id must be a string'],
+      ['subagent_model', 'native subagent_model must be a string'],
+      ['is_parallel_worker', 'native is_parallel_worker must be a boolean'],
+    ] as const) {
+      const { [field]: _omitted, ...missing } = startInput;
+      await expect(runNativeHook(join(outputRoot, 'cursor', 'hooks', 'subagent-start.mjs'), missing)).resolves.toEqual({
+        code: 1,
+        stderr: `Agent Bundle hook error: ${message}\n`,
+        stdout: '',
+      });
+    }
+    for (const [field, message] of [
+      ['description', 'native description must be a string'],
+      ['duration_ms', 'native subagentStop duration_ms must be a number'],
+      ['modified_files', 'native modified_files must be an array of strings'],
+      ['agent_transcript_path', 'native agent_transcript_path must be a string or null'],
+    ] as const) {
+      const { [field]: _omitted, ...missing } = stopInput;
+      await expect(runNativeHook(join(outputRoot, 'cursor', 'hooks', 'subagent-stop.mjs'), missing)).resolves.toEqual({
+        code: 1,
+        stderr: `Agent Bundle hook error: ${message}\n`,
+        stdout: '',
+      });
+    }
   } finally {
     await rm(root, { force: true, recursive: true });
   }
-}, 15_000);
+}, 30_000);
 
 it('rejects malformed event-specific native input before calling generated Codex and Claude hooks', async () => {
   const root = await mkdtemp(join(tmpdir(), 'agent-bundle-hooks-native-input-'));