feat(soul): agent logic upgrade

.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.