From 62dad58ebc88edbef40147c46cc7675cb26c4228 Mon Sep 17 00:00:00 2001 From: Lucas Dow Date: Wed, 7 Oct 2026 22:28:03 +0200 Subject: [PATCH] feat: send subagent description and model on agent.start (0.31.0) SubagentStart carries only agent_type and agent_id. The Agent tool's PreToolUse now queues {agentType, description, model} per session before going async, and agent-start.sh takes the oldest fresh intent of its type. Private mode keeps the model only. Tests: tests/agents/run.sh. Co-Authored-By: Claude Opus 5.5 DevScope-Session: 7ed92b1f-21e5-4a3b-b933-e2ce8af3a7ee --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 11 ++++++ README.md | 2 +- scripts/_helpers.sh | 44 ++++++++++++++++++++++++ scripts/agent-start.sh | 14 ++++++-- scripts/tool-use.sh | 11 ++++++ tests/agents/run.sh | 61 +++++++++++++++++++++++++++++++++ 8 files changed, 142 insertions(+), 5 deletions(-) create mode 100644 tests/agents/run.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1150e39..1252044 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "devscope", "description": "Real-time developer activity monitoring for Claude Code sessions", - "version": "0.30.0", + "version": "0.31.0", "author": { "name": "Lucas Dow", "email": "lucdow7@gmail.com" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bc7ff6b..f7ccd16 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "devscope", - "version": "0.30.0", + "version": "0.31.0", "description": "Real-time developer activity monitoring for Claude Code sessions", "author": { "name": "Lucas Dow", diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c43eaf..74cc7a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [0.31.0] - 2026-10-07 + +### Added +- **Subagents report what they were asked to do.** `agent.start` now carries + the subagent's `description` and `model` from the Agent tool call, so the + DevScope topology can label each subagent. SubagentStart itself has neither, + so the Agent tool's PreToolUse queues them per session + (`~/.cache/devscope/intents/`) and `agent-start.sh` takes the oldest one of + its type from the last 10 minutes. In `private` mode only the model is kept; + the description is never written or sent. + ## [0.30.0] - 2026-10-07 ### Added diff --git a/README.md b/README.md index 4434973..2b51063 100644 --- a/README.md +++ b/README.md @@ -263,7 +263,7 @@ Auto voice is a short spoken summary whenever Claude finishes a reply: the outco | Session start/end | Session duration, permission mode | | Tool use | Tool name, duration, success/failure | | Prompt submit | Prompt length | -| Subagent start/stop | Agent type | +| Subagent start/stop | Agent type, task description (not in `private` mode) and model | | Response complete | Tools used, response length | | Task completed | Task details | | And more... | Notifications, compaction, config changes | diff --git a/scripts/_helpers.sh b/scripts/_helpers.sh index 428949b..a6ab6e7 100755 --- a/scripts/_helpers.sh +++ b/scripts/_helpers.sh @@ -88,6 +88,50 @@ _ds_project_hash() { _ds_sha256 "${email}:${cwd}:${PPID}" } +# Subagent intents. SubagentStart carries only agent_type and agent_id, so the +# PreToolUse of the Agent tool queues what the subagent was asked to do and +# agent-start.sh takes the oldest fresh intent of its type. Private mode keeps +# the model but never the description. +_ds_agent_intent_file() { + echo "${HOME}/.cache/devscope/intents/$(printf '%s' "$1" | tr -cd 'a-zA-Z0-9_-').jsonl" +} + +# Usage: _ds_record_agent_intent "$HOOK_INPUT_JSON" +_ds_record_agent_intent() { + local session file + session=$(printf '%s' "$1" | jq -r '.session_id // ""' 2>/dev/null) || return 0 + [ -n "$session" ] || return 0 + file=$(_ds_agent_intent_file "$session") + mkdir -p -m 0700 "$(dirname "$file")" + printf '%s' "$1" | jq -c --arg privacy "$DEVSCOPE_PRIVACY" --argjson now "$(date +%s)" ' + .tool_input // {} | { + agentType: (.subagent_type // "general-purpose"), + description: (if $privacy == "private" then null else (.description // null) end), + model: (.model // null), + ts: $now + }' >> "$file" 2>/dev/null || true +} + +# Prints the oldest intent of the type queued in the last 10 minutes and drops +# it (and any older ones) from the queue. Prints nothing when there is none. +# Usage: INTENT=$(_ds_take_agent_intent "$SESSION_ID" "$AGENT_TYPE") +_ds_take_agent_intent() { + local file + file=$(_ds_agent_intent_file "$1") + [ -f "$file" ] || return 0 + ( + command -v flock >/dev/null 2>&1 && flock -w 2 9 + picked=$(jq -cs --arg t "$2" --argjson now "$(date +%s)" ' + map(select(.ts >= $now - 600)) + | (map(.agentType == $t) | index(true)) as $i + | if $i == null then {take: null, rest: .} + else {take: .[$i], rest: (.[:$i] + .[$i + 1:])} end' "$file" 2>/dev/null) || exit 0 + printf '%s' "$picked" | jq -c '.rest[]' > "$file" + [ -s "$file" ] || rm -f "$file" + printf '%s' "$picked" | jq -c '.take // empty | del(.ts)' + ) 9>"${file}.lock" +} + # Cross-platform reverse file (tac on Linux, tail -r on macOS) _ds_tac() { if command -v tac >/dev/null 2>&1; then diff --git a/scripts/agent-start.sh b/scripts/agent-start.sh index 24d9a9e..4e27df5 100755 --- a/scripts/agent-start.sh +++ b/scripts/agent-start.sh @@ -8,6 +8,7 @@ INPUT=$(cat) AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // "unknown"') AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // ""') CWD=$(echo "$INPUT" | jq -r '.cwd // empty') +SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""') # Detect parent agent via agent stack PARENT_AGENT_ID="" @@ -22,8 +23,17 @@ if [ -n "$CWD" ] && [ -n "$AGENT_ID" ]; then echo "$AGENT_ID" >> "$STACK_FILE" fi -PAYLOAD=$(jq -n --arg at "$AGENT_TYPE" --arg ai "$AGENT_ID" --arg pai "$PARENT_AGENT_ID" \ +# Description and model, as queued by the Agent tool's PreToolUse (tool-use.sh) +INTENT="{}" +if [ -n "$SESSION_ID" ]; then + INTENT=$(_ds_take_agent_intent "$SESSION_ID" "$AGENT_TYPE") + [ -n "$INTENT" ] || INTENT="{}" +fi + +PAYLOAD=$(jq -n --arg at "$AGENT_TYPE" --arg ai "$AGENT_ID" --arg pai "$PARENT_AGENT_ID" --argjson intent "$INTENT" \ '{agentType: $at, agentId: $ai} - | if $pai != "" then . + {parentAgentId: $pai} else . end') + | if $pai != "" then . + {parentAgentId: $pai} else . end + | if $intent.description then . + {description: $intent.description} else . end + | if $intent.model then . + {model: $intent.model} else . end') echo "$INPUT" | "$SCRIPT_DIR/send-event.sh" "agent.start" "$PAYLOAD" diff --git a/scripts/tool-use.sh b/scripts/tool-use.sh index 091301a..3c29dc1 100755 --- a/scripts/tool-use.sh +++ b/scripts/tool-use.sh @@ -19,6 +19,17 @@ INPUT=$(cat) # on the first line of stdout. Claude Code sees it, backgrounds this process and # stops waiting — everything below then runs detached, at no cost to the session. # In hard mode we stay synchronous so the deny below can be honored. +# +# The Agent tool's intent is queued before that, so SubagentStart (which runs +# once the tool starts) always finds it. +case "$INPUT" in + *'"Agent"'*|*'"Task"'*) + case "$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)" in + Agent|Task) _ds_record_agent_intent "$INPUT" ;; + esac + ;; +esac + if [ "${DEVSCOPE_NUDGE_MODE:-soft}" != "hard" ]; then printf '{"async": true}\n' fi diff --git a/tests/agents/run.sh b/tests/agents/run.sh new file mode 100644 index 0000000..99ccbab --- /dev/null +++ b/tests/agents/run.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +# Tests for the subagent intent queue: tool-use.sh (PreToolUse of the Agent +# tool) queues description and model, agent-start.sh puts them on agent.start. +# +# bash tests/agents/run.sh +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +TMP=$(mktemp -d) +export HOME="$TMP" XDG_CONFIG_HOME="$TMP/config" +unset DEVSCOPE_PRIVACY DEVSCOPE_NUDGE_MODE +# shellcheck disable=SC1091 +. "$ROOT/tests/lib/stub.sh" +respond '{}' + +pass=0; fail=0 +ok() { pass=$((pass + 1)); echo "ok $1"; } +bad() { fail=$((fail + 1)); echo "FAIL $1: $2"; } +pre() { # session subagent_type description [model] + jq -n --arg s "$1" --arg t "$2" --arg d "$3" --arg m "${4:-}" \ + '{session_id: $s, cwd: "/tmp", hook_event_name: "PreToolUse", tool_name: "Agent", + tool_input: ({subagent_type: $t, description: $d, prompt: "do it"} + + (if $m != "" then {model: $m} else {} end))}' \ + | "$ROOT/scripts/tool-use.sh" >/dev/null +} +start() { # session agent_type agent_id + jq -n --arg s "$1" --arg t "$2" --arg a "$3" \ + '{session_id: $s, cwd: "/tmp", hook_event_name: "SubagentStart", agent_type: $t, agent_id: $a}' \ + | "$ROOT/scripts/agent-start.sh" >/dev/null + last_at /api/events '.body.payload' +} +wait_hits() { for _ in $(seq 1 30); do [ "$(hits)" -ge "$1" ] && return; sleep 0.1; done; } + +pre s1 Explore "Map the topology code" haiku +p=$(start s1 Explore a1) +[ "$(printf '%s' "$p" | jq -r .description)" = "Map the topology code" ] && ok "description reaches agent.start" || bad "description" "$p" +[ "$(printf '%s' "$p" | jq -r .model)" = "haiku" ] && ok "model reaches agent.start" || bad "model" "$p" + +pre s2 Explore "first"; pre s2 Plan "the plan"; pre s2 Explore "second" +[ "$(start s2 Plan a2 | jq -r .description)" = "the plan" ] && ok "matches by agent type" || bad "type match" "" +[ "$(start s2 Explore a3 | jq -r .description)" = "first" ] && ok "same type: oldest first" || bad "fifo 1" "" +[ "$(start s2 Explore a4 | jq -r .description)" = "second" ] && ok "same type: then the next" || bad "fifo 2" "" +p=$(start s2 Explore a5) +[ "$(printf '%s' "$p" | jq -r '.description // "none"')" = "none" ] && [ "$(printf '%s' "$p" | jq -r .agentId)" = "a5" ] \ + && ok "empty queue: plain agent.start" || bad "empty" "$p" + +pre s4 general-purpose "secret task" sonnet +p=$(start s4 general-purpose a7) +[ "$(printf '%s' "$p" | jq -r .description)" = "secret task" ] && ok "standard mode keeps description" || bad "standard" "$p" +DEVSCOPE_PRIVACY=private pre s5 general-purpose "secret task" sonnet +grep -q "secret task" "$HOME/.cache/devscope/intents/s5.jsonl" && bad "private queue" "description written to disk" || ok "private mode never stores the description" +p=$(start s5 general-purpose a8) +[ "$(printf '%s' "$p" | jq -r '.description // "none"')" = "none" ] && [ "$(printf '%s' "$p" | jq -r .model)" = "sonnet" ] \ + && ok "private mode: model only" || bad "private" "$p" + +pre s6 Explore "old one" +jq -c '.ts = (.ts - 3600)' "$HOME/.cache/devscope/intents/s6.jsonl" > "$TMP/x" && mv "$TMP/x" "$HOME/.cache/devscope/intents/s6.jsonl" +[ "$(start s6 Explore a9 | jq -r '.description // "none"')" = "none" ] && ok "intents older than 10 min are dropped" || bad "stale" "" +[ ! -f "$HOME/.cache/devscope/intents/s6.jsonl" ] && ok "empty queue file is removed" || bad "cleanup" "file left" + +echo "---"; echo "$pass passed, $fail failed" +[ "$fail" -eq 0 ]