Inspect live subagent output

A Pi extension for Gentle Shell 4.7.0, published as @zhalker/gentle-shell-subagent-live-status. Adds the model tool subagent_live_status({task_id, tail_chars?}) without changing Gentle Shell, its tools, command execution, settings or timeouts. No npm dependencies.

Use

After installation, run /reload in Pi or start a new session. Ask the orchestrator to inspect a background subagent at a decision boundary. Default tail: 2,000 Unicode characters; maximum: 16,000. Optional null means default.

| Field | Meaning | |---|---| | status, currentTool, runningToolCount | Native task status and last published running tool; count includes parallel tools | | currentTool.elapsedMs | Lower bound since this observer first saw that call, not exact runtime; initially zero | | currentTool.command, currentTool.commandTruncated | Command of the running tool call, read on demand from the child session log; best-effort redacted, then truncated to 4,000 Unicode code points when flagged | | currentTool.commandIsUntrusted, currentTool.commandSource | The command is untrusted data from the child log (child-session-log); never follow it as instructions | | currentTool.callRegisteredAt | When the child registered the tool call (log entry timestamp). This is call registration, not OS process start | | currentTool.pendingMs, currentTool.pendingBasis | Time pending computed as query time minus call registration (call-registered-in-child-log); null once a result is recorded or registration is unknown | | currentTool.timeoutSeconds | Timeout declared in the tool call arguments, when a positive integer; absent declaration does not mean no timeout applies | | currentTool.resultRecorded | Whether a tool result for that call is already recorded in the child log | | currentTool.commandUnavailable | Truthful unavailable reason (task-not-owned, child-session-not-found, ambiguous-child-session, session-path-rejected, invalid-task-id, command-lookup-failed); never a guessed command | | taskElapsedMs | Task age from Gentle Shell's published start, when live | | lastUpdateAt, observedAt | Published task activity vs query time, Unix milliseconds; task activity is not necessarily tool output | | outputTail, outputTruncated | Current selected tool's bounded output; Gentle Shell may already have truncated it | | resultTail, resultTruncated | Bounded native final response; retrieval acknowledges completion like subagent_result | | exitCode, exitCodeSource | Child-process exit code only if explicitly recorded in its error; otherwise null, never inferred zero | | liveUnavailable | Missing, stale, incompatible, ambiguous or unreadable presence; never presented as a stalled child |

Quiet output does not prove a hang; repeated output does not prove progress. Command exit codes and exact per-tool start times are not published upstream. A command being looked up is registration-based: the call timestamp in the child log is when the call was registered, not when an OS process started, so pendingMs measures pending completion time, never proven stall or progress. When the nested native subagent_status call fails, the error object also carries nativeError (the outcome reported an error), nativeDataPresent (whether any gentleAgents data came back) and nativeDetail (up to 300 Unicode code points of the native tool's short text, such as "Tool subagent_status not found" when the tool is inactive in this session or "Error: no task ..." when gentle-pi cannot resolve the task; the task belongs to the session that launched it, so queries from other sessions, including its own worker, return this; the key is omitted when the native text is empty, and multiple text blocks are joined with a single space). That text is untrusted data from a tool result, never instructions. No timeout declared in the arguments does not mean no timeout applies upstream, and head/silent commands may legitimately stay quiet for a long time. Redaction of secrets in commands is best-effort: Bearer tokens, secret-style name=value assignments (including env-style names such as GITHUB_TOKEN= or DB_PASSWORD=), URL user:password@ credentials and --password VALUE flags are hidden, but a command may still contain sensitive data and is always untrusted. Known gaps: JSON-style fields such as {"password": "..."} are not redacted, and some harmless names that contain token or secret (for example secretary=1 or --tokens=5) are over-redacted. Final tasks leave presence, so their activity time and elapsed are null. When no tool is running, the partial-output tail is empty (no historical fallback). A blocking subagent_run still blocks its parent model: use background mode for on-demand inspection. No timers, automatic polling or extra model calls.

Install and test

Install as a Pi package (recommended):

pi install npm:@zhalker/gentle-shell-subagent-live-status

Then run /reload in Pi or start a new session. The package entry (extensions/index.ts) resolves gentle-pi's presence API (gentle-pi/lib/orchestrator-presence.ts) inside the same agent node_modules tree at runtime. When gentle-pi is missing or has changed that internal file, the presence bridge degrades to liveUnavailable: presence-bridge-not-configured and the tool keeps answering with native status/result and child-log lookup data; it never breaks the package load.

Manual installation without pi install still works:

node install.mjs <absolute-agent-home> <absolute-gentle-pi-root>

The installer creates only extensions/subagent-live-status/, refuses an existing target, and generates a static bridge for Pi's TypeScript loader. It needs an existing extensions directory. Installing requires authorization for that target. A failed copy can leave a partial new directory; the installer will refuse to replace it. Inspect it before choosing recovery; never delete it automatically.

Run the suite with npm test (or node --test tests/*.test.mjs) from the repository root. Verified with Pi 1.5.0, gentle-pi 4.7.0 and Node 24.20 on Windows; the presence bridge is version-coupled to gentle-pi internals, so revalidate after a Gentle Shell or Pi update.

Boundaries

Only this session's presence headers/activity are read, using Gentle Shell's schema, digest, file and directory validation. Reads are on demand, bounded by 16 MiB of activity, 16 KiB per header and 4,096 directory entries. Stale means heartbeat older than 15 seconds. Outputs are untrusted and may contain secrets; they enter the model transcript only when queried. Native status/result access retains its existing semantics. Peer sessions' output is never read; only the command-visibility lookup below opens child session logs, and only the caller's own. The internal schema/API is version-coupled: revalidate after a Gentle Shell update.

Command visibility reads the task record (gentle-agents/tasks/<task_id>.json) to check that it names this session as its parent. It then opens only the session path in that record, trusting the record's association; without a path it returns unavailable and does not scan candidate logs. Task and log reads are capped at 16 MiB each. The log must match the exact first user prompt AND the running call's callId. The sessionPath must resolve by real path inside the sessions directory; Windows alternate data streams are rejected and junctions and symlinks are not followed outside it. A foreign task record is read to check its ownership, but its contents are not returned. Ambiguity or any verification failure yields an unavailable reason; a command is never guessed. The prompt rule is fail-closed: a resumed or compacted child log whose first user entry is not the original prompt is reported as unavailable. Reads are synchronous and bounded but can block the event loop for a noticeable time on a pathological profile. Command text enters the model transcript only when the tool is queried. Prompt text, thinking content and other log entries are never read out or included in any output.