feat(runtime): P1 接入 internal hooks 到工具与完成前生命周期（#489）

internal/runtime/events.go

@@ -227,6 +227,29 @@ type RepositoryContextUnavailablePayload struct {
 	Reason string `json:"reason"`
 }
 
+// HookEventPayload 描述 hook 生命周期事件负载。
+type HookEventPayload struct {
+	HookID     string    `json:"hook_id"`
+	Point      string    `json:"point"`
+	Scope      string    `json:"scope"`
+	Kind       string    `json:"kind"`
+	Mode       string    `json:"mode"`
+	Status     string    `json:"status,omitempty"`
+	StartedAt  time.Time `json:"started_at,omitempty"`
+	DurationMS int64     `json:"duration_ms,omitempty"`
+	Error      string    `json:"error,omitempty"`
+}
+
+// HookBlockedPayload 描述 hook 阻断事件负载。
+type HookBlockedPayload struct {
+	HookID     string `json:"hook_id"`
+	Point      string `json:"point"`
+	ToolCallID string `json:"tool_call_id,omitempty"`
+	ToolName   string `json:"tool_name,omitempty"`
+	Reason     string `json:"reason,omitempty"`
+	Enforced   bool   `json:"enforced"`
+}
+
 const (
 	// EventUserMessage 表示用户消息已写入会话。
 	EventUserMessage EventType = "user_message"
@@ -302,6 +325,14 @@ const (
 	EventAssetSaveFailed EventType = "asset_save_failed"
 	// EventRepositoryContextUnavailable 表示本轮 repository 事实本应获取但失败，已降级为空上下文。
 	EventRepositoryContextUnavailable EventType = "repository_context_unavailable"
+	// EventHookStarted 表示 hook 执行开始。
+	EventHookStarted EventType = "hook_started"
+	// EventHookFinished 表示 hook 执行结束。
+	EventHookFinished EventType = "hook_finished"
+	// EventHookFailed 表示 hook 执行失败。
+	EventHookFailed EventType = "hook_failed"
+	// EventHookBlocked 表示某个 hook 返回 block（是否生效由 payload.enforced 决定）。
+	EventHookBlocked EventType = "hook_blocked"
 )
 
 // TokenUsagePayload 承载单轮 token 用量统计。

internal/runtime/hooks_integration.go

@@ -0,0 +1,170 @@
+package runtime
+
+import (
+	"context"
+	"strings"
+
+	runtimehooks "neo-code/internal/runtime/hooks"
+)
+
+const (
+	// hookErrorClassBlocked 标识由 before_tool_call hook 拦截产生的工具错误分类。
+	hookErrorClassBlocked = "hook_blocked"
+)
+
+type hookContextKey string
+
+const hookRuntimeEnvelopeKey hookContextKey = "runtime_hook_envelope"
+
+type hookRuntimeEnvelope struct {
+	RunID     string
+	SessionID string
+	Turn      int
+	Phase     string
+}
+
+// HookExecutor 定义 runtime 调用 hook 的最小执行契约。
+type HookExecutor interface {
+	Run(ctx context.Context, point runtimehooks.HookPoint, input runtimehooks.HookContext) runtimehooks.RunOutput
+}
+
+type hookRuntimeEventEmitter struct {
+	service *Service
+}
+
+func newHookRuntimeEventEmitter(service *Service) *hookRuntimeEventEmitter {
+	return &hookRuntimeEventEmitter{service: service}
+}
+
+// EmitHookEvent 将 hooks 包内事件桥接为 runtime 事件，供 TUI 与日志统一消费。
+func (e *hookRuntimeEventEmitter) EmitHookEvent(ctx context.Context, event runtimehooks.HookEvent) error {
+	if e == nil || e.service == nil {
+		return nil
+	}
+	envelope, _ := runtimeHookEnvelopeFromContext(ctx)
+	kind := EventType(strings.TrimSpace(string(event.Type)))
+	if kind == "" {
+		return nil
+	}
+	return e.service.emitWithEnvelope(ctx, RuntimeEvent{
+		Type:           kind,
+		RunID:          envelope.RunID,
+		SessionID:      envelope.SessionID,
+		Turn:           envelope.Turn,
+		Phase:          envelope.Phase,
+		PayloadVersion: 0,
+		Payload: HookEventPayload{
+			HookID:     event.HookID,
+			Point:      string(event.Point),
+			Scope:      string(event.Scope),
+			Kind:       string(event.Kind),
+			Mode:       string(event.Mode),
+			Status:     string(event.Status),
+			StartedAt:  event.StartedAt,
+			DurationMS: event.DurationMS,
+			Error:      event.Error,
+		},
+	})
+}
+
+// runHookPoint 在指定运行态上下文执行一个 hook 点，并自动注入 run/session 元数据。
+func (s *Service) runHookPoint(
+	ctx context.Context,
+	state *runState,
+	point runtimehooks.HookPoint,
+	input runtimehooks.HookContext,
+) runtimehooks.RunOutput {
+	if s == nil || s.hookExecutor == nil {
+		return runtimehooks.RunOutput{}
+	}
+	input.RunID = firstNonBlank(input.RunID, hookRunIDFromState(state))
+	input.SessionID = firstNonBlank(input.SessionID, hookSessionIDFromState(state))
+	scopedCtx := withRuntimeHookEnvelope(ctx, hookRuntimeEnvelope{
+		RunID:     hookRunIDFromState(state),
+		SessionID: hookSessionIDFromState(state),
+		Turn:      hookTurnFromState(state),
+		Phase:     hookPhaseFromState(state),
+	})
+	return s.hookExecutor.Run(scopedCtx, point, input)
+}
+
+func withRuntimeHookEnvelope(ctx context.Context, envelope hookRuntimeEnvelope) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return context.WithValue(ctx, hookRuntimeEnvelopeKey, envelope)
+}
+
+func runtimeHookEnvelopeFromContext(ctx context.Context) (hookRuntimeEnvelope, bool) {
+	if ctx == nil {
+		return hookRuntimeEnvelope{}, false
+	}
+	raw := ctx.Value(hookRuntimeEnvelopeKey)
+	envelope, ok := raw.(hookRuntimeEnvelope)
+	return envelope, ok
+}
+
+func hookRunIDFromState(state *runState) string {
+	if state == nil {
+		return ""
+	}
+	return strings.TrimSpace(state.runID)
+}
+
+func hookSessionIDFromState(state *runState) string {
+	if state == nil {
+		return ""
+	}
+	return strings.TrimSpace(state.session.ID)
+}
+
+func hookTurnFromState(state *runState) int {
+	if state == nil {
+		return turnUnspecified
+	}
+	return state.turn
+}
+
+func hookPhaseFromState(state *runState) string {
+	if state == nil {
+		return ""
+	}
+	if state.lifecycle == "" {
+		return ""
+	}
+	return string(state.lifecycle)
+}
+
+func firstNonBlank(values ...string) string {
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func findHookBlockMessage(output runtimehooks.RunOutput) string {
+	if !output.Blocked {
+		return ""
+	}
+	for _, result := range output.Results {
+		if !strings.EqualFold(strings.TrimSpace(result.HookID), strings.TrimSpace(output.BlockedBy)) {
+			continue
+		}
+		message := strings.TrimSpace(result.Message)
+		if message != "" {
+			return message
+		}
+		errText := strings.TrimSpace(result.Error)
+		if errText != "" {
+			return errText
+		}
+		break
+	}
+	if blockedBy := strings.TrimSpace(output.BlockedBy); blockedBy != "" {
+		return "hook blocked by " + blockedBy
+	}
+	return "hook blocked"
+}