docs: move the agent tool docs to 4-implementation/agent-tools

docs/4-implementation/agent-tools/README.md

@@ -0,0 +1,32 @@
+# Agent tools
+
+The tool surface your **agents** get inside their containers (the MCP tools
+an agent's own claude session can call, plus the CLIs it shells out to).
+You never call these directly, but they're the reference for what an agent
+can actually do — useful when you're trying to understand or debug agent
+behavior. The operator's own tools are in
+[`2-handbook/tools/`](../../2-handbook/tools/README.md).
+
+## What your agents can do
+
+- **[bash](bash.md)** — background shell execution (`mcp__bash__*`),
+  available on every agent unconditionally.
+- **[subagent](subagent.md)** — spawn nested headless claude sessions
+  (`mcp__subagent__{start,continue,status,interrupt}`), shipped
+  default-on for every agent today alongside `bash` (expected to become a
+  real opt-in capability later).
+- **[forge](forge.md)** — the `hive-forge` Forgejo CLI every agent has
+  for issues, PRs, and comments. Not an MCP tool — a binary agents
+  shell out to instead of ad-hoc curl.
+- **[forge-cli](forge-cli.md)** — the exhaustive, autogenerated
+  flag-by-flag reference for `hive-forge`, kept in lockstep with the
+  binary by CI the same way `hivectl-cli.md` is.
+- **[swarm-logs-cli](swarm-logs-cli.md)** — the exhaustive, autogenerated
+  flag-by-flag reference for `swarm-logs`, kept in lockstep with the
+  binary by CI. No curated guide.
+- **[swarm-metrics-cli](swarm-metrics-cli.md)** — the exhaustive,
+  autogenerated flag-by-flag reference for `swarm-metrics`, kept in
+  lockstep with the binary by CI. No curated guide.
+- **[matrix](matrix.md)** — the matrix MCP tool surface
+  (`mcp__matrix__*`) for agents with a matrix account, multiple
+  accounts per agent, and declaring extra MCP servers generally.