Skip to content

feat: add server-side Thought-Aligner defense - #16

Merged
alexps9 merged 1 commit into
WhitzardAgent:mainfrom
jiangchangyue:main
Jul 20, 2026
Merged

feat: add server-side Thought-Aligner defense#16
alexps9 merged 1 commit into
WhitzardAgent:mainfrom
jiangchangyue:main

Conversation

@jiangchangyue

Copy link
Copy Markdown
Contributor

Summary

Adds an opt-in, server-side Thought-Aligner defense for Python agents.

The integration intercepts an agent model response before its action reaches the framework parser or tool executor, extracts the exposed instruction, current thought, and previous thought/observation history, and sends them to a configured Thought-Aligner endpoint. When the thought is rewritten, the Python client asks the original agent model to regenerate its Action and Action Input from the aligned thought.

This provides thought-level behavioral safety intervention while preserving the existing AgentGuard tool-policy enforcement path.

Thought-Aligner model card: https://huggingface.co/WhitzardAgent/Thought-Aligner-7B

Type of Change

  • Bug fix
  • New feature (framework adapter, plugin, policy capability, ...)
  • Breaking change
  • Documentation
  • CI / tooling / chore

Changes

  • Added the opt-in server-side thought_aligner plugin in the llm_after phase.
  • Added extraction and normalization for:
    • explicit normalized thought fields;
    • common reasoning aliases such as reasoning_content, reasoning, thinking, plan, and analysis;
    • <think>, <thought>, <reason>, <reasoning>, and <analysis> blocks;
    • ReAct-style Thought: output;
    • user instructions from metadata, messages, prompts, and LangChain-style inputs;
    • completed historical Thought/Observation pairs formatted with <thought> and <observation> markers.
  • Added an OpenAI-compatible Thought-Aligner client with dedicated server-side URL, API key, model, timeout, and context-size configuration.
  • Added Python client regeneration support:
    • holds the original LLM response before framework action parsing/execution;
    • injects the aligned thought into a copy of the original request;
    • invokes the original agent model once more to regenerate Action and Action Input;
    • returns only the regenerated response to the framework.
  • Added loop prevention so each LLM turn can be regenerated at most once.
  • Added fail-safe handling for unsupported or malformed alignment responses.
  • Preserved the existing tool_before policy path for regenerated actions.
  • Added an example plugin configuration:
    config/plugins.thought-aligner.example.json.
  • Added English and Chinese Thought-Aligner documentation.
  • Added regression tests for extraction, server transport, plugin decisions, synchronous/asynchronous regeneration, request immutability, unsupported clients, and loop prevention.

@jiangchangyue
jiangchangyue requested a review from a team as a code owner July 20, 2026 15:48
@jiangchangyue
jiangchangyue requested review from JSGforever and removed request for a team July 20, 2026 15:48
@github-actions

Copy link
Copy Markdown

🎉 Thanks for your first pull request to AgentGuard! A maintainer will review it soon. While you wait, please double-check the PR checklist and make sure ruff check src tests, pytest -q, and node --test pass locally — see CONTRIBUTING.md for details.

@github-actions github-actions Bot added documentation Improvements or additions to documentation python-client server tests labels Jul 20, 2026
@alexps9
alexps9 merged commit 4b755fb into WhitzardAgent:main Jul 20, 2026
12 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation python-client server tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants