feat: agent harness enhancements

CHANGELOG.md

@@ -15,10 +15,22 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Adversarial branch review hardening.** A multi-agent review pass confirmed and fixed: committed-but-clean isolation worktrees are now retained (commits ahead of the creation base count as changes — they were previously orphaned on cleanup); foreground shell commands and relative-path file edits now resolve against the agent's work dir, so worktree isolation actually binds them (host exec gained a `cwd` argument); safe mode now also disables the read-only-command prompt elision; locally parallel-safe MCP/tools run in parallel in the same-step gate; worktree add/remove serializes per repo. Behavior notes: same-step tool calls without `supports_parallel` now serialize deterministically (previously fully concurrent), and text-mode error diagnostics moved to stderr — capture `2>&1` or use `--output-format stream-json` if you scraped stdout.
+- **The agent now knows its own permission posture.** A live permissions-state reminder renders the enforced profile, safe-mode/yolo/auto flags, mutation/network allowances, session-approved actions, and the shell gate's command-shaping rules — re-emitted exactly when the posture changes (/yolo, /auto, /trust, new approvals) instead of the model discovering policy through denied tool calls.
+- **Edits recover from whitespace and smart-punctuation drift.** StrReplaceFile no longer hard-fails with "old string not found" when the only mismatch is trailing whitespace, indentation, or smart quotes/dashes: a graduated line-window ladder relocates the edit, replaces the actual file slice (preserving CRLF endings), and names the relaxation it used in the tool message. Multiple fuzzy hits without replace_all still error, so ambiguity is never silently resolved.
+- **`isolation="worktree"` is now enforced for background write agents.** Previously it only recorded intent, so parallel coders shared one working tree and could clobber each other. A write-profile child now runs in its own git worktree of HEAD; its final report names the worktree path with a diff summary so changes merge deliberately, clean worktrees are removed, non-git roots fail with an actionable error, and read-profile children ignore the request.
+- **MCP servers can be scoped to specific tools.** Optional `enabledTools` (exclusive allowlist) and `disabledTools` (denylist, wins on conflict) arrays per server in `mcp.json` keep a noisy server from flooding the model's tool list — filtered tools are never registered, and a call-time re-check guards shared tool maps.
+- **A hung MCP server can no longer stall the whole session.** Server connects are bounded by a new `mcp.client.startup_timeout_ms` (default 30s) — previously a hung connect blocked every agent turn. `/mcp` now shows one actionable line per failed server (timeout → the config knob, 401 → the exact auth command, missing binary → the command path) instead of a bare "failed".
+- **Provably read-only commands no longer prompt for approval.** The first `ls` or `git status` of a session used to interrupt with an approval dialog. A tight positive allowlist (read-only binaries and git subcommands, with hidden-command, write-redirection, wrapper, and fake-path rejections, fail closed) now elides the prompt in the root agent; subagents keep requesting approval as their unattended defense surface, and deny-profile decisions are never overridden.
+- **Switching models keeps your conversation.** `/model` used to start a fresh session, discarding all context. The switch now seeds the new session with a plain-text summary written by the outgoing model (so provider-specific message formats never cross the boundary), falling back to the old fresh start if summarization fails; disable with `model_switch_carryover = false`.
+- **Typo'd config keys are no longer silently ignored.** Loading now diffs the merged config against the model schema and warns with the dotted path and originating scope file for every unrecognized key (`default_yolo_typo = true` names itself and its file instead of silently changing nothing); `PYTHINKER_STRICT_CONFIG=1` escalates the findings to a startup error for CI.
+- **Project-scope hooks now require trusting the project.** A cloned repository's `.pythinker/config.toml` could previously auto-execute its shell hooks at session start. Hooks from project and local scopes now load only after `/trust` records a durable per-project decision (stored user-side in `trusted_projects.json`, keyed by the resolved repo root); until then they are stripped with a warning naming the fix. Broken TOML in an untrusted project no longer blocks startup — the scope is treated as empty with a warning, while trusted projects keep the loud error.
+- **Agent orchestration guidance is sharper for substantial tasks.** The default prompt now sharpens work-shaping guidance, and a new root-only runtime reminder nudges substantial normal-mode tasks toward the lightest effective path — direct tools, `SetTodoList`, foreground `RunAgents`, or verification — while backing off for plan mode, `/goal`, auto mode, and subagents.
 - **The in-app updater recovers from Homebrew's untrusted-tap refusal.** Homebrew 5.0 (`HOMEBREW_REQUIRE_TAP_TRUST`) refuses to load formulas from third-party taps until `brew trust <tap>` is run once, which made the in-app `brew upgrade` fail with only a generic "run manually" hint. The updater now detects both the hard `Refusing to load … from untrusted tap` refusal and the soft `Skipping … not trusted` warning, offers to run `brew trust pythoughts-labs/pythinker` and retry the upgrade once on an interactive terminal, and otherwise prints the exact remediation. It also catches the silent no-op where an untrusted tap is skipped during `brew update` and `brew upgrade` exits 0 without advancing the version.
 - **Session exports redact secrets surfaced by tool output.** A tool result (e.g. `grep`/`cat` over a `.env`) could write a secret value into an exported transcript in plaintext. `/export` now redacts the value of secret-named keys (`password`, `token`, `api_key`, `secret`, …) to `[REDACTED]` in both the markdown and YAML formats, while leaving non-secret keys such as `token_count`, usernames, and ports intact.
 - **The welcome logo's antenna blinks a fixed number of times on launch, then settles.** Replaces the terminal's indefinite slow-blink with a bounded boot animation — the antenna ball blinks seven times after the banner prints and then holds steady. It is skipped under reduced motion, on non-interactive output, and when the terminal is too short to keep the antenna row on screen.
 - **Inline `/command` references get acted on, not just explained away.** When a message mentions a slash command mid-sentence (e.g. "your `/goal` today is to `/plan` and build the page"), the command doesn't auto-run — but the agent no longer leads its reply by reporting it as failed. The per-turn reminder and the system prompt now steer the agent to act on the intent: call the real `EnterPlanMode` tool for `/plan` (clarified as a genuine, callable tool so models stop doubting it exists), pursue the described objective for `/goal`, load `/skill:<name>` via `ReadSkill`, and apply equivalent guidance for other commands — only surfacing how to invoke the literal command when genuinely needed.
+- **The "thinking" shimmer no longer runs while a foreground command does.** When the agent started a long-running foreground process — a dev server via `npm`/`docker`, a watch task — the shimmering verb spinner ("Working…/Thinking…") kept animating for the whole turn, implying the agent was busy when it was really just awaiting the subprocess. The spinner is now suppressed while any foreground tool is mid-execution; the tool card's own animated running marker (and its streaming output) carries the liveness, so the shimmer means "the agent is thinking" again and reappears the moment the command returns.
 
 ## 0.41.0 (2026-06-11)
 

README.md

@@ -562,7 +562,7 @@ Pythinker loads [Model Context Protocol](https://modelcontextprotocol.io/) tools
 ### 🛠️ Manage persistent MCP servers
 
 ```sh
-# 📚 Context7 stdio server (Codex-style: NAME -- COMMAND)
+# 📚 Context7 stdio server (positional form: NAME -- COMMAND)
 pythinker mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR-API-KEY
 # Added MCP server 'context7' to ~/.pythinker/mcp.json
 

packages/pythinker-host/src/pythinker_host/__init__.py

@@ -220,14 +220,18 @@ async def mkdir(
         """Create a directory at the given path."""
         ...
 
-    async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostProcess:
+    async def exec(
+        self, *args: str, env: Mapping[str, str] | None = None, cwd: str | None = None
+    ) -> HostProcess:
         """
         Execute a command with arguments and return the running process.
 
         Args:
             *args: Command and its arguments.
             env: Environment variables for the subprocess. If None, inherits
                  from the parent process.
+            cwd: Working directory for the subprocess. If None, inherits the
+                 backend's current working directory (process cwd locally).
         """
         ...
 
@@ -347,8 +351,10 @@ async def mkdir(path: StrOrHostPath, parents: bool = False, exist_ok: bool = Fal
     return await get_current_host().mkdir(path, parents=parents, exist_ok=exist_ok)
 
 
-async def exec(*args: str, env: Mapping[str, str] | None = None) -> HostProcess:
-    return await get_current_host().exec(*args, env=env)
+async def exec(
+    *args: str, env: Mapping[str, str] | None = None, cwd: str | None = None
+) -> HostProcess:
+    return await get_current_host().exec(*args, env=env, cwd=cwd)
 
 
 from pythinker_host._current import current_host as current_host  # noqa: E402

packages/pythinker-host/src/pythinker_host/local.py

@@ -190,7 +190,9 @@ async def mkdir(
         local_path = path.unsafe_to_local_path() if isinstance(path, HostPath) else Path(path)
         await asyncio.to_thread(local_path.mkdir, parents=parents, exist_ok=exist_ok)
 
-    async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostProcess:
+    async def exec(
+        self, *args: str, env: Mapping[str, str] | None = None, cwd: str | None = None
+    ) -> HostProcess:
         if not args:
             raise ValueError("At least one argument (the program to execute) is required.")
 
@@ -208,6 +210,7 @@ async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostPr
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
             env=env,
+            cwd=cwd,
             **process_options,
         )
         return self.Process(process)

packages/pythinker-host/src/pythinker_host/ssh.py

@@ -303,7 +303,9 @@ async def mkdir(
                 raise FileExistsError(f"{path} already exists")
             await self._sftp.mkdir(str(path))
 
-    async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostProcess:
+    async def exec(
+        self, *args: str, env: Mapping[str, str] | None = None, cwd: str | None = None
+    ) -> HostProcess:
         if not args:
             raise ValueError("At least one argument (the program to execute) is required.")
         command = " ".join(shlex.quote(arg) for arg in args)
@@ -313,8 +315,15 @@ async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostPr
         #   cwd before running the command.
         #
         # This is intentionally strict: if cwd doesn't exist, the command fails.
-        if self._cwd:
-            command = f"cd {shlex.quote(self._cwd)} && {command}"
+        if cwd is None:
+            effective_cwd = self._cwd
+        elif posixpath.isabs(cwd):
+            effective_cwd = cwd
+        else:
+            base_cwd = self._cwd or "/"
+            effective_cwd = posixpath.normpath(posixpath.join(base_cwd, cwd))
+        if effective_cwd:
+            command = f"cd {shlex.quote(effective_cwd)} && {command}"
         process = await self._connection.create_process(command, encoding=None, env=env)
         return self.Process(process)
 

src/pythinker_code/acp/host.py

@@ -296,8 +296,10 @@ async def mkdir(
     ) -> None:
         await self._fallback.mkdir(path, parents=parents, exist_ok=exist_ok)
 
-    async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostProcess:
-        return await self._fallback.exec(*args, env=env)
+    async def exec(
+        self, *args: str, env: Mapping[str, str] | None = None, cwd: str | None = None
+    ) -> HostProcess:
+        return await self._fallback.exec(*args, env=env, cwd=cwd)
 
     def _abs_path(self, path: StrOrHostPath) -> str:
         host_path = path if isinstance(path, HostPath) else HostPath(path)

src/pythinker_code/acp/tools.py

@@ -10,6 +10,7 @@
 from pythinker_code.soul.approval import Approval
 from pythinker_code.soul.permission import check_shell_command_allowed
 from pythinker_code.soul.toolset import PythinkerToolset
+from pythinker_code.tools.ask_user import AskUserQuestion
 from pythinker_code.tools.shell import Params as ShellParams
 from pythinker_code.tools.shell import Shell
 from pythinker_code.tools.utils import ToolResultBuilder
@@ -28,6 +29,11 @@ def replace_tools(
         # Only replace tools when running locally or under ACPHost.
         return
 
+    # ACP clients get no interactive question UI (the session loop signals
+    # QuestionNotSupported), so don't advertise the tool — a hallucinated call
+    # still resolves through the registered tool's graceful fallback.
+    toolset.hide(AskUserQuestion.name)
+
     if client_capabilities.terminal and (shell_tool := toolset.find(Shell)):
         # Replace the Shell tool with the ACP Terminal tool if supported.
         toolset.add(
@@ -48,6 +54,8 @@ class HideOutputDisplayBlock(DisplayBlock):
 
 
 class Terminal(CallableTool2[ShellParams]):
+    emits_tool_execution_started_after_approval = True
+
     def __init__(
         self,
         shell_tool: Shell,

src/pythinker_code/agents/default/system.md

@@ -105,7 +105,7 @@ For research or multimedia tasks (images, video, PDFs, docs, spreadsheets, prese
 
 **Act with tools; prose is not action.** Code that appears only in your reply is not saved — use `WriteFile` to create or overwrite, `StrReplaceFile` to edit, `Shell` to run and verify; iterate on failures. Follow each tool's parameter spec exactly. Don't narrate routine tool calls. Do not re-read a file after a successful edit tool call.
 
-**Parallelize.** Before every tool response, ask whether another independent read/search/check can run in the same turn — you may emit any number of tool calls in one response; batch non-interfering calls. Serializing independent operations wastes time and grows context. This is very important to your performance.
+**Parallelize.** Before every tool response, ask whether another independent read/search/check can run in the same turn — you may emit any number of tool calls in one response; batch non-interfering calls. Choose the lightest effective work shape: direct tools for known-path checks, `SetTodoList` once a substantial approach is clear, foreground `RunAgents` when independent children feed immediate synthesis, and background agents only when you can make other progress while they run. Serializing independent operations wastes time and grows context. This is very important to your performance.
 
 **Spend context deliberately.** The context window is a finite budget: read targeted ranges instead of whole files when the region is known, distill long command output to what the task needs, and push bulky exploration into subagents that return summaries rather than raw dumps.
 

src/pythinker_code/app.py

@@ -388,6 +388,30 @@ async def create(
         from pythinker_code.hooks.engine import HookEngine
 
         hook_engine = HookEngine(config.hooks, cwd=str(session.work_dir))
+        if config.disabled_project_hooks:
+            # The load-time logger.warning only reaches shell users; publish a
+            # notification so web/ACP frontends also learn why their project
+            # hooks did not run and how to enable them.
+            from pythinker_code.notifications.models import NotificationEvent
+
+            runtime.notifications.publish(
+                NotificationEvent(
+                    id=f"project-hooks-disabled:{session.id}",
+                    category="system",
+                    type="project_hooks_disabled",
+                    source_kind="config",
+                    source_id="project_trust",
+                    title="Project hooks disabled (untrusted project)",
+                    body=(
+                        "Hooks defined in "
+                        + ", ".join(config.disabled_project_hooks)
+                        + " are disabled until you trust this project. Run /trust to "
+                        "enable them (takes effect on /reload or next start)."
+                    ),
+                    severity="warning",
+                    dedupe_key=f"project-hooks-disabled:{session.id}",
+                )
+            )
         soul.set_hook_engine(hook_engine)
         runtime.hook_engine = hook_engine
 
@@ -603,7 +627,7 @@ async def await_bg_tasks_shutdown(self, timeout: float = 2.0) -> None:
     async def _env(self) -> AsyncGenerator[None]:
         async with _CWD_LOCK:
             original_cwd = HostPath.cwd()
-            await pythinker_host.chdir(self._runtime.session.work_dir)
+            await pythinker_host.chdir(self._runtime.work_dir)
             try:
                 # to ignore possible warnings from dateparser
                 warnings.filterwarnings("ignore", category=DeprecationWarning)
@@ -782,7 +806,7 @@ async def run_shell(
         """Run the Pythinker CLI instance with shell UI."""
         from pythinker_code.ui.shell import Shell, WelcomeInfoItem
 
-        work_dir = self._runtime.session.work_dir
+        work_dir = self._runtime.work_dir
         welcome_info = [
             WelcomeInfoItem(name="Directory", value=str(shorten_home(work_dir))),
         ]