@agmonetti/disambiguator

Zero-execution ambiguity gatekeeper for AI coding agents

Packages

Package details

extensionskill

Install @agmonetti/disambiguator from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@agmonetti/disambiguator
Package
@agmonetti/disambiguator
Version
1.2.0
Published
Nov 9, 2026
Downloads
365/mo · 239/wk
Author
agmonetti
License
MIT
Types
extension, skill
Size
18.4 MB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./pi-extension/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README


Why Disambiguator?

AI coding assistants frequently rush into execution when handed vague instructions like "make the UI look nice" or "refactor the backend". This leads to:

  • Wasted tokens rewriting files you didn't want touched
  • Hallucinated styling and unaligned architectural patterns
  • Silent drift and destructive unintended edits

Disambiguator acts as a zero-execution gatekeeper: it halts the model before any tool execution, groups ambiguities by category, and generates realistic multiple-choice suggestions (a/b/c/d) so you can answer with just a letter instead of writing essays.


Operating Modes

Mode Type A (Subjectivity) Type B (Scope) Type C (Context Assumptions)
strict (Default) Always halts Always halts Always halts
soft Always halts Halts only on high-risk/destructive actions Assumes safest standard, notes assumption, and proceeds
off No interception No interception No interception

Switching Modes at Runtime

Runtime behavior depends on the host surface:

  • Run /disambiguator soft to switch to soft mode.
  • Run /disambiguator strict to switch back to strict mode.
  • Run /disambiguator off to temporarily disable Disambiguator.
  • Run /disambiguator status to check the active mode.
  • Run /disambiguator with no argument to check the active mode.
Surface Persisted state Workspace writes Interaction cost
Pi extension Session journal plus ~/.config/disambiguator/mode None Local command handling; no model turn
Antigravity lifecycle hook ~/.config/disambiguator/mode None Hook-managed invocation
OpenCode plugin Isolated ~/.config/opencode/.disambiguator-active None Local command hook
disambiguator CLI ~/.config/disambiguator/mode Updates existing AGENTS.md and .agents/rules/disambiguator.md in consumer workspaces Shell command; no model turn
Prompt-only commands and skills Conversation memory only None Consumes a model turn and depends on that conversation retaining the selected mode

Running the CLI from this package's source checkout never rewrites generated rule files. A consumer workspace remains eligible for static-rule updates even if it has an unrelated scripts/sync.py.

Skill catalogs expose these five entries (optimized in v1.2.0 with dedicated, low-footprint skill instructions saving up to 95% tokens):

  • disambiguator: Loads the canonical gatekeeper instructions and ambiguity taxonomy.
  • disambiguator-strict: Switches to strict mode (halts on all Type A, B, and C ambiguities) with a lightweight, focused operational skill body (~200 tokens vs ~5,000 tokens in v1.1.0).
  • disambiguator-soft: Switches to soft mode (halts on Type A & high-risk Type B; auto-assumes safest standard for Type C & low-risk Type B) with a lightweight, focused operational skill body (~280 tokens vs ~5,000 tokens in v1.1.0).
  • disambiguator-off: Disables ambiguity interception (~220 tokens).
  • disambiguator-status: Reports the active mode (~150 tokens).

To change the permanent repository default, configure the top of system-prompt.md and run npm run sync:

# CONFIGURATION
# MODE: strict   <--- Change to "soft" to reduce interruptions

Install & Integration Tiers

Disambiguator operates across three integration tiers depending on your agent harness's architecture:

Tier 1: Native Plugin & Lifecycle Hooks (Zero-Token Runtime Switching)

Antigravity CLI (agy) & Antigravity IDE

agy plugin install https://github.com/agmonetti/disambiguator

(On legacy Gemini CLI: gemini extensions install https://github.com/agmonetti/disambiguator).

  • CLI Runtime Mode Switcher: Change the global mode without an LLM call. In consumer workspaces, the CLI also rewrites the # MODE: header in existing AGENTS.md and .agents/rules/disambiguator.md files:
    npx @agmonetti/disambiguator strict   # Enforce strict mode across ambiguities
    npx @agmonetti/disambiguator soft     # Set soft mode (assume safest for Type C)
    npx @agmonetti/disambiguator off      # Temporarily disable Disambiguator
    npx @agmonetti/disambiguator status   # View active mode
  • Antigravity Lifecycle Hook (hooks.json): Listens on PreInvocation, tracks slash commands (/disambiguator strict|soft|off), persists active mode, and injects ephemeral context notes.
  • Native Workspace Rules (.agents/rules/disambiguator.md): Automatically loaded by Antigravity CLI and IDE with zero setup in cloned repositories.
  • Marketplace Distribution: Manifested in .agents/plugins/marketplace.json for seamless Antigravity plugin marketplace discovery.

Pi Agent Harness

pi install git:github.com/agmonetti/disambiguator

(Or if running locally: pi -e ./pi-extension/index.js).

  • First-Class Slash Command: Direct /disambiguator [strict|soft|off|status] command with argument autocomplete in Pi's terminal dropdown.
  • Local Runtime Toggles: Pi handles mode commands without sending them to the model.
  • Session and Global Persistence: Persists mode switches in the Pi session journal and user configuration without writing a workspace state file.
  • Terminal Status Bar: Displays the live mode (● disambiguator: Strict / Soft) in the terminal footer.
  • Dynamic Prompt Hook: Injects or updates active mode directly on each turn via Pi's before_agent_start event.

Experimental Pi TUI V2 (V1 remains the default; verified on Pi 1.0.4 and 1.1.0): start with DISAMBIGUATOR_V2=1 pi -e ./pi-extension/index.js. Before editing, the model must call disambiguator_assess in a separate batch; clear or a TUI answer permits edit/write only in a later batch. A cancelled dialog never grants permission. Shell and unreviewed tools stay blocked even after assessment, and V2 offers no per-call approval for them: the block reason says so and points to /disambiguator off or V1, rather than naming a permission mechanism that does not exist. Decisions are journaled in the active session branch, but permissions are not restored after restart or branch navigation. Runtime abort revokes live permission; compaction requires reassessment, and that holds for automatic threshold compaction, for the cancelled case, and for overflow recovery with retry. Partial answers are journaled and unanswered questions cannot be skipped or rewritten by clear or reassessment. Within one assessment, scope and context questions (B, C) are asked before subjective styling (A); an unfinished phase holds the rest and releases no effects. The free-text limit counts per question, so exhausting one question does not restrict the others; after two free-text answers on the same question it is no longer offered and the question stays pending for an explicit a/b/c choice. Type A and high or unknown risk are never auto-resolved in any mode; in soft only low-risk B/C is assumed as a. A policy assumption requires a separate TUI confirmation of each exact edit/write call (up to 4000 characters of arguments); cancellation, absent UI, changed arguments, or journal failure blocks the operation. This is intentionally more restrictive than V1 soft. A detector's false clear or low classification is not an independent destructive-operation safeguard, and the per-question problem identity is deterministic, not semantic. RPC, context reduction, and pre-flight are not supported by this opt-in. Which model runs each test suite is documented in pi-extension/spikes/MODELS.md.

OpenCode

Add to opencode.json:

{ "plugin": ["@agmonetti/disambiguator"] }

Or run directly from a local repository checkout:

{ "plugin": ["./.opencode/plugins/disambiguator.mjs"] }
  • Transform Hook: Injects one Disambiguator ruleset when absent and rewrites the first # MODE: header in every preinjected Disambiguator prompt, including neutralization to off.
  • Skills Catalog: Registers all five skills (disambiguator, disambiguator-strict, disambiguator-soft, disambiguator-off, disambiguator-status).
  • Slash Commands: Exposes /disambiguator [strict|soft|status|off] and /disambiguator-help.
  • Isolated Persistence: Persists mode changes across sessions in ~/.config/opencode/.disambiguator-active.

Tier 2: Universal Rules & IDE Context (Always-On Workspace Gatekeeper)

OpenChamber & VS Code

OpenChamber and VS Code environments automatically discover and load AGENTS.md from your repository root with zero setup required. Drop AGENTS.md into your project root or clone this repository to activate Disambiguator immediately.

Dedicated Editor Rules (Copy & Paste)

For editor environments with dedicated instruction directories, copy the matching rule file from this repo:

Editor / Environment Target Path in Your Project Global Path
OpenChamber AGENTS.md —
Cursor .cursor/rules/disambiguator.mdc —
Codeium Windsurf .windsurf/rules/disambiguator.md —
Cline / Roo-Code .clinerules —
VS Code Copilot Chat .github/copilot-instructions.md ~/.copilot/copilot-instructions.md
Kiro .kiro/steering/disambiguator.md ~/.kiro/steering/disambiguator.md
Antigravity Workspace Rule .agents/rules/disambiguator.md ~/.gemini/config/

Zero-Setup Universal Context (AGENTS.md)

The following agents automatically discover and load AGENTS.md from your repository root:

  • OpenChamber, Amp (Sourcegraph), Jules (Google), JetBrains Junie, VS Code with Codex extension, Zed, Qoder.

Tier 3: Assisted Configuration & Skills Catalog

Claude Code

Install via plugin marketplace:

/plugin marketplace add agmonetti/disambiguator
/plugin install disambiguator@disambiguator

(You have to send two separate prompts for the install to work)

  • Slash Commands & Skills: Registers /disambiguator [strict|soft|status|off] and the full skills catalog.
  • Continuous Turn-by-Turn Protection: Claude Code plugins register on-demand commands. To enforce Disambiguator as an always-on continuous gatekeeper across all prompts in your workspace, add AGENTS.md or append Disambiguator instructions to CLAUDE.md (or ~/.claude/CLAUDE.md).

Aider

Configure Aider to automatically load Disambiguator rules on every session:

  • In .aider.conf.yml:
    read: [AGENTS.md]
  • Or pass via CLI:
    aider --read AGENTS.md

Universal Agent Skills (skills.sh / npx skills)

Works across 70+ AI coding agents automatically:

npx skills add agmonetti/disambiguator

To install globally across all workspaces on your machine:

npx skills add agmonetti/disambiguator -g

Other Supported Environments

  • Codex CLI: codex plugin marketplace add agmonetti/disambiguator && codex plugin add disambiguator@disambiguator
  • GitHub Copilot CLI: /plugin marketplace add agmonetti/disambiguator && /plugin install disambiguator@disambiguator
  • Devin CLI: devin plugins install agmonetti/disambiguator
  • Hermes Agent: hermes plugins install agmonetti/disambiguator --enable
  • Swival: swival skills add --global https://github.com/agmonetti/disambiguator && swival skills add disambiguator
  • OpenClaw: clawhub install disambiguator

Generic Web LLMs (ChatGPT, Claude Web, LibreChat, OpenWebUI)

  1. Open system-prompt.md.
  2. Copy the full content.
  3. Paste into the Custom Instructions, System Prompt, or Model Instructions field of your preferred interface.

Uninstall

Host Command
Claude Code /plugin remove disambiguator
Codex codex plugin remove disambiguator
Devin CLI devin plugins remove disambiguator
Pi agent pi uninstall disambiguator
Antigravity CLI agy plugin remove disambiguator
Agent Skills npx skills remove disambiguator
OpenClaw clawhub uninstall disambiguator
Cursor / Windsurf / Cline / OpenChamber / etc. Delete the copied rule file

How It Works in Practice

Ambiguity Taxonomy

  • Type A — Pure Subjectivity: Unmeasurable adjectives ("clean", "modern", "elegant", "faster").
  • Type B — Undefined Scope: Unbounded targets or open-ended verbs ("fix the UI", "refactor the code", "clean up tests").
  • Type C — Missing Context: Unspecified dependencies, stacks, or target files when multiple valid choices exist.

Example Interaction

User:

"Update the landing page UI so it looks clean and modern."

Disambiguator Response:

Before proceeding, I found 3 items to clarify:

1. **"the landing page UI"** (Type B — Undefined Scope) — The page contains multiple independent sections.

   - **a)** The entire page (Hero, Features, Pricing, and Footer)
   - **b)** Header and Hero section only
   - **c)** Content and conversion sections (Features and CTA)
   - **d) Other** — (specify target sections)

2. **"clean"** (Type A — Pure Subjectivity) — No measurable aesthetic standard was provided.

   - **a)** Minimalist layout with generous whitespace and high-contrast typography
   - **b)** Subtle borders, soft background tones, and reduced element density
   - **c)** Structured corporate layout with clear grid dividers
   - **d) Other** — (describe your preferred style)

3. **"modern"** (Type A — Unspecified Reference) — No design reference was specified.

   - **a)** Linear / Vercel style (subtle dark theme, fine borders, monochrome accents)
   - **b)** Glassmorphism with soft gradients and rounded corners
   - **c)** Geometric flat design with crisp edges
   - **d) Other** — (share a reference URL or design guideline)

Reply with your selected options (e.g., 1a, 2b, 3a) or describe your preferences to proceed.

Edge Case Protocols

Disambiguator includes a prioritized 10-point robustness protocol to prevent deadlocks and maintain user trust:

  1. "Just assume" override: Maps to the safest, most conservative option (option a), states it explicitly in one line, and proceeds immediately without further questions.
  2. Chained ambiguities (2-round limit): Imposes a hard limit of two clarification rounds. Round 1 presents primary ambiguities; Round 2 resolves any direct followup ambiguity. If ambiguity remains after Round 2, the safest conservative choice is applied with an explicit declaration.
  3. Mid-clarification cancellation & partial answers: If a user answers only one question and requests immediate action, unaddressed Type B/C items apply safe fallbacks with a 1-line declaration, while unaddressed Type A (subjectivity) items halt again to request the missing criterion.
  4. Pseudo-technical buzzword blacklist: Generic terms like "clean code", "best practices", "enterprise-grade", and "scalable" are treated as Type A subjectivity unless grounded in concrete standards.
  5. Nested ambiguity deconstruction: When an instruction relies on a relative comparison anchored to an undefined baseline ("more professional than the current version"), it separates the baseline from the target criteria into a single coordinated item.
  6. Overload triage (Phase 1 vs. Phase 2): When 4 or more ambiguities arise, core architectural choices are grouped into Phase 1 (max 3 questions), deferring visual styling and micro-details to Phase 2.
  7. Scope shift recognition: When a user's clarifying response expands scope (e.g., "actually redesign the entire auth flow"), it is recognized as a new request rather than an answer, resetting analysis without loops.
  8. Conversational silence & implicit prompts: When an asset (snippet, stack trace, image) is shared without an explicit action verb, Disambiguator prompts for the user's intent first rather than hallucinating options.
  9. Mixed prompts / partial stops (deterministic core + ambiguous expansion): When an instruction pairs an unambiguous command with an ambiguous goal, Disambiguator lists the deterministic segment as pending without tools, code, or diff output, then clarifies only the ambiguous remainder.
  10. Operational mode interactions (strict, soft, off): In strict mode, edge cases enforce halting on all ambiguity types; in soft mode, Type C and localized low-risk Type B adopt Option a automatically with a 1-line notice, reserving halts exclusively for Type A and high-risk destructive actions.

Automated Test Runner & Benchmarks

Disambiguator provides both an instant offline test suite and a standardized multi-provider LLM-as-a-judge evaluation harness.

1. Instant Offline Test Suite (< 50ms)

Validates parser schema, YAML assertion integrity, generated-path completeness, hook parity, and package-version parity using Python's standard library:

python3 -m unittest discover -v -s tests

# or execute both Python and Node test suites together:
npm test

2. Multi-Provider Automated LLM Runner

Evaluates the cases in tests/test-cases.md through a target model and grades compliance using an LLM judge (tests/runner.py).

  • Zero Mandatory Dependencies: Built entirely on Python standard library modules (urllib, json, re, pathlib, unittest).
  • Provider Support: Native REST drivers for Google Gemini and Anthropic Claude, plus OpenAI-compatible routing for openai, ollama, groq, deepseek, openrouter, and vllm. The hosted aliases require an explicit OPENAI_BASE_URL; openai and ollama retain safe defaults.
  • Mode-Aware Cases: Every test block declares Mode: strict|soft|off; the runner rewrites only the canonical # MODE: header for that case.
  • Machine-Evaluable Assertions: Every case declares exactly contains_question, min_questions, no_code_executed, ambiguity_types_flagged, proceeds_directly, aviso_emitido, and partial_stop. Every expected ambiguity type is mandatory.
  • Fail-Closed Results: PASS means every expected assertion was returned and passed; FAIL means semantic evaluation completed but an assertion failed or the judge result was malformed; ERROR records transport/model failure without fabricated assertion verdicts.
  • Provenance: Each local result payload includes system_prompt_sha256 and test_cases_sha256, plus case mode and model identifiers.

Running the Test Suite Locally

Configure environment variables in a .env file or export them directly:

# Example 1: Run with Google Gemini (default)
GEMINI_API_KEY="your-api-key" python3 tests/runner.py

# Example 2: Run with local Ollama (zero API costs)
PROVIDER=ollama OPENAI_BASE_URL=http://localhost:11434/v1 TEST_MODEL=llama3.2 python3 tests/runner.py

# Example 3: Run with OpenAI
PROVIDER=openai OPENAI_API_KEY="sk-..." TEST_MODEL=gpt-4o-mini python3 tests/runner.py

# Example 4: Run with Anthropic Claude
PROVIDER=anthropic ANTHROPIC_API_KEY="sk-ant-..." python3 tests/runner.py

The runner writes an ignored local results.json with per-assertion verdicts, PASS/FAIL/ERROR summaries, judge reasoning, and provenance hashes. Generated benchmark output is not tracked in the repository.


Design Decisions & Limitations

  • Cognitive Gatekeeper vs. Tool Execution: Disambiguator evaluates intent, gatekeeping rules, and ambiguity taxonomy. In agentic hosts with modification tools, deterministic requests execute through those tools. Surfaces without tools return complete code or diffs rather than claiming future execution.
  • Decoupled Code Output in Partial Stops: In mixed prompts, the deterministic segment is identified and listed as pending; tools, code, and diffs remain deferred until the ambiguous segment is resolved.
  • Language Adaptation: Prompts are matched dynamically. Spanish user prompts yield Spanish clarifying options; English prompts yield English options. No separate localized prompt files are required.

Maintainers & Anti-Drift Architecture

Disambiguator maintains strict parity across the generated target set (AGENTS.md, SKILL.md, editor rules, skills, commands, OpenCode commands, and both hook manifests). package.json supplies generated skill versions; system-prompt.md supplies canonical instructions.

The single canonical source of truth is always system-prompt.md.

# Synchronize all adapters after editing system-prompt.md
python3 scripts/sync.py

# Verify parity in CI or locally (fails with code 1 if drift is detected)
python3 scripts/sync.py --check

Continuous integration runs .github/workflows/sync-check.yml on every pull request to enforce zero drift.


License

MIT License. Free for personal and commercial use.