feat: per-server SSH agent forwarding (ForwardAgent)

[bvisible]

Summary

Implements per-server SSH agent forwarding (the equivalent of OpenSSH's ForwardAgent yes), as requested in #52 by @raphaelbahat. Processes on the remote host can authenticate to other SSH hosts using the keys in the operator's local ssh-agent — e.g. git clone over SSH on a remote server using a local GitHub key — without copying any private key to the server.

Thanks @raphaelbahat for the exceptionally well-researched issue (accurate code citations, correct security note, right implementation location).

Changes

• src/config-loader.js — read the new option from both formats into a camelCase forwardAgent field, and emit it from exportToToml():
  • .env: SSH_SERVER_<NAME>_FORWARD_AGENT=true
  • TOML: forward_agent = true
  • A new parseBool() helper coerces the value. This matters: in .env every value is a string, so a naive read would make FORWARD_AGENT=false truthy. parseBool treats only true/1/yes/on as true; false/absent/empty → false.
• src/ssh-manager.js — set connConfig.agentForward = true only inside the existing if (process.env.SSH_AUTH_SOCK) block. ssh2 throws ("You must set a valid agent path to allow agent forwarding") if agentForward is set without a valid agent, so nesting it guarantees that can't happen.

Why no per-command change is needed

The MCP tools run commands via SSHManager.execCommand() → client.exec(cmd, cb) with no per-channel options. I verified against the installed ssh2 1.17.0 (lib/client.js:1221) that the agent-forward channel request fires when this.config.allowAgentFwd === true OR the per-exec opts.agentForward === true. The connection-level option (agentForward: true → allowAgentFwd) therefore forwards on every exec/shell channel automatically. Setting it once at connect is sufficient.

Security

Opt-in, defaults to false. Documented in README (new SSH Agent Forwarding section) and CLAUDE.md with the standard warning: anyone with root on the remote host can use the forwarded socket to impersonate the operator for the life of the connection — mirroring ssh_config(5)'s ForwardAgent caution. No new files, no prompts, no behaviour change for existing configs.

Tests / verification

• tests/test-agent-forward.js (new, npm run test:agentforward) — drives connect() with a stubbed ssh2 client and asserts the wiring across four states: forwarding on (agentForward set), explicitly off, absent (default off), and the critical forwardAgent:true but no SSH_AUTH_SOCK case where neither agent nor agentForward is set (so ssh2 never throws).
• tests/test-config-field-names.js — extended to cover forwardAgent for both .env and TOML, the boolean coercion (incl. false → false), and a TOML export→reload round-trip.
• Full suite green locally: npm test ✅ · ./scripts/validate.sh ✅ · npx knip ✅ · npx eslint src/ 0 errors.

Closes #52