pool: four run modes, and an Auto approval mode that delegates the risk call to a model

The same binary is a terminal app, a server, a client, and a one-shot

Pool describes itself as Poolside's coding agent and lists four ways it can run, which is the first thing to understand because the modes are not variations on one interface.

It runs in a terminal as a standalone interactive application, which is the default. It runs as an agent protocol server, so an editor can drive it. It runs as an agent protocol client, so it can drive another agent server instead of its own. And it runs non-interactively through a subcommand for scripts and pipelines.

That last pair is the interesting inversion. The same tool is on both sides of the same protocol, and the documentation is explicit about the consequence: when you connect to a different server, the available modes and the agent-side features depend on that server. Interactive features are listed with the caveat attached. Mid-turn steering is available when the connected server supports it. Renaming a session is available when the server supports it. If the other end does not support steering, your prompt simply waits for the next turn.

So the feature list you read is the feature list of the default agent, and connecting to something else changes the surface. That is stated in the opening rather than discovered later.

The interactive layer itself is a small set of conventions worth knowing: slash commands, an at-sign for fuzzy search over files and directories, a bang for shell mode, double escape to rewind to a previous message, and session management commands. Enter steers a running turn, control-enter queues for the next one where the terminal can tell the keys apart, and shell input waits for the current turn to finish.

Four approval modes, and one of them is a risk classifier you have to supply

The agent asks before tool actions that are not already allowed, and there are four settings, each with an identifier you can use in a command.

Always ask is the default and prompts for anything not already allowed. Accept edits auto-approves workspace file reads and writes, which is narrower than it sounds because it is scoped to the workspace. Auto classifies the remaining permission requests by risk. Allow all approves tool calls automatically.

You cycle through them with a shifted tab, or name one directly with a mode command.

Auto is the setting that needs work before it is useful, and the documentation is specific about that. It uses Accept edits as a baseline, so file reads and writes are already handled, and then it runs low-risk actions immediately, runs medium-risk ones with a notice, and opens the approval dialog for high-risk ones. The classification is done by a model, and that model is not supplied:

pool:
  auto_mode_classifier: <model-id>

That goes in a personal settings file under a vendor-named directory in your home rather than a dot directory named after the tool, which is worth knowing before you go looking for it. For a single run you can set the same choice through an environment variable when starting the agent, and an explicitly empty value turns Auto off for that invocation.

The documentation also says where to look for the details that matter: a separate permissions page covers the classifier's inputs, its behaviour on failure, and its safety constraints. Auto mode without that page read is a guess at what the risk tiers mean.

Plan mode is a review gate you cannot turn off from the command line

Build and Plan are described as controlling how the agent works without changing approval behaviour, which is a deliberate separation. Whether the agent edits files and whether the agent is permitted to is two different questions, and Plan mode only affects the first.

In Plan mode the agent can inspect your codebase and prepare a plan without modifying source files. You enter it after starting the agent with a slash command or an explicit agent-mode command, and return with the build variant.

Two details are worth more than the rest. There is no startup flag for Plan mode, so it cannot be baked into a shell alias or a project script and relied on as a guard. And returning from Plan to Build always requires your review, including when the approval mode is Allow all.

That second point is the interesting one, because it is a hard stop that a permissive approval setting does not bypass. If you have set the agent to Allow all and you expected Plan to be escapable automatically, it is not. The transition is one you have to make deliberately, every time, in every approval mode.

It is a small feature and it is a good one: it means the least dangerous configuration is still reachable without a ceremony, and the most dangerous configuration does not silently make Plan mode decorative.

Hooks run with no approval and fail open, and the documentation says so

Six lifecycle events can trigger shell commands: before and after tool use, on prompt submit, on stop, before compaction, and at session start. The set is broader than most agent hook systems expose, with the compaction and stop events being the two that tend to be missing.

What the hooks can do is equally broad. They can inspect or rewrite tool calls and prompts, block matching actions, inject context, and ask the agent to continue at the end of a turn. So this is not a notification mechanism, it is a programmable layer in the middle of the agent's decision path.

The security statement is the most important line in the section, and it is unambiguous. Hooks run automatically without an approval prompt. They fail open if they fail, if they time out, or if they return output the agent cannot parse. And they are explicitly not a security boundary. The instruction is to use permissions and sandboxes for enforced controls instead.

Fail open is the part to sit with. A hook that blocks a dangerous action will not block it if the hook crashes, if it takes too long, or if it prints something the agent cannot read. That is a deliberate trade for a mechanism that runs on every tool call, and it is the right trade, but it means a broken hook silently disables itself rather than failing loudly.

Configuration lives under a top-level key in the settings file, and a separate documentation page covers the configuration, the protocol details, examples, and the security guidance.

Subagents share a workspace, which is the conflict you have to plan around

A subagent configuration is the other place where the tool extends past what a single loop can do.

One subagent named general needs no configuration at all. It exists so the main agent can delegate a focused task to it, and the point is separate context: the delegated work does not pollute the parent's conversation. You ask the main agent to delegate, rather than invoking it directly.

Beyond that one, you can define named subagents that use custom instructions, another agent in the same process, or a command-based agent protocol server. So the delegation target is pluggable in the same way the top-level mode is.

The cost is stated directly. Subagents share the workspace, so parallel changes to the same files can conflict. There is no locking and no merge step described; the conflict is yours to avoid by not pointing two of them at the same file.

Usage is observable, which is the practical answer to that. A usage command shows the parent, each subagent, and the total, so you can see where a run's tokens went across the tree. The subagent documentation covers configuration, permissions, and the usage accounting in more detail.

The repository holds documentation, not the code

The top level of this repository contains four entries: a changelog, a licence file, the readme, and a directory for third-party material. There is no source directory, no build file, no test suite, and no recorded primary language.

That is worth stating plainly at the start, because the repository description reads like a project you can clone and build. What you can clone is the documentation. The actual agent is distributed as a binary through an install script:

curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh

with a separate script for Windows, which is marked as a preview rather than as supported. Updating is a command after you exit any active session, and the agent also prompts you at startup when it knows a newer version exists.

The split has a consequence for anyone auditing the tool. You can read every claim the documentation makes, and you can read the changelog, but the approval behaviour, the hook execution, and the risk classifier are all things you would have to inspect in the binary. For an agent that runs shell commands on request, that is a real difference from a tool whose source is public.

The documentation itself is organised as a manual rather than as a tutorial. The table of contents runs from install and quick start through approval modes, agent modes, hooks, subagents, spec support, the two protocol directions, the non-interactive mode, the three model provider sections, MCP servers, configuration, permissions, and a feedback section. That ordering tells you what the project considers important: the control surfaces come before the integrations.

Editorial conclusion

This suits someone who wants a coding agent that works in the terminal and in whichever editor already speaks the agent protocol, and who wants to control how much it acts without asking. It is a poor fit if you need the source, since the repository holds documentation and a changelog rather than a code tree, and a poor fit if you want the risk classifier to be your own model without extra configuration, because Auto mode needs a model identifier before it does anything. Before you install, check three things: which approval mode you actually want on a shared machine, since Allow all disables the prompt entirely; that you read the hooks section before enabling it, because hooks run with no approval and fail open, and the documentation is explicit that they are not a security boundary; and where your configuration lives, since the settings file path is under a vendor directory in your home rather than a dot directory named after the tool. The newest release is v1.0.16 from 2026-08-14 and the last push was 2026-08-18.

Frequently asked questions

Official sources

1. Issues
2. poolsideai/pool on GitHub
3. Project website
4. README
5. Releases