feat(sdk): expose typed pending terminal-agent interactions

[toddagent01]

What problem are you trying to solve?

Superset already knows when a terminal agent needs attention: its lifecycle hooks record PermissionRequest, and the workspace board and notifications show the workspace as waiting. Public terminal consumers can read that normalized state once #7007 lands, but the host retains no typed description of the pending interaction.

That prevents another interface attached to the same terminal—for example a Linear agent session—from showing the question or choices the agent is waiting on. Claude Code demonstrates the gap clearly: its PermissionRequest hook fires with a structured AskUserQuestion payload before the question is committed to the provider transcript. Superset correctly shows Needs attention while an external consumer can only say generically that input is required.

Reading terminal screen text is not a safe contract, and making each integration independently scrape provider files would create competing lifecycle owners. Slack and Linear launch integrations are separate workflows; they do not expose the local terminal's pending interaction.

Downstream reproduction and acceptance context: todd-studio/workstation#252.

Proposed solution

Extend the host-owned terminal-agent binding with an optional provider-neutral pendingInteraction that is exposed alongside agentStatus on workspace-scoped terminal listings.

The contract should carry only user-facing interaction data, for example:

• interaction kind (question or approval)
• provider request/item id when available
• one or more questions with stable id, short header, question text, and optional choices/descriptions
• whether free-form input is accepted

Provider adapters should normalize their native event into that contract. Raw hook/tool payloads must not be persisted or exposed: they can contain commands, file content, or secrets. The pending interaction should clear on the canonical event that proves it was answered or the turn ended, while the terminal/session identity remains intact.

Claude Code can populate this from its structured PermissionRequest / AskUserQuestion hook input. Codex exposes a typed item/tool/requestUserInput request in its app-server protocol and records its custom tool call in the rollout; its adapter should map the same public contract rather than introducing Codex-specific fields. Providers without structured content can continue to expose only PermissionRequest.

This keeps one owner for lifecycle and lets SDK/CLI consumers render an exact prompt without interpreting terminal output.

Workarounds you've tried

• Provider transcript observation works for Codex and Kimi, but Claude does not commit an interactive AskUserQuestion until after the dialog is answered.
• Reading terminal output or window titles would be brittle screen scraping and can capture sensitive content.
• Superset's documented Linear custom script launches/opens a workspace; it does not relay terminal state. Its Slack integration starts a separate cloud agent/workspace and therefore does not mirror an existing local terminal.
• #7007 deliberately exposes only the existing normalized lifecycle state so that small, reviewable change is not coupled to this larger interaction/security contract.

[github-actions]

This is a feature request rather than a bug report, so I traced the current data path end-to-end to confirm the gap and pin down where each piece of the proposed contract would have to land.

---

Summary

The request is to add a provider-neutral pendingInteraction to the host-owned terminal-agent binding, so that a non-Superset consumer attached to the same terminal (the cited case is a Linear agent session) can render what the agent is blocked on rather than just that it is blocked. I confirmed the gap: Superset does record the blocked state, but the structured content that produced it is discarded at the very first hop — the shell hook — long before it reaches the store, the DB, or any public read. Nothing in the proposal is speculative; every piece it asks for is genuinely absent today.

Where the structured payload is currently dropped

The hook receives the full provider payload and throws all but four scalars away:

• packages/agent-setup/templates/notify-hook.template.sh:8-12 reads the whole hook JSON into $INPUT (argv for Codex, stdin for Claude and friends), then :23-71 extract only agent_id, session_id/sessionId, resourceId, thread-id, and the event type via grep -oE.
• :124 builds the POST body, and it carries exactly terminalId, eventType, agent.agentId, agent.sessionId. $INPUT is never forwarded.
• Even if it were, packages/host-service/src/trpc/router/notifications/notifications.ts:19-23 (hookInput) is a closed Zod object with those same three keys, so anything extra is stripped.
• packages/host-service/src/events/map-event-type.ts:65-76 collapses Claude's PermissionRequest, Codex's exec_approval_request / apply_patch_approval_request / request_user_input, and Grok's remapped Notification into one opaque "PermissionRequest" string. That single string is the entire surviving description of the interaction.

From there it is stored as a bare event name and nothing else:

• packages/host-service/src/terminal-agents/types.ts:32-43 — TerminalAgentBinding has lastEventType: string and no payload field.
• packages/host-service/src/db/schema.ts:46-70 — terminal_agent_bindings has no column for it (a migration is required; per AGENTS.md, via .agents/skills/db-migrations/SKILL.md, not by hand-editing packages/db/drizzle/).
• packages/host-service/src/terminal-agents/persistence.ts:15-26 — bindingColumns is the projection every read shares.
• apps/desktop/src/renderer/hooks/host-service/useTerminalAgentStatuses/deriveTerminalAgentStatus.ts:18 — the desktop UI's "permission" status is derived purely from that string, which is exactly why the board can only say Needs attention.

And the public surface confirms #7007 has not landed here: packages/sdk/src/resources/terminals.ts:116-124 (TerminalSummary) and its host-side source packages/host-service/src/terminal/terminal.ts:751-759 (TerminalSessionSummary, served by terminal.list at trpc/router/terminal/terminal.ts:128-140) carry no agent fields at all today. The richer terminalAgents.list / listByWorkspace (trpc/router/terminal-agents/terminal-agents.ts:228-246) return whole bindings but are protectedProcedure on the host router, not part of the SDK's terminal listing.

Prior art worth reusing rather than reinventing

The repo already has a provider-neutral pending-interaction contract, in the chat stack:

• packages/chat/src/protocol/items.ts:137-149 — approvalRequestSchema: targetItemId, title, detail, options[{ optionId, label }], status: pending | answered | stale, decision.
• Both adapters already normalize into it: packages/chat-runtime/src/harness/claude/claudeAdapter/claudeAdapter.ts:289 and packages/chat-runtime/src/harness/codex/codexAdapter/codexAdapter.ts:445-497 (the latter maps item/commandExecution/requestApproval and item/fileChange/requestApproval from the app-server protocol the issue references).

That is a different runtime from terminal agents, so it can't be wired up directly — but adopting a subset of that shape would avoid a third vocabulary for the same concept, and the Codex adapter is a working reference for the mapping the issue asks its adapter to perform.

Design constraints a maintainer should settle first

1. The hook script cannot parse this. notify-hook.template.sh is POSIX sh with grep -oE and no jq. It can scrape a flat "key": "string" pair, and no more — nested questions[].options[] from AskUserQuestion is out of reach. So either the raw hook input gets forwarded to the host for server-side normalization (raw parsed and discarded, never persisted — compatible with the issue's requirement, but see the next point), or the hook shells out to a small Node/Bun normalizer.

2. notifications.hook is deliberately unauthenticated. The comment at notifications.ts:76-85 justifies this explicitly: the worst a forged call achieves is "a chime, a sidebar indicator, and the idempotent forward-only task nudge". Adding attacker-controllable user-facing text that a Linear or Slack surface will render changes that calculus — any local process could attribute an arbitrary question to a real workspace. The SUPERSET_* env guard at :18 protects the agent side, not the endpoint. This is worth an explicit decision in the design, not an implementation detail.

3. Clearing has three call sites, not one. store.recordEvent (terminal-agents/store.ts:96-164) overwrites lastEventType on every event, so a new column must be explicitly nulled on any non-PermissionRequest event; clearWorkspaceStatuses (store.ts:187-200, the sidebar "Clear Status" escape hatch and the pane-interrupt path in useTerminalInterruptClear) must clear it too; and so must endBinding (store.ts:261-278). Note also that mapEventType maps PermissionResult → Start (map-event-type.ts:51), but PermissionResult is not in CLAUDE_MANAGED_EVENTS (agent-wrappers-claude-codex-opencode.ts:70-79) — so for Claude there is no registered "answered" event today, and clearing would ride on the subsequent PostToolUse/Stop. Registering PermissionResult would give the canonical clear-on-answered signal the issue asks for.

4. Size cap. A JSON TEXT column fed from provider payloads needs a hard length bound at ingest; a question body is unbounded in principle.

5. The straggler/revival logic is sensitive. store.ts:113-131 and persistence.ts:41-56 go to some length to stop late events from resurrecting ended rows and destroying resume candidates. A new column has to follow the same rules or it will resurface a stale question against a dead terminal.

Reproducing / verifying the gap

Manually: run claude in a Superset terminal, get it to call AskUserQuestion, and while the dialog is open compare superset terminals list --workspace <id> (packages/cli/src/commands/terminals/list/command.ts) against the desktop board. The board shows the workspace waiting; the listing has no agent field at all, and the underlying binding's only description of the interaction is lastEventType === "PermissionRequest".

As a bun:test, the smallest failing assertion sits in the existing harness at packages/host-service/src/trpc/router/notifications/notifications.test.ts:16-45 — post a hook with a structured AskUserQuestion body and assert the resulting terminalAgentStore.get(terminalId) exposes the question text and choices. It fails at the schema boundary today. packages/host-service/src/terminal-agents/store.test.ts is the right place for the clear-on-answer and no-revival-after-end cases, and packages/agent-setup/src/notify-hook.test.ts for whatever the hook ends up forwarding.

Suggested direction

1. Define the contract in shared code, as a narrow subset of approvalRequestSchema (packages/chat/src/protocol/items.ts:137-149): kind: "question" | "approval", optional provider requestId, questions[{ id, header, question, options?[{ optionId, label, description? }] }], acceptsFreeform: boolean.
2. Normalize per provider before it crosses the host boundary, so raw hook input never reaches the store or the DB — settle question 1 above on whether that's a Node normalizer in the hook or server-side parsing behind an authenticated field.
3. Add a nullable pending_interaction TEXT column to terminal_agent_bindings plus bindingColumns/rowToBinding (persistence.ts:15-56), and clear it at all three sites in question 3.
4. Join it alongside agentStatus in whatever feat(sdk): expose terminal agent lifecycle status #7007 adds to TerminalSessionSummary (terminal/terminal.ts:751-759) and TerminalSummary (sdk/src/resources/terminals.ts:116-124).
5. Add a test asserting no raw hook field ever reaches the persisted column — this is the security property the issue is really buying, and it should be enforced rather than reviewed.

One scoping note: the issue frames Claude as the motivating case, but Claude is the only provider where the structured payload is reachable and absent from the transcript. Codex already exposes it in the rollout and via the app-server protocol, and Grok's elicitation_dialog is already recognized as a blocking subtype (agent-wrappers-grok.ts:41-48) without its content being captured. Landing Claude first and mapping the others onto the same contract afterwards would keep the security-sensitive surface small.