SWAT+ Investigator

Recorded, evidence-gated SWAT+ investigations for VS Code agent mode.

The extension registers one MCP server, swat-investigator, and a Copilot agent of the same name. The server's investigation_* tools let your assistant work through an investigation:

1. create it from a config file;
2. inspect the dataset and the source;
3. check file.cio before any run;
4. run SWAT+ in an isolated copy of the dataset;
5. validate the outputs;
6. assess claims and write a report.

Every action is journaled. Conclusions are capped by deterministic evidence gates, not by the assistant's wording, and the report can be rebuilt from the saved records without any model or network.

It works best together with the other SWAT+ Tools:

• SWAT+ Dataset Selector inspects the dataset and preflights file.cio.
• Fortran Debug (ifx / gfortran) provides owned debug sessions for runtime observations.

Getting started

1. Have Python 3.11 or newer installed.
2. The first time the server starts, the extension builds a private Python environment and installs its bundled agent into it. This downloads the agent's dependencies from PyPI once and never touches your own Python environments. SWAT+ Investigator: Set Up or Repair Python Runtime does this on demand.
3. Once per workspace, run SWAT+ Investigator: Set Up Workspace Defaults…. Pick the SWAT+ builds you use, and optionally the source tree they come from.
4. In Copilot Chat, start a new chat and pick swat-investigator from the agent dropdown. Ask in plain words, for example "Investigate why reservoir res17 releases no water, using the dataset in datasets/Osu_1hru."
5. The assistant drafts the config and VS Code asks "Start this SWAT+ investigation?", showing what will run. Nothing runs until you approve.

Prefer forms to chat? SWAT+ Investigator: New Investigation… asks four questions, produces the same approved draft, and puts a ready prompt on your clipboard.

How approval works

The config pins exactly what is tested: the dataset, the SWAT+ build, the source and the output checks. That is what makes the result reproducible proof. You never write it; you only approve it.

Approving signs the draft's exact bytes with a key that only this editor session and the server it started know. The server refuses to create an investigation from a draft that was not signed, or that changed after approval. Each report says how its config was approved:

• editor_dialog: you approved it in this dialog;
• client_reported: another client, such as Claude Code, reported your approval;
• hand_written: the config did not come from a draft.

Experiments

To test what changed inputs would do, ask for it in plain words, for example "Run the dataset again with days_mat written as whole numbers." The assistant makes a variant: a recorded, read-only copy of the inputs with exactly those edits. Your dataset is never modified. What a variant run shows is reported as an experiment_outcome about that variant, never as a fact about the original dataset.

Why use the swat-investigator agent

The agent sees only the investigation tools. Your other tools stay on for every other chat. Without the agent, a typical setup sends Copilot hundreds of tools at once, and two things go wrong:

• Copilot hits its 128-tool limit, or VS Code tucks some tools behind placeholders that the model may not open, including the one that records observations.
• The assistant can work around the investigation: it can run SWAT+ or read files itself. Those actions are not recorded, so their conclusions cannot count. If they touch the dataset, the report warns about it at the top.

Use VS Code's own local chat agent. New chats may default to the Copilot CLI harness (the session-type chip under the chat box), which this release has not yet been verified with.

Settings

Updates

Each release bundles the matching agent. When VS Code updates the extension, the runtime is rebuilt from the new wheel the next time the server starts.