feat(soul): agent logic upgrade (#149)

* fix(update): improve native update flow (#64)

* feat(soul): port blackbox agent-loop observability and session tools

Add wire events for todo updates, tool skips, subagent fallback, agent-list
deltas, and overflow recovery. Wire opt-in ToolUseSkipped telemetry,
AgentList injection, budget nudge, microcompact pruning, ToolSearch
discovery, session worktree enter/exit, and opt-in harvest-on-stop memory
capture. Update changelog, architecture docs, and tests.

* feat(toolset): surface cross-step dedup via ToolUseSkipped wire event

Add opt-in emits_tool_use_skipped hook for cross-step duplicate visibility,
pin exclusive default for unflagged plugin tools, and document the gate contract.

* feat(todo): emit TodoListUpdated wire event on write/read

* feat(agent): emit SubagentToolFallback wire event on unknown type

* feat(soul): emit ContextOverflowRecovered wire event; assert one-shot reactive retry

* feat(soul): add opt-in token-budget nudge (config-gated, one-shot per turn)

* docs(agent): add brief hygiene note to Agent tool description

* docs: changelog + architecture note for agent-loop best-practice port

* test: refresh inline snapshots for agent-loop port

* test: refresh default agent snapshot for hygiene note

* test: align agent-loop port tests with wire and fail-fast semantics

* test(e2e): refresh wire snapshots for TodoListUpdated events

* chore(test): fix ruff/pyright and format snapshot refresh files

* fix(soul): resolve merge duplicates from blackbox port integration

Drop duplicate budget-nudge, ToolUseSkipped emit paths, and conflicting
tests introduced when merging feat/blackbox-agent-loop-port into main.

* fix(wire): remove duplicate ContextOverflowRecovered class definition

* test: refresh snapshots for new worktree/tool_search tools and AgentListDelta wire events

* test: fix ruff formatting and refresh wire snapshots for agent-logic-upgrade

4 files were unformatted (ruff would-reformat). 5 e2e snapshot tests were
stale after new slash commands (/recap, /accept-edits, /goal, /learn,
/best-practices) and skill entries were added to the wire initialize handshake.

* fix: address PR #149 review comments from code-quality and security bots

- ci-pythinker-host.yml: add workflow-level `permissions: contents: read`
- llm.py: use urlparse hostname check instead of substring match for dashscope
  and workspace endpoint detection (prevents false positives from path segments)
- dependencies.py: remove duplicate '=' from _VERSION_PREFIX_RE character class
- test_memory_phase_bcd.py: consolidate to single import style for pythinkersoul module
- test_toolset.py: replace standalone awaits with gather/assignment forms
- test_toolset_concurrency.py: remove always-true redundant assertion
- examples/feedback-worker/index.ts: replace .+? with [^<]*? to prevent ReDoS

* fix(examples): linear parseMailbox to avoid polynomial ReDoS

CodeQL flagged the angle-bracket regex in the feedback-worker example as a
polynomial regular expression on uncontrolled header input. Replace it with
an indexOf/slice parse that is linear in input length while preserving the
"Name <addr>" parsing behavior.

Author: elkaix

.cursor/rules/no-co-author-trailers.mdc

@@ -0,0 +1,31 @@
+---
+description: Never add Co-authored-by or other AI/tool trailers to git commits or PRs
+alwaysApply: true
+---
+
+# No co-author or AI trailers on commits
+
+**Never** add `Co-authored-by`, `Signed-off-by` for an AI tool, or any Cursor/Claude/Copilot
+footer to commit messages or PR descriptions.
+
+This matches `AGENTS.md`: commits use Conventional Commits subject (+ optional body) only.
+
+## When creating commits
+
+- Pass the message via HEREDoc or `-m` with **only** the intended subject/body.
+- Do **not** append `Co-authored-by: Cursor <cursoragent@cursor.com>` or similar.
+- If a hook or tool adds a co-author trailer, **amend it out** before pushing (only when amend rules allow).
+
+## Examples
+
+```text
+feat(soul): emit TodoListUpdated wire event
+```
+
+Not:
+
+```text
+feat(soul): emit TodoListUpdated wire event
+
+Co-authored-by: Cursor <cursoragent@cursor.com>
+```

.github/workflows/ci-pythinker-host.yml

@@ -17,6 +17,9 @@ on:
       - "uv.lock"
 
 
+permissions:
+  contents: read
+
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 

CHANGELOG.md

@@ -15,6 +15,28 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Stop-time memory extraction can now be enabled explicitly.** Added an opt-in
+  `memory.harvest_on_stop` setting that stages safe assistant decisions, blockers, evidence, and
+  next steps into the existing scratchpad recall flow at turn end without writing directly to
+  durable `MEMORY.md`.
+- **Agents can now discover visible tools and temporarily work from a session worktree.** Added
+  `ToolSearch` plus root-session `EnterWorktree` and `ExitWorktree` tools so agents can find
+  currently available capabilities by keyword and isolate a session's operational working directory
+  in a git worktree without deleting user work on exit.
+- **Agent-loop observability now emits explicit Wire events for key runtime state.** Added
+  `TodoListUpdated`, `SubagentToolFallback`, `AgentListDelta`, `ToolUseSkipped`, and
+  `ContextOverflowRecovered` events, with todo updates, subagent launch fallbacks, same-step tool
+  reuse/policy skips for tools that explicitly opt in, agent-list injections, and
+  context-overflow recovery now surfaced best-effort over Wire without changing existing tool
+  results.
+- **Spend ceilings now warn before they stop a session.** When `max_session_cost_usd` is configured,
+  the loop appends a bounded system reminder after a turn crosses `budget_nudge_ratio` of the
+  ceiling, nudging the agent to conserve budget without auto-continuing or hiding a later
+  `budget_exhausted` stop.
+- **The Agent tool description now gives clearer prompt-briefing guidance.** Fresh subagents should
+  receive the goal, scope, expected output contract, and verification criteria; the Haiku-style
+  tool-use summary from the blackbox reference was deliberately not ported.
+
 ## 0.46.0 (2026-06-14)
 
 - **Startup auto-update now picks up new releases within half an hour instead of up to a day.** The background update check was throttled to once every 24h, so a freshly published release could go unnoticed for a full day after the last check; the interval is now 30 minutes. The silent installer also no longer marks the throttle *before* the network call — a transient startup network error returns `FAILED` and is retried on the next launch instead of suppressing updates for the whole window.

docs/en/customization/architecture.md

@@ -87,6 +87,12 @@ The end-to-end flow when a session starts and processes a turn:
 The soul is the heart of the runtime. Beyond the loop itself it owns approvals, context and
 compaction, slash commands, dynamic prompt injection, and a checkpoint-rewind mechanism.
 
+The agent loop emits per-turn and per-step wire events for orchestration observability. The
+canonical list lives in `src/pythinker_code/wire/types.py` (`Event` union): `StepBegin`,
+`StepRetry`, `StepInterrupted`, `ToolExecutionStarted`, `StatusUpdate`, plus
+`TodoListUpdated`, `SubagentToolFallback`, `AgentListDelta`, `ToolUseSkipped`, and
+`ContextOverflowRecovered`.
+
 | Path | Purpose | Key entry points and interfaces |
 | --- | --- | --- |
 | `src/pythinker_code/soul/pythinkersoul.py` | Core loop: user input, slash commands, LLM calls, tool runs, compaction, telemetry spans. | `PythinkerSoul`, `PythinkerSoul.run`, `FLOW_COMMAND_PREFIX` |
@@ -168,6 +174,12 @@ model; `/usage` defaults to the active provider, with `/usage all` as the explic
 | `src/pythinker_code/ui/print/` | Non-interactive output (text / stream-json). | `Print` |
 | `src/pythinker_code/ui/acp/` | Deprecated single-session ACP shim (raises on use); the live server is `src/pythinker_code/acp/`. | `ACP` |
 
+The agent loop emits per-turn and per-step events for UI, replay, and dashboard consumers. The
+canonical list lives in the `Event` union in `src/pythinker_code/wire/types.py`; commonly consumed
+events include `StepBegin`, `StepRetry`, `StepInterrupted`, `ToolExecutionStarted`, `StatusUpdate`,
+`TodoListUpdated`, `SubagentToolFallback`, `AgentListDelta`, `ToolUseSkipped`, and
+`ContextOverflowRecovered`.
+
 The shell can run with a working directory inside its subtree, so `src/pythinker_code/ui/`
 is a candidate for a focused nested guide on prompt, visualization, and component layout.
 

docs/en/release-notes/changelog.md

@@ -17,6 +17,28 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Stop-time memory extraction can now be enabled explicitly.** Added an opt-in
+  `memory.harvest_on_stop` setting that stages safe assistant decisions, blockers, evidence, and
+  next steps into the existing scratchpad recall flow at turn end without writing directly to
+  durable `MEMORY.md`.
+- **Agents can now discover visible tools and temporarily work from a session worktree.** Added
+  `ToolSearch` plus root-session `EnterWorktree` and `ExitWorktree` tools so agents can find
+  currently available capabilities by keyword and isolate a session's operational working directory
+  in a git worktree without deleting user work on exit.
+- **Agent-loop observability now emits explicit Wire events for key runtime state.** Added
+  `TodoListUpdated`, `SubagentToolFallback`, `AgentListDelta`, `ToolUseSkipped`, and
+  `ContextOverflowRecovered` events, with todo updates, subagent launch fallbacks, same-step tool
+  reuse/policy skips for tools that explicitly opt in, agent-list injections, and
+  context-overflow recovery now surfaced best-effort over Wire without changing existing tool
+  results.
+- **Spend ceilings now warn before they stop a session.** When `max_session_cost_usd` is configured,
+  the loop appends a bounded system reminder after a turn crosses `budget_nudge_ratio` of the
+  ceiling, nudging the agent to conserve budget without auto-continuing or hiding a later
+  `budget_exhausted` stop.
+- **The Agent tool description now gives clearer prompt-briefing guidance.** Fresh subagents should
+  receive the goal, scope, expected output contract, and verification criteria; the Haiku-style
+  tool-use summary from the blackbox reference was deliberately not ported.
+
 ## 0.46.0 (2026-06-14)
 
 - **Startup auto-update now picks up new releases within half an hour instead of up to a day.** The background update check was throttled to once every 24h, so a freshly published release could go unnoticed for a full day after the last check; the interval is now 30 minutes. The silent installer also no longer marks the throttle *before* the network call — a transient startup network error returns `FAILED` and is retried on the next launch instead of suppressing updates for the whole window.