feat: Agent phase-0 enhancements + review/login hardening

AGENTS.md

@@ -54,6 +54,55 @@ subagents, skills, web/visualization UIs, and multi-provider LLM authentication.
   Context7 MCP documentation lookups and targeted web search to verify the latest updates, APIs,
   CI/GitHub Actions behavior, dependency guidance, and best practices relevant to the task.
 
+## Global invariants and tripwires
+
+Always-on, tracked safety and truthfulness invariants — promoted here from the local
+`AGENTS.local` contract so they apply on a fresh clone and in CI, not only where a local file
+exists. They complement the rules above; the full contract, defensive patterns (P1–P7), and PR
+template live in `AGENTS.local` when present.
+
+### Failure truthfulness contract
+
+Observable output must reflect whether an operation succeeded, failed, partially succeeded, or
+degraded.
+
+- Never return success / `true` / `ok` / empty after a required internal step failed; never
+  report healthy when a required dependency is down; never continue startup past a critical
+  initialization failure.
+- Use explicit error contracts that distinguish no-data, invalid input, unauthenticated,
+  unauthorized, forbidden, conflict, timeout, dependency-unavailable, partial failure, and
+  internal error. Prefer typed results, domain exceptions, or status enums over ambiguous
+  `None`/empty/`False` returns. Convert errors at boundaries, not deep in domain logic.
+- Fallbacks are explicit decisions: degraded, stale, estimated, cached, or partial output must
+  carry source/status and be logged — and must never feed authorization or security decisions.
+  Security, approval, signature, and idempotency uncertainty fail closed.
+
+### AI-risk audit tripwires (C01–C15)
+
+Reject or flag for human review any change that exhibits:
+
+- **C01** success returned after a critical internal failure.
+- **C02** silent drop of audit, telemetry, transaction, or security evidence.
+- **C03** broad `except`/catch that swallows errors without logging, recovery, rethrow, or typed conversion.
+- **C04** scattered fallback values that hide dependency failures or weaken guarantees.
+- **C05** hidden flags, debug routes, local shortcuts, or backdoors past auth/validation/limits/audit.
+- **C06** returns that blur no-data, failure, denial, and partial success.
+- **C07** duplicate business-logic paths that can diverge from the primary rule.
+- **C08** background tasks/threads/queues without lifecycle, cancellation, error handling, timeout, and observability.
+- **C09** safety disabled on an environment flag unless narrow, documented, tested, and impossible in production.
+- **C10** startup that continues after critical init failure, or readiness that ignores required-dependency health.
+- **C11** non-determinism in execution-critical paths (unseeded randomness, floating temperature, wall-clock-dependent decisions).
+- **C12** missing source-to-output lineage for outbound payloads, persisted records, and audit events.
+- **C13** degraded/estimated/stale/fallback output presented as authoritative.
+- **C14** tests covering only happy paths — ignoring failure, security, edge, concurrency, and malformed-input cases.
+- **C15** retries around writes without proven idempotency (keys, constraints, dedupe records, atomic operations).
+
+In this codebase the most load-bearing instances are: approvals fail closed and are never
+bypassed (`soul/approval.py`); untrusted content is wrapped/neutralized before the prompt
+(`utils/trust.py`); hooks fail open by design *except* that a `PreToolUse` block result is
+never discarded; background workers must define lifecycle and recovery; and tool/LLM output is
+validated, never trusted.
+
 ## Simplicity and scope discipline
 
 - Before implementing, identify the Minimum Viable Change: the smallest code delta that solves the
@@ -159,14 +208,24 @@ instead of claiming success.
 
 ## Repo map
 
+For the full per-subsystem routing index (entry points, key interfaces, trust boundaries),
+see `docs/en/customization/architecture.md`. This list is a quick orientation only.
+
 - `src/pythinker_code/agents/`: built-in YAML agent specs and prompt files.
 - `src/pythinker_code/auth/`: OAuth/API-key provider integrations.
 - `src/pythinker_code/background/`: background task worker/runtime support.
-- `src/pythinker_code/cli/`: Typer command tree, including MCP, plugin, web, vis, info, export,
-  and terminal commands.
+- `src/pythinker_code/cli/`: Typer command tree (lazy-loaded subcommands `mcp`, `plugin`,
+  `skill`, `web`, `vis`, `info`, `export`, `review`, `secscan`, `security-scan`, `debug`,
+  `update`, plus eager `login`, `logout`, `term`, `acp`).
 - `src/pythinker_code/hooks/`: hook definitions and execution engine.
 - `src/pythinker_code/plugin/`: plugin discovery and installation support.
-- `src/pythinker_code/prompts/`: shared prompt templates.
+- `src/pythinker_code/prompts/`: shared prompt templates (`INIT`, `COMPACT`).
+- `src/pythinker_code/telemetry/`, `src/pythinker_code/notifications/`: opt-out telemetry
+  (OTel + Sentry) and the claim/ack/recover notification delivery queue.
+- `src/pythinker_code/memory/`, `src/pythinker_code/approval_runtime/`,
+  `src/pythinker_code/wire/`, `src/pythinker_code/utils/`: recall/consolidation, the pending-
+  approval source of truth, the Wire event protocol, and shared security-relevant helpers.
+- `src/pythinker_code/deps/`: build-time `Makefile` target that vendors the ripgrep binary.
 - `src/pythinker_code/skill/`, `src/pythinker_code/skills/`: skill discovery, loading, bundled
   skills, and flow-skill support.
 - `src/pythinker_code/soul/`: core runtime loop, context, compaction, approvals, slash commands.
@@ -233,7 +292,9 @@ from the active model, not from a hard-coded list.
 
 - **Supported providers** (`src/pythinker_code/auth/`): `openai` (API + ChatGPT OAuth),
   `anthropic_direct` (API + Anthropic OAuth), `opencode_go` (OAuth), `minimax` (OAuth),
-  `deepseek` (API key), `openrouter` (API key).
+  `deepseek` (API key), `openrouter` (API key), plus `z_ai`, `alibaba`, `moonshot`,
+  `lm_studio`, `ollama` (local), and `github_feedback`. Derive the provider from the active
+  model; never hard-code the list.
 - **Shared token store / refresh**: `OAuthManager` in `src/pythinker_code/auth/oauth.py`.
 - **Platform registry**: `src/pythinker_code/auth/platforms.py` defines `Platform` records and key
   conventions:
@@ -287,12 +348,18 @@ everything sequentially.
 - **Parallelize independent work**: batch unrelated reads/searches/checks in one turn. If an
   investigation needs more than a few tool calls, launch multiple `explore` subagents concurrently
   and synthesize their findings before editing.
-- **Use role-specific subagents**:
+- **Use role-specific subagents** (12 built-ins registered in
+  `src/pythinker_code/agents/default/agent.yaml`):
   - `explore`: read-only mapping, call-site discovery, architecture reconnaissance.
-  - `plan`: evidence-backed implementation strategy and trade-offs.
+  - `scout`: read-only, breadth-first fan-out reconnaissance over many files at once.
+  - `plan` / `planner`: evidence-backed implementation strategy; `planner` decomposes a task
+    into distinct parallel seeds.
   - `coder`: general software-engineering work when the brief still needs judgment.
   - `implementer`: tightly scoped edits from a concrete brief; no drive-by refactors.
-  - `review`: severity-scored read-only critique with suggested fixes.
+  - `debugger`: failure/log/stack-trace root-cause analysis with reproduction evidence.
+  - `review` / `code-reviewer`: severity-scored read-only critique with suggested fixes
+    (`code-reviewer` is diff-focused).
+  - `security-reviewer`: read-only security critique.
   - `verifier`: run tests/lint/build gates and report PASS / FAIL / FLAKY without fixing.
   - `judge`: independent final quality gate for non-trivial code changes, reports, and findings.
 - **Steer with complete prompts**: new subagents do not inherit the full parent transcript by

CHANGELOG.md

@@ -17,6 +17,11 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 - **Refreshed TUI theme and Catppuccin syntax highlighting.** The interface adopts a brand periwinkle/indigo accent (`#B3B9F4` dark / `#0B114E` light) with a reharmonized selection tint, and code blocks now highlight with Catppuccin Mocha (dark) / Latte (light), adaptive to the active theme — implemented as foreground-only Pygments styles with no new dependency. Markdown inline code and links render terminal-native cyan, blockquotes green, and ordered-list markers bright blue (so they adapt per terminal), and user messages sit on a neutral grey block instead of the prior blue tint.
 - **Homebrew updater no longer no-ops or false-reports success.** `pythinker update` on a Homebrew install now runs `brew update` to refresh the tap before `brew upgrade`, so a stale local tap clone can't pin the old formula and silently no-op ("0.37.0 already installed"). After upgrading it re-checks the installed version via `brew list --versions` and reports a clear failure instead of "Updated successfully!" when the version did not actually advance.
+- **Friendlier usage-limit (429) messages and ChatGPT account switching.** When a provider returns a 429, Pythinker now renders a human-readable notice — the plan name, the reset window, and a dimmed `Server:` detail line (all markup-escaped) — instead of a raw error string. `/login` for ChatGPT now uses `prompt=login`, so you can switch between ChatGPT accounts instead of being silently kept on the previous session.
+- **Agent phase-0 enhancements.** Adds a model-invocable cross-session Recall tool (search and read prior sessions on demand, sanitized and read-only for subagents), read-only MCP resources/prompts surfaced as tools, project-scoped `.pythinker/mcp.json` layering, subagent token/cost roll-up to the orchestrator, and truncated tool output that spills to disk with a recovery hint instead of being lost.
+- **No more spurious `coroutine … was never awaited` warnings.** Dropped Sentry's `AsyncioIntegration`, whose `create_task` monkeypatch wrapped every coroutine and — when a task was cancelled before its first step during turn/prompt teardown — orphaned the inner coroutine, printing `WireUISide.receive` and prompt_toolkit "never awaited" `RuntimeWarning`s to the console. The integration added no spans (tracing/profiling are off), and exception capture for async tasks is preserved by the existing asyncio exception handler.
+- **Read-only profile guard hardened against version-pinned interpreters.** Inline-code interpreter invocations that use a version-suffixed or absolute binary (`python3.14 -c …`, `/usr/bin/python3.12 -c …`, `node20 -e …`) are now classified as mutating/destructive just like the bare `python`/`node` forms, so they can no longer bypass a read-only subagent profile or skip destructive deliberation.
+- **The agent sets up and removes MCP servers on request instead of refusing.** Asked to add, remove, or set up an MCP server, the default agent now knows it runs in Pythinker: it configures the server with the `pythinker mcp add`/`remove` CLI (or by editing `~/.pythinker/mcp.json` / `./.pythinker/mcp.json`), verifies with `pythinker mcp list`/`test`, and tells you to restart or `/reload` to load the change — rather than refusing or citing Claude Code/Desktop config paths (`~/.claude.json`) it cannot use. The prompt now also hard-steers the agent away from writing `mcpServers` into `~/.pythinker/config.yaml` (YAML is never parsed for MCP, so such an entry is silently dropped and the server never appears in `/mcp`). As a backstop, MCP config loading now logs a warning when it finds an `mcpServers` block in a `config.yaml` (global or project), so a human or agent that misplaces it gets a diagnosable trace instead of a silent drop.
 - **Security: dependency vulnerability remediation.** Cleared the open Dependabot advisories across all manifests. Python: `asyncssh` 2.22.0 → 2.23.0 (path-traversal in `AuthorizedKeysFile %u`) in the `pythinker-host` pin and both lockfiles, and `starlette` 1.0.0 → 1.2.1 (Host-header path poisoning). JS: regenerated the `web`, `vis`, and `install-counter-worker` lockfiles and bumped the worker's `vitest` to `^3.2.6` (critical Vitest UI arbitrary file read/exec), clearing all critical/high/moderate advisories. The only residual is a handful of low-severity transitive `elliptic`/`bn.js` advisories in `web`'s browser crypto polyfill chain, left unforced because the fix downgrades `vite-plugin-node-polyfills` and majors `ai`, breaking the build for marginal benefit.
 
 ## 0.38.0 (2026-06-08)

docs/.vitepress/config.ts

@@ -53,6 +53,7 @@ export default withMermaid(defineConfig({
                 { text: 'Agent Skills', link: '/en/customization/skills' },
                 { text: 'Agents and Subagents', link: '/en/customization/agents' },
                 { text: 'Agent Architecture', link: '/en/customization/agent-architecture' },
+                { text: 'Repository Map', link: '/en/customization/architecture' },
                 { text: 'Print Mode', link: '/en/customization/print-mode' },
                 { text: 'Wire Mode', link: '/en/customization/wire-mode' },
               ],