Noesis — Know When to Stop

AI coding agents are increasingly trusted to make real changes to real codebases. They refactor, clean up "unused" code, and fix what looks like a bug. But an agent reads code, not intent. A function with no direct callers looks safe to delete, even if it is invoked dynamically from a config file. A rounding calculation that looks like a mistake might exist because of a legal requirement explained only in a commit message from months ago. None of this is visible from the current code alone. Without a safeguard, an agent could edit anyway, breaking something that was working correctly on purpose. Noesis is a safety layer that sits between a change request and the actual edit. Instead of asking "can this be coded," it asks "does the agent actually know enough about this codebase to make this change safely." When a task comes in, a project rule forces the agent to run Noesis first. Noesis investigates using evidence the agent would not otherwise gather. It searches the codebase for indirect references, such as config files or string-based dynamic lookups. It reads git history for commit messages explaining non-obvious decisions. It finds files that consistently change together, revealing coupling invisible from reading one file at a time. From this evidence, Noesis builds a list of concrete unknowns, each with a severity. These are specific things that would make the change unsafe if guessed wrong. A critical unknown can only be resolved once it has at least two independent pieces of evidence, so a vague "this looks fine" is never enough. If unresolved critical unknowns remain, the agent is told exactly what to investigate next, down to the file and line. If, after repeated attempts, it still cannot resolve something, Noesis stops and asks a human, with the specific open question written out. Only once every critical unknown is backed by real evidence does it allow the edit to proceed. Even then, it lists remaining lower-severity concerns as guardrails to watch. After the edit, a drift check compares what actually changed against what was predicted. Our target users are development teams using AI coding agents on real, unfamiliar, or legacy codebases. This is exactly where an agent is most likely to miss context a careful engineer would have caught. Unlike generic caution prompts, Noesis requires cited, checkable evidence before allowing an edit, and it is honest about its own limits. Our own adversarial testing surfaced a real gap. It does not yet catch a hidden meaning encoded in a plain function argument, like a sentinel value. We documented this as future work rather than hiding it, because knowing where a safety tool's coverage ends is part of using it responsibly. We validated Noesis against a sandbox codebase built with deliberately planted, invisible-from-code traps. These include a config-driven dynamic dispatch, a commit explaining a legal-requirement calculation, and coupled files. Across our tests, it correctly triggered every decision path. It flagged the hidden dependency, refused insufficient evidence, resolved once real evidence was provided, proceeded with guardrails, and escalated to a human after repeated failed attempts. This turns "the agent might break something" from an invisible risk into a visible, investigable, and answerable question, before the edit happens, not after.