feat(cli): JSON output envelope with stable error codes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

internal/cli/envelope.go

@@ -0,0 +1,49 @@
+// Package cli implements command dispatch and the agent JSON envelope.
+package cli
+
+import (
+	"encoding/json"
+	"io"
+)
+
+const (
+	CodeConfig   = "config"
+	CodeDB       = "db"
+	CodeNetwork  = "network"
+	CodeAuth     = "auth"
+	CodePolicy   = "policy"
+	CodeNotFound = "not_found"
+	CodeUsage    = "usage"
+)
+
+// Envelope is the single JSON object every agent command emits.
+type Envelope struct {
+	Error       bool           `json:"error"`
+	ErrorDetail map[string]any `json:"error_detail"`
+	Data        any            `json:"data"`
+}
+
+func Success(data any) Envelope {
+	if data == nil {
+		data = map[string]any{}
+	}
+	return Envelope{Error: false, ErrorDetail: map[string]any{}, Data: data}
+}
+
+func Failure(code, message string) Envelope {
+	return Envelope{
+		Error:       true,
+		ErrorDetail: map[string]any{"code": code, "message": message},
+		Data:        map[string]any{},
+	}
+}
+
+func (e Envelope) Write(w io.Writer) error {
+	b, err := json.Marshal(e)
+	if err != nil {
+		return err
+	}
+	b = append(b, '\n')
+	_, err = w.Write(b)
+	return err
+}