feat: emit session_ready & tools_resolve event with session object

[NovusEdge]

Summary

Add two new lifecycle events that enable extensions to integrate properly with subagent sessions:

1. subagents:session_ready - Fires when an agent's session is created and ready
2. subagents:tools_resolve - Fires before session creation to allow tool injection

Motivation

Extensions like memory/context systems need to:

1. Attach state to the subagent's session when it starts
2. Inject additional tools (e.g., memory tools) into subagent sessions
3. Access the session object to inject context or track activity
4. Clean up when the agent completes

Currently, the existing events (subagents:started, subagents:completed) don't expose the session object or allow tool injection, making this impossible without relying on internal APIs.

Changes

• Emit subagents:session_ready event in agent-manager.ts right after onSessionCreated fires
• Emit subagents:tools_resolve event in agent-runner.ts before session creation
• Add onToolsResolve callback option to SpawnOptions and RunOptions
• Update README to document the new events

Event Payloads

session_ready

{
  id: string;            // agent ID
  type: string;          // subagent type (Explore, Plan, etc.)
  session: AgentSession; // the session object
  record: AgentRecord;   // full record for metadata
}

tools_resolve

{
  type: string;    // subagent type
  tools: any[];    // mutable array - push to inject tools
  agentId: string; // agent ID
}

Use Cases

Context propagation (session_ready)

pi.events.on("subagents:session_ready", ({ id, type, session, record }) => {
  const childHarness = parentHarness.fork({ mode: 'fork', tagPrefix: type });
  session.veilHarness = childHarness;
  trackForMerge(id, childHarness);
});

Tool injection (tools_resolve)

pi.events.on("subagents:tools_resolve", (event) => {
  const veilTools = parentHarness.getTools();
  event.tools.push(...veilTools);
});

Backward Compatibility

This is purely additive - existing code is unaffected. Extensions can opt-in to the new events.

[NovusEdge]

PS: heya! @tintinweb working on a fork of pi with smarter builtins for memory & context mgmt (think smart eviction while the user's still in the loop) and needed this :D

• https://github.com/engrammic-ai/veil

[tintinweb]

happy to add lifecycle events with a minimal proposal attached. for security reasons I cannot accept PRs with package changes or github workflows.

[NovusEdge]

Superseded by #113 - clean version without package.json/workflow changes