fix: forward subagent events to parent event bus in core spawn_subagent tool

The spawner closure in generate() called m.Subagent() without setting
OnEvent, so child events (tool calls, text streaming, reasoning deltas)
were silently discarded. Wire OnEvent to re-emit on the parent's bus,
matching the behavior already present in the extension SpawnSubagent path.

cmd/root.go

@@ -925,7 +925,40 @@ func runNormalMode(ctx context.Context) error {
 				}
 			},
 			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
-				return extensions.SpawnSubagent(config)
+				// In-process subagent via SDK.
+				sdkCfg := kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				}
+				// Bridge SDK events to extension SubagentEvents.
+				if config.OnEvent != nil {
+					sdkCfg.OnEvent = func(e kit.Event) {
+						se := sdkEventToSubagentEvent(e)
+						if se.Type != "" {
+							config.OnEvent(se)
+						}
+					}
+				}
+				result, err := kitInstance.Subagent(ctx, sdkCfg)
+				if result == nil {
+					return nil, &extensions.SubagentResult{Error: err}, err
+				}
+				extResult := &extensions.SubagentResult{
+					Response:  result.Response,
+					Error:     result.Error,
+					SessionID: result.SessionID,
+					Elapsed:   result.Elapsed,
+				}
+				if result.Usage != nil {
+					extResult.Usage = &extensions.SubagentUsage{
+						InputTokens:  result.Usage.InputTokens,
+						OutputTokens: result.Usage.OutputTokens,
+					}
+				}
+				return nil, extResult, err
 			},
 		})
 		kitInstance.EmitSessionStart()
@@ -1086,15 +1119,19 @@ func buildJSONOutput(result *kit.TurnResult, model string) ([]byte, error) {
 		CacheCreationTokens int64 `json:"cache_creation_tokens"`
 	}
 	type jsonEnvelope struct {
-		Response string        `json:"response"`
-		Model    string        `json:"model"`
-		Usage    *jsonUsage    `json:"usage,omitempty"`
-		Messages []jsonMessage `json:"messages"`
+		Response   string        `json:"response"`
+		Model      string        `json:"model"`
+		StopReason string        `json:"stop_reason,omitempty"`
+		SessionID  string        `json:"session_id,omitempty"`
+		Usage      *jsonUsage    `json:"usage,omitempty"`
+		Messages   []jsonMessage `json:"messages"`
 	}
 
 	out := jsonEnvelope{
-		Response: result.Response,
-		Model:    model,
+		Response:   result.Response,
+		Model:      model,
+		StopReason: result.StopReason,
+		SessionID:  result.SessionID,
 	}
 
 	if result.TotalUsage != nil {
@@ -1205,3 +1242,42 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 	_, runErr := program.Run()
 	return runErr
 }
+
+// sdkEventToSubagentEvent converts an SDK event to an extension-facing
+// SubagentEvent. Returns a zero-value event (Type=="") for events that
+// don't map to anything useful.
+func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
+	switch ev := e.(type) {
+	case kit.MessageUpdateEvent:
+		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
+	case kit.ReasoningDeltaEvent:
+		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
+	case kit.ToolCallEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_call", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
+		}
+	case kit.ToolExecutionStartEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolExecutionEndEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolResultEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_result", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+			ToolResult: ev.Result, IsError: ev.IsError,
+		}
+	case kit.TurnStartEvent:
+		return extensions.SubagentEvent{Type: "turn_start"}
+	case kit.TurnEndEvent:
+		return extensions.SubagentEvent{Type: "turn_end"}
+	default:
+		return extensions.SubagentEvent{}
+	}
+}

internal/acpserver/agent.go

@@ -186,7 +186,10 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 			update = &u
 
 		case kit.ToolCallEvent:
-			tcID := acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Add(1)))
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Add(1)))
+			}
 			u := acp.StartToolCall(tcID, ev.ToolName,
 				acp.WithStartStatus(acp.ToolCallStatusInProgress),
 				acp.WithStartRawInput(parseToolArgs(ev.ToolArgs)),
@@ -194,7 +197,10 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 			update = &u
 
 		case kit.ToolResultEvent:
-			tcID := acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Load()))
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Load()))
+			}
 			status := acp.ToolCallStatusCompleted
 			if ev.IsError {
 				status = acp.ToolCallStatusFailed

internal/acpserver/session.go

@@ -6,6 +6,9 @@ import (
 	"strings"
 	"sync"
 
+	"github.com/charmbracelet/log"
+
+	"github.com/mark3labs/kit/internal/extensions"
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
@@ -55,6 +58,147 @@ func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession,
 		return nil, fmt.Errorf("kit instance has no session ID")
 	}
 
+	// Wire extension context with headless implementations so extensions
+	// work in ACP mode. TUI-dependent features (widgets, prompts, editor)
+	// become no-ops or return cancelled; all data/model/tool APIs work
+	// identically to interactive mode.
+	if kitInstance.HasExtensions() {
+		kitInstance.SetExtensionContext(extensions.Context{
+			SessionID:   sessionID,
+			CWD:         cwd,
+			Model:       kitInstance.GetModelString(),
+			Interactive: false,
+
+			// Output — route through structured logger.
+			Print:      func(text string) { log.Debug("extension: print", "text", text) },
+			PrintInfo:  func(text string) { log.Info("extension: info", "text", text) },
+			PrintError: func(text string) { log.Error("extension: error", "text", text) },
+			PrintBlock: func(opts extensions.PrintBlockOpts) {
+				log.Info("extension: block", "subtitle", opts.Subtitle, "text", opts.Text)
+			},
+
+			// Message injection — no-ops for now; ACP clients drive prompts.
+			SendMessage:   func(string) {},
+			CancelAndSend: func(string) {},
+			Exit:          func() {},
+
+			// TUI widgets/chrome — silent no-ops (no TUI in ACP).
+			SetWidget:       func(extensions.WidgetConfig) {},
+			RemoveWidget:    func(string) {},
+			SetHeader:       func(extensions.HeaderFooterConfig) {},
+			RemoveHeader:    func() {},
+			SetFooter:       func(extensions.HeaderFooterConfig) {},
+			RemoveFooter:    func() {},
+			SetEditor:       func(extensions.EditorConfig) {},
+			ResetEditor:     func() {},
+			SetEditorText:   func(string) {},
+			SetUIVisibility: func(extensions.UIVisibility) {},
+			SetStatus:       func(string, string, int) {},
+			RemoveStatus:    func(string) {},
+
+			// Interactive prompts — return cancelled (no user to prompt).
+			PromptSelect: func(extensions.PromptSelectConfig) extensions.PromptSelectResult {
+				return extensions.PromptSelectResult{Cancelled: true}
+			},
+			PromptConfirm: func(extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
+				return extensions.PromptConfirmResult{Cancelled: true}
+			},
+			PromptInput: func(extensions.PromptInputConfig) extensions.PromptInputResult {
+				return extensions.PromptInputResult{Cancelled: true}
+			},
+			ShowOverlay: func(extensions.OverlayConfig) extensions.OverlayResult {
+				return extensions.OverlayResult{Cancelled: true, Index: -1}
+			},
+			SuspendTUI: func(callback func()) error { callback(); return nil },
+
+			// Data access — delegate to Kit instance.
+			GetContextStats: func() extensions.ContextStats {
+				s := kitInstance.GetContextStats()
+				return extensions.ContextStats{
+					EstimatedTokens: s.EstimatedTokens,
+					ContextLimit:    s.ContextLimit,
+					UsagePercent:    s.UsagePercent,
+					MessageCount:    s.MessageCount,
+				}
+			},
+			GetMessages:    func() []extensions.SessionMessage { return kitInstance.GetSessionMessages() },
+			GetSessionPath: func() string { return kitInstance.GetSessionFilePath() },
+			AppendEntry: func(entryType, data string) (string, error) {
+				return kitInstance.AppendExtensionEntry(entryType, data)
+			},
+			GetEntries: func(entryType string) []extensions.ExtensionEntry {
+				return kitInstance.GetExtensionEntries(entryType)
+			},
+
+			// Options, model, and tool management.
+			GetOption: func(name string) string { return kitInstance.GetExtensionOption(name) },
+			SetOption: func(name, value string) { kitInstance.SetExtensionOption(name, value) },
+			SetModel: func(modelString string) error {
+				previousModel := kitInstance.GetExtensionContext().Model
+				if err := kitInstance.SetModel(context.Background(), modelString); err != nil {
+					return err
+				}
+				kitInstance.UpdateExtensionContextModel(modelString)
+				kitInstance.EmitModelChange(modelString, previousModel, "extension")
+				return nil
+			},
+			GetAvailableModels: func() []extensions.ModelInfoEntry { return kitInstance.GetAvailableModels() },
+			EmitCustomEvent:    func(name, data string) { kitInstance.EmitExtensionCustomEvent(name, data) },
+			GetAllTools:        func() []extensions.ToolInfo { return kitInstance.GetExtensionToolInfos() },
+			SetActiveTools:     func(names []string) { kitInstance.SetExtensionActiveTools(names) },
+
+			// LLM completions and subagents.
+			Complete: func(req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
+				return kitInstance.ExecuteCompletion(context.Background(), req)
+			},
+			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+				sdkCfg := kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				}
+				if config.OnEvent != nil {
+					sdkCfg.OnEvent = func(e kit.Event) {
+						se := sdkEventToSubagentEvent(e)
+						if se.Type != "" {
+							config.OnEvent(se)
+						}
+					}
+				}
+				result, err := kitInstance.Subagent(context.Background(), sdkCfg)
+				if result == nil {
+					return nil, &extensions.SubagentResult{Error: err}, err
+				}
+				extResult := &extensions.SubagentResult{
+					Response:  result.Response,
+					Error:     result.Error,
+					SessionID: result.SessionID,
+					Elapsed:   result.Elapsed,
+				}
+				if result.Usage != nil {
+					extResult.Usage = &extensions.SubagentUsage{
+						InputTokens:  result.Usage.InputTokens,
+						OutputTokens: result.Usage.OutputTokens,
+					}
+				}
+				return nil, extResult, err
+			},
+
+			// Render — fall back to logging.
+			RenderMessage: func(name, content string) {
+				renderer := kitInstance.GetExtensionMessageRenderer(name)
+				if renderer != nil && renderer.Render != nil {
+					content = renderer.Render(content, 80)
+				}
+				log.Info("extension: message", "renderer", name, "content", content)
+			},
+			ReloadExtensions: func() error { return kitInstance.ReloadExtensions() },
+		})
+		kitInstance.EmitSessionStart()
+	}
+
 	sess := &acpSession{
 		kit:       kitInstance,
 		cwd:       cwd,
@@ -111,3 +255,40 @@ func (s *acpSession) clearCancel() {
 	defer s.cancelMu.Unlock()
 	s.cancelFn = nil
 }
+
+// sdkEventToSubagentEvent converts an SDK event to an extension SubagentEvent.
+func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
+	switch ev := e.(type) {
+	case kit.MessageUpdateEvent:
+		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
+	case kit.ReasoningDeltaEvent:
+		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
+	case kit.ToolCallEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_call", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
+		}
+	case kit.ToolExecutionStartEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolExecutionEndEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolResultEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_result", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+			ToolResult: ev.Result, IsError: ev.IsError,
+		}
+	case kit.TurnStartEvent:
+		return extensions.SubagentEvent{Type: "turn_start"}
+	case kit.TurnEndEvent:
+		return extensions.SubagentEvent{Type: "turn_end"}
+	default:
+		return extensions.SubagentEvent{}
+	}
+}

internal/agent/agent.go

@@ -41,13 +41,15 @@ type AgentConfig struct {
 }
 
 // ToolCallHandler is a function type for handling tool calls as they happen.
-type ToolCallHandler func(toolName, toolArgs string)
+type ToolCallHandler func(toolCallID, toolName, toolArgs string)
 
 // ToolExecutionHandler is a function type for handling tool execution start/end events.
-type ToolExecutionHandler func(toolName, toolArgs string, isStarting bool)
+type ToolExecutionHandler func(toolCallID, toolName, toolArgs string, isStarting bool)
 
 // ToolResultHandler is a function type for handling tool results.
-type ToolResultHandler func(toolName, toolArgs, result string, isError bool)
+// The metadata parameter carries optional structured data (e.g. file diff
+// info) from the tool execution, JSON-encoded. It may be empty.
+type ToolResultHandler func(toolCallID, toolName, toolArgs, result, metadata string, isError bool)
 
 // ResponseHandler is a function type for handling LLM responses.
 type ResponseHandler func(content string)
@@ -90,6 +92,8 @@ type GenerateWithLoopResult struct {
 	Messages []message.Message
 	// TotalUsage contains aggregate token usage across all steps
 	TotalUsage fantasy.Usage
+	// StopReason is the LLM provider's finish reason for the final response.
+	StopReason string
 }
 
 // NewAgent creates a new Agent with core tools and optional MCP tool integration.
@@ -283,12 +287,12 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 
 				// Notify about the tool call
 				if onToolCall != nil {
-					onToolCall(tc.ToolName, tc.Input)
+					onToolCall(tc.ToolCallID, tc.ToolName, tc.Input)
 				}
 
 				// Notify tool execution starting
 				if onToolExecution != nil {
-					onToolExecution(tc.ToolName, tc.Input, true)
+					onToolExecution(tc.ToolCallID, tc.ToolName, tc.Input, true)
 				}
 
 				return nil
@@ -301,13 +305,13 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				}
 				// Notify tool execution finished
 				if onToolExecution != nil {
-					onToolExecution(tr.ToolName, currentToolArgs, false)
+					onToolExecution(tr.ToolCallID, tr.ToolName, currentToolArgs, false)
 				}
 
 				if onToolResult != nil {
 					// Extract result text and error status
 					resultText, isError := extractToolResultText(tr)
-					onToolResult(tr.ToolName, currentToolArgs, resultText, isError)
+					onToolResult(tr.ToolCallID, tr.ToolName, currentToolArgs, resultText, tr.ClientMetadata, isError)
 				}
 
 				return nil
@@ -426,6 +430,7 @@ func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.
 		ConversationMessages: allFantasyMessages,
 		Messages:             allMessages,
 		TotalUsage:           result.TotalUsage,
+		StopReason:           string(result.Response.FinishReason),
 	}
 }
 

internal/app/app.go

@@ -532,14 +532,14 @@ func (a *App) subscribeSDKEvents(sendFn func(tea.Msg)) func() {
 	unsubs = append(unsubs, k.Subscribe(func(e kit.Event) {
 		switch ev := e.(type) {
 		case kit.ToolCallEvent:
-			sendFn(ToolCallStartedEvent{ToolName: ev.ToolName, ToolArgs: ev.ToolArgs})
+			sendFn(ToolCallStartedEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs})
 		case kit.ToolExecutionStartEvent:
-			sendFn(ToolExecutionEvent{ToolName: ev.ToolName, ToolArgs: ev.ToolArgs, IsStarting: true})
+			sendFn(ToolExecutionEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs, IsStarting: true})
 		case kit.ToolExecutionEndEvent:
-			sendFn(ToolExecutionEvent{ToolName: ev.ToolName, IsStarting: false})
+			sendFn(ToolExecutionEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, IsStarting: false})
 		case kit.ToolResultEvent:
 			sendFn(ToolResultEvent{
-				ToolName: ev.ToolName, ToolArgs: ev.ToolArgs,
+				ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs,
 				Result: ev.Result, IsError: ev.IsError,
 			})
 		case kit.ToolCallContentEvent:

internal/app/events.go

@@ -19,6 +19,8 @@ type ReasoningChunkEvent struct {
 // ToolCallStartedEvent is sent when a tool call has been parsed and is about to execute.
 // It carries the tool name and its arguments for display purposes.
 type ToolCallStartedEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being called.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments for the tool call.
@@ -28,6 +30,8 @@ type ToolCallStartedEvent struct {
 // ToolExecutionEvent is sent when a tool starts or finishes executing.
 // The IsStarting flag distinguishes between the start and end of execution.
 type ToolExecutionEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being executed.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments for the tool call (only set when IsStarting is true).
@@ -38,6 +42,8 @@ type ToolExecutionEvent struct {
 
 // ToolResultEvent is sent after a tool execution completes with its result.
 type ToolResultEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool that was executed.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments that were passed to the tool.

internal/core/edit.go

@@ -76,13 +76,15 @@ func executeEdit(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 	// If no exact match, try fuzzy matching
 	if count == 0 {
 		if idx, matchLen := fuzzyMatch(normalized, normalizedOld); idx >= 0 {
-			// Apply fuzzy match
+			// Apply fuzzy match — the matched text is the original content slice
+			matchedText := normalized[idx : idx+matchLen]
 			newContent := normalized[:idx] + args.NewText + normalized[idx+matchLen:]
 			if err := os.WriteFile(absPath, []byte(newContent), 0644); err != nil {
 				return fantasy.NewTextErrorResponse(fmt.Sprintf("failed to write file: %v", err)), nil
 			}
 			diff := generateDiff(absPath, normalized, newContent, idx)
-			return fantasy.NewTextResponse(fmt.Sprintf("Applied edit (fuzzy match) to %s\n%s", args.Path, diff)), nil
+			resp := fantasy.NewTextResponse(fmt.Sprintf("Applied edit (fuzzy match) to %s\n%s", args.Path, diff))
+			return fantasy.WithResponseMetadata(resp, editDiffMeta(absPath, matchedText, args.NewText)), nil
 		}
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("old_text not found in %s", args.Path)), nil
 	}
@@ -100,7 +102,23 @@ func executeEdit(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 
 	idx := strings.Index(normalized, normalizedOld)
 	diff := generateDiff(absPath, normalized, newContent, idx)
-	return fantasy.NewTextResponse(fmt.Sprintf("Applied edit to %s\n%s", args.Path, diff)), nil
+	resp := fantasy.NewTextResponse(fmt.Sprintf("Applied edit to %s\n%s", args.Path, diff))
+	return fantasy.WithResponseMetadata(resp, editDiffMeta(absPath, normalizedOld, args.NewText)), nil
+}
+
+// editDiffMeta builds the structured metadata attached to edit tool responses.
+func editDiffMeta(path, oldText, newText string) map[string]any {
+	return map[string]any{
+		"file_diffs": []map[string]any{{
+			"path":      path,
+			"additions": strings.Count(newText, "\n") + 1,
+			"deletions": strings.Count(oldText, "\n") + 1,
+			"diff_blocks": []map[string]any{{
+				"old_text": oldText,
+				"new_text": newText,
+			}},
+		}},
+	}
 }
 
 // fuzzyMatch tries to find old_text with relaxed matching:

internal/core/subagent.go

@@ -6,12 +6,50 @@ import (
 	"time"
 
 	"charm.land/fantasy"
-	"github.com/mark3labs/kit/internal/extensions"
 )
 
 const defaultSubagentTimeout = 5 * time.Minute
 const maxSubagentTimeout = 30 * time.Minute
 
+// ---------------------------------------------------------------------------
+// Context-based subagent spawner
+// ---------------------------------------------------------------------------
+
+// SubagentSpawnResult carries the outcome of an in-process subagent spawn.
+type SubagentSpawnResult struct {
+	Response     string
+	Error        error
+	SessionID    string
+	InputTokens  int64
+	OutputTokens int64
+	Elapsed      time.Duration
+}
+
+// SubagentSpawnFunc is a callback that spawns an in-process subagent. The
+// parent Kit instance injects this into the context so the core tool can
+// call back without importing pkg/kit (which would create a cycle).
+type SubagentSpawnFunc func(ctx context.Context, prompt, model, systemPrompt string, timeout time.Duration) (*SubagentSpawnResult, error)
+
+type subagentCtxKey struct{}
+
+// WithSubagentSpawner stores a spawn function in the context so that the
+// spawn_subagent core tool can create in-process subagents.
+func WithSubagentSpawner(ctx context.Context, fn SubagentSpawnFunc) context.Context {
+	return context.WithValue(ctx, subagentCtxKey{}, fn)
+}
+
+// getSubagentSpawner retrieves the spawn function from the context.
+func getSubagentSpawner(ctx context.Context) SubagentSpawnFunc {
+	if fn, ok := ctx.Value(subagentCtxKey{}).(SubagentSpawnFunc); ok {
+		return fn
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// spawn_subagent tool
+// ---------------------------------------------------------------------------
+
 type subagentArgs struct {
 	Task           string `json:"task"`
 	Model          string `json:"model,omitempty"`
@@ -24,9 +62,10 @@ func NewSubagentTool(opts ...ToolOption) fantasy.AgentTool {
 	return &coreTool{
 		info: fantasy.ToolInfo{
 			Name: "spawn_subagent",
-			Description: `Spawn a background subagent to perform a task autonomously.
+			Description: `Spawn a subagent to perform a task autonomously.
 
-The subagent runs as a separate Kit instance with full tool access. Use this to:
+The subagent runs as a separate in-process Kit instance with full tool access
+(except spawning further subagents). Use this to:
 - Delegate independent subtasks that can run in parallel
 - Perform research or analysis without blocking your main work
 - Execute tasks that benefit from a fresh context window
@@ -74,42 +113,53 @@ func executeSubagent(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolRe
 		return fantasy.NewTextErrorResponse("task parameter is required"), nil
 	}
 
-	// Determine timeout
+	// Determine timeout.
 	timeout := defaultSubagentTimeout
 	if args.TimeoutSeconds > 0 {
 		timeout = min(time.Duration(args.TimeoutSeconds)*time.Second, maxSubagentTimeout)
 	}
 
-	// Spawn subagent in blocking mode
-	_, result, err := extensions.SpawnSubagent(extensions.SubagentConfig{
-		Prompt:       args.Task,
-		Model:        args.Model,
-		SystemPrompt: args.SystemPrompt,
-		Timeout:      timeout,
-		Blocking:     true,
-	})
-	if err != nil {
-		return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to spawn subagent: %v", err)), nil
+	// Retrieve in-process spawner from context.
+	spawner := getSubagentSpawner(ctx)
+	if spawner == nil {
+		return fantasy.NewTextErrorResponse(
+			"Error: subagent spawner not available. " +
+				"Ensure Kit is initialized with subagent support.",
+		), fmt.Errorf("no subagent spawner in context")
 	}
 
-	if result.Error != nil {
-		// Subagent failed but we still have partial output
-		response := fmt.Sprintf("Subagent failed (exit code %d) after %ds.\n\nError: %v",
-			result.ExitCode, int(result.Elapsed.Seconds()), result.Error)
+	// Spawn in-process subagent.
+	result, err := spawner(ctx, args.Task, args.Model, args.SystemPrompt, timeout)
+	if err != nil || result.Error != nil {
+		spawnErr := err
+		if spawnErr == nil {
+			spawnErr = result.Error
+		}
+		response := fmt.Sprintf("Subagent failed after %ds.\n\nError: %v",
+			int(result.Elapsed.Seconds()), spawnErr)
 		if result.Response != "" {
 			response += fmt.Sprintf("\n\nPartial output:\n%s", truncateResponse(result.Response, 8000))
 		}
 		return fantasy.NewTextErrorResponse(response), nil
 	}
 
-	// Build successful response
+	// Build successful response.
 	response := fmt.Sprintf("Subagent completed successfully in %ds.", int(result.Elapsed.Seconds()))
-	if result.Usage != nil {
-		response += fmt.Sprintf(" (tokens: %d in / %d out)", result.Usage.InputTokens, result.Usage.OutputTokens)
+	if result.InputTokens > 0 || result.OutputTokens > 0 {
+		response += fmt.Sprintf(" (tokens: %d in / %d out)", result.InputTokens, result.OutputTokens)
 	}
 	response += fmt.Sprintf("\n\nResult:\n%s", truncateResponse(result.Response, 12000))
 
-	return fantasy.NewTextResponse(response), nil
+	resp := fantasy.NewTextResponse(response)
+
+	// Attach subagent session ID as metadata when available.
+	if result.SessionID != "" {
+		resp = fantasy.WithResponseMetadata(resp, map[string]any{
+			"subagent_session_id": result.SessionID,
+		})
+	}
+
+	return resp, nil
 }
 
 // truncateResponse limits the response length to avoid overwhelming context windows.

internal/core/tools.go

@@ -86,8 +86,9 @@ func ReadOnlyTools(opts ...ToolOption) []fantasy.AgentTool {
 	}
 }
 
-// AllTools returns all available core tools.
-func AllTools(opts ...ToolOption) []fantasy.AgentTool {
+// SubagentTools returns all core tools except spawn_subagent. This prevents
+// infinite recursion when a subagent is itself a Kit instance.
+func SubagentTools(opts ...ToolOption) []fantasy.AgentTool {
 	return []fantasy.AgentTool{
 		NewBashTool(opts...),
 		NewReadTool(opts...),
@@ -96,6 +97,10 @@ func AllTools(opts ...ToolOption) []fantasy.AgentTool {
 		NewGrepTool(opts...),
 		NewFindTool(opts...),
 		NewLsTool(opts...),
-		NewSubagentTool(opts...),
 	}
 }
+
+// AllTools returns all available core tools.
+func AllTools(opts ...ToolOption) []fantasy.AgentTool {
+	return append(SubagentTools(opts...), NewSubagentTool(opts...))
+}

internal/core/write.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"charm.land/fantasy"
 )
@@ -53,6 +54,14 @@ func executeWrite(ctx context.Context, call fantasy.ToolCall, workDir string) (f
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("invalid path: %v", err)), nil
 	}
 
+	// Read existing content before writing (for diff metadata).
+	var beforeContent string
+	isNew := true
+	if existing, readErr := os.ReadFile(absPath); readErr == nil {
+		beforeContent = string(existing)
+		isNew = false
+	}
+
 	// Create parent directories
 	dir := filepath.Dir(absPath)
 	if err := os.MkdirAll(dir, 0755); err != nil {
@@ -63,5 +72,27 @@ func executeWrite(ctx context.Context, call fantasy.ToolCall, workDir string) (f
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("failed to write file: %v", err)), nil
 	}
 
-	return fantasy.NewTextResponse(fmt.Sprintf("Wrote %d bytes to %s", len(args.Content), args.Path)), nil
+	resp := fantasy.NewTextResponse(fmt.Sprintf("Wrote %d bytes to %s", len(args.Content), args.Path))
+	return fantasy.WithResponseMetadata(resp, writeDiffMeta(absPath, beforeContent, args.Content, isNew)), nil
+}
+
+// writeDiffMeta builds the structured metadata attached to write tool responses.
+func writeDiffMeta(path, beforeContent, afterContent string, isNew bool) map[string]any {
+	additions := strings.Count(afterContent, "\n") + 1
+	deletions := 0
+	if !isNew {
+		deletions = strings.Count(beforeContent, "\n") + 1
+	}
+	return map[string]any{
+		"file_diffs": []map[string]any{{
+			"path":      path,
+			"additions": additions,
+			"deletions": deletions,
+			"is_new":    isNew,
+			"diff_blocks": []map[string]any{{
+				"old_text": beforeContent,
+				"new_text": afterContent,
+			}},
+		}},
+	}
 }

internal/extensions/api.go

@@ -1432,7 +1432,9 @@ type EditorConfig struct {
 type ToolCallEvent struct {
 	ToolName   string
 	ToolCallID string
-	Input      string // JSON-encoded tool parameters
+	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
+	Input      string         // JSON-encoded tool parameters
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
 	// Source indicates who initiated the tool call.
 	// Currently always "llm" (all tool calls originate from the LLM agent loop).
 	// Future user-initiated tool features may set this to "user".
@@ -1451,24 +1453,31 @@ func (ToolCallResult) isResult() {}
 
 // ToolExecutionStartEvent fires when a tool begins executing.
 type ToolExecutionStartEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }
 
 func (e ToolExecutionStartEvent) Type() EventType { return ToolExecutionStart }
 
 // ToolExecutionEndEvent fires when a tool finishes executing.
 type ToolExecutionEndEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }
 
 func (e ToolExecutionEndEvent) Type() EventType { return ToolExecutionEnd }
 
 // ToolResultEvent fires after tool execution with the output.
 type ToolResultEvent struct {
-	ToolName string
-	Input    string
-	Content  string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	Input      string
+	Content    string
+	IsError    bool
+	Metadata   string // Optional JSON-encoded structured metadata (e.g. file diffs)
 }
 
 func (e ToolResultEvent) Type() EventType { return ToolResult }

internal/extensions/subagent.go

@@ -38,6 +38,11 @@ type SubagentConfig struct {
 	// Called from a goroutine; must be safe for concurrent use.
 	OnOutput func(chunk string)
 
+	// OnEvent receives real-time events from the subagent's execution:
+	// text chunks, tool calls, tool results, reasoning deltas, etc.
+	// Called synchronously from the subagent's event loop.
+	OnEvent func(SubagentEvent)
+
 	// OnComplete is called when the subagent finishes (success or error).
 	// Called from a goroutine; must be safe for concurrent use.
 	OnComplete func(result SubagentResult)
@@ -47,11 +52,45 @@ type SubagentConfig struct {
 	// and returns immediately with a handle.
 	Blocking bool
 
+	// NoSession, when true, runs the subagent without persisting a session
+	// file. By default (false), subagent sessions are persisted so they can
+	// be loaded for replay/inspection. Set to true for ephemeral tasks
+	// where session history is not needed.
+	NoSession bool
+
 	// ParentSessionID links the subagent's session to the parent (optional).
-	// When set, the subagent's session is persisted with a parent reference.
+	// When set, the subagent's session header includes a parent reference
+	// so viewers can navigate the session tree.
 	ParentSessionID string
 }
 
+// SubagentEvent carries a real-time event from a running subagent. Extensions
+// use the Type field to determine what happened and read the relevant fields.
+// This is a concrete struct (not an interface) for Yaegi compatibility.
+type SubagentEvent struct {
+	// Type identifies the event: "text", "reasoning", "tool_call",
+	// "tool_result", "tool_execution_start", "tool_execution_end",
+	// "turn_start", "turn_end".
+	Type string
+
+	// Content carries text for "text" and "reasoning" events.
+	Content string
+
+	// ToolCallID is set on tool_call, tool_result, tool_execution_start,
+	// and tool_execution_end events.
+	ToolCallID string
+	// ToolName is set on tool-related events.
+	ToolName string
+	// ToolKind is set on tool-related events.
+	ToolKind string
+	// ToolArgs is set on tool_call events (JSON-encoded).
+	ToolArgs string
+	// ToolResult is set on tool_result events.
+	ToolResult string
+	// IsError is set on tool_result events.
+	IsError bool
+}
+
 // SubagentResult contains the outcome of a subagent execution.
 type SubagentResult struct {
 	// Response is the subagent's final text response.
@@ -68,6 +107,11 @@ type SubagentResult struct {
 
 	// Usage contains token usage if available.
 	Usage *SubagentUsage
+
+	// SessionID is the subagent's session identifier, if available.
+	// Populated when the subagent persists its session (requires running
+	// without --no-session). Empty for ephemeral sessions.
+	SessionID string
 }
 
 // SubagentUsage contains token usage from the subagent's run.
@@ -120,8 +164,10 @@ func (h *SubagentHandle) Done() <-chan struct{} {
 
 // subagentJSONOutput matches the JSON envelope produced by `kit --json`.
 type subagentJSONOutput struct {
-	Response string `json:"response"`
-	Usage    *struct {
+	Response   string `json:"response"`
+	StopReason string `json:"stop_reason,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	Usage      *struct {
 		InputTokens  int64 `json:"input_tokens"`
 		OutputTokens int64 `json:"output_tokens"`
 	} `json:"usage,omitempty"`
@@ -175,9 +221,11 @@ func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error)
 	// Build subprocess arguments.
 	args := []string{
 		"--json",
-		"--no-session",
 		"--no-extensions",
 	}
+	if cfg.NoSession {
+		args = append(args, "--no-session")
+	}
 	if cfg.Model != "" {
 		args = append(args, "--model", cfg.Model)
 	}
@@ -294,6 +342,7 @@ func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error)
 		var parsed subagentJSONOutput
 		if raw != "" && json.Unmarshal([]byte(raw), &parsed) == nil {
 			result.Response = parsed.Response
+			result.SessionID = parsed.SessionID
 			if parsed.Usage != nil {
 				result.Usage = &SubagentUsage{
 					InputTokens:  parsed.Usage.InputTokens,

internal/extensions/symbols.go

@@ -115,6 +115,7 @@ func Symbols() interp.Exports {
 			"SubagentResult": reflect.ValueOf((*SubagentResult)(nil)),
 			"SubagentUsage":  reflect.ValueOf((*SubagentUsage)(nil)),
 			"SubagentHandle": reflect.ValueOf((*SubagentHandle)(nil)),
+			"SubagentEvent":  reflect.ValueOf((*SubagentEvent)(nil)),
 
 			// Event structs
 			"ToolCallEvent":           reflect.ValueOf((*ToolCallEvent)(nil)),

internal/extensions/wrapper.go

@@ -40,6 +40,37 @@ func ExtensionToolsAsFantasy(defs []ToolDef, runner *Runner) []fantasy.AgentTool
 	return tools
 }
 
+// coreToolKinds maps built-in tool names to their kind classification.
+var coreToolKinds = map[string]string{
+	"bash":           "execute",
+	"edit":           "edit",
+	"write":          "edit",
+	"read":           "read",
+	"ls":             "read",
+	"grep":           "search",
+	"find":           "search",
+	"spawn_subagent": "agent",
+}
+
+// toolKindFor returns the ToolKind for a given tool name, defaulting to
+// "execute" for unknown tools (including MCP tools).
+func toolKindFor(toolName string) string {
+	if kind, ok := coreToolKinds[toolName]; ok {
+		return kind
+	}
+	return "execute"
+}
+
+// parseToolArgsJSON attempts to parse JSON-encoded tool args into a map.
+// Returns nil on failure (non-fatal convenience parsing).
+func parseToolArgsJSON(input string) map[string]any {
+	var parsed map[string]any
+	if json.Unmarshal([]byte(input), &parsed) == nil {
+		return parsed
+	}
+	return nil
+}
+
 // ---------------------------------------------------------------------------
 // wrappedTool — intercepts tool calls through the extension runner
 // ---------------------------------------------------------------------------
@@ -63,12 +94,16 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T
 			fmt.Errorf("tool %q disabled by extension", toolName)
 	}
 
+	kind := toolKindFor(toolName)
+
 	// 1. Emit ToolCall — extensions can block execution.
 	if w.runner.HasHandlers(ToolCall) {
 		result, _ := w.runner.Emit(ToolCallEvent{
 			ToolName:   toolName,
 			ToolCallID: call.ID,
+			ToolKind:   kind,
 			Input:      call.Input,
+			ParsedArgs: parseToolArgsJSON(call.Input),
 			Source:     "llm",
 		})
 		if r, ok := result.(ToolCallResult); ok && r.Block {
@@ -83,7 +118,7 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T
 
 	// 2. Emit ToolExecutionStart.
 	if w.runner.HasHandlers(ToolExecutionStart) {
-		_, _ = w.runner.Emit(ToolExecutionStartEvent{ToolName: toolName})
+		_, _ = w.runner.Emit(ToolExecutionStartEvent{ToolCallID: call.ID, ToolName: toolName, ToolKind: kind})
 	}
 
 	// 3. Execute the actual tool.
@@ -91,16 +126,19 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T
 
 	// 4. Emit ToolExecutionEnd.
 	if w.runner.HasHandlers(ToolExecutionEnd) {
-		_, _ = w.runner.Emit(ToolExecutionEndEvent{ToolName: toolName})
+		_, _ = w.runner.Emit(ToolExecutionEndEvent{ToolCallID: call.ID, ToolName: toolName, ToolKind: kind})
 	}
 
 	// 5. Emit ToolResult — extensions can modify output.
 	if w.runner.HasHandlers(ToolResult) {
 		result, _ := w.runner.Emit(ToolResultEvent{
-			ToolName: toolName,
-			Input:    call.Input,
-			Content:  resp.Content,
-			IsError:  err != nil || resp.IsError,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolKind:   kind,
+			Input:      call.Input,
+			Content:    resp.Content,
+			IsError:    err != nil || resp.IsError,
+			Metadata:   resp.Metadata,
 		})
 		if r, ok := result.(ToolResultResult); ok {
 			if r.Content != nil {

pkg/kit/events.go

@@ -1,6 +1,9 @@
 package kit
 
-import "sync"
+import (
+	"encoding/json"
+	"sync"
+)
 
 // ---------------------------------------------------------------------------
 // Event types
@@ -48,6 +51,54 @@ type Event interface {
 	EventType() EventType
 }
 
+// ---------------------------------------------------------------------------
+// Tool kind constants
+// ---------------------------------------------------------------------------
+
+// ToolKind constants classify what a tool does, enabling UIs to render
+// appropriate visualizations (e.g. diff view for edit tools, command+output
+// for execute tools) and file trackers to identify which results contain
+// modifications.
+const (
+	ToolKindExecute  = "execute" // Shell execution (bash)
+	ToolKindEdit     = "edit"    // File modification (edit, write)
+	ToolKindRead     = "read"    // File reading (read, ls)
+	ToolKindSearch   = "search"  // Content/file search (grep, find)
+	ToolKindSubagent = "agent"   // Subagent spawning (spawn_subagent)
+)
+
+// coreToolKinds maps built-in tool names to their kind. MCP and extension
+// tools without an entry default to ToolKindExecute.
+var coreToolKinds = map[string]string{
+	"bash":           ToolKindExecute,
+	"edit":           ToolKindEdit,
+	"write":          ToolKindEdit,
+	"read":           ToolKindRead,
+	"ls":             ToolKindRead,
+	"grep":           ToolKindSearch,
+	"find":           ToolKindSearch,
+	"spawn_subagent": ToolKindSubagent,
+}
+
+// toolKindFor returns the ToolKind for a given tool name, defaulting to
+// ToolKindExecute for unknown tools.
+func toolKindFor(toolName string) string {
+	if kind, ok := coreToolKinds[toolName]; ok {
+		return kind
+	}
+	return ToolKindExecute
+}
+
+// parseToolArgs attempts to parse a JSON-encoded tool args string into a map.
+// Returns nil on failure (non-fatal convenience parsing).
+func parseToolArgs(toolArgs string) map[string]any {
+	var parsed map[string]any
+	if json.Unmarshal([]byte(toolArgs), &parsed) == nil {
+		return parsed
+	}
+	return nil
+}
+
 // ---------------------------------------------------------------------------
 // Concrete event structs
 // ---------------------------------------------------------------------------
@@ -62,8 +113,9 @@ func (e TurnStartEvent) EventType() EventType { return EventTurnStart }
 
 // TurnEndEvent fires after the agent finishes processing.
 type TurnEndEvent struct {
-	Response string
-	Error    error
+	Response   string
+	Error      error
+	StopReason string // "end_turn", "max_tokens", "tool_use", "error", etc.
 }
 
 // EventType implements Event.
@@ -101,8 +153,11 @@ func (e MessageEndEvent) EventType() EventType { return EventMessageEnd }
 
 // ToolCallEvent fires when a tool call has been parsed.
 type ToolCallEvent struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string // Stable ID for correlating tool lifecycle events
+	ToolName   string
+	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
+	ToolArgs   string         // JSON-encoded arguments
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
 }
 
 // EventType implements Event.
@@ -110,8 +165,10 @@ func (e ToolCallEvent) EventType() EventType { return EventToolCall }
 
 // ToolExecutionStartEvent fires when a tool begins executing.
 type ToolExecutionStartEvent struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	ToolArgs   string
 }
 
 // EventType implements Event.
@@ -119,7 +176,9 @@ func (e ToolExecutionStartEvent) EventType() EventType { return EventToolExecuti
 
 // ToolExecutionEndEvent fires when a tool finishes executing.
 type ToolExecutionEndEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }
 
 // EventType implements Event.
@@ -127,10 +186,35 @@ func (e ToolExecutionEndEvent) EventType() EventType { return EventToolExecution
 
 // ToolResultEvent fires after a tool execution completes with its result.
 type ToolResultEvent struct {
-	ToolName string
-	ToolArgs string
-	Result   string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	ToolArgs   string
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience
+	Result     string
+	IsError    bool
+	Metadata   *ToolResultMetadata // Optional structured metadata from tool execution
+}
+
+// ToolResultMetadata carries structured data from tool executions.
+type ToolResultMetadata struct {
+	FileDiffs         []FileDiffInfo `json:"file_diffs,omitempty"`          // Present for edit/write tools
+	SubagentSessionID string         `json:"subagent_session_id,omitempty"` // Present for spawn_subagent tool
+}
+
+// FileDiffInfo describes a file modification from an edit or write tool.
+type FileDiffInfo struct {
+	Path       string      `json:"path"`             // Absolute file path
+	Additions  int         `json:"additions"`        // Lines added
+	Deletions  int         `json:"deletions"`        // Lines removed
+	IsNew      bool        `json:"is_new,omitempty"` // True if file was created (write only)
+	DiffBlocks []DiffBlock `json:"diff_blocks,omitempty"`
+}
+
+// DiffBlock represents a single old→new text replacement within a file.
+type DiffBlock struct {
+	OldText string `json:"old_text"`
+	NewText string `json:"new_text"`
 }
 
 // EventType implements Event.

pkg/kit/extensions_bridge.go

@@ -89,11 +89,13 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 	if runner.HasHandlers(extensions.AgentEnd) {
 		m.Subscribe(func(e Event) {
 			if ev, ok := e.(TurnEndEvent); ok {
-				stopReason := "completed"
+				stopReason := ev.StopReason
 				response := ev.Response
 				if ev.Error != nil {
 					stopReason = "error"
 					response = ""
+				} else if stopReason == "" {
+					stopReason = "completed"
 				}
 				_, _ = runner.Emit(extensions.AgentEndEvent{
 					Response:   response,

pkg/kit/hooks.go

@@ -31,8 +31,9 @@ const (
 
 // BeforeToolCallHook is the input for hooks that fire before a tool executes.
 type BeforeToolCallHook struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string
+	ToolName   string
+	ToolArgs   string
 }
 
 // BeforeToolCallResult controls whether the tool call proceeds.
@@ -43,10 +44,11 @@ type BeforeToolCallResult struct {
 
 // AfterToolResultHook is the input for hooks that fire after a tool executes.
 type AfterToolResultHook struct {
-	ToolName string
-	ToolArgs string
-	Result   string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolArgs   string
+	Result     string
+	IsError    bool
 }
 
 // AfterToolResultResult can modify the tool's output before it reaches the LLM.
@@ -258,8 +260,9 @@ func (h *hookedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.To
 	// 1. BeforeToolCall — can block execution.
 	if h.beforeToolCall.hasHooks() {
 		if result := h.beforeToolCall.run(BeforeToolCallHook{
-			ToolName: toolName,
-			ToolArgs: call.Input,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolArgs:   call.Input,
 		}); result != nil && result.Block {
 			reason := result.Reason
 			if reason == "" {
@@ -276,10 +279,11 @@ func (h *hookedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.To
 	// 3. AfterToolResult — can modify output.
 	if h.afterToolResult.hasHooks() {
 		if result := h.afterToolResult.run(AfterToolResultHook{
-			ToolName: toolName,
-			ToolArgs: call.Input,
-			Result:   resp.Content,
-			IsError:  err != nil || resp.IsError,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolArgs:   call.Input,
+			Result:     resp.Content,
+			IsError:    err != nil || resp.IsError,
 		}); result != nil {
 			if result.Result != nil {
 				resp.Content = *result.Result

pkg/kit/kit.go

@@ -2,6 +2,7 @@ package kit
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -13,6 +14,7 @@ import (
 
 	"github.com/mark3labs/kit/internal/agent"
 	"github.com/mark3labs/kit/internal/config"
+	"github.com/mark3labs/kit/internal/core"
 	"github.com/mark3labs/kit/internal/extensions"
 	"github.com/mark3labs/kit/internal/kitsetup"
 	"github.com/mark3labs/kit/internal/message"
@@ -347,6 +349,50 @@ func (m *Kit) GetSessionMessages() []extensions.SessionMessage {
 	return msgs
 }
 
+// StructuredMessage represents a conversation message with typed content parts
+// (tool calls, reasoning, finish markers, etc.) instead of flattened text.
+type StructuredMessage struct {
+	ID        string
+	ParentID  string
+	Role      MessageRole
+	Parts     []ContentPart
+	Model     string
+	Provider  string
+	Timestamp string // RFC3339 format
+}
+
+// GetStructuredMessages returns the conversation messages on the current
+// branch with full typed content parts. Unlike GetSessionMessages() which
+// flattens all content to a single text string, this preserves tool calls,
+// tool results, reasoning blocks, and finish markers as distinct typed parts.
+func (m *Kit) GetStructuredMessages() []StructuredMessage {
+	if m.treeSession == nil {
+		return nil
+	}
+	branch := m.treeSession.GetBranch("")
+	var msgs []StructuredMessage
+	for _, entry := range branch {
+		me, ok := entry.(*session.MessageEntry)
+		if !ok {
+			continue
+		}
+		msg, err := me.ToMessage()
+		if err != nil {
+			continue
+		}
+		msgs = append(msgs, StructuredMessage{
+			ID:        me.ID,
+			ParentID:  me.ParentID,
+			Role:      msg.Role,
+			Parts:     msg.Parts,
+			Model:     msg.Model,
+			Provider:  msg.Provider,
+			Timestamp: me.Timestamp.Format("2006-01-02T15:04:05Z07:00"),
+		})
+	}
+	return msgs
+}
+
 // GetSessionFilePath returns the JSONL file path of the current session.
 func (m *Kit) GetSessionFilePath() string {
 	if m.treeSession == nil {
@@ -849,11 +895,19 @@ func InitTreeSession(opts *Options) (*session.TreeManager, error) {
 // New creates a Kit instance using the same initialization as the CLI.
 // It loads configuration, initializes MCP servers, creates the LLM model, and
 // sets up the agent for interaction. Returns an error if initialization fails.
+// viperInitMu serializes viper writes during kit.New(). Viper's global state
+// is not thread-safe, so concurrent calls (e.g. parallel subagent spawns)
+// must not overlap the Set()/Get() window.
+var viperInitMu sync.Mutex
+
 func New(ctx context.Context, opts *Options) (*Kit, error) {
 	if opts == nil {
 		opts = &Options{}
 	}
 
+	viperInitMu.Lock()
+	defer viperInitMu.Unlock()
+
 	// Set CLI-equivalent defaults for viper. When used as an SDK (without
 	// cobra), these defaults are not registered via flag bindings.
 	setSDKDefaults()
@@ -1150,6 +1204,14 @@ type TurnResult struct {
 	// Response is the assistant's final text response.
 	Response string
 
+	// StopReason indicates why the turn ended. Derived from the LLM
+	// provider's finish reason: "stop", "length" (max tokens), "tool-calls",
+	// "content-filter", "error", "other", "unknown".
+	StopReason string
+
+	// SessionID is the UUID of the session this turn belongs to.
+	SessionID string
+
 	// TotalUsage is the aggregate token usage across all steps in the turn
 	// (includes tool-calling loop iterations). Nil if the provider didn't
 	// report usage.
@@ -1165,6 +1227,168 @@ type TurnResult struct {
 	Messages []FantasyMessage
 }
 
+// ---------------------------------------------------------------------------
+// In-process subagent
+// ---------------------------------------------------------------------------
+
+// SubagentConfig configures an in-process subagent spawned via Kit.Subagent().
+type SubagentConfig struct {
+	// Prompt is the task/instruction for the subagent (required).
+	Prompt string
+
+	// Model overrides the parent's model (e.g. "anthropic/claude-haiku-3-5-20241022").
+	// Empty string uses the parent's current model.
+	Model string
+
+	// SystemPrompt provides domain-specific instructions for the subagent.
+	// Empty string uses a minimal default prompt.
+	SystemPrompt string
+
+	// Tools overrides the tool set. If nil, SubagentTools() is used (all
+	// core tools except spawn_subagent, preventing infinite recursion).
+	Tools []Tool
+
+	// NoSession, when true, uses an in-memory ephemeral session. When false
+	// (default), the subagent's session is persisted and can be loaded for
+	// replay/inspection.
+	NoSession bool
+
+	// Timeout limits execution time. Zero means 5 minute default.
+	Timeout time.Duration
+
+	// OnEvent, when set, receives all events from the subagent's event bus.
+	// This enables the parent to stream subagent tool calls, text chunks,
+	// etc. in real time.
+	OnEvent func(Event)
+}
+
+// SubagentResult contains the outcome of an in-process subagent execution.
+type SubagentResult struct {
+	// Response is the subagent's final text response.
+	Response string
+	// Error is set if the subagent failed (nil on success).
+	Error error
+	// SessionID is the subagent's session identifier (for replay).
+	SessionID string
+	// StopReason is the LLM's finish reason for the subagent's final turn.
+	StopReason string
+	// Usage contains token usage from the subagent's run.
+	Usage *FantasyUsage
+	// Elapsed is the total execution time.
+	Elapsed time.Duration
+}
+
+// Subagent spawns an in-process child Kit instance to perform a task. The
+// child gets its own session, event bus, and agent loop but shares the
+// parent's config (API keys, provider settings) and defaults to the parent's
+// model when SubagentConfig.Model is empty.
+//
+// This is the recommended way to run subagents in the SDK — no subprocess,
+// no kit binary dependency, native Go types for results.
+func (m *Kit) Subagent(ctx context.Context, cfg SubagentConfig) (*SubagentResult, error) {
+	if cfg.Prompt == "" {
+		return nil, fmt.Errorf("subagent prompt is required")
+	}
+
+	start := time.Now()
+
+	// Default timeout.
+	timeout := cfg.Timeout
+	if timeout == 0 {
+		timeout = 5 * time.Minute
+	}
+	ctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	// Resolve model: fall back to parent's model, and inherit the parent's
+	// provider when only a bare model name is given (e.g. "claude-haiku"
+	// instead of "anthropic/claude-haiku"). This avoids provider guessing.
+	model := cfg.Model
+	if model == "" {
+		model = m.modelString
+	} else if !strings.Contains(model, "/") {
+		// Bare model name — prepend parent's provider.
+		if parts := strings.SplitN(m.modelString, "/", 2); len(parts) == 2 {
+			model = parts[0] + "/" + model
+		}
+	}
+
+	// Default system prompt.
+	systemPrompt := cfg.SystemPrompt
+	if systemPrompt == "" {
+		systemPrompt = "You are a helpful coding assistant. Complete the task efficiently and thoroughly."
+	}
+
+	// Default tools: everything except spawn_subagent.
+	tools := cfg.Tools
+	if tools == nil {
+		tools = SubagentTools()
+	}
+
+	// Create child Kit instance. If the requested model fails (bad name,
+	// unsupported provider, etc.), fall back to the parent's model so the
+	// agent gets a useful error message instead of a hard failure.
+	childOpts := &Options{
+		Model:        model,
+		SystemPrompt: systemPrompt,
+		Tools:        tools,
+		NoSession:    cfg.NoSession,
+		Quiet:        true,
+	}
+	child, err := New(ctx, childOpts)
+	if err != nil && model != m.modelString {
+		// Model-specific failure — retry with parent's model.
+		childOpts.Model = m.modelString
+		child, err = New(ctx, childOpts)
+		if err != nil {
+			return &SubagentResult{
+				Error:   fmt.Errorf("failed to create subagent: %w", err),
+				Elapsed: time.Since(start),
+			}, err
+		}
+		// Prepend a note so the agent knows which model is actually running.
+		cfg.Prompt = fmt.Sprintf(
+			"[Note: requested model %q was not available, using %s instead.]\n\n%s",
+			model, m.modelString, cfg.Prompt,
+		)
+	} else if err != nil {
+		return &SubagentResult{
+			Error:   fmt.Errorf("failed to create subagent: %w", err),
+			Elapsed: time.Since(start),
+		}, err
+	}
+	defer func() { _ = child.Close() }()
+
+	// Forward events to parent if requested.
+	if cfg.OnEvent != nil {
+		child.Subscribe(cfg.OnEvent)
+	}
+
+	// Run the prompt.
+	result, err := child.PromptResult(ctx, cfg.Prompt)
+	elapsed := time.Since(start)
+
+	if err != nil {
+		return &SubagentResult{
+			Error:     err,
+			SessionID: child.GetSessionID(),
+			Elapsed:   elapsed,
+		}, err
+	}
+
+	subResult := &SubagentResult{
+		Response:   result.Response,
+		SessionID:  child.GetSessionID(),
+		StopReason: result.StopReason,
+		Elapsed:    elapsed,
+	}
+	if result.TotalUsage != nil {
+		subResult.Usage = result.TotalUsage
+	}
+
+	return subResult, nil
+}
+
 // ---------------------------------------------------------------------------
 // Shared generation helpers
 // ---------------------------------------------------------------------------
@@ -1173,22 +1397,64 @@ type TurnResult struct {
 // All prompt modes (Prompt, Steer, FollowUp, PromptWithOptions) share this
 // single code path so callback wiring is never duplicated.
 func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.GenerateWithLoopResult, error) {
+	// Inject the in-process subagent spawner into the context so the
+	// spawn_subagent core tool can create child Kit instances without
+	// importing pkg/kit (which would create an import cycle).
+	ctx = core.WithSubagentSpawner(ctx, func(
+		spawnCtx context.Context, prompt, model, systemPrompt string, timeout time.Duration,
+	) (*core.SubagentSpawnResult, error) {
+		result, err := m.Subagent(spawnCtx, SubagentConfig{
+			Prompt:       prompt,
+			Model:        model,
+			SystemPrompt: systemPrompt,
+			Timeout:      timeout,
+			OnEvent: func(e Event) {
+				m.events.emit(e)
+			},
+		})
+		if result == nil {
+			return &core.SubagentSpawnResult{Error: err}, err
+		}
+		sr := &core.SubagentSpawnResult{
+			Response:  result.Response,
+			Error:     result.Error,
+			SessionID: result.SessionID,
+			Elapsed:   result.Elapsed,
+		}
+		if result.Usage != nil {
+			sr.InputTokens = result.Usage.InputTokens
+			sr.OutputTokens = result.Usage.OutputTokens
+		}
+		return sr, err
+	})
+
 	return m.agent.GenerateWithLoopAndStreaming(ctx, messages,
-		func(toolName, toolArgs string) {
-			m.events.emit(ToolCallEvent{ToolName: toolName, ToolArgs: toolArgs})
+		func(toolCallID, toolName, toolArgs string) {
+			m.events.emit(ToolCallEvent{
+				ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName),
+				ToolArgs: toolArgs, ParsedArgs: parseToolArgs(toolArgs),
+			})
 		},
-		func(toolName, toolArgs string, isStarting bool) {
+		func(toolCallID, toolName, toolArgs string, isStarting bool) {
 			if isStarting {
-				m.events.emit(ToolExecutionStartEvent{ToolName: toolName, ToolArgs: toolArgs})
+				m.events.emit(ToolExecutionStartEvent{ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName), ToolArgs: toolArgs})
 			} else {
-				m.events.emit(ToolExecutionEndEvent{ToolName: toolName})
+				m.events.emit(ToolExecutionEndEvent{ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName)})
 			}
 		},
-		func(toolName, toolArgs, resultText string, isError bool) {
-			m.events.emit(ToolResultEvent{
-				ToolName: toolName, ToolArgs: toolArgs,
+		func(toolCallID, toolName, toolArgs, resultText, metadata string, isError bool) {
+			evt := ToolResultEvent{
+				ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName),
+				ToolArgs: toolArgs, ParsedArgs: parseToolArgs(toolArgs),
 				Result: resultText, IsError: isError,
-			})
+			}
+			if metadata != "" {
+				var meta ToolResultMetadata
+				if err := json.Unmarshal([]byte(metadata), &meta); err == nil {
+					evt.Metadata = &meta
+				}
+			}
+			m.events.emit(evt)
 		},
 		func(content string) {
 			m.events.emit(ResponseEvent{Content: content})
@@ -1317,8 +1583,10 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 		m.lastInputTokensMu.Unlock()
 	}
 
+	stopReason := result.StopReason
+
 	m.events.emit(MessageEndEvent{Content: responseText})
-	m.events.emit(TurnEndEvent{Response: responseText})
+	m.events.emit(TurnEndEvent{Response: responseText, StopReason: stopReason})
 
 	// Run AfterTurn hooks.
 	if m.afterTurn.hasHooks() {
@@ -1327,8 +1595,10 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 
 	// Build TurnResult with usage stats.
 	turnResult := &TurnResult{
-		Response: responseText,
-		Messages: result.ConversationMessages,
+		Response:   responseText,
+		StopReason: stopReason,
+		SessionID:  m.GetSessionID(),
+		Messages:   result.ConversationMessages,
 	}
 	totalUsage := result.TotalUsage
 	turnResult.TotalUsage = &totalUsage

pkg/kit/tools.go

@@ -51,3 +51,8 @@ func CodingTools(opts ...ToolOption) []Tool { return core.CodingTools(opts...) }
 // ReadOnlyTools returns tools for read-only exploration:
 // read, grep, find, ls.
 func ReadOnlyTools(opts ...ToolOption) []Tool { return core.ReadOnlyTools(opts...) }
+
+// SubagentTools returns all core tools except spawn_subagent. Use this when
+// creating child Kit instances (in-process subagents) to prevent infinite
+// recursion.
+func SubagentTools(opts ...ToolOption) []Tool { return core.SubagentTools(opts...) }

skills/kit-extensions/SKILL.md

@@ -846,8 +846,8 @@ func applyMode(ctx ext.Context, active bool, tools []string) {
 
 ## Key Files for Reference
 
-- `internal/extensions/api.go` — Complete API type definitions
-- `internal/extensions/runner.go` — Event dispatch and state management
-- `internal/extensions/loader.go` — Yaegi interpreter setup
-- `internal/extensions/symbols.go` — All types exported to extensions
-- `examples/extensions/` — 25+ working example extensions
+- [`internal/extensions/api.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/api.go) — Complete API type definitions
+- [`internal/extensions/runner.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/runner.go) — Event dispatch and state management
+- [`internal/extensions/loader.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/loader.go) — Yaegi interpreter setup
+- [`internal/extensions/symbols.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/symbols.go) — All types exported to extensions
+- [`examples/extensions/`](https://github.com/mark3labs/kit/tree/main/examples/extensions) — 25+ working example extensions