@rex_koh/subagent-budget-guard 0.4.0 → 0.5.1

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "subagent-cap",
   "displayName": "Subagent Cap",
   "description": "Hard-deny subagent launches, record verified subagent usage, and enforce a session budget against Claude Code's 5-hour rate-limit percentage.",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "author": {
     "name": "ClaudeSubAgentSuppressor"
   },

package/README.md

@@ -10,10 +10,13 @@ Recommended Claude Code install:
 /plugin marketplace add rexkoh425/ClaudeSubAgentSuppressor
 /plugin install subagent-cap@subagent-tools
 /subagent-cap:init
+/sub-agent-view
 ```
 
 After `/subagent-cap:init`, fully exit and reopen Claude Code so the statusLine bridge from `settings.json` is active. Some Claude Code builds do not provide an in-session plugin reload command.
 
+`/sub-agent-view` can be run after a session to display how many subagents were spawned, the verified token total, total duration, and each saved subagent run with its token count, duration, model, and tool-call count.
+
 ## NPM Package
 
 This package is npm-ready as `@rex_koh/subagent-budget-guard`.
@@ -24,8 +27,11 @@ Claude Code plugin discovery is marketplace-based, so npm is mainly useful as a
 npm install -g @rex_koh/subagent-budget-guard
 subagent-cap doctor --offline
 subagent-cap status
+sub-agent-view
 ```
 
+`sub-agent-view` prints the latest session's recorded subagents with per-subagent status, type, description, verified token count, duration, model, and tool-call count. Use `sub-agent-view --session <session-id>` for a specific saved session, or `sub-agent-view --json` for machine-readable output. The same view is also available as the Claude command `/sub-agent-view` and the npm alias `subagent-cap view`.
+
 Maintainer publish command:
 
 ```bash

package/bin/subagent-cap.js

@@ -14,6 +14,10 @@ const COMMANDS = Object.freeze({
     script: 'report.js',
     help: 'show the current guard report'
   },
+  view: {
+    script: 'view.js',
+    help: 'show recorded subagent tokens and duration'
+  },
   doctor: {
     script: 'verify.js',
     help: 'verify the install without spending Claude quota'
@@ -31,6 +35,7 @@ function usage() {
     '  subagent-cap init',
     '  subagent-cap init --defaults',
     '  subagent-cap status',
+    '  subagent-cap view',
     '  subagent-cap doctor --offline'
   ].join('\n');
 }

package/bin/view.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { buildReport, formatSubagentView } from '../lib/guard.js';
+
+function argValue(name) {
+  const index = process.argv.indexOf(name);
+  if (index === -1) return null;
+  return process.argv[index + 1] || null;
+}
+
+async function main() {
+  const asJson = process.argv.includes('--json');
+  const sessionId = argValue('--session');
+  const report = await buildReport(sessionId, process.env);
+  const view = {
+    plugin: report.plugin,
+    sessionId: report.sessionId,
+    spawnedSubagents: report.state.subagents.runs.length,
+    verifiedTokens: report.state.subagents.verifiedTokens,
+    totalDurationMs: report.state.subagents.totalDurationMs,
+    subagents: report.state.subagents.runs
+  };
+
+  process.stdout.write(
+    asJson ? `${JSON.stringify(view, null, 2)}\n` : `${formatSubagentView(report)}\n`
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`sub-agent-view failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/commands/sub-agent-view.md

@@ -0,0 +1,17 @@
+---
+description: Show recorded subagent count, verified tokens, and duration for saved sessions.
+argument-hint: "[--session <session-id>] [--json]"
+disable-model-invocation: true
+---
+
+# View Recorded Subagents
+
+Run this command:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/view.js" $ARGUMENTS
+```
+
+Show the command output verbatim.
+
+If the command fails, show the error output and say that `/subagent-cap:init` must be run before saved session data is available.

package/lib/guard.js

@@ -780,6 +780,39 @@ export function formatReport(report) {
   return lines.join('\n');
 }
 
+function formatDuration(ms) {
+  const value = Number(ms || 0);
+  if (value >= 1000) return `${(value / 1000).toFixed(value % 1000 === 0 ? 0 : 1)}s`;
+  return `${value}ms`;
+}
+
+export function formatSubagentView(report) {
+  const runs = report.state.subagents.runs;
+  const lines = [
+    `Sub-agent view for ${report.sessionId}`,
+    `Spawned subagents: ${runs.length}`,
+    `Verified tokens: ${formatCount(report.state.subagents.verifiedTokens)}`,
+    `Total duration: ${formatDuration(report.state.subagents.totalDurationMs)}`
+  ];
+
+  if (runs.length === 0) {
+    lines.push('No subagents recorded for this session.');
+    return lines.join('\n');
+  }
+
+  for (const [index, run] of runs.entries()) {
+    const type = run.subagentType || 'unknown';
+    const description = run.description ? ` "${run.description}"` : '';
+    lines.push(`#${index + 1} ${run.status} ${type}${description}`);
+    lines.push(`  tokens: ${run.verified ? `${formatCount(run.totalTokens)} verified` : 'pending'}`);
+    lines.push(`  duration: ${formatDuration(run.totalDurationMs)}`);
+    lines.push(`  model: ${run.resolvedModel || 'unknown'}`);
+    lines.push(`  tools: ${Number(run.totalToolUseCount || 0)}`);
+  }
+
+  return lines.join('\n');
+}
+
 function quoteShellArg(value) {
   const normalized = String(value).replace(/\\/g, '/').replace(/"/g, '\\"');
   return `"${normalized}"`;

package/lib/verifier.js

@@ -111,7 +111,7 @@ export async function runOfflineVerification({
         entry.source?.package === '@rex_koh/subagent-budget-guard',
         'marketplace npm package mismatch'
       );
-      assert(entry.source?.version === '0.4.0', 'marketplace npm version mismatch');
+      assert(entry.source?.version === '0.5.1', 'marketplace npm version mismatch');
       return marketplacePath;
     });
   } else {
@@ -172,9 +172,11 @@ export async function runOfflineVerification({
       'bin/statusline.js',
       'bin/setup.js',
       'bin/report.js',
+      'bin/view.js',
       'bin/verify.js',
       'lib/guard.js',
       'lib/verifier.js',
+      'commands/sub-agent-view.md',
       'skills/init/SKILL.md'
     ];
     for (const script of scripts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rex_koh/subagent-budget-guard",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Claude Code plugin that blocks subagents by default, records verified subagent usage, and enforces 5-hour usage budgets.",
   "license": "MIT",
   "author": "ClaudeSubAgentSuppressor",
@@ -24,6 +24,7 @@
   "type": "module",
   "files": [
     ".claude-plugin/",
+    "commands/",
     "hooks/",
     "skills/",
     "bin/",
@@ -32,7 +33,8 @@
     "LICENSE"
   ],
   "bin": {
-    "subagent-cap": "bin/subagent-cap.js"
+    "subagent-cap": "bin/subagent-cap.js",
+    "sub-agent-view": "bin/view.js"
   },
   "publishConfig": {
     "access": "public"
@@ -41,7 +43,7 @@
     "test": "node --test test/*.test.js",
     "verify:offline": "node bin/verify.js --offline",
     "verify:live": "node bin/verify.js --live",
-    "prepack": "node --check bin/hook.js && node --check bin/statusline.js && node --check bin/setup.js && node --check bin/report.js && node --check bin/verify.js && node --check bin/subagent-cap.js && node --check lib/guard.js && node --check lib/verifier.js"
+    "prepack": "node --check bin/hook.js && node --check bin/statusline.js && node --check bin/setup.js && node --check bin/report.js && node --check bin/view.js && node --check bin/verify.js && node --check bin/subagent-cap.js && node --check lib/guard.js && node --check lib/verifier.js"
   },
   "engines": {
     "node": ">=20"