Acp Debug

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.claude/agents

.claude/skills

.github/CLAUDE.md

CLAUDE.md

apps/backend/CLAUDE.md

import { test, expect } from "../../fixtures/test-base";

apps/web/generated/licenses.json

Audit 0.4.1 · source sha 786d4817799e · 18 Oct 2026Report an issue or request a re-scan

• Publisherkdlbs GitHub organizationOwner of the repository this skill is read from
• Source folderkdlbs/kandev/.agents/skills/acp-debugThe exact folder we audited
• LicenceAGPL-3.0As the repository states it
• Commit pinned for this verdict786d4817799eA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect…

---
name: acp-debug
description: Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect raw ACP wire frames, or investigate why an agent fails to initialize.
---

# ACP Debug

Run a headless ACP JSON-RPC session against any registered kandev agent (or an arbitrary command), record every wire frame to a JSONL file, and summarize the handshake. Backed by the `acpdbg` binary at `apps/backend/bin/acpdbg`.

## When to use this skill

- "what models does auggie advertise"
- "probe claude-acp" / "probe all agents" / "run the matrix"
- "debug why copilot-acp isn't starting"
- "what does a `session/new` response actually look like for X"
- "try this prompt against auggie with mode=ask"
- "reproduce session/load for session <id> against claude-acp"
- User mentions inspecting raw ACP wire payloads or a JSONL file from an earlier run

## Before anything else: build the binary if missing

```bash
test -x apps/backend/bin/acpdbg || make -C apps/backend build-acpdbg
```

## Sub-commands

```text
acpdbg list                                            # enumerate registered ACP agents
acpdbg probe <agent>                                   # initialize + session/new + close
acpdbg probe --exec "<cmd> [args...]"                  # probe an arbitrary binary not in the registry
acpdbg mcp-probe <agent>                                # inject a temporary MCP sentinel into session/new
acpdbg prompt --prompt "..." [--model M] [--mode M] <agent>
acpdbg session-load --session-id <id> <agent>
acpdbg matrix                                          # probe every ACP agent in parallel
```

> **Flags MUST come before the positional `<agent>`.** The CLI uses Go's stdlib
> `flag` parser, which stops at the first non-flag token — so any flag placed
> *after* `<agent>` is silently ignored (`probe`/`matrix`, e.g. a dropped
> `--timeout`) or errors (`prompt` → `--prompt is required`). Always write
> `acpdbg prompt --prompt "..." --timeout 240s <agent>`, not `acpdbg prompt <agent> --prompt ...`.

**Shared flags** (apply to every sub-command):
- `--out DIR` — JSONL output directory (default `./acp-debug/`)
- `--file PATH` — exact JSONL path, overrides `--out`
- `--timeout DUR` — overall run timeout (default `30s`)
- `--workdir PATH` — child cwd (default: fresh `/tmp/kandev-acpdbg-<pid>-*`)
- `--verbose` — mirror frames to stderr
- `--stderr` — capture child stderr into the JSONL

## Steps

**Create a task for each step below and mark them as completed as you go.**

### 1. Pick the sub-command that matches the user's intent

- "what models does X have" / "does X support modes" → `acpdbg probe X`
- "test a prompt against X" → `acpdbg prompt --prompt "..." X`
- "compare all agents" / "run the matrix" → `acpdbg matrix`
- "resume session <id>" → `acpdbg session-load --session-id <id> X`
- "did this agent attach the injected MCP server" → `acpdbg mcp-probe X`
- "try this random binary" → `acpdbg probe --exec "path/to/bin --acp"`

### 2. Run the command

Always capture stdout — it contains the JSONL file path (and for `matrix`, the summary table and `matrix-summary.json` path).

```bash
apps/backend/bin/acpdbg probe --timeout 45s auggie
```

For `matrix`, prefer `--timeout 60s` so `npx`-spawned agents have time to cold-start.

For Claude ACP, the generated default workdir is an absolute temporary
directory and is sent as the ACP `cwd`; no `--workdir` flag is required. If
you override it, supply an existing absolute directory (for example, run
`mkdir -p /tmp/kandev-acpdbg-claude` before passing that path to `--workdir`).
An empty `cwd` can cause Claude to reject `session/new`; confirm the `cwd` in
the recorded request frame before diagnosing a provider failure.

### 3. Read the JSONL file

The JSONL schema is:

| `direction` | Meaning | Extra fields |
|---|---|---|
| `meta` | acpdbg-generated marker | `event` (`start` / `close`), `meta` (map with `agent`, `command`, `workdir` for start; `exit_code`, `reason` for close) |
| `sent` | Frame written to child's stdin | `frame` (JSON-RPC request or reply) |
| `received` | Frame read from child's stdout | `frame` (JSON-RPC request, response, or notification) |
| `stderr` | Child stderr line (only when `--stderr`) | `line` |

Entries are strictly chronological. Each line is a single JSON object terminated by `\n`.

Useful `jq` recipes:

```bash
# Full initialize response
jq -c 'select(.direction == "received" and .frame.id == 1)' acp-debug/<file>.jsonl

# Full session/new response (models, modes, auth)
jq '.frame.result' acp-debug/<file>.jsonl | head -50

# Just the models advertised
jq -r 'select(.direction == "received") | .frame.result.models.availableModels[]?.modelId' acp-debug/<file>.jsonl

# Close event (exit code + reason)
jq -c 'select(.direction == "meta" and .event == "close")' acp-debug/<file>.jsonl

# All agent-initiated requests we auto-replied to
jq -c 'select(.direction == "received" and .frame.method and .frame.id)' acp-debug/<file>.jsonl
```

### 4. Summarize for the user

Give a concise markdown summary: agent, protocol version, models found (with currentModelId), modes found (with currentModeId), auth methods, any errors, and the JSONL path for deeper inspection. Example:

```text
**auggie** (protocol v1, auggie 0.20.1)
Models (11): claude-sonnet-4-6 (current), claude-opus-4-6, gpt-5-4, ...
Modes  (2):  default (current), ask
Auth methods: (none advertised)
JSONL: acp-debug/auggie-probe-20260409-183104.jsonl
```

### 5. If something looks wrong, walk the frames

Common failure modes:

| Symptom | Likely cause | Next step |
|---|---|---|
| meta close `exit_code: 127` immediately | child binary not installed | Check `which <cmd>`; suggest install command |
| meta close before any `received` frame | child crashed on startup | Re-run with `--stderr` to capture the error |
| `initialize` response has populated `authM

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-18
   !CAUTION B 89 / 100

   first audit · source 786d4817799e

Questions about Acp Debug

• github.com/kdlbs/kandev/tree/main/.agents/skills/acp-debug — the audited source at commit 786d4817799e and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology