Intent (by Augment) — Integration & Debugging Runbook

Intent (by Augment) — Integration & Debugging Runbook

Status: Active. Owner: Liam. Audience: anyone debugging Intent-hosted Claude Code agents (hangs, spawn failures, permission stalls) or scripting Intent via its WebSocket API.

Intent hosts Claude Code agents over ACP (entrypoint: sdk-ts). Key locations:

Thing	Where
Workspace config + event log	~/intent/workspaces/<name>/.workspace/ (workspace.json, events.jsonl, agents/, logs/)
Worktree checkout	~/intent/workspaces/<name>/canonical (branch per workspace.json)
Claude Code transcripts for a workspace	~/.claude/projects/-Users-liamj-intent-workspaces-<name>-canonical/*.jsonl
Intent app log	~/Library/Application Support/intent/logs/console-output.log — WARN/ERROR only; logger.info lines (permission handling, set_mode, terminal create) never appear
Intent app settings	~/Library/Application Support/intent/settings.json
App source (for deeper debugging)	npx @electron/asar extract "/Applications/Intent by Augment.app/Contents/Resources/app.asar" <dest>

1. Permission model (the 30-min-hang class, fixed 24/07/2026)

• Intent runs sessions in permissionMode default — its ACP session/set_mode → bypassPermissions does not take effect on the claude-code adapter, and Claude-side defaultMode: bypassPermissions is overridden per-session.
• Unanswered permission requests are the hang mechanism: Intent routes them to a blocking dialog on the focused window (+ desktop notification, 5-min serialized auto-cancel). Background agent panels never surface it → tool call sits 10–30 min → Intent’s 30-min stream watchdog kills the turn (agent:failed: Stream timeout after 30 minutes; transcript shows toolDenialKind: user-rejected + [Request interrupted by user for tool use]).
• Fix (shipped): user-level PreToolUse hook ~/.claude/hooks/intent-acp-autoallow.sh auto-allows tool calls whose session cwd is under ~/intent/workspaces/ — requests never reach Intent. Cross-repo safe (keys on cwd, not target path); guard hooks (heredoc / ip-leak / sentinel) still deny with precedence.
• Residual — force-ask files: .claude/settings*.json, .claude/hooks/, .claude/skills/, .claude/agents/ are protected by Claude Code itself; hook allow cannot override. Any Write/Edit to them inside Intent still stalls. Do those edits from a terminal session (in ANY repo, docs-site included).

2. Detecting hung tool calls

events.jsonl nests tool blocks inside agent:stream:content-blocks (there are no top-level tool_use events), and rotates at 5,000 lines. Corrected detector:

python3 - <<'PY'
import json,glob
for f in glob.glob('/Users/liamj/intent/workspaces/*/.workspace/events.jsonl'):
    uses,res={},set()
    for l in open(f):
        try: d=json.loads(l)
        except: continue
        if d.get('type')!='agent:stream:content-blocks': continue
        for b in d.get('data',{}).get('content',[]):
            if b.get('type')=='tool_use': uses[b['id']]=b.get('name')
            elif b.get('type')=='tool_result': res.add(b.get('tool_use_id'))
    for i,n in uses.items():
        if i not in res: print(f.split('/')[-3], n, i)
PY

Better signal (no rotation loss): gap-scan the Claude transcripts — tool_use → 20 min+ gap → tool_result(is_error, "The user doesn't want to proceed") in ~/.claude/projects/-Users-liamj-intent-workspaces-*/*.jsonl.

3. WebSocket API

• Endpoint: wss://127.0.0.1:5180/ws — the /ws path is mandatory; any other path is destroyed with no HTTP response (reads as EOFError: connection closed while reading HTTP status line).
• Auth: Authorization: Bearer <token>; token + TLS fingerprint live in canonical/.env.local under # Intent Websocket (token == websocketApiToken in Intent settings.json; API gated on websocketApiEnabled: true).
• TLS: self-signed CN=Intent Local; clients pin the SHA-256 cert fingerprint (Intent’s pairing model) instead of CA verification. Record the FULL fingerprint in .env.local (it is currently truncated with …) so the pin is strong.
• Note: the server binds 0.0.0.0 — LAN-reachable by design (token + TLS gated).
• Protocol: JSON-RPC 2.0 — {"jsonrpc":"2.0","id":1,"method":"workspace.list","params":{}}.
• Probe script: scripts/intent-ws-probe.py (docs-site) — connects, pins the fingerprint, runs workspace.list + agent.list. Verified working 24/07/2026.
• Method families (~100 methods): workspace.* (list/get/create/archive), agent.* (list/get/getConversation/sendMessage/queueMessage/stop/delegate/ wakeOrCreate/setModel), note.*, task.* (assignAgent/updateStatus), git.* (status/stage/commit/agentCommit), pr.*, script.* (run/start/output), event.* (subscribe/query/agentActivity/workspaceSummary — useful for hang telemetry), crossWorkspace.* (listSiblings/listNotes/readNote), file.*, terminal.* (list/readOutput), browser.*, comment.*, specialist.list, repo.list, primitive.*.

4. App-level timeouts (spawn failures)

Timeout	Symptom
initialize 5 s (hardcoded)	[ACPProvider] Request timeout for initialize then Received response but no pending request found — cold claude boot is ~9 s with the current 9 MCP servers; repeated failures surface as Agent process died before initialization and -32603 Failed to create agent spawn-ceiling blocks. Mitigation: trim MCP servers loaded in Intent workspaces, or retry the spawn.
Stream watchdog 30 min	agent:failed: Stream timeout after 30 minutes — kills a turn with no stream activity (see §1).
Event delivery 30 s	agent:event-delivery-timeout — inter-agent event handoff (team mode) timed out.
Safety timeout 60 s	[AgentBackendHandler] Safety timeout — stop-flag failsafe.

Upstream-reportable (Augment): set_mode success-but-not-applied; permission dialog routed to focused window with serialized 5-min timeouts under a 30-min watchdog; 5 s initialize timeout vs real-world cold-boot latency.

5. Seeding a workspace — the context spine (id-386)

Intent Coordinators bypass the session-start spine structurally: the seeding prompt is their whole world, and a bare “create a spec from this file” produces sessions with zero Skill invocations and zero recall calls (measured across the S501/S502 lanes: 1,113 shell calls in one lane; KH_PRIVATE_DOCS_DIR guessed wrong three times; mempalace mandated in all 21 agent system prompts, never called). The fix lives where Intent actually starts: every workspace seeding prompt carries the spine below, and the Coordinator’s first deliverable is a Grounding note that all task briefs cite.

Paste (and fill {…}) as the seeding prompt / first Coordinator message:

You are the Coordinator for {task/wave}. Before ANY planning, spec-writing, or
dispatch, build your grounding — in this order, with real command output, not
memory:

1. Resolve paths — never guess:
   - KH_PRIVATE_DOCS_DIR: `echo $KH_PRIVATE_DOCS_DIR`; if unset it is the
     sibling clone `/Users/liamj/Documents/development/knowledge-hub-docs-site`.
     Verify with `ls` before first use. Below, DOCS = $KH_PRIVATE_DOCS_DIR/src/content/docs.
   - This workspace's checkout is a worktree of the SECOND clone
     (`~/Developer/canonical`) — `git worktree list` in the dev checkout cannot
     see it.
2. Read: the latest continuation prompt
   (`ls -1 $DOCS/continuation-prompts/continuation-prompt-ca-*.md | sort -V | tail -2`);
   `$DOCS/reference/platform-context.md` (the load anchor); your task file(s)
   `$KH_PRIVATE_DOCS_DIR/tasks/id-{N}.md`; the owning initiative record
   (`grep -rn "Linked tasks:.*\b{N}\b" $DOCS/ledgers/initiatives/`); the
   "In force" table in `$DOCS/reference/decision-register.md`; the last two
   retros (`ls -1 $DOCS/ledgers/retros/S*.md | sort -V | tail -2`).
3. Recall pass (mandatory, before any conclusion citing prior work): mempalace
   MCP `mempalace_search` seeded with your task ids + titles; on ANY MCP error
   fall through to the lock-free FTS — do not proceed recall-blind:
   sqlite3 "file:$HOME/.mempalace/palace/chroma.sqlite3?mode=ro&immutable=1" \
     "SELECT substr(replace(string_value,char(10),' '),1,200)
      FROM embedding_fulltext_search WHERE string_value MATCH '{seed terms}'
      AND string_value NOT LIKE 'CHECKPOINT:%' ORDER BY rowid DESC LIMIT 8"
4. Session number: check `ls $DOCS/ledgers/retros/` AND the continuation
   prompt's allocation before claiming an S-number (collisions are
   thrice-burned; ids may be pre-allocated). The workspace/branch name is NOT
   a session id.
5. Write ONE workspace note titled "Grounding — S{NNN}" (tag: grounding)
   recording only what you VERIFIED against the filesystem: resolved paths,
   session number, repo/worktree state, register + retro counts, and every
   place the continuation prompt is stale. Every task brief you dispatch cites
   this note as its context base.
6. Working rules: never `git stash` in a worktree; never remove a worktree;
   findings go in workspace notes, not new repo .md files; owner rulings gate
   any mutation of ledgers or the register.

Exemplar (the pattern’s origin): the S502 “Grounding — S502” note, preserved at specs/id-386-intent-context-spine/notes/23b4fa45-9db3-4ced-85f2-7aa2ff4b50b6.md.

When the workspace closes or a wave lands, run the canonical repo’s sync-intent-notes skill to preserve .workspace/notes/ under the task’s specs/id-N-<slug>/notes/ — that sync is what makes the Grounding note and the task notes citable evidence afterwards.