feat: v4 redesign — 13 fat verb-tools, token-efficient output, adoption layer

.claude/hooks/ssh-bash-nudge.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook for the Bash tool. Detects a simple ssh/scp/rsync invocation
+ * against a configured server and prints a soft, non-blocking nudge toward the
+ * matching ssh_* MCP tool. Best-effort: simple shapes nudged, complex command
+ * lines passed through. Fail-open -- any error exits 0 with no nudge.
+ *
+ * Wired in .claude/settings.json under hooks.PreToolUse, matcher "Bash".
+ */
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+// Shell metacharacters => the command line is not a simple invocation. Bail.
+const COMPLEX = /[|&;<>`]|\$\(/;
+
+/** Configured server names from the project .env (best-effort, never throws). */
+export function configuredServers(envPath) {
+  try {
+    const text = readFileSync(envPath, 'utf8');
+    const names = new Set();
+    for (const line of text.split('\n')) {
+      // SSH_SERVER_<NAME>_HOST=... -- <NAME> is the server identifier.
+      const m = /^\s*SSH_SERVER_([A-Za-z0-9]+)_HOST\s*=/.exec(line);
+      if (m) names.add(m[1].toLowerCase());
+    }
+    return [...names];
+  } catch {
+    return [];
+  }
+}
+
+/** Strip a leading user@ and return the bare host token, lowercased. */
+function bareHost(token) {
+  const at = token.lastIndexOf('@');
+  return (at === -1 ? token : token.slice(at + 1)).toLowerCase();
+}
+
+/**
+ * Inspect a Bash command string. Returns { tool, message } when it is a simple
+ * ssh/scp/rsync call against a configured server, else null. Never throws.
+ */
+export function detectSshNudge(command, servers) {
+  try {
+    if (!command || typeof command !== 'string') return null;
+    if (!Array.isArray(servers) || servers.length === 0) return null;
+    if (COMPLEX.test(command)) return null;
+
+    const set = new Set(servers.map((s) => String(s).toLowerCase()));
+    const tokens = command.trim().split(/\s+/);
+    const head = tokens[0];
+
+    if (head === 'ssh') {
+      // First token after the flags that is not a flag or a flag-value is the host.
+      for (let i = 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '-p' || t === '-i' || t === '-l' || t === '-o' || t === '-F') {
+          i++; // skip this flag's value
+          continue;
+        }
+        if (t.startsWith('-')) continue;
+        return set.has(bareHost(t))
+          ? { tool: 'ssh_run', message: nudgeText(bareHost(t), 'ssh_run', 'ssh') }
+          : null;
+      }
+      return null;
+    }
+
+    if (head === 'scp' || head === 'rsync') {
+      // Any non-flag token of the form host:path against a configured server.
+      for (let i = 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.startsWith('-')) continue;
+        const colon = t.indexOf(':');
+        if (colon > 0 && set.has(bareHost(t.slice(0, colon)))) {
+          const host = bareHost(t.slice(0, colon));
+          return { tool: 'ssh_file', message: nudgeText(host, 'ssh_file', head) };
+        }
+      }
+      return null;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** The soft nudge text shown in the PreToolUse hook output. */
+function nudgeText(host, tool, rawCmd) {
+  return `[ssh-manager] '${host}' is a configured server. Consider the `
+    + `${tool} MCP tool instead of raw \`${rawCmd}\` -- pooled connection, `
+    + `bounded output, structured result. (This is a hint, not a block.)`;
+}
+
+// --- CLI shell: invoked by Claude Code as a PreToolUse hook --------------
+// Reads the hook JSON payload on stdin; prints a nudge on stdout if one
+// applies; always exits 0 so the Bash call is never blocked.
+function main() {
+  let raw = '';
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    process.exit(0); // no stdin -> nothing to inspect
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0); // unparseable payload -> fail open
+  }
+
+  const command = payload && payload.tool_input && payload.tool_input.command;
+  const envPath = fileURLToPath(new URL('../../.env', import.meta.url));
+  const nudge = detectSshNudge(command, configuredServers(envPath));
+  if (nudge) console.log(nudge.message);
+  process.exit(0);
+}
+
+// Run main() only when executed directly, never when imported by a test.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ssh-bash-nudge.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

AGENTS.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **claude-code-ssh** (1340 symbols, 3668 relationships, 111 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **claude-code-ssh** (1341 symbols, 3675 relationships, 111 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -6,11 +6,11 @@ This file provides guidance to Claude Code when working on this repository.
 
 **claude-code-ssh** is an MCP server that gives Claude Code direct SSH access to a configured fleet of servers. The goal: Claude stops being a read-only assistant and becomes a hands-on operator — reading logs, editing configs, running backups, deploying, debugging — without a human typing commands between them.
 
-51 tools, 7 groups, opt-in per user. Connection pooling, streaming exec, head+tail output truncation, ASCII-only rendering.
+13 fat verb-tools, each covering one domain via an `action` enum. Always loaded (un-deferred). Connection pooling, streaming exec, head+tail output truncation, command-output compression, ASCII-only rendering.
 
 ## Architecture
 
-- **`src/index.js`** — MCP server entry, registers all 51 tools via `registerToolConditional()`
+- **`src/index.js`** — MCP server entry, registers the 13 v4 tools via `registerToolConditional()`; descriptions sourced from `src/tool-descriptions.js`
 - **`src/tools/*.js`** — 17 modular handler files, one per logical tool area (exec, files, backup, db, etc.)
 - **`src/tool-registry.js`** — tool metadata + group membership (core, sessions, monitoring, backup, database, advanced, gamechanger)
 - **`src/tool-config-manager.js`** — per-user enablement via `~/.ssh-manager/tools-config.json`
@@ -58,14 +58,14 @@ ssh-manager tools export-claude               # Export auto-approval config
 
 **Tool Groups**: core (5), sessions (4), monitoring (6), backup (4), database (4), advanced (14)
 
-**Modes**: all (37 tools, ~43.5k tokens), minimal (5 tools, ~3.5k tokens), custom (variable)
+**Modes**: v4 surface is always loaded (13 tools, ~5k tokens); the per-group mode system is deprecated.
 
 See [docs/TOOL_MANAGEMENT.md](docs/TOOL_MANAGEMENT.md) for complete guide.
 
 ### Development and Testing
 ```bash
 npm start                    # Start MCP server (requires stdin)
-npm test                     # Run 551 tests across 26 suites
+npm test                     # Run 1028 tests
 ./scripts/validate.sh        # Syntax + startup check
 node --check src/index.js    # JavaScript syntax only
 ```
@@ -204,10 +204,25 @@ claude mcp add ssh-manager node /absolute/path/to/claude-code-ssh/src/index.js
 
 Configuration is stored in `~/.config/claude-code/claude_code_config.json`
 
+## Using the SSH Tools
+
+**For any server configured in this MCP server, use the `ssh_*` MCP tools — not raw `ssh`, `scp`, or `rsync` through the Bash tool.**
+
+The 13 v4 tools (`ssh_run`, `ssh_file`, `ssh_find`, `ssh_logs`, `ssh_service`, `ssh_health`, `ssh_db`, `ssh_backup`, `ssh_session`, `ssh_net`, `ssh_docker`, `ssh_fleet`, `ssh_plan`) are not a read-only convenience layer — they are the intended way to operate the fleet. Reach for them first.
+
+Why they beat raw `ssh` in Bash:
+
+- **Connection pooling** — the MCP server holds persistent SSH connections, so there is no per-call handshake. Raw `ssh` in Bash reconnects every single time.
+- **Bounded output** — results are compressed and head+tail truncated, so a noisy command (`journalctl`, `ps`, a 100k-line log) will not flood the context window. Raw `ssh` dumps everything.
+- **Credential handling** — passwords and sudo passwords are passed via stdin or env, never leaked on the argv of a `ps`-visible process. Raw `ssh` with an inline password is exposed.
+- **Structured results** — per-segment exit codes for command chains, typed service/health snapshots, SFTP transfers with sha256 verification. Raw `ssh` gives an unstructured terminal dump.
+
+Raw `ssh` through Bash is acceptable only for a host that is **not** in the MCP configuration. Run `ssh_fleet action: servers` to see which servers are configured.
+
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **claude-code-ssh** (1340 symbols, 3668 relationships, 111 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **claude-code-ssh** (1341 symbols, 3675 relationships, 111 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

README.md

@@ -103,7 +103,7 @@ flowchart LR
     C[Claude Code]
   end
   subgraph mcp["claude-code-ssh (MCP server)"]
-    T[51 typed tools]
+    T[13 verb-tools]
     P[ssh2 connection pool]
     O[head+tail output]
     T --> P
@@ -121,9 +121,9 @@ flowchart LR
   B --> H1
 ```
 
-- **51 typed tools across 7 groups** — shell, files, databases, backups, deploys, tunnels, sessions. Claude picks; you never enumerate.
+- **13 fat verb-tools** — one per domain (run, files, logs, db, docker, services, ...), each with an action enum. Claude picks; you never enumerate.
 - **Pooled connections** — 30-minute idle timeout. Reconnects cost zero.
-- **Opt-in per group** — minimal mode (5 tools, ~3.5k tokens) to full mode (51 tools, ~43k tokens).
+- **Always loaded** — the 13-tool schema is small enough (~5k tokens) to stay un-deferred. No per-group opt-in to manage.
 
 ## Install
 
@@ -224,8 +224,8 @@ Claude already has a bash tool. Why this server?
 | Sudo password handling | argv / `echo pwd \| sudo -S` (leaks to `ps`) | stdin only, never argv |
 | DB query safety | Claude can send `DROP TABLE` | token-level SQL parser, SELECT only |
 | Host key verification | TOFU by default, no MITM check | SHA256 fingerprint match, strict mode available |
-| Tool surface | 1 generic shell exec | 51 typed tools with JSON schemas |
-| Context cost | unbounded per command | ~3.5k tokens minimal mode, ~43k full |
+| Tool surface | 1 generic shell exec | 13 verb-tools with JSON schemas |
+| Context cost | unbounded per command | ~5k tokens, always loaded |
 
 The pitch isn't "Claude couldn't SSH before." The pitch is "Claude could SSH, but badly — and one bad command on prod is one too many."
 
@@ -241,7 +241,7 @@ What this doesn't do, today, honestly:
 ## Testing
 
 ```bash
-npm test       # 551 tests across 26 suites
+npm test       # 1031 tests
 ```
 
 ## Layout

docs/TOOL_MANAGEMENT.md

@@ -2,33 +2,18 @@
 
 ## Overview
 
-claude-code-ssh provides **37 tools** organized into **6 functional groups**. You can enable or disable tool groups to customize your experience and reduce context usage in Claude Code.
-
-### Why Manage Tools?
-
-- **Reduce Context Usage**: By default, all 37 tools consume ~43.5k tokens in Claude Code. Minimal mode uses only ~3.5k tokens (92% reduction)
-- **Fewer Approval Prompts**: Only enabled tools require approval in Claude Code
-- **Faster Loading**: Less tools mean faster MCP server startup
-- **Cleaner Interface**: Only see the tools you actually use
-
-## Quick Start
-
-### View Current Configuration
-
-```bash
-ssh-manager tools list
-```
-
-### Interactive Configuration Wizard
-
-```bash
-ssh-manager tools configure
-```
-
-Choose from three modes:
-1. **All tools** (37 tools) - Full feature set, recommended for most users
-2. **Minimal** (5 tools) - Only core operations, maximum efficiency
-3. **Custom** - Pick which groups to enable
+> **v4 update:** the v4 surface is **13 fat verb-tools**, always loaded. The
+> per-group enable/disable model described below belonged to the v3 51-tool
+> surface and no longer applies — there are no tool *groups* in v4. The 13
+> tools serialize to roughly 5k schema tokens, small enough that Claude Code
+> keeps them loaded without `ToolSearch`. This guide is retained for historical
+> reference; the `ssh-manager tools` CLI subcommands are deprecated.
+
+claude-code-ssh provides **13 tools**, each a verb-tool covering one domain
+through an `action` enum (`ssh_run`, `ssh_file`, `ssh_find`, `ssh_logs`,
+`ssh_service`, `ssh_health`, `ssh_db`, `ssh_backup`, `ssh_session`, `ssh_net`,
+`ssh_docker`, `ssh_fleet`, `ssh_plan`). All 13 are registered unconditionally —
+there is nothing to enable or disable.
 
 ### Enable/Disable Specific Groups
 
@@ -157,8 +142,8 @@ Advanced features for power users:
 }
 ```
 
-- **Enabled tools**: 37/37
-- **Context usage**: ~43.5k tokens
+- **Enabled tools**: the full v3 tool set
+- **Context usage**: the full v3 schema cost
 - **Best for**: Users who need all features
 
 ### Minimal Mode
@@ -198,7 +183,7 @@ Advanced features for power users:
 }
 ```
 
-- **Enabled tools**: Custom (5-37 tools)
+- **Enabled tools**: Custom (a hand-picked v3 subset)
 - **Context usage**: Varies based on selection
 - **Best for**: Tailoring to specific workflows
 
@@ -270,7 +255,7 @@ ssh-manager tools enable monitoring
 ssh-manager tools configure  # Choose "1) All tools"
 ```
 
-**Result**: 37 tools = ~43.5k tokens
+**Result**: the full v3 tool set loaded
 
 ### Scenario 3: Database Administrator
 
@@ -431,7 +416,7 @@ Add comments to your config file to remember why you enabled specific groups:
 
 ### Q: Will existing users see any changes?
 
-**A**: No. If no configuration file exists, all 37 tools are enabled by default (current behavior).
+**A**: No. Under the v3 model, with no configuration file every tool was enabled by default. The v4 surface is always fully loaded -- there is nothing to enable or disable.
 
 ### Q: Can I enable individual tools without enabling the whole group?
 
@@ -451,7 +436,7 @@ Add comments to your config file to remember why you enabled specific groups:
 
 ### Q: How much does minimal mode actually save?
 
-**A**: Minimal mode (5 tools) uses ~3.5k tokens vs all tools (37 tools) at ~43.5k tokens. That's a **92% reduction** or **~40k tokens saved**.
+**A**: Under the v3 model, minimal mode (5 tools) cut the schema cost sharply versus enabling the full tool set. This no longer applies -- the v4 surface is a flat 13-tool set, always loaded.
 
 ## Command Reference