[FEATURE] Session pinning is invisible from the CLI: expose it in `agents --json` and `--help`

Summary

Session pinning exists in the agent view (Ctrl+T) and in the desktop/web GUI, but it is effectively invisible from the CLI. A terminal-first user has no way to discover that pinning exists, no way to check whether a session is pinned, and no non-interactive way to pin one.

This is a discoverability and parity gap rather than a missing feature — which is arguably worse, because the feature is already built and users are not finding it.

What I checked (v2.1.220)

| Surface | Result |
|---|---|
| claude --help | No mention of pin, favourite, bookmark, or star |
| claude agents --help | Documents ~20 flags; none relate to pinning |
| claude agents --json | Session object exposes pid, id, cwd, kind, startedAt, sessionId, name, status, state — no pinned field |
| Subcommands (agents, project, auth, mcp, plugin, …) | None expose pin state |
| ~/.claude.json | No pin-related key |

The only place Ctrl+T is documented, as far as I can find, is inside the agent-view TUI itself and in #70491.

Why it matters

For background agents, pinning is not cosmetic — per #70491 it also keeps the process alive past the ~1h idle timeout. So the pin state has a real operational effect on long-running sessions, and it is currently:

• not discoverable without already knowing about it,
• not queryable for scripting or monitoring,
• not settable outside an interactive TUI.

A user running long background jobs can lose a session to the idle supervisor purely because they never learned that a keybinding would have prevented it.

Suggested changes

Roughly in order of effort-to-value:

1. Expose pinned in claude agents --json. Smallest change, immediately useful for scripting and for checking state without attaching to the TUI.
2. Mention pinning in claude agents --help — one line naming Ctrl+T and the fact that it exempts the session from the idle timeout.
3. Add a non-interactive way to set it, e.g. claude agents --pin <session-id> / --unpin, so pinning can be scripted alongside --bg.

Related

• #70491 — auto-pin new background agent sessions (marked stale); overlapping motivation, different ask
• #63842 — pinning to exempt sessions from cleanup retention; different surface

Environment

• Claude Code v2.1.220, macOS (Darwin 25.5.0), zsh
• Usage pattern: long-running background agents (--bg) doing continuous production monitoring, resumed across days