chore: classify User-Agent mode as interactive/agent/noninteractive

The non-TTY soft signal (pipes, redirects, CI/CD) enables agent-mode
behavior but isn't a confirmed AI agent. Tagging it mode=agent would
conflate genuine agent traffic with CI and piped use in analytics.

Derive a three-value mode= token from the detection reason: agent (only
for explicit --agent/DCI_AGENT_MODE=1 or a known AI-agent env var),
noninteractive (non-TTY soft signal), and interactive (human TTY or
explicit human mode). Runtime behavior is unchanged.

Author: claude

README.md

@@ -92,7 +92,7 @@ that is cheap to parse and free of decoration:
 - Default `--output` becomes `toon` (compact, token-efficient) instead of `table`
 - No color, spinners, or other terminal decoration
 - Banners, tips, and status chatter go to **stderr**, leaving **stdout** for data only
-- The request `User-Agent` carries `mode=agent` (human invocations carry `mode=interactive`) so API traffic can be segmented by interface
+- The request `User-Agent` carries a `mode=` token — `agent` (explicit flag/env or a known AI-agent environment), `noninteractive` (piped/redirected output or CI/CD), or `interactive` (human at a terminal) — so API traffic can be segmented by interface
 
 ### How agent mode is detected
 

main.go

@@ -64,6 +64,22 @@ var agentMode bool
 // agentModeReason records why agentMode resolved the way it did, for diagnostics.
 var agentModeReason string
 
+// uaMode classifies how dci is being driven, for the User-Agent "mode=" token.
+// It is finer-grained than agentMode (a bool): agent mode reached via the
+// non-TTY soft signal (pipes, redirects, CI/CD) is reported as noninteractive
+// rather than agent, so analytics can tell genuine AI-agent traffic apart from
+// incidental non-interactive use.
+type uaMode string
+
+const (
+	uaModeInteractive    uaMode = "interactive"    // human at a TTY (or explicit human mode)
+	uaModeAgent          uaMode = "agent"          // explicit --agent/DCI_AGENT_MODE=1, or a known AI-agent env var
+	uaModeNonInteractive uaMode = "noninteractive" // non-TTY soft signal: pipe/redirect/CI
+)
+
+// agentUAMode records the interface classification for the User-Agent token.
+var agentUAMode uaMode
+
 // agentEnvDetected holds the name of the detected agent environment variable (if
 // any), used to surface the human-mode "an optimized agent mode exists" tip.
 var agentEnvDetected string
@@ -218,6 +234,7 @@ func run() (exitCode int) {
 	dec := resolveAgentMode(os.Getenv("DCI_AGENT_MODE"), os.Args, agentEnvDetected, stdoutIsTTY())
 	agentMode = dec.enabled
 	agentModeReason = dec.reason
+	agentUAMode = dec.mode
 	if agentMode {
 		// Disable restish/aurora color before cli.Init configures the output
 		// writers; it reads this via viper's automatic env binding.
@@ -260,10 +277,10 @@ func run() (exitCode int) {
 	viper.Set("rsh-profile", "default")
 
 	// Hardcode user-agent so the DCI API can identify CLI traffic. It carries a
-	// mode=agent|interactive token (never the end user) so traffic can be
-	// segmented by interface. Restish picks this up via rsh-header and skips its
-	// own default.
-	viper.Set("rsh-header", []string{"user-agent:" + buildUserAgent(agentMode)})
+	// mode=<interactive|agent|noninteractive> token (never the end user) so
+	// traffic can be segmented by interface. Restish picks this up via rsh-header
+	// and skips its own default.
+	viper.Set("rsh-header", []string{"user-agent:" + buildUserAgent(agentUAMode)})
 
 	cli.Load("dci", cli.Root)
 	applyAPIKeyAuth()
@@ -513,6 +530,7 @@ var agentEnvVars = []string{
 
 type agentModeResult struct {
 	enabled bool
+	mode    uaMode
 	reason  string
 }
 
@@ -530,22 +548,27 @@ func resolveAgentMode(dciAgentMode string, args []string, agentEnv string, stdou
 		// (e.g. DCI_AGENT_MODE=2) is ignored so a typo can't silently force a
 		// mode; run() warns about it separately.
 		if b, ok := parseBoolish(v); ok {
-			return agentModeResult{enabled: b, reason: "DCI_AGENT_MODE override"}
+			if b {
+				return agentModeResult{enabled: true, mode: uaModeAgent, reason: "DCI_AGENT_MODE override"}
+			}
+			return agentModeResult{enabled: false, mode: uaModeInteractive, reason: "DCI_AGENT_MODE override"}
 		}
 	}
 	switch agentFlagOverride(args) {
 	case 1:
-		return agentModeResult{enabled: true, reason: "--agent/--no-agent flag"}
+		return agentModeResult{enabled: true, mode: uaModeAgent, reason: "--agent/--no-agent flag"}
 	case -1:
-		return agentModeResult{enabled: false, reason: "--agent/--no-agent flag"}
+		return agentModeResult{enabled: false, mode: uaModeInteractive, reason: "--agent/--no-agent flag"}
 	}
 	if agentEnv != "" {
-		return agentModeResult{enabled: true, reason: "agent env var " + agentEnv}
+		return agentModeResult{enabled: true, mode: uaModeAgent, reason: "agent env var " + agentEnv}
 	}
 	if !stdoutTTY {
-		return agentModeResult{enabled: true, reason: "non-TTY stdout"}
+		// Non-TTY is a soft signal (pipe/redirect/CI), not a confirmed agent, so
+		// it gets its own UA classification even though behavior matches agent mode.
+		return agentModeResult{enabled: true, mode: uaModeNonInteractive, reason: "non-TTY stdout"}
 	}
-	return agentModeResult{enabled: false, reason: "interactive terminal"}
+	return agentModeResult{enabled: false, mode: uaModeInteractive, reason: "interactive terminal"}
 }
 
 // detectedAgentEnv returns the name of the first agent env var found, or "".
@@ -611,14 +634,13 @@ func parseBoolish(v string) (bool, bool) {
 }
 
 // buildUserAgent returns the User-Agent header value identifying CLI traffic to
-// the DCI API. It always carries a mode=agent|interactive token so API traffic
-// can be segmented by interface (agent- vs human-driven) in analytics. The
-// token reflects only the interface, never the end user, so the value stays a
+// the DCI API. It always carries a mode=<interactive|agent|noninteractive>
+// token so API traffic can be segmented by interface in analytics. The token
+// reflects only how dci was driven, never the end user, so the value stays a
 // stable client identifier.
-func buildUserAgent(agent bool) string {
-	mode := "interactive"
-	if agent {
-		mode = "agent"
+func buildUserAgent(mode uaMode) string {
+	if mode == "" {
+		mode = uaModeInteractive
 	}
 	return fmt.Sprintf("dci-cli/%s (%s; %s/%s; mode=%s)", version, runtime.Version(), runtime.GOOS, runtime.GOARCH, mode)
 }

main_test.go

@@ -395,34 +395,39 @@ func TestResolveAgentMode(t *testing.T) {
 		agentEnv  string
 		stdoutTTY bool
 		want      bool
+		wantMode  uaMode
 	}{
 		// 1. DCI_AGENT_MODE always wins.
-		{name: "env mode 1 wins over tty", envMode: "1", args: nil, agentEnv: "", stdoutTTY: true, want: true},
-		{name: "env mode true", envMode: "true", stdoutTTY: true, want: true},
-		{name: "env mode 0 forces human", envMode: "0", agentEnv: "CLAUDECODE", stdoutTTY: false, want: false},
-		{name: "env mode false forces human", envMode: "false", stdoutTTY: false, want: false},
-		{name: "env mode wins over --agent", envMode: "0", args: []string{"--agent"}, stdoutTTY: false, want: false},
-		{name: "env mode garbage ignored, falls through to tty", envMode: "2", stdoutTTY: true, want: false},
-		{name: "env mode garbage ignored, falls through to env var", envMode: "banana", agentEnv: "KIRO_AGENT", stdoutTTY: true, want: true},
+		{name: "env mode 1 wins over tty", envMode: "1", args: nil, agentEnv: "", stdoutTTY: true, want: true, wantMode: uaModeAgent},
+		{name: "env mode true", envMode: "true", stdoutTTY: true, want: true, wantMode: uaModeAgent},
+		{name: "env mode 0 forces human", envMode: "0", agentEnv: "CLAUDECODE", stdoutTTY: false, want: false, wantMode: uaModeInteractive},
+		{name: "env mode false forces human", envMode: "false", stdoutTTY: false, want: false, wantMode: uaModeInteractive},
+		{name: "env mode wins over --agent", envMode: "0", args: []string{"--agent"}, stdoutTTY: false, want: false, wantMode: uaModeInteractive},
+		{name: "env mode garbage ignored, falls through to tty", envMode: "2", stdoutTTY: true, want: false, wantMode: uaModeInteractive},
+		{name: "env mode garbage ignored, falls through to env var", envMode: "banana", agentEnv: "KIRO_AGENT", stdoutTTY: true, want: true, wantMode: uaModeAgent},
 
 		// 2. Flags override heuristics.
-		{name: "--agent forces agent", args: []string{"dci", "--agent", "status"}, stdoutTTY: true, want: true},
-		{name: "--no-agent forces human", args: []string{"dci", "--no-agent", "list"}, agentEnv: "CLAUDECODE", stdoutTTY: false, want: false},
-		{name: "--no-agent over tty", args: []string{"--no-agent"}, stdoutTTY: false, want: false},
+		{name: "--agent forces agent", args: []string{"dci", "--agent", "status"}, stdoutTTY: true, want: true, wantMode: uaModeAgent},
+		{name: "--no-agent forces human", args: []string{"dci", "--no-agent", "list"}, agentEnv: "CLAUDECODE", stdoutTTY: false, want: false, wantMode: uaModeInteractive},
+		{name: "--no-agent over tty", args: []string{"--no-agent"}, stdoutTTY: false, want: false, wantMode: uaModeInteractive},
 
 		// 3. Agent env var heuristic.
-		{name: "agent env enables", agentEnv: "CURSOR_AGENT", stdoutTTY: true, want: true},
+		{name: "agent env enables", agentEnv: "CURSOR_AGENT", stdoutTTY: true, want: true, wantMode: uaModeAgent},
 
-		// 4. Non-TTY soft signal.
-		{name: "non-tty enables", stdoutTTY: false, want: true},
-		{name: "interactive tty stays human", stdoutTTY: true, want: false},
+		// 4. Non-TTY soft signal — agent behavior, but classified noninteractive
+		// (covers CI/CD and piped/redirected use).
+		{name: "non-tty enables", stdoutTTY: false, want: true, wantMode: uaModeNonInteractive},
+		{name: "interactive tty stays human", stdoutTTY: true, want: false, wantMode: uaModeInteractive},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got := resolveAgentMode(tt.envMode, tt.args, tt.agentEnv, tt.stdoutTTY)
 			if got.enabled != tt.want {
-				t.Fatalf("resolveAgentMode() = %v (reason %q), want %v", got.enabled, got.reason, tt.want)
+				t.Fatalf("resolveAgentMode() enabled = %v (reason %q), want %v", got.enabled, got.reason, tt.want)
+			}
+			if got.mode != tt.wantMode {
+				t.Fatalf("resolveAgentMode() mode = %q (reason %q), want %q", got.mode, got.reason, tt.wantMode)
 			}
 		})
 	}
@@ -460,26 +465,33 @@ func TestAgentFlagOverride(t *testing.T) {
 }
 
 func TestBuildUserAgent(t *testing.T) {
-	human := buildUserAgent(false)
-	if !strings.HasPrefix(human, "dci-cli/") {
-		t.Fatalf("unexpected User-Agent prefix: %q", human)
-	}
 	// The mode token is always present and self-describing so analytics can
-	// segment by interface; human mode is explicitly mode=interactive.
-	if !strings.Contains(human, "mode=interactive") {
-		t.Fatalf("human User-Agent must carry mode=interactive: %q", human)
-	}
-	if strings.Contains(human, "mode=agent") {
-		t.Fatalf("human User-Agent must not carry mode=agent: %q", human)
+	// segment by interface across all three classifications.
+	cases := []struct {
+		mode uaMode
+		want string
+	}{
+		{uaModeInteractive, "mode=interactive"},
+		{uaModeAgent, "mode=agent"},
+		{uaModeNonInteractive, "mode=noninteractive"},
+	}
+	for _, c := range cases {
+		ua := buildUserAgent(c.mode)
+		if !strings.HasPrefix(ua, "dci-cli/") {
+			t.Fatalf("unexpected User-Agent prefix: %q", ua)
+		}
+		if !strings.Contains(ua, c.want) {
+			t.Fatalf("buildUserAgent(%q) = %q, want it to contain %q", c.mode, ua, c.want)
+		}
+		// Guard against the legacy opaque tag regressing.
+		if strings.Contains(ua, "agent=1") {
+			t.Fatalf("User-Agent must use mode=, not the legacy agent=1 tag: %q", ua)
+		}
 	}
 
-	agent := buildUserAgent(true)
-	if !strings.Contains(agent, "mode=agent") {
-		t.Fatalf("agent User-Agent must carry mode=agent: %q", agent)
-	}
-	// Guard against the legacy opaque tag regressing.
-	if strings.Contains(agent, "agent=1") {
-		t.Fatalf("User-Agent must use mode=agent, not the legacy agent=1 tag: %q", agent)
+	// An unset mode falls back to interactive rather than emitting "mode=".
+	if ua := buildUserAgent(""); !strings.Contains(ua, "mode=interactive") {
+		t.Fatalf("empty mode should default to interactive: %q", ua)
 	}
 }