feat(acp): surface Cursor subagent metadata via cursor/task (#2867)

This commit is contained in:
Carlos Florêncio
2026-08-21 16:36:30 +01:00
committed by GitHub
parent 981110a42e
commit c8b0b50ff8
25 changed files with 1362 additions and 11 deletions
+12 -2
View File
@@ -73,7 +73,7 @@ Usage:
acpdbg probe [flags] <agent>
acpdbg probe --exec "<cmd> [args...]" [flags]
acpdbg mcp-probe [flags] <agent>
acpdbg prompt --prompt TEXT [--model M] [--mode M] [flags] <agent>
acpdbg prompt --prompt TEXT [--model M] [--mode M] [--linger DUR] [flags] <agent>
acpdbg session-load --session-id ID [--prompt TEXT] [flags] <agent>
acpdbg matrix [flags]
@@ -240,12 +240,19 @@ func runPrompt(ctx context.Context, args []string) error {
model := fs.String("model", "", "model to set before prompting")
mode := fs.String("mode", "", "session mode to set before prompting")
prompt := fs.String("prompt", "", "prompt text (required)")
linger := fs.Duration("linger", 0, "keep the session open this long after the prompt returns, recording any late frames; extends the run beyond --timeout (must be >= 0)")
if err := fs.Parse(args); err != nil {
return err
}
if *prompt == "" {
return errors.New("--prompt is required")
}
if *linger < 0 {
// A negative linger would shrink the run deadline below --timeout and
// could cancel the prompt before it completes. The linger window only
// ever extends the run.
return errors.New("--linger must not be negative")
}
cfg, err := resolveRunConfig(fs, shared, "prompt")
if err != nil {
@@ -253,7 +260,9 @@ func runPrompt(ctx context.Context, args []string) error {
}
jsonlPath := resolveJSONLPath(shared, cfg.AgentID, "prompt")
runCtx, cancel := context.WithTimeout(ctx, shared.timeout)
// The run deadline has to cover the prompt turn plus the linger window,
// otherwise the shared --timeout would cancel the session mid-linger.
runCtx, cancel := context.WithTimeout(ctx, shared.timeout+*linger)
defer cancel()
runner, err := acpdbg.NewRunner(runCtx, jsonlPath, cfg)
@@ -266,6 +275,7 @@ func runPrompt(ctx context.Context, args []string) error {
Model: *model,
Mode: *mode,
Prompt: *prompt,
Linger: *linger,
})
if err != nil {
fmt.Fprintf(os.Stderr, "prompt failed: %v\n", err)
+1 -1
View File
@@ -124,4 +124,4 @@ require (
gopkg.in/ini.v1 v1.67.0 // indirect
)
replace github.com/coder/acp-go-sdk => github.com/kdlbs/acp-go-sdk v0.13.6-0.20260722160645-1ce4653527f6
replace github.com/coder/acp-go-sdk => github.com/kdlbs/acp-go-sdk v0.13.6-0.20260821092416-13e3f4dc12c2
+2 -2
View File
@@ -229,8 +229,8 @@ github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnr
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU=
github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk=
github.com/kdlbs/acp-go-sdk v0.13.6-0.20260722160645-1ce4653527f6 h1:PIUaLxC1PZ4Y1ESMzucH2ThVq4yOAH8x8VfCKRSX5pc=
github.com/kdlbs/acp-go-sdk v0.13.6-0.20260722160645-1ce4653527f6/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
github.com/kdlbs/acp-go-sdk v0.13.6-0.20260821092416-13e3f4dc12c2 h1:aWN8W+iAeSlt5iIf+YwzyZ55VevQO0jKp6TvhL818vs=
github.com/kdlbs/acp-go-sdk v0.13.6-0.20260821092416-13e3f4dc12c2/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
github.com/kevinburke/ssh_config v1.6.0 h1:J1FBfmuVosPHf5GRdltRLhPJtJpTlMdKTBjRgTaQBFY=
github.com/kevinburke/ssh_config v1.6.0/go.mod h1:q2RIzfka+BXARoNexmF9gkxEX7DmvbW9P4hIVx2Kg4M=
github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+24
View File
@@ -111,6 +111,11 @@ type PromptOptions struct {
Model string // if non-empty, set via session/set_model (or unstable variant)
Mode string // if non-empty, set via session/set_mode
Prompt string // required — text body of the session/prompt request
// Linger, when > 0, keeps the session open after session/prompt returns
// its stopReason and drains (recording, auto-replying to) any further
// out-of-band frames the agent pushes. This is how we observe a delayed
// async subagent result delivered on the same session after end_turn.
Linger time.Duration
}
// PromptResult holds the text response collected from session/update
@@ -160,9 +165,28 @@ func Prompt(ctx context.Context, r *Runner, opts PromptOptions) (*PromptResult,
if err != nil {
return nil, fmt.Errorf("session/prompt: %w", err)
}
if opts.Linger > 0 {
lingerAfterPrompt(ctx, r, opts.Linger)
}
return &PromptResult{ProbeResult: *probe, Text: text}, nil
}
// lingerAfterPrompt keeps draining out-of-band frames for the given duration
// after session/prompt has already returned its stopReason. Every frame is
// still recorded by the read loop, and NextOOB auto-replies to any
// agent-initiated request so the agent does not hang. This exists to capture a
// delayed async update (e.g. Cursor pushing a background subagent result on the
// same session after end_turn). We swallow the terminal error: a deadline or a
// child that exits first are both expected ways to stop lingering.
func lingerAfterPrompt(ctx context.Context, r *Runner, d time.Duration) {
lingerCtx, cancel := context.WithTimeout(ctx, d)
defer cancel()
// Never returns true, so it drains until the linger deadline or EOF.
_ = r.DrainOOBUntil(lingerCtx, func(Frame) bool { return false })
}
// SessionLoad runs initialize → session/load → [session/prompt].
func SessionLoad(ctx context.Context, r *Runner, opts SessionLoadOptions) (*SessionLoadResult, error) {
if opts.SessionID == "" {
@@ -0,0 +1,95 @@
//go:build !windows
package acpdbg
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
"time"
)
// TestLingerAfterPromptDrainsDelayedFrameAndAutoReplies proves the prompt
// linger path: a frame the agent emits after session/prompt already returned is
// still drained and recorded, an agent-initiated request during the window is
// auto-replied so the agent does not hang, and the linger deadline stops the
// drain harmlessly.
func TestLingerAfterPromptDrainsDelayedFrameAndAutoReplies(t *testing.T) {
framesPath := filepath.Join(t.TempDir(), "frames.jsonl")
// Emit one late agent-initiated request (has id + method) then idle. The
// linger window must outlive the emit but the deadline must still land.
req := `{"jsonrpc":"2.0","id":99,"method":"cursor/task"}`
cmd := fmt.Sprintf("printf '%%s\\n' '%s'; sleep 30", req)
ctx, cancel := context.WithCancel(context.Background())
runner, err := NewRunner(ctx, framesPath, RunConfig{
AgentID: "linger-helper",
Command: []string{"sh", "-c", cmd},
})
if err != nil {
t.Fatalf("NewRunner: %v", err)
}
t.Cleanup(func() {
cancel()
runner.tree.kill(runner.cmd)
runner.Close("test cleanup")
})
start := time.Now()
lingerAfterPrompt(ctx, runner, 300*time.Millisecond)
elapsed := time.Since(start)
// The deadline was honored: lingering returned only after the window, and
// well before the child's 30s sleep.
if elapsed < 250*time.Millisecond {
t.Fatalf("linger returned after %s, want it to honor the ~300ms window", elapsed)
}
if elapsed > 5*time.Second {
t.Fatalf("linger returned after %s, want it bounded by the window", elapsed)
}
// The delayed request was recorded and auto-replied with method-not-found.
raw, err := os.ReadFile(framesPath)
if err != nil {
t.Fatalf("read frames: %v", err)
}
frames := string(raw)
if !strings.Contains(frames, `"cursor/task"`) {
t.Fatalf("delayed request not recorded; frames:\n%s", frames)
}
if !strings.Contains(frames, "-32601") {
t.Fatalf("delayed agent request was not auto-replied with method-not-found; frames:\n%s", frames)
}
}
// TestLingerAfterPromptDeadlineWithNoFramesIsHarmless proves the linger window
// terminates cleanly when the agent emits nothing after the prompt.
func TestLingerAfterPromptDeadlineWithNoFramesIsHarmless(t *testing.T) {
framesPath := filepath.Join(t.TempDir(), "frames.jsonl")
ctx, cancel := context.WithCancel(context.Background())
runner, err := NewRunner(ctx, framesPath, RunConfig{
AgentID: "linger-idle-helper",
Command: []string{"sh", "-c", "sleep 30"},
})
if err != nil {
t.Fatalf("NewRunner: %v", err)
}
t.Cleanup(func() {
cancel()
runner.tree.kill(runner.cmd)
runner.Close("test cleanup")
})
start := time.Now()
lingerAfterPrompt(ctx, runner, 200*time.Millisecond)
elapsed := time.Since(start)
if elapsed < 150*time.Millisecond {
t.Fatalf("linger returned after %s, want it to honor the ~200ms window", elapsed)
}
if elapsed > 5*time.Second {
t.Fatalf("linger returned after %s, want it bounded by the window", elapsed)
}
}
@@ -3,6 +3,7 @@ package acp
import (
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
@@ -23,6 +24,12 @@ type UpdateHandler func(notification acp.SessionNotification)
// Returns the selected option ID, or empty string with cancelled=true to cancel
type PermissionRequestHandler func(ctx context.Context, req *types.PermissionRequest) (*types.PermissionResponse, error)
// CursorTaskHandler is called when Cursor sends its non-standard `cursor/task`
// request with subagent metadata. The handler is fire-and-forget: it must be
// best-effort, return without surfacing errors to Cursor, and has no
// cancellation semantics, so it takes no context.
type CursorTaskHandler func(params json.RawMessage)
// Client implements acp.Client interface and handles all agent requests
type Client struct {
logger *zap.Logger
@@ -32,6 +39,7 @@ type Client struct {
mu sync.RWMutex
updateHandler UpdateHandler
permissionHandler PermissionRequestHandler
cursorTaskHandler CursorTaskHandler
}
// ClientOption configures a Client
@@ -65,6 +73,13 @@ func WithPermissionHandler(h PermissionRequestHandler) ClientOption {
}
}
// WithCursorTaskHandler sets the handler for Cursor's `cursor/task` request.
func WithCursorTaskHandler(h CursorTaskHandler) ClientOption {
return func(c *Client) {
c.cursorTaskHandler = h
}
}
// NewClient creates a new ACP client implementation
func NewClient(opts ...ClientOption) *Client {
c := &Client{
@@ -92,6 +107,13 @@ func (c *Client) SetPermissionHandler(h PermissionRequestHandler) {
c.permissionHandler = h
}
// SetCursorTaskHandler sets the Cursor `cursor/task` handler (thread-safe).
func (c *Client) SetCursorTaskHandler(h CursorTaskHandler) {
c.mu.Lock()
defer c.mu.Unlock()
c.cursorTaskHandler = h
}
// RequestPermission handles permission requests from the agent
// If a permission handler is set, it forwards the request to the handler.
// Otherwise, auto-approves by selecting the first "allow" option.
@@ -269,6 +291,28 @@ func (c *Client) SessionUpdate(ctx context.Context, n acp.SessionNotification) e
return nil
}
// HandleExtensionMethod accepts explicitly-supported inbound extension-style
// requests from the agent. Cursor currently sends subagent metadata over the
// non-standard vendor method `cursor/task`; unknown methods still decline with
// method-not-found. The ctx satisfies the SDK's ExtensionMethodHandler
// signature; the fire-and-forget cursor/task handler does not consume it.
func (c *Client) HandleExtensionMethod(_ context.Context, method string, params json.RawMessage) (any, error) {
if method != cursorTaskMethod {
return nil, acp.NewMethodNotFound(method)
}
c.mu.RLock()
handler := c.cursorTaskHandler
c.mu.RUnlock()
if handler != nil {
handler(params)
}
return struct{}{}, nil
}
const cursorTaskMethod = "cursor/task"
// resolvePath resolves a file path, making relative paths relative to the workspace root.
// It validates that the resolved path stays within the workspace root to prevent path traversal.
func (c *Client) resolvePath(reqPath string) (string, error) {
@@ -2,6 +2,8 @@ package acp
import (
"context"
"encoding/json"
"errors"
"path/filepath"
"reflect"
"testing"
@@ -217,3 +219,68 @@ func TestForwardPermissionRequestTitleDerivation(t *testing.T) {
})
}
}
func TestHandleExtensionMethod(t *testing.T) {
tests := []struct {
name string
method string
params json.RawMessage
wantErr bool
wantCalled bool
}{
{
name: "cursor task succeeds and forwards params",
method: cursorTaskMethod,
params: json.RawMessage(`{"toolCallId":"tool-1","prompt":"summarize"}`),
wantCalled: true,
},
{
name: "unknown method returns method not found",
method: "foo/bar",
params: json.RawMessage(`{"x":1}`),
wantErr: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
var called bool
var gotParams json.RawMessage
client := NewClient(WithCursorTaskHandler(func(params json.RawMessage) {
called = true
gotParams = append(json.RawMessage(nil), params...)
}))
resp, err := client.HandleExtensionMethod(context.Background(), tt.method, tt.params)
if tt.wantErr {
if err == nil {
t.Fatal("expected error, got nil")
}
var reqErr *acp.RequestError
if !errors.As(err, &reqErr) {
t.Fatalf("error type = %T, want *acp.RequestError", err)
}
if reqErr.Code != -32601 {
t.Fatalf("error code = %d, want -32601", reqErr.Code)
}
if called {
t.Fatal("handler was called for unknown method")
}
return
}
if err != nil {
t.Fatalf("HandleExtensionMethod returned error: %v", err)
}
if !reflect.DeepEqual(resp, struct{}{}) {
t.Fatalf("response = %#v, want empty success object", resp)
}
if called != tt.wantCalled {
t.Fatalf("handler called = %v, want %v", called, tt.wantCalled)
}
if !reflect.DeepEqual(gotParams, tt.params) {
t.Fatalf("params = %s, want %s", gotParams, tt.params)
}
})
}
}
@@ -0,0 +1,120 @@
package acp
import (
"bufio"
"encoding/json"
"io"
"reflect"
"testing"
"time"
acpsdk "github.com/coder/acp-go-sdk"
)
func TestClientSideConnection_InterceptsCursorTaskRequest(t *testing.T) {
clientToAgentReader, clientToAgentWriter := io.Pipe()
agentToClientReader, agentToClientWriter := io.Pipe()
t.Cleanup(func() {
_ = clientToAgentReader.Close()
_ = clientToAgentWriter.Close()
_ = agentToClientReader.Close()
_ = agentToClientWriter.Close()
})
paramsCh := make(chan json.RawMessage, 1)
_ = acpsdk.NewClientSideConnection(
NewClient(WithCursorTaskHandler(func(params json.RawMessage) {
paramsCh <- append(json.RawMessage(nil), params...)
})),
clientToAgentWriter,
agentToClientReader,
)
if err := writeJSONRPCLine(agentToClientWriter, map[string]any{
"jsonrpc": "2.0",
"id": 7,
"method": cursorTaskMethod,
"params": map[string]any{
"toolCallId": "tool-1",
"prompt": "summarize",
},
}); err != nil {
t.Fatalf("write cursor/task request: %v", err)
}
response := readJSONRPCLine(t, clientToAgentReader)
if !reflect.DeepEqual(response["result"], map[string]any{}) {
t.Fatalf("response result = %#v, want empty success object", response["result"])
}
if response["error"] != nil {
t.Fatalf("response error = %#v, want nil", response["error"])
}
select {
case got := <-paramsCh:
var gotParams map[string]any
if err := json.Unmarshal(got, &gotParams); err != nil {
t.Fatalf("unmarshal params %q: %v", string(got), err)
}
wantParams := map[string]any{"toolCallId": "tool-1", "prompt": "summarize"}
if !reflect.DeepEqual(gotParams, wantParams) {
t.Fatalf("params = %#v, want %#v", gotParams, wantParams)
}
case <-time.After(1 * time.Second):
t.Fatal("timed out waiting for cursor/task handler")
}
}
func TestClientSideConnection_UnknownVendorRequestReturnsMethodNotFound(t *testing.T) {
clientToAgentReader, clientToAgentWriter := io.Pipe()
agentToClientReader, agentToClientWriter := io.Pipe()
t.Cleanup(func() {
_ = clientToAgentReader.Close()
_ = clientToAgentWriter.Close()
_ = agentToClientReader.Close()
_ = agentToClientWriter.Close()
})
_ = acpsdk.NewClientSideConnection(NewClient(), clientToAgentWriter, agentToClientReader)
if err := writeJSONRPCLine(agentToClientWriter, map[string]any{
"jsonrpc": "2.0",
"id": 8,
"method": "foo/bar",
"params": map[string]any{"x": 1},
}); err != nil {
t.Fatalf("write vendor request: %v", err)
}
response := readJSONRPCLine(t, clientToAgentReader)
errorMap, ok := response["error"].(map[string]any)
if !ok {
t.Fatalf("response error = %#v, want JSON-RPC error object", response["error"])
}
if errorMap["code"] != float64(-32601) {
t.Fatalf("error code = %#v, want -32601", errorMap["code"])
}
}
func writeJSONRPCLine(w io.Writer, payload map[string]any) error {
encoded, err := json.Marshal(payload)
if err != nil {
return err
}
encoded = append(encoded, '\n')
_, err = w.Write(encoded)
return err
}
func readJSONRPCLine(t *testing.T, r io.Reader) map[string]any {
t.Helper()
line, err := bufio.NewReader(r).ReadBytes('\n')
if err != nil {
t.Fatalf("read response line: %v", err)
}
var decoded map[string]any
if err := json.Unmarshal(line, &decoded); err != nil {
t.Fatalf("unmarshal response %q: %v", string(line), err)
}
return decoded
}
@@ -177,6 +177,13 @@ type Adapter struct {
// Tool call tracking for result normalization
// Maps toolCallId -> NormalizedPayload so we can update with results
activeToolCalls map[string]*streams.NormalizedPayload
// cursorTaskMetaBySession stores Cursor's non-standard `cursor/task`
// metadata until the matching subagent tool_call appears, keyed by session
// then wire tool-call ID. An entry is drained either when its tool_call
// arrives (applyPendingCursorTaskMetaLocked) or when the session is cleared
// on turn end / reset (clearCursorTaskMetaLocked), so it never outlives the
// turn that produced it.
cursorTaskMetaBySession map[string]map[string]cursorTaskMeta
// toolCallParents preserves nested tool lineage while a handed-off
// predecessor continues streaming beside its human successor.
toolCallParents map[string]string
@@ -375,6 +382,7 @@ func NewAdapter(cfg *shared.Config, log *logger.Logger) *Adapter {
updatesCh: make(chan AgentEvent, 100),
notifQueue: make(chan notifWork, notifQueueCapacity),
activeToolCalls: make(map[string]*streams.NormalizedPayload),
cursorTaskMetaBySession: make(map[string]map[string]cursorTaskMeta),
toolCallParents: make(map[string]string),
handoffProtectedToolCalls: make(map[string]struct{}),
activeMonitors: make(map[string]map[string]string),
@@ -437,6 +445,7 @@ func (a *Adapter) Initialize(ctx context.Context) error {
acpclient.WithWorkspaceRoot(a.cfg.WorkDir),
acpclient.WithUpdateHandler(a.enqueueACPUpdate),
acpclient.WithPermissionHandler(a.handlePermissionRequest),
acpclient.WithCursorTaskHandler(a.handleCursorTask),
)
// Create ACP SDK connection. Raise the inbound notification queue cap
@@ -683,6 +692,7 @@ func (a *Adapter) Close() error {
a.updateSendWg.Wait()
a.mu.Lock()
a.clearCodexSubagentCorrelationsLocked("")
a.clearCursorTaskMetaLocked("")
a.clearPromptHandoffToolTrackingLocked()
clear(a.usageBySession)
a.mu.Unlock()
@@ -0,0 +1,89 @@
package acp
import (
"encoding/json"
"github.com/kandev/kandev/internal/agentctl/types/streams"
)
func (a *Adapter) handleCursorTask(params json.RawMessage) {
meta := parseCursorTaskParams(params)
if meta.ToolCallID == "" {
return
}
a.mu.Lock()
sessionID := a.sessionID
var emitted *streams.NormalizedPayload
if active := a.activeToolCalls[meta.ToolCallID]; active != nil && active.Kind() == streams.ToolKindSubagentTask {
applyCursorTaskMeta(active.SubagentTask(), meta)
emitted = cloneSubagentPayload(active)
} else if sessionID != "" {
a.storeCursorTaskMetaLocked(sessionID, meta)
}
a.mu.Unlock()
if emitted != nil && sessionID != "" {
a.sendUpdate(AgentEvent{
Type: streams.EventTypeToolUpdate,
SessionID: sessionID,
ToolCallID: meta.ToolCallID,
ToolStatus: toolStatusInProgress,
NormalizedPayload: emitted,
})
}
}
func (a *Adapter) applyPendingCursorTaskMetaLocked(sessionID, toolCallID string, payload *streams.NormalizedPayload) {
if payload == nil || payload.Kind() != streams.ToolKindSubagentTask {
return
}
sessionMeta := a.cursorTaskMetaBySession[sessionID]
if sessionMeta == nil {
return
}
meta, ok := sessionMeta[toolCallID]
if !ok {
return
}
applyCursorTaskMeta(payload.SubagentTask(), meta)
delete(sessionMeta, toolCallID)
if len(sessionMeta) == 0 {
delete(a.cursorTaskMetaBySession, sessionID)
}
}
func (a *Adapter) storeCursorTaskMetaLocked(sessionID string, meta cursorTaskMeta) {
if sessionID == "" || meta.ToolCallID == "" {
return
}
if a.cursorTaskMetaBySession == nil {
a.cursorTaskMetaBySession = make(map[string]map[string]cursorTaskMeta)
}
if a.cursorTaskMetaBySession[sessionID] == nil {
a.cursorTaskMetaBySession[sessionID] = make(map[string]cursorTaskMeta)
}
stored := a.cursorTaskMetaBySession[sessionID][meta.ToolCallID]
a.cursorTaskMetaBySession[sessionID][meta.ToolCallID] = mergeCursorTaskMeta(stored, meta)
}
// sweepCursorTaskMetaOnPromptEnd drops any pending cursor/task metadata for the
// session that never matched a subagent tool_call during the turn. The entries
// are keyed by wire tool-call ID, which Cursor can reuse across turns, so an
// unmatched entry left behind would attach to an unrelated subagent later.
func (a *Adapter) sweepCursorTaskMetaOnPromptEnd(sessionID string) {
if sessionID == "" {
return
}
a.mu.Lock()
a.clearCursorTaskMetaLocked(sessionID)
a.mu.Unlock()
}
func (a *Adapter) clearCursorTaskMetaLocked(sessionID string) {
if sessionID == "" {
clear(a.cursorTaskMetaBySession)
return
}
delete(a.cursorTaskMetaBySession, sessionID)
}
@@ -239,6 +239,10 @@ func (a *Adapter) sendPrompt(
// state when the parent prompt completes naturally.
a.sweepMonitorsOnPromptEnd(sessionID)
// Drop any Cursor `cursor/task` metadata for this session that never matched
// a subagent tool_call this turn.
a.sweepCursorTaskMetaOnPromptEnd(sessionID)
if a.agentID == codexAgentID && turn.codexCapacityFailure() {
const safeMessage = codexModelCapacityErrorMessage
a.logger.Info("codex prompt ended with model-capacity evidence",
@@ -40,6 +40,7 @@ func (a *Adapter) NewSession(ctx context.Context, mcpServers []types.McpServer)
a.mu.Lock()
a.pendingWakeups = make(map[string]*pendingWakeup)
a.clearCodexSubagentCorrelationsLocked("")
a.clearCursorTaskMetaLocked("")
a.clearPromptHandoffToolTrackingLocked()
clear(a.usageBySession)
a.wakeup.cancel()
@@ -400,6 +401,7 @@ func (a *Adapter) LoadSession(ctx context.Context, sessionID string, mcpServers
a.mu.Lock()
a.pendingWakeups = make(map[string]*pendingWakeup)
a.clearCodexSubagentCorrelationsLocked("")
a.clearCursorTaskMetaLocked("")
a.clearPromptHandoffToolTrackingLocked()
a.wakeup.cancel()
a.mu.Unlock()
@@ -200,6 +200,7 @@ func (a *Adapter) trackToolCallPayload(
a.mu.Lock()
defer a.mu.Unlock()
if signal == codexSubagentSignalNone {
a.applyPendingCursorTaskMetaLocked(sessionID, toolCallID, payload)
a.activeToolCalls[toolCallID] = payload
return payload, eventType, signal, toolCallID, "", false
}
@@ -0,0 +1,69 @@
package acp
import (
"encoding/json"
"github.com/kandev/kandev/internal/agentctl/types/streams"
)
type cursorTaskMeta struct {
ToolCallID string
AgentID string
Description string
Model string
Prompt string
}
func parseCursorTaskParams(params json.RawMessage) cursorTaskMeta {
if len(params) == 0 {
return cursorTaskMeta{}
}
var raw map[string]any
if err := json.Unmarshal(params, &raw); err != nil {
return cursorTaskMeta{}
}
return cursorTaskMeta{
ToolCallID: stringFromAnyMap(raw, "toolCallId"),
AgentID: stringFromAnyMap(raw, "agentId"),
Description: stringFromAnyMap(raw, "description"),
Model: stringFromAnyMap(raw, "model"),
Prompt: stringFromAnyMap(raw, "prompt"),
}
}
func mergeCursorTaskMeta(base, update cursorTaskMeta) cursorTaskMeta {
if base.ToolCallID == "" {
base.ToolCallID = update.ToolCallID
}
if base.AgentID == "" {
base.AgentID = update.AgentID
}
if base.Description == "" {
base.Description = update.Description
}
if base.Model == "" {
base.Model = update.Model
}
if base.Prompt == "" {
base.Prompt = update.Prompt
}
return base
}
func applyCursorTaskMeta(payload *streams.SubagentTaskPayload, meta cursorTaskMeta) {
if payload == nil {
return
}
fillIfEmpty(&payload.Description, meta.Description)
fillIfEmpty(&payload.Prompt, meta.Prompt)
fillIfEmpty(&payload.Model, meta.Model)
fillIfEmpty(&payload.AgentID, meta.AgentID)
}
func stringFromAnyMap(raw map[string]any, key string) string {
if raw == nil {
return ""
}
value, _ := raw[key].(string)
return value
}
@@ -0,0 +1,151 @@
package acp
import (
"encoding/json"
"testing"
acpsdk "github.com/coder/acp-go-sdk"
"github.com/kandev/kandev/internal/agentctl/types/streams"
)
func TestParseCursorTaskParams(t *testing.T) {
tests := []struct {
name string
params string
want cursorTaskMeta
}{
{
name: "full payload ignores object subagentType",
params: `{"agentId":"agent-1","description":"Summarize JS","model":"composer-2.5-fast",` +
`"prompt":"Summarize src JS files","subagentType":{"custom":{"unspecified":{}}},"toolCallId":"tool-1"}`,
want: cursorTaskMeta{
ToolCallID: "tool-1",
AgentID: "agent-1",
Description: "Summarize JS",
Model: "composer-2.5-fast",
Prompt: "Summarize src JS files",
},
},
{
name: "missing fields stay empty",
params: `{"toolCallId":"tool-2","prompt":"Only prompt"}`,
want: cursorTaskMeta{ToolCallID: "tool-2", Prompt: "Only prompt"},
},
{
name: "invalid json tolerated",
params: `{`,
want: cursorTaskMeta{},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := parseCursorTaskParams(json.RawMessage(tt.params)); got != tt.want {
t.Fatalf("parseCursorTaskParams() = %+v, want %+v", got, tt.want)
}
})
}
}
func TestCursorTaskRequestBeforeToolCallMergesOnCreate(t *testing.T) {
a := newTestAdapter()
a.sessionID = "session-1"
a.handleCursorTask(json.RawMessage(`{"toolCallId":"tool-1","agentId":"agent-1","description":"Summarize JS","model":"composer-2.5-fast","prompt":"Summarize src JS files"}`))
event := a.convertToolCallUpdate("session-1", &acpsdk.SessionUpdateToolCall{
ToolCallId: "tool-1",
Kind: "other",
Title: "Task: Subagent task",
Status: toolStatusInProgress,
RawInput: map[string]any{"_toolName": "task"},
})
if event == nil || event.Type != streams.EventTypeToolCall {
t.Fatalf("event = %+v, want initial tool_call", event)
}
sa := event.NormalizedPayload.SubagentTask()
if sa.Description != "Summarize JS" || sa.Prompt != "Summarize src JS files" || sa.Model != "composer-2.5-fast" || sa.AgentID != "agent-1" {
t.Fatalf("subagent payload = %+v", sa)
}
if pending := len(a.cursorTaskMetaBySession["session-1"]); pending != 0 {
t.Fatalf("pending cursor/task entries = %d, want 0 after match", pending)
}
}
func TestCursorTaskRequestAfterToolCallEmitsUpdate(t *testing.T) {
a := newTestAdapter()
a.sessionID = "session-1"
start := a.convertToolCallUpdate("session-1", &acpsdk.SessionUpdateToolCall{
ToolCallId: "tool-1",
Kind: "other",
Title: "Task: Subagent task",
Status: toolStatusInProgress,
RawInput: map[string]any{"_toolName": "task"},
})
if start == nil || start.Type != streams.EventTypeToolCall {
t.Fatalf("start event = %+v", start)
}
a.handleCursorTask(json.RawMessage(`{"toolCallId":"tool-1","description":"Summarize JS","model":"composer-2.5-fast","prompt":"Summarize src JS files"}`))
events := drainEvents(a)
if len(events) != 1 {
t.Fatalf("drained events = %d, want 1 metadata update", len(events))
}
update := events[0]
if update.Type != streams.EventTypeToolUpdate || update.ToolCallID != "tool-1" || update.ToolStatus != toolStatusInProgress {
t.Fatalf("update event = %+v", update)
}
sa := update.NormalizedPayload.SubagentTask()
if sa.Description != "Summarize JS" || sa.Prompt != "Summarize src JS files" || sa.Model != "composer-2.5-fast" {
t.Fatalf("updated payload = %+v", sa)
}
}
func TestCursorTaskUnmatchedMetaClearedAtPromptEnd(t *testing.T) {
a := newTestAdapter()
a.sessionID = "session-1"
// An unmatched cursor/task arrives (no subagent tool_call this turn).
a.handleCursorTask(json.RawMessage(`{"toolCallId":"tool-1","description":"Stale","prompt":"stale prompt"}`))
if pending := len(a.cursorTaskMetaBySession["session-1"]); pending != 1 {
t.Fatalf("pending cursor/task entries = %d, want 1 before prompt end", pending)
}
a.sweepCursorTaskMetaOnPromptEnd("session-1")
if pending := len(a.cursorTaskMetaBySession["session-1"]); pending != 0 {
t.Fatalf("pending cursor/task entries = %d, want 0 after prompt end", pending)
}
// A later turn reuses tool-1 for an unrelated subagent. Without the
// prompt-end sweep the stale "Stale" metadata would attach here.
event := a.convertToolCallUpdate("session-1", &acpsdk.SessionUpdateToolCall{
ToolCallId: "tool-1",
Kind: "other",
Title: "Task: Subagent task",
Status: toolStatusInProgress,
RawInput: map[string]any{"_toolName": "task"},
})
if event == nil || event.Type != streams.EventTypeToolCall {
t.Fatalf("event = %+v, want initial tool_call", event)
}
if sa := event.NormalizedPayload.SubagentTask(); sa.Description == "Stale" || sa.Prompt == "stale prompt" {
t.Fatalf("stale cursor/task metadata leaked into later turn: %+v", sa)
}
}
func TestCursorTaskCleanupDropsUnmatchedSessionState(t *testing.T) {
a := newTestAdapter()
a.mu.Lock()
a.storeCursorTaskMetaLocked("session-1", cursorTaskMeta{ToolCallID: "tool-1", Prompt: "queued"})
a.storeCursorTaskMetaLocked("session-2", cursorTaskMeta{ToolCallID: "tool-2", Prompt: "other"})
a.clearCursorTaskMetaLocked("session-1")
_, existsSession1 := a.cursorTaskMetaBySession["session-1"]
remaining := a.cursorTaskMetaBySession["session-2"]["tool-2"]
a.mu.Unlock()
if existsSession1 {
t.Fatal("session-1 cursor/task cache survived targeted cleanup")
}
if remaining.ToolCallID != "tool-2" {
t.Fatalf("session-2 entry = %+v, want untouched", remaining)
}
}
@@ -343,15 +343,20 @@ func openCodeSubagentMetadata(out map[string]any, res *SubagentTaskResult) bool
return found
}
// cursorSubagentResult reads Cursor's flat `rawOutput.durationMs` into res.
// Returns false when no Cursor-shaped field is present so it doesn't claim
// unrelated rawOutput maps.
// cursorSubagentResult reads Cursor's flat `rawOutput.durationMs` and
// `rawOutput.isBackground` into res. Returns false only when neither field is
// present so it doesn't claim unrelated rawOutput maps; a result carrying only
// `isBackground` still marks the subagent async.
func cursorSubagentResult(out map[string]any, res *SubagentTaskResult) bool {
dur, present := out["durationMs"]
if !present {
dur, durPresent := out["durationMs"]
background, backgroundPresent := out["isBackground"].(bool)
if !durPresent && !backgroundPresent {
return false
}
res.DurationMs = asInt64(dur)
if durPresent {
res.DurationMs = asInt64(dur)
}
res.IsAsync = background
return true
}
@@ -180,6 +180,37 @@ func TestExtractSubagentResult_Cursor(t *testing.T) {
if res.DurationMs != 4200 {
t.Errorf("DurationMs = %d", res.DurationMs)
}
if res.IsAsync {
t.Error("IsAsync = true, want false when isBackground=false")
}
}
func TestExtractSubagentResult_CursorBackground(t *testing.T) {
rawOutput := map[string]any{"durationMs": float64(4200), "isBackground": true}
res, ok := extractSubagentResult(nil, rawOutput)
if !ok {
t.Fatal("expected Cursor result to be extracted")
}
if !res.IsAsync {
t.Error("IsAsync = false, want true when isBackground=true")
}
}
// TestExtractSubagentResult_CursorBackgroundNoDuration covers a Cursor result
// carrying only isBackground: the async flag must still be recognized when
// durationMs is absent.
func TestExtractSubagentResult_CursorBackgroundNoDuration(t *testing.T) {
rawOutput := map[string]any{"isBackground": true}
res, ok := extractSubagentResult(nil, rawOutput)
if !ok {
t.Fatal("expected Cursor result to be extracted from isBackground alone")
}
if res.DurationMs != 0 {
t.Errorf("DurationMs = %d, want 0 when durationMs absent", res.DurationMs)
}
if !res.IsAsync {
t.Error("IsAsync = false, want true when isBackground=true without durationMs")
}
}
// TestExtractSubagentResult_ClaudeAsyncLaunched covers the claude-acp
@@ -1484,6 +1515,18 @@ func TestEnrichSubagentResult_Cursor(t *testing.T) {
if payload.SubagentTask().DurationMs != 4200 {
t.Errorf("DurationMs = %d", payload.SubagentTask().DurationMs)
}
if payload.SubagentTask().IsAsync {
t.Error("IsAsync = true, want false when isBackground=false")
}
}
func TestEnrichSubagentResult_CursorBackground(t *testing.T) {
n := NewNormalizer("")
payload := streams.NewSubagentTask("", "", "")
n.EnrichSubagentResult(payload, nil, map[string]any{"durationMs": float64(4200), "isBackground": true})
if !payload.SubagentTask().IsAsync {
t.Error("IsAsync = false, want true when isBackground=true")
}
}
// --- Auggie subagent detection ---
@@ -0,0 +1,78 @@
# ADR-2026-08-20-acp-client-non-underscore-extension-methods: Route Non-Underscore Inbound Client Methods to the Extension Handler
**Status:** accepted
**Date:** 2026-08-20
**Area:** backend, protocol
## Context
ACP reserves the `_`-prefix namespace for extension methods, and the
`kdlbs/acp-go-sdk` fork only routes `_`-prefixed inbound methods to a peer's
`ExtensionMethodHandler`; every other unrecognized method falls through the
generated `handle` switch and returns `-32601` method-not-found. Cursor breaks
that assumption: it delivers rich subagent metadata over an agent-to-client
**request** named `cursor/task` (no `_` prefix), so Kandev, acting as the ACP
client, rejects it today and drops the subagent's prompt, model, description, and
agent id. Other current and future agent CLIs are likely to introduce their own
vendor-namespaced (`vendor/method`) inbound requests for the same reason, and the
adapter needs one consistent seam to accept or decline them rather than a
per-method fork patch each time.
## Decision
Widen the SDK fork's client-side dispatch and let Kandev's ACP `Client` own the
accept/decline policy for unrecognized inbound methods.
- In `github.com/kdlbs/acp-go-sdk` `extensions.go`,
`ClientSideConnection.handleWithExtensions` routes **any** method the generated
`ClientSideConnection.handle` switch does not recognize to the client's
`ExtensionMethodHandler` when the `Client` implements one, instead of only
`_`-prefixed names. The `_`-prefix contract for the *outbound*
`CallExtension` / `NotifyExtension` helpers (`validateExtensionMethodName`) is
unchanged: Kandev only relaxes what it will *accept*, not what it will *send*.
The `AgentSideConnection` path is unchanged. A new pseudo-version is published
and the `replace` in `apps/backend/go.mod` is bumped to it.
- Kandev's `Client`
(`apps/backend/internal/agentctl/server/acp/client.go`) implements
`HandleExtensionMethod(ctx, method, params)`. It returns an empty success
result only for methods it explicitly recognizes (`cursor/task` first) and
returns `acp.NewMethodNotFound(method)` for everything else, so an unknown
method still declines correctly rather than being silently accepted.
- Parsing and correlation of a recognized method's params stay out of the SDK and
out of `client.go`; they live in the agent-specific dialect
(`internal/agentctl/server/adapter/transport/acp/dialect_cursor.go`), consistent
with [ADR 0044](0044-acp-agent-compatibility-dialects.md).
## Consequences
- Kandev can accept vendor-namespaced inbound requests from any ACP agent CLI
through one client-owned allowlist, without a fork patch per method.
- The accept/decline decision is centralized and explicit: an unrecognized method
still returns method-not-found, so the change does not blanket-accept unknown
traffic.
- The fork now diverges further from upstream `coder/acp-go-sdk` on inbound
client dispatch, so the divergence must be re-checked on every SDK rebase and
is recorded here as the reason.
- The relaxation is asymmetric (inbound accept only); outbound sends still refuse
non-`_` names, preserving spec-compliant behavior toward peers.
## Alternatives Considered
### Wrap the transport instead of touching the fork (plan Option B)
Interpose a reader between agent stdout and `NewClientSideConnection` that peeks
frames, replies to `cursor/task` out-of-band on the shared writer, and passes
everything else through. Rejected: it duplicates the SDK's JSON-RPC framing and
response correctness, adds a second code path that must stay in lockstep with the
SDK, and is higher risk than a small, well-scoped fork change we already own.
### Ask Cursor to use a `_`-prefixed method
Not actionable: `cursor/task` is Cursor's wire contract and Kandev does not
control it. The client must adapt to observed agent behavior.
### Handle `cursor/task` with a hardcoded branch in the SDK fork
Rejected: it embeds one vendor's method name in a protocol library and forces a
fork bump for the next agent that does the same. Routing unrecognized methods to
the client keeps vendor knowledge in Kandev's dialect layer.
+1
View File
@@ -180,3 +180,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-08-17-release-pr-ruleset-bypass | [Give Stable Release PRs an Administrator Token Bypass](2026-08-17-release-pr-ruleset-bypass.md) | accepted | infra, workflow, security | 2026-08-17 |
| 2026-08-18-never-started-agent-stall-terminal | [Treat Never-Started Agent Stalls as Terminal](2026-08-18-never-started-agent-stall-terminal.md) | accepted | backend, frontend, protocol | 2026-08-18 |
| 2026-08-14-kandev-native-agent-rich-output | [Keep Agent Rich Output Host Native](2026-08-14-kandev-native-agent-rich-output.md) | accepted | backend, frontend, protocol, security | 2026-08-14 |
| 2026-08-20-acp-client-non-underscore-extension-methods | [Route Non-Underscore Inbound Client Methods to the Extension Handler](2026-08-20-acp-client-non-underscore-extension-methods.md) | accepted | backend, protocol | 2026-08-20 |
+130
View File
@@ -0,0 +1,130 @@
---
spec: docs/specs/agents/cursor-subagent-metadata.md
created: 2026-08-20
status: in_progress
---
# Implementation Plan: Cursor Subagent Metadata
## Overview
Cursor delivers its subagent's prompt, model, description, and agent id over a
non-standard agent-to-client request, `cursor/task`, which Kandev currently
rejects with `-32601`. This plan (1) opens a seam so the ACP client can accept a
non-`_`-prefixed extension method, (2) parses `cursor/task` and correlates it to
the standard subagent `tool_call` by `toolCallId`, merging its fields onto the
existing `SubagentTaskPayload`, and (3) maps Cursor's `isBackground` completion
flag onto the payload's existing `IsAsync` so the current "background" chip
renders. The frontend already renders model, prompt (fallback), and the
background chip, so no frontend change is required for the golden path.
---
## Resolved decision and implemented seam
The upstream ACP client routes inbound client extension handling only for
method names starting with `_`, so `cursor/task` would fall through to the
generated `ClientSideConnection.handle` switch and return `-32601`.
The implementation that landed widens that seam in the pinned ACP fork instead
of proxying it in-repo: the fork routes any unrecognized inbound client
*request* to the client's `ExtensionMethodHandler`, and Kandev keeps the
client-owned allow/deny policy in
`apps/backend/internal/agentctl/server/acp/client.go`. The adapter registers a
`CursorTaskHandler` via `acpclient.WithCursorTaskHandler` and passes the client
straight to `acp.NewClientSideConnection` (`adapter.go`), so there is no
repo-local connection proxy. The relaxation is inbound-accept only; the outbound
`CallExtension`/`NotifyExtension` `_`-prefix contract is unchanged.
---
## Backend
### Area 1 — client extension seam (Task 01)
Kandev implements `HandleExtensionMethod(ctx, method, params)` on
`acpclient.Client` (`apps/backend/internal/agentctl/server/acp/client.go`),
returning an empty result for `cursor/task` and `NewMethodNotFound` otherwise.
The pinned ACP fork routes any unrecognized inbound client request to that
handler, so no repo-local connection helper is needed. A `CursorTaskHandler`
option (mirroring `WithUpdateHandler`) hands the raw params to the adapter.
### Area 2 — parse + correlate cursor/task (Task 02)
New `dialect_cursor.go` in `apps/backend/internal/agentctl/server/adapter/transport/acp/`: parse the `cursor/task` params (`agentId`, `description`, `model`, `prompt`, `toolCallId`; `subagentType` is an object and is ignored) defensively over untyped maps. The adapter keeps a per-session `map[toolCallId]cursorTaskMeta` (bounded, cleared on session teardown). On either the `cursor/task` request or the subagent `tool_call` (whichever is second), merge onto the `SubagentTaskPayload` via the existing fill-if-present rule (extend `applySubagentResult` or a sibling `applyCursorTaskMeta`). Wire the adapter's `CursorTaskHandler` in `adapter.go` next to `enqueueACPUpdate`.
### Area 3 — background flag (Task 02, same change)
Extend `cursorSubagentResult` (`subagent.go:349`) to read `rawOutput.isBackground` and set `res.IsAsync = true` when it is `true`. This reuses `SubagentTaskPayload.IsAsync` and the frontend background chip; no new payload field.
---
## Frontend
> No change required for the golden path. `model` already renders as a chip
> (`subagent-meta.ts:85`), `is_async` already renders the "background" chip
> (`subagent-meta.ts:56`), and `prompt` already renders as the card body
> fallback when there is no `result_text` and no children
> (`tool-subagent-message.tsx`). The `SubagentTaskPayload` TS type
> (`apps/web/components/task/chat/types.ts`) already carries every field this
> feature populates. Confirm in Task 04 (E2E/manual) and only add rendering if a
> gap is observed.
---
## Tests
- **Extension dispatch (Task 01):** `cursor/task` returns a success result, not
`-32601`. File: `apps/backend/internal/agentctl/server/acp/client_test.go`
(table-driven: `cursor/task` → ok; unknown `foo/bar` → method-not-found).
- **cursor/task parse (Task 02):** parses `agentId`/`description`/`model`/
`prompt`; ignores object `subagentType`; tolerates missing fields. File:
`apps/backend/internal/agentctl/server/adapter/transport/acp/dialect_cursor_test.go`.
- **Correlation both orders (Task 02):** request-before-tool_call and
tool_call-before-request both merge onto one payload; unmatched entry is
dropped at teardown. File: `..._cursor_test.go` /
`subagent_test.go`.
- **isBackground (Task 02):** completion `rawOutput.isBackground:true` sets
`IsAsync`; `false`/absent leaves it unset. File: `subagent_test.go`.
- **No-regression (Task 02/03):** existing subagent tests for Claude/OpenCode/
Auggie still pass unchanged.
---
## E2E Tests
> No new Playwright spec. `cursor/task` requires a live Cursor login and cannot
> run in CI. Task 04 is a manual `acpdbg`/live-session verification against a
> real Cursor subagent, recording the rendered card (prompt, model, background).
---
## Verification Results
- `cd apps/backend && go test ./internal/agentctl/server/acp/... ./internal/agentctl/server/adapter/transport/acp/... ./internal/agentctl/server/utility/...` passed after adding a real wire-path test for inbound `cursor/task` handling.
- `cd apps && pnpm install --frozen-lockfile` passed in the worktree so focused frontend tests could run.
- `cd apps && pnpm --filter @kandev/web exec vitest run components/task/chat/messages/subagent-meta.test.ts components/task/chat/messages/tool-subagent-message.test.tsx` passed 41 tests across 2 files.
- No frontend code change was required: the existing subagent metadata chip/body renderers already display `model`, `is_async`, and `prompt` once the backend populates them.
- Manual live verification against a real Cursor-authenticated session is still pending (Task 04).
---
## Implementation Waves And Parallel Candidates
```text
Wave 1:
- [x] [task-01-sdk-extension-seam](task-01-sdk-extension-seam.md)
Wave 2:
- [x] [task-02-parse-correlate-cursor-task](task-02-parse-correlate-cursor-task.md)
Wave 3 (verification):
- [x] [task-03-frontend-confirm](task-03-frontend-confirm.md) (parallel-safe with Task 04)
- [ ] [task-04-manual-live-verify](task-04-manual-live-verify.md)
```
Sequential by default. Task 02 depends on Task 01's `CursorTaskHandler` seam.
---
## Open Questions
- None. The one architectural question (Option A vs Option B) is resolved by
[ADR-2026-08-20-acp-client-non-underscore-extension-methods](../../decisions/2026-08-20-acp-client-non-underscore-extension-methods.md)
(Option A). Task 01 is unblocked.
@@ -0,0 +1,70 @@
---
id: "01-sdk-extension-seam"
title: "SDK extension seam for cursor/task"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/agents/cursor-subagent-metadata.md"
---
# Task 01: SDK extension seam for cursor/task
Open a seam so the ACP client can accept the non-`_`-prefixed `cursor/task`
request instead of returning `-32601`, and expose the parsed request to the
adapter.
Upstream ACP rejects non-`_` inbound methods on the client side. The
implementation that landed opens the seam in the pinned ACP fork instead: the
fork routes any unrecognized inbound client request to the client's
`ExtensionMethodHandler`, and Kandev passes its client to
`acp.NewClientSideConnection` with `WithCursorTaskHandler` (no repo-local
connection helper is involved).
## Acceptance
- The pinned ACP fork routes inbound vendor request methods (including
`cursor/task`) to `Client.HandleExtensionMethod`; the outbound `_`-prefix
contract is unchanged (inbound-accept only).
- `apps/backend/internal/agentctl/server/acp/client.go` `Client` implements the
extension handler: `cursor/task` returns an empty success result; any other
unrecognized method returns `acp.NewMethodNotFound(method)`.
- A `WithCursorTaskHandler` client option (mirroring `WithUpdateHandler`) hands
the raw params to a callback the adapter can set.
## Verification
`cd apps/backend && go test ./internal/agentctl/server/acp/...`
## Files likely touched
- `apps/backend/internal/agentctl/server/acp/client.go` — add
`HandleExtensionMethod`, `WithCursorTaskHandler`, and the handler field.
- `apps/backend/internal/agentctl/server/acp/client_test.go` — dispatch tests.
- The pinned ACP fork (`kdlbs/acp-go-sdk` PR #3) — widen the client extension
seam; consumed via the `go.mod` `replace`.
- `apps/backend/internal/agentctl/server/acp/connection_test.go` (new) — live
wire-path test for `cursor/task` and unknown vendor requests.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go` and
`apps/backend/internal/agentctl/server/utility/acp_executor.go` — use the new
helper instead of constructing the ACP SDK connection directly.
## Dependencies
None. ADR-2026-08-20 (Option A) is accepted; this task is unblocked.
## Parallelism
sequential.
## Inputs
- Spec: "API surface", "Failure modes".
- Plan: "Resolved decision and implemented seam", "Area 1".
- Code refs: `client.go` option pattern (`WithUpdateHandler`), ACP
`ClientSideConnection` wire framing, and the adapter/utility connection
call-sites.
## Output contract
Summary, files changed, tests run, blockers, risks; update this task's status
and the `plan.md` Wave 1 checkbox.
## Results
- Added `CursorTaskHandler`, `WithCursorTaskHandler`, `SetCursorTaskHandler`,
and `HandleExtensionMethod` to `apps/backend/internal/agentctl/server/acp/client.go` so `cursor/task` returns a success result and unknown vendor methods still return `-32601`.
- Widened the client extension seam in the pinned ACP fork (`kdlbs/acp-go-sdk` PR #3) so any unrecognized inbound client request routes to `HandleExtensionMethod`; consumed via the `go.mod` `replace`. No repo-local connection proxy was added; the adapter passes its client to `acp.NewClientSideConnection` with `WithCursorTaskHandler`.
- `cd apps/backend && go test ./internal/agentctl/server/acp/...` passed.
@@ -0,0 +1,77 @@
---
id: "02-parse-correlate-cursor-task"
title: "Parse and correlate cursor/task onto the subagent payload"
status: done
wave: 2
depends_on: ["01-sdk-extension-seam"]
plan: "plan.md"
spec: "../../specs/agents/cursor-subagent-metadata.md"
---
# Task 02: Parse and correlate cursor/task onto the subagent payload
Parse `cursor/task`, correlate it to the standard subagent `tool_call` by
`toolCallId`, and merge its metadata (`description`, `prompt`, `model`,
`agentId`) onto the existing `SubagentTaskPayload`. Also map the completion
`rawOutput.isBackground` onto `IsAsync`.
## Acceptance
- A subagent `tool_call` plus a matching `cursor/task` (in either arrival order)
produces one `SubagentTaskPayload` carrying Cursor's description, prompt,
model, and agent id.
- An object-shaped `subagentType` is ignored (never coerced to the string
`SubagentType`); missing fields leave their targets zero-valued.
- An already-set field is not blanked by a later empty Cursor value.
- A `cursor/task` with no matching `tool_call` is dropped at session teardown.
- Completion `rawOutput.isBackground:true` sets `IsAsync`; `false`/absent does
not.
## Verification
`cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp/...`
## Files likely touched
- `apps/backend/internal/agentctl/server/adapter/transport/acp/dialect_cursor.go` (new)
— parse params, `applyCursorTaskMeta`.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_cursor.go` (new)
— store pending Cursor metadata, merge it in either arrival order, and clear
it on teardown.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go` — set
the `WithCursorTaskHandler` callback; per-session `map[toolCallId]cursorTaskMeta`;
clear on teardown.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_tools.go` —
merge pending metadata onto the first matching `tool_call` payload.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_session.go`
— clear unmatched pending metadata on session reset/teardown.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/subagent.go` —
extend `cursorSubagentResult` to read `isBackground` → `IsAsync`.
- `apps/backend/internal/agentctl/server/adapter/transport/acp/dialect_cursor_test.go` (new)
- `apps/backend/internal/agentctl/server/adapter/transport/acp/subagent_test.go` — isBackground + correlation cases.
## Dependencies
Task 01 (needs the `CursorTaskHandler` seam).
## Parallelism
sequential.
## Inputs
- Spec: "API surface" (exact param shape), "Failure modes", "Scenarios".
- Plan: "Area 2", "Area 3".
- Code refs: `subagent.go:224,349,371` (`extractSubagentResult`,
`cursorSubagentResult`, `applySubagentResult`); `tool_payload.go`
`SubagentTaskPayload`; `adapter.go:449` connection wiring.
- Wire fixture: `acp-debug/cursor-acp-linger-20260820-145213.jsonl`.
## Output contract
Summary, files changed, tests run + counts, blockers, risks; update this task's
status and `plan.md` Wave 2 checkbox and Verification Results.
## Results
- Added defensive Cursor param parsing for `toolCallId`, `agentId`,
`description`, `model`, and `prompt`, ignoring object-shaped
`subagentType`.
- Added per-session correlation state so `cursor/task` and the subagent
`tool_call` merge into one `SubagentTaskPayload` in either arrival order, and
unmatched pending state is dropped on teardown.
- Extended Cursor result enrichment so `rawOutput.isBackground:true` sets
`IsAsync`, which reuses the existing background-chip UI.
- `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp/...` passed.
@@ -0,0 +1,61 @@
---
id: "03-frontend-confirm"
title: "Confirm frontend renders the Cursor subagent metadata"
status: done
wave: 3
depends_on: ["02-parse-correlate-cursor-task"]
plan: "plan.md"
spec: "../../specs/agents/cursor-subagent-metadata.md"
---
# Task 03: Confirm frontend renders the Cursor subagent metadata
Verify no frontend change is needed, or make the minimal one if a gap is found.
The `SubagentTaskPayload` TS type and the card/chip components already carry and
render `model`, `is_async` (background chip), and `prompt` (body fallback).
## Acceptance
- With a populated Cursor `SubagentTaskPayload`, the subagent card shows the
model chip, the background chip (when `is_async`), and the prompt in the
expandable body (when no `result_text` and no children).
- If any expected field is present in the payload but not rendered, a minimal
targeted change is made and covered by a unit test; otherwise this task is a
confirmation with no code change.
## Verification
`cd apps && pnpm install --frozen-lockfile && pnpm --filter @kandev/web test -- components/task/chat/messages/subagent-meta.test.ts`
(and `cd apps/web && pnpm run typecheck` if any `.ts`/`.tsx` file changed)
## Files likely touched
- (confirm only, likely none) `apps/web/components/task/chat/types.ts`,
`apps/web/components/task/chat/messages/subagent-meta.ts`,
`apps/web/components/task/chat/messages/tool-subagent-message.tsx`.
- `apps/web/components/task/chat/messages/subagent-meta.test.ts` — only if a
change is made.
## Dependencies
Task 02 (the payload must actually be populated to verify).
## Parallelism
parallel-safe with Task 04 (disjoint: frontend unit vs manual live run).
## Inputs
- Spec: "What", "Scenarios".
- Plan: "Frontend".
- Code refs: `subagent-meta.ts:56,85`; `tool-subagent-message.tsx`;
`types.ts` `SubagentTaskPayload`.
## Output contract
Summary (change vs confirm-only), files changed, tests run, blockers, risks;
update this task's status and `plan.md` Wave 3 checkbox.
## Results
- Confirmed `apps/web/components/task/chat/types.ts` already includes the
populated fields (`prompt`, `model`, `agent_id`, `is_async`).
- Confirmed `apps/web/components/task/chat/messages/subagent-meta.ts` already
renders the model chip and background chip, and
`apps/web/components/task/chat/messages/tool-subagent-message.tsx` already
renders the prompt fallback body.
- No frontend code change was required.
- `cd apps && pnpm install --frozen-lockfile` passed.
- `cd apps && pnpm --filter @kandev/web exec vitest run components/task/chat/messages/subagent-meta.test.ts components/task/chat/messages/tool-subagent-message.test.tsx` passed 41 tests across 2 files.
@@ -0,0 +1,52 @@
---
id: "04-manual-live-verify"
title: "Manual live verification against a real Cursor subagent"
status: pending
wave: 3
depends_on: ["02-parse-correlate-cursor-task"]
plan: "plan.md"
spec: "../../specs/agents/cursor-subagent-metadata.md"
---
# Task 04: Manual live verification against a real Cursor subagent
`cursor/task` needs a live Cursor login and cannot run in CI, so this is a
manual end-to-end check with `acpdbg` and/or a real Kandev session.
## Acceptance
- `acpdbg` no longer records a `<<< SENT-reply ... err=method not found:
cursor/task` frame; instead a success reply is sent for `cursor/task`.
- In a live Kandev session using Cursor, launching a subagent renders a card
showing the subagent's description, prompt, and model; a background subagent
shows the background affordance.
- No regression for a Cursor non-subagent tool call, and no error surfaced to
the user.
## Verification
Run the recorded reproduction and inspect frames:
`apps/backend/bin/acpdbg prompt --workdir /tmp/kandev-cursor-subagent --model "composer-2.5[fast=true]" --timeout 60s --file acp-debug/cursor-verify-$(date -u +%Y%m%d-%H%M%S).jsonl --prompt "Launch a subagent to summarize the JS files under src/." cursor-acp`
then confirm the `cursor/task` reply carries a result (not error) and the
metadata was captured. Also verify visually in a live Cursor session.
## Files likely touched
- None (verification only). Records artifacts under `acp-debug/`.
## Dependencies
Task 02 (behavior must be implemented). Task 01 (seam) transitively.
## Parallelism
parallel-safe with Task 03.
## Inputs
- Spec: "Scenarios", "Notes".
- Plan: "E2E Tests".
- Skill: `.claude/skills/acp-debug/SKILL.md`.
- Pinned: use `composer-2.5[fast=true]`; workspace `/tmp/kandev-cursor-subagent`.
## Output contract
Summary, artifact paths (JSONL + any screenshots), pass/fail per acceptance
bullet, blockers, risks; update this task's status and `plan.md` Wave 3 checkbox
and Verification Results. Note the temporary capture files created.
## Results
Pending. Not run in this workspace because it requires a real Cursor-authenticated live session and manual visual confirmation.
@@ -0,0 +1,148 @@
---
status: draft
created: 2026-08-20
owner: cfl12
---
# Cursor Subagent Metadata
## Why
When Cursor's agent dispatches a subagent, the only thing a Kandev user sees is a
generic `Task: Subagent task` card with no prompt, no model, and no identity. All
the useful detail (what the subagent was asked to do, which model runs it, its
agent id, whether it runs in the background) is delivered by Cursor over a
non-standard agent-to-client request, `cursor/task`, which Kandev currently
rejects. The subagent's work is therefore opaque, and a backgrounded subagent
looks identical to one that already finished.
## What
- A Cursor subagent card SHALL show the subagent's description, prompt, model,
and (for background subagents) a background indicator, sourced from the
`cursor/task` request Cursor emits alongside the standard `tool_call`.
- The rich metadata is correlated to the standard subagent `tool_call` by the
shared `toolCallId` Cursor puts in both, so the existing subagent card is
enriched in place rather than a second card appearing.
- `cursor/task` MUST NOT cause a JSON-RPC error back to Cursor. Kandev accepts
the request and returns an empty success result.
- A `cursor/task` that arrives with no matching subagent `tool_call` (or before
it) is retained and applied when the matching `tool_call` appears; a stored
correlation that is never matched is bounded and dropped when the session ends.
- Cursor reports background dispatch two ways that both map to the payload's
existing async concept: `cursor/task.model` ending in `-fast` is informational
only, while the completion `tool_call_update.rawOutput.isBackground == true`
marks the subagent as background. A background Cursor subagent renders the same
"background" affordance Claude's async subagents use.
- No behavior changes for any non-Cursor agent, and no change to how Cursor's
ordinary (non-subagent) tool calls render.
## Data model
No new persistent tables. The existing in-message
`streams.SubagentTaskPayload`
(`apps/backend/internal/agentctl/types/streams/tool_payload.go`) is the store;
its `Description`, `Prompt`, `SubagentType`, `Model`, `AgentID`, `DurationMs`,
and `IsAsync` fields already exist and already serialize to the frontend
`SubagentTaskPayload` (`apps/web/components/task/chat/types.ts`). This feature
populates the Cursor-shaped subset that is currently dropped; it adds no new
payload field unless correlation requires transient adapter-side state (a
per-session `map[toolCallId]cursorTask`, not persisted).
## API surface
`cursor/task` is an inbound agent-to-client JSON-RPC **request** (it carries an
`id`, so a response is required). Kandev is the ACP client. The method name does
not start with `_`, so the stock SDK extension hook
(`ExtensionMethodHandler`, only invoked for `_`-prefixed methods in
`kdlbs/acp-go-sdk` `extensions.go`) does not reach it, and the generated
`ClientSideConnection.handle` switch returns `-32601`.
Observed request params (wire capture, `composer-2.5`):
```text
cursor/task (request, has id)
agentId string e.g. "eaa12f70-...-60506ebd5c78"
description string e.g. "Summarize src JS files"
durationMs number launch duration, not the subagent's run time
model string e.g. "composer-2.5-fast"
prompt string the full subagent prompt
subagentType object e.g. {"custom":{"unspecified":{}}} — opaque, not a string
toolCallId string correlates to the standard tool_call, e.g. "tool_2494c23d-..."
```
Response: an empty JSON object result (no error).
The correlated standard frames (unchanged path): the `tool_call` carries
`rawInput:{"_toolName":"task"}` and title `Task: Subagent task`; the completion
`tool_call_update` carries `rawOutput:{"durationMs":N,"isBackground":true|false}`.
## Failure modes
- **Unknown/extra fields in `cursor/task`:** parsed defensively over untyped
maps; missing fields stay zero-valued and the card degrades to whatever is
present. Never errors the request.
- **`subagentType` is an object, not a string:** it is not coerced into the
string `SubagentType` field; it is ignored unless a stable string label can be
derived. A malformed value never blocks the rest of the metadata.
- **Ordering (request before or after the `tool_call`):** correlation by
`toolCallId` is order-independent; whichever arrives second applies the merge.
- **No matching `tool_call` ever arrives:** the stored `cursor/task` is bounded
per session and discarded at session teardown; it never leaks across sessions.
- **A field already set by the standard frame is not blanked** by a later empty
Cursor value (mirrors `applySubagentResult`'s fill-if-present rule).
## Persistence guarantees
Captured metadata lives on the message payload and persists with the transcript
exactly as today. The transient `toolCallId -> cursorTask` correlation map is
in-memory adapter state and does NOT survive a restart; a subagent whose
`cursor/task` was seen only before a restart keeps whatever was already merged
onto its stored payload.
## Scenarios
- **GIVEN** Cursor emits a subagent `tool_call` and a matching `cursor/task`
request, **WHEN** both are processed, **THEN** the subagent card shows the
Cursor description, prompt, and model, and Kandev returns a success (not
`-32601`) for `cursor/task`.
- **GIVEN** a `cursor/task` arrives before its `tool_call`, **WHEN** the
`tool_call` later arrives, **THEN** the card is enriched with the earlier
metadata.
- **GIVEN** the completion `tool_call_update.rawOutput.isBackground` is `true`,
**WHEN** the card renders, **THEN** it shows the background affordance.
- **GIVEN** `isBackground` is `false` or absent, **WHEN** the card renders,
**THEN** no background affordance shows.
- **GIVEN** a `cursor/task` with a missing `model` and a present `prompt`,
**WHEN** the card renders, **THEN** the prompt shows and no empty model chip
appears.
- **GIVEN** any non-Cursor agent's subagent, **WHEN** it is processed, **THEN**
its rendering is byte-identical to before this feature.
- **GIVEN** a `cursor/task` that never matches a `tool_call`, **WHEN** the
session ends, **THEN** the stored correlation is dropped and no card appears.
## Out of scope
- Fetching or resuming a **parked background subagent's result** by `agentId`.
A wire capture proved Cursor never pushes the async result back over the ACP
session (125s linger, zero post-`end_turn` frames); retrieval would need a new
follow-up-prompt flow and is a separate feature.
- Result-text capture for Cursor. Unlike Claude, Cursor's completion frame
carries only `durationMs`/`isBackground`, no result content; this remains as
noted out of scope in
[subagent-observability](../ui/subagent-observability.md).
- Interpreting Cursor's `subagentType` object taxonomy.
- Any change to `active_subagent_count`, liveness, or the board chip
([background-work-liveness](../platform/background-work-liveness.md)).
## Notes
- Wire evidence and the SDK dispatch analysis are recorded against task
`hey-a-user-reported` (`acpdbg --linger`, `composer-2.5`). The `cursor/task`
params and the `tool_call`/`tool_call_update` shapes above are from
`acp-debug/cursor-acp-linger-20260820-145213.jsonl`.
- Decision: [ADR-2026-08-20-acp-client-non-underscore-extension-methods](../../decisions/2026-08-20-acp-client-non-underscore-extension-methods.md)
resolves how `cursor/task` is accepted: the `kdlbs/acp-go-sdk` fork routes any
unrecognized inbound client method to the client's `ExtensionMethodHandler`,
and Kandev's `Client` returns success only for methods it recognizes
(`cursor/task`) and `NewMethodNotFound` otherwise.