[alexeyzimarev]

Closes #1291 — AI-3456

What & why

kcap agent ls gains a TITLE column, so you can tell agents apart without attaching. The daemon already resolves a title per agent for the desktop app's status payload — the session title once one lands, else the launch prompt's first line — and now appends it as a seventh column of the agent table.

Where to look

The column is opt-in: the CLI asks for it with a List request whose payload is title. An older CLI refuses any table that is not 3 or 6 columns wide, so an unrequested seventh column would break its ls and stop --all. An older daemon ignores the payload and answers with 6 columns, and the CLI then omits TITLE. A plain List is still a zero-length payload.

Verification

• dotnet build Capacitor.slnx: 0 warnings, 0 errors
• AgentIdResolutionTests 14/14, ListFrameCodecTests 2/2, AgentOrchestratorLocalAttachTests 48/48 — including a real-socket round trip asserting the title arrives

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-02T11:07:14.890431Z	3fbf62c	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[qodo-code-review]

PR Summary by Qodo

Show agent session titles in kcap agent ls

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Add a TITLE column so users can distinguish agents without attaching to them.
• Request titles explicitly to preserve compatibility with older CLIs and daemons.
• Test protocol compatibility, table formatting, and a real-socket title round trip.

Diagram

sequenceDiagram
    actor User
    participant CLI
    participant Codec
    participant Daemon
    participant Orchestrator
    User->>CLI: agent ls
    CLI->>Codec: List with title request
    Codec->>Daemon: List frame
    alt Daemon supports titles
        Daemon->>Orchestrator: List with titles
        Orchestrator-->>Daemon: Seven-column table
    else Older daemon
        Note over Daemon: Ignores request payload
    end
    Daemon-->>Codec: AgentList table
    Codec-->>CLI: Parsed response
    CLI-->>User: Table with available columns

Loading

High-Level Assessment

Keep the opt-in column on the existing List protocol. An unconditional seventh column would break older CLIs, while a separate title lookup would duplicate title resolution and add a request; the current approach preserves both compatibility directions.

Files changed (11) +135 / -27

Enhancement (5) +42 / -19

FrameCodec.csCarry optional text in List frames +4/-4

Carry optional text in List frames

• Encodes and decodes List requests as UTF-8 text while retaining an empty payload for plain requests.

src/Capacitor.Cli.Core/LocalIpc/FrameCodec.cs

LocalFrame.csAdd a title-requesting List frame helper +6/-0

Add a title-requesting List frame helper

• Defines the title request value and provides a constructor for opt-in List requests.

src/Capacitor.Cli.Core/LocalIpc/LocalFrame.cs

AgentOrchestrator.LocalIpc.csAppend resolved titles when requested +3/-2

Append resolved titles when requested

• Adds a sanitized seventh table field using the resolved session title or launch title. Requests without the title option retain six fields.

src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.LocalIpc.cs

LocalControlServer.csPass the List title option to the orchestrator +1/-1

Pass the List title option to the orchestrator

• Checks the List request text and enables the title column only when explicitly requested.

src/Capacitor.Cli.Daemon/Services/LocalControlServer.cs

AgentCommand.csRequest, parse, and display agent titles +28/-12

Request, parse, and display agent titles

• Requests titles and accepts three-, six-, or seven-field daemon rows. Displays an aligned TITLE column when any title is present and preserves the older layout otherwise.

src/Capacitor.Cli/Commands/AgentCommand.cs

Tests (3) +89 / -4

ListFrameCodecTests.csTest List frame payload compatibility +26/-0

Test List frame payload compatibility

• Verifies plain List requests remain payload-free and title requests survive a codec round trip.

test/Capacitor.Cli.Core.Tests.Unit/LocalIpc/ListFrameCodecTests.cs

AgentOrchestratorLocalAttachTests.csTest opt-in titles over daemon IPC +29/-4

Test opt-in titles over daemon IPC

• Checks six-field versus seven-field replies and title delimiter sanitization. Extends a real-socket test to assert title delivery.

test/Capacitor.Cli.Daemon.Tests.Unit/Services/AgentOrchestratorLocalAttachTests.cs

AgentIdResolutionTests.csTest title parsing and table layout +34/-0

Test title parsing and table layout

• Covers title parsing, empty titles from older daemons, repo-column alignment, and omission of TITLE for legacy rows.

test/Capacitor.Cli.Tests.Unit/Commands/AgentIdResolutionTests.cs

Documentation (3) +4 / -4

README.mdDocument titles in agent listings +1/-1

Document titles in agent listings

• Adds title to the documented fields shown by 'kcap agent ls'.

README.md

FrameType.csDescribe the optional title-column protocol +2/-2

Describe the optional title-column protocol

• Documents the 'title' List request and the optional seventh AgentList field.

src/Capacitor.Cli.Core/LocalIpc/FrameType.cs

help-usage.txtMention titles in CLI help +1/-1

Mention titles in CLI help

• Adds title to the 'agent ls' field description.

src/Capacitor.Cli.Core/Resources/help-usage.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Newly started agents lack a TITLE column ✓ Resolved

Description

FormatAgentTable treats an empty title value as proof that the daemon did not send a title column.
A current daemon sends seven columns even for empty titles, and locally spawned agents start without
a prompt title, so a list containing only those agents omits the requested column.

Code

src/Capacitor.Cli/Commands/AgentCommand.cs[332]

+        if (agents.All(a => a.Title.Length == 0)) {

Relevance

●●● Strong

Accepted precedents favor fixing incorrect empty-value inference and preserving optional-column
semantics.

PR-#408
PR-#1183

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The daemon appends the requested seventh field regardless of its value, while the CLI decides
whether to display that field solely by checking for a nonempty parsed title. The local spawn path
constructs agents with a null prompt, which yields no initial prompt title.

src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.LocalIpc.cs[13-18]
src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.LocalIpc.cs[330-333]
src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.cs[90-96]
src/Capacitor.Cli/Commands/AgentCommand.cs[329-343]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A seven-column response with empty title values is rendered as though it came from an older daemon, hiding TITLE for newly spawned agents.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/AgentCommand.cs[329-343]
- src/Capacitor.Cli/Commands/AgentCommand.cs[384-393]
- src/Capacitor.Cli/Commands/AgentCommand.cs[504-508]

## Recommended Fix
Preserve the response's column count separately from title values and use that to decide whether to render TITLE. Add a test for a seven-column row with an empty title.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Agent titles can control the terminal ✓ Resolved

Description

FormatAgentTable prints the new title field without removing terminal control characters, while
the daemon's Cell helper removes only tabs and line breaks. A launch prompt containing an ANSI
escape sequence can become the agent's title and reach Console.WriteLine when someone runs `kcap
agent ls`.

Code

src/Capacitor.Cli/Commands/AgentCommand.cs[343]

+            yield return $"{a.Id,-34} {a.Status,-10} {a.Kind,-12} {RepoCell(a).PadRight(repoWidth)} {a.Title}".TrimEnd();

Relevance

●●● Strong

Recent precedents accept sanitizing untrusted control characters before emitting CLI output.

PR-#505
PR-#250
PR-#1178

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Launch prompts are strings, and the prompt-title extraction trims and truncates them without
filtering ESC. The daemon's table sanitizer replaces only tab, LF and CR; the parsed seventh field
is then interpolated directly into console output.

src/Capacitor.Cli.Core/Models.cs[1550-1555]
src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.cs[120-131]
src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.LocalIpc.cs[13-26]
src/Capacitor.Cli/Commands/AgentCommand.cs[339-343]
src/Capacitor.Cli/Commands/AgentCommand.cs[498-509]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Control characters from an agent title can pass through the new list column and be interpreted by the user's terminal.

## Fix Focus Areas
- src/Capacitor.Cli.Daemon/Services/AgentOrchestrator.LocalIpc.cs[13-26]
- src/Capacitor.Cli/Commands/AgentCommand.cs[339-343]

## Recommended Fix
Sanitize terminal control characters in the title before displaying it, including ESC and other nonprinting controls; retain delimiter neutralization for the wire format. Add a test using a prompt title containing an ANSI escape sequence.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 64 rules

✅ Cross-repo context — repo relationships

Review mode: ⚖️ Balanced: This is a cross-component IPC protocol and CLI/daemon behavior change with backward-compatibility logic and multiple parsing/formatting paths, warranting a complete single-pass review.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗