v1.0.0 to v1.0.0

+ ## Subagent Lifecycle Management

+

+ Managing subagents spawned from plugins requires careful attention to timeouts, abort handling, and cleanup to prevent runaway processes.

+

+ ### Spawning Subagents

+

+ Use `ctx.client.session.create` with subagent configuration:

+

+ ```typescript

+ const subagent = await ctx.client.session.create({

+ parentID: ctx.session.id,

+ agent: "fixer",

+ message: "Fix the failing tests in auth.ts",

+ })

+ ### Timer-Based Abort

+

+ The critical pattern for preventing runaway subagents:

+

+ ```typescript

+ const TIMEOUT_MS = 60000 // 60 seconds

+

+ const subagent = await ctx.client.session.create({

+ parentID: ctx.session.id,

+ agent: "fixer",

+ message: "Fix failing tests",

+ })

+

+ const timer = setTimeout(async () => {

+ try {

+ await ctx.client.session.abort({ id: subagent.id })

+ ctx.logger.warn(`Subagent ${subagent.id} aborted after timeout`)

+ } catch (error) {

+ ctx.logger.error(`Failed to abort subagent: ${error}`)

+ }

+ }, TIMEOUT_MS)

+

+ // Clear timer when subagent completes

+ ctx.client.session.subscribe(subagent.id, (event) => {

+ if (event.type === "session.end" || event.type === "session.error") {

+ clearTimeout(timer)

+ }

+ })

+ ```

+

+ ### Abort API

+

+ Use `ctx.client.session.abort({ id })` to terminate a subagent:

+

+ ```typescript

+ try {

+ await ctx.client.session.abort({ id: subagent.id })

+ ctx.logger.info(`Subagent ${subagent.id} aborted successfully`)

+ } catch (error) {

+ // Abort may throw if session already ended

+ ctx.logger.warn(`Subagent ${subagent.id} already ended: ${error}`)

+ }

+ ```

+

+ ### State Polling

+

+ Check subagent status:

+

+ ```typescript

+ const status = await ctx.client.session.get({ id: subagent.id })

+ if (status.status === "completed") {

+ // Process results

+ const messages = await ctx.client.session.messages({ id: subagent.id })

+ // ... process messages

+ } else if (status.status === "running") {

+ // Still working

+ } else if (status.status === "aborted") {

+ // Was terminated

+ }

+ ```

+

+ ### Cleanup on Abort

+

+ When a subagent is aborted mid-execution, clean up resources:

+

+ ```typescript

+ async function spawnWithCleanup(ctx: any, config: SubagentConfig) {

+ const subagent = await ctx.client.session.create(config)

+ const tempFiles: string[] = []

+

+ // Register cleanup handler

+ const cleanup = async () => {

+ for (const file of tempFiles) {

+ await ctx.client.fs.remove({ path: file }).catch(() => {})

+ }

+ }

+

+ ctx.client.session.subscribe(subagent.id, async (event) => {

+ if (event.type === "session.end" || event.type === "session.error" || event.type === "session.aborted") {

+ await cleanup()

+ }

+ })

+

+ return { subagent, cleanup }

+ }

+ ```

+

+ ### Common Pitfalls

+

+ | Issue | Cause | Solution |

+ |-------|-------|----------|

+ | Subagent hangs forever | No timeout set | Always set a timer with abort |

+ | Timer fires after completion | Not cleared on success | Clear timer in completion handler |

+ | Abort throws | Session already ended | Wrap abort in try/catch |

+ | Parent waits forever | No abort on parent exit | Register cleanup handler on parent end |

+

+ ## Event Handler Patterns

+

+ Event handlers are critical for plugins that need to react to AI behavior, especially for auto-resume and tool-call interception.

+

+ ### Handler Registration

+

+ Use `handleEvent` pattern for subscribing to specific event types:

+

+ ```typescript

+ export const handleEvent: Plugin.EventHandler = async (ctx, event) => {

+ // Only handle events we care about

+ if (event.type !== "message.part") return

+

+ // Process the event

+ const part = event.properties.part

+ // ...

+ }

+ ```

+

+ ### checkForToolCallAsText

+

+ Detecting tool calls embedded in assistant text output. This pattern is used by auto-resume plugins to intercept when the AI tries to call a tool by writing it as text instead of using the tool API:

+

+ ```typescript

+ function checkForToolCallAsText(text: string): ToolCall | null {

+ // Pattern: AI writes tool call as text instead of using tool API

+ // Look for patterns like JSON tool calls or function call syntax

+

+ const toolCallPattern = /```(?:json)?\s*(\{[^}]*"tool"[^}]*\})\s*```/

+ const match = text.match(toolCallPattern)

+ if (!match) return null

+

+ try {

+ const parsed = JSON.parse(match[1])

+ if (parsed.tool && parsed.parameters) {

+ return {

+ name: parsed.tool,

+ parameters: parsed.parameters,

+ }

+ }

+ } catch (e) {

+ return null

+ }

+ return null

+ }

+

+ export const handleEvent: Plugin.EventHandler = async (ctx, event) => {

+ if (event.type !== "message.part") return

+

+ const part = event.properties.part

+ if (part.type !== "text") return

+

+ const toolCall = checkForToolCallAsText(part.text)

+ if (toolCall) {

+ // Intercept and execute the tool call properly

+ ctx.logger.info(`Detected tool call in text: ${toolCall.name}`)

+ await ctx.client.tool.execute({

+ name: toolCall.name,

+ parameters: toolCall.parameters,

+ })

+ }

+ }

+ ```

+

+ ### Event Dispatch Flow

+

+ Events flow from source → bus → handlers:

+ 1. Event is published to the bus

+ 2. All registered handlers are called in priority order

+ 3. Handlers should not throw (breaks dispatch chain)

+ 4. Use `event.properties.source` to filter own events

+

+ ### Error Handling in Handlers

+

+ Wrap handler body in try/catch - never throw:

+

+ ```typescript

+ export const handleEvent: Plugin.EventHandler = async (ctx, event) => {

+ try {

+ // Handler logic

+ if (event.type !== "message.part") return

+ const part = event.properties.part

+ // ... process event

+ } catch (error) {

+ ctx.logger.error(`Handler failed: ${error}`)

+ // Don't rethrow — it breaks the event dispatch chain

+ }

+ }

+ ```

+

+ ### Testing Event Handlers

+

+ Test handlers with mock events:

+

+ ```typescript

+ import { describe, it, expect, vi } from 'vitest'

+

+ describe('checkForToolCallAsText', () => {

+ it('detects JSON tool call in code block', () => {

+ const text = 'Here is the tool call:\n```json\n{"tool":"read_file","parameters":{"path":"test.ts"}}\n```'

+ const result = checkForToolCallAsText(text)

+ expect(result).not.toBeNull()

+ expect(result!.name).toBe('read_file')

+ })

+

+ it('returns null for plain text', () => {

+ expect(checkForToolCallAsText('just some text')).toBeNull()

+ })

+ })

+

+ describe('handleEvent', () => {

+ it('processes message.part events', async () => {

+ const mockCtx = { client: { tool: { execute: vi.fn() } }, logger: { info: vi.fn() } }

+ const event = {

+ type: 'message.part',

+ properties: { part: { type: 'text', text: '```json\n{"tool":"read","parameters":{}}\n```' } }

+ }

+ await handleEvent(mockCtx as any, event as any)

+ expect(mockCtx.client.tool.execute).toHaveBeenCalled()

+ })

+ })

+ ```

+

+ ### Common Pitfalls

+

+ | Issue | Cause | Solution |

+ |-------|-------|----------|

+ | Handler not called | Wrong event type check | Verify event.type matches exactly |

+ | Event dispatch breaks | Handler throws | Wrap handler body in try/catch |

+ | Duplicate tool execution | Handler + tool API both fire | Use checkForToolCallAsText to intercept only text-based calls |

+ | Handler runs on own events | No source filter | Check event.properties.source !== "self" |

+

+ 4. **Subagent hangs forever**: No timeout set on spawned subagents

+ 5. **Event handler crashes**: Handlers throwing errors instead of catching them