feat(agent): harden runtime agent design

[elkaix]

Summary

• filter advertised tools by active execution policy, permission profile, role, and plan-mode state
• add agent metadata fields plus ask/debug primary agents and scout subagent
• update compaction handoff structure, agent docs, changelog, and focused tests

Verification

• uv run pytest tests/core/test_agent_spec.py tests/core/test_default_agent.py tests/core/test_simple_compaction.py tests/core/test_load_agent.py tests/core/test_permission_profiles.py -q
• make check-pythinker-code
• graphify update .

Summary by CodeRabbit

• New Features

  • Selectable primary agents: new read-only "ask" and diagnostic "debug" modes via CLI
  • New "scout" subagent for external docs/dependency/API freshness research
  • Agent specs now support mode, hidden, steps, temperature, and top_p metadata

• Improvements

  • Stronger runtime tool-visibility filtering tied to permission/profile/role and plan-state
  • New strict compact handoff summary template for clearer, consistent handoffs

• Documentation

  • Expanded agent architecture/configuration docs and CLI response style guidance

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6a32b312-ab16-4aa0-ab14-1dd69d933da2

📥 Commits

Reviewing files that changed from the base of the PR and between 1b31ac2 and 668ce74.

📒 Files selected for processing (2)

• src/pythinker_code/agents/default/ask.yaml
• src/pythinker_code/prompts/compact.md

💤 Files with no reviewable changes (1)

• src/pythinker_code/agents/default/ask.yaml

---

📝 Walkthrough

Walkthrough

Adds agent metadata and runtime wiring, new built-in agents (ask, debug) and a scout subagent, enforces execution-policy-aware tool advertising, replaces the compact handoff prompt, and updates tests/docs accordingly.

Changes

Agent Metadata & Built-in Agents

Layer / File(s)	Summary
Agent spec metadata model and resolution src/pythinker_code/agentspec.py	AgentSpec and ResolvedAgentSpec gain mode, hidden, steps, temperature, and top_p; load_agent_spec() populates defaults and merges child overrides.
Agent dataclass and loading src/pythinker_code/soul/agent.py	Agent dataclass exposes metadata fields; load_agent() passes spec values; supports_background set from hidden.
CLI agent selection and dispatch src/pythinker_code/cli/__init__.py	--agent accepts ask and debug; ASK_AGENT_FILE and DEBUG_AGENT_FILE added and dispatched.
Built-in agent YAMLs & prompts src/pythinker_code/agents/default/{ask,debug,scout}.yaml, src/pythinker_code/agents/default/agent.yaml, src/pythinker_code/agents/default/system.md	Adds ask (read-only Q&A), debug (diagnosis) primary configs, scout subagent config, wires scout into default agent, and adds CLI response style guidance.
Agent metadata tests tests/core/test_agent_spec.py, tests/core/test_load_agent.py	Snapshots assert new metadata fields and scout registration; new test verifies inheritance/overrides and loaded-agent metadata exposure.

Tool Visibility Hardening

Layer / File(s)	Summary
PythinkerToolset tool visibility filtering src/pythinker_code/soul/toolset.py	Adds _is_external_side_effect_tool() and _is_tool_visible() to gate advertised tools by permission profile, execution policy, file/shell/network/agent allowances, and plan-mode state.
Agent step limit override src/pythinker_code/soul/pythinkersoul.py	PythinkerSoul applies agent.steps to per-turn max_steps_per_turn when present.
Tool visibility tests & snapshots tests/core/test_permission_profiles.py, tests/core/test_default_agent.py	Adds tests for read-only subagent tool hiding, plan-mode behavior, plan-only profile behavior; updates snapshots (scout addition, ExitPlanMode removal).

Documentation and Prompt Updates

Layer / File(s)	Summary
Architecture docs docs/en/customization/agent-architecture.md	Clarifies that the advertised tool list is filtered per step by role/profile/plan-mode while execution-time guards remain authoritative; adds Behavioral Invariants table.
Agents docs docs/en/customization/agents.md	Documents primary agent selection via --agent; adds ask and debug descriptions; extends YAML configuration fields; adds planner and scout to subagent types; updates Agent tool docs.
Compaction prompt src/pythinker_code/prompts/compact.md	Replaces tag-based compact format with strict Markdown template sections and explicit retention/merging rules.
Changelog CHANGELOG.md	Adds entries for tool visibility hardening and agent design upgrades.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Pythoughts-labs/pythinker-code#75: Related changes around StatusUpdate fields and model/provider metadata (possible consumer overlap).
• Pythoughts-labs/pythinker-code#43: Prior permission/profile-based tool filtering and tests that overlap with this PR’s tool visibility logic.

Suggested labels

enhancement

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	Description summarizes changes and provides verification steps, but lacks related issue link and checklist completion required by template.	Add 'Resolve #(issue_number)' section and complete the checklist items in the description template.
Docstring Coverage	⚠️ Warning	Docstring coverage is 39.29% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows conventional commits format with proper type and scope, clearly describing the main change of hardening agent runtime design.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-runtime-hardening

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/pythinker_code/agents/default/ask.yaml`:
- Around line 8-13: The Ask-mode policy in ask.yaml declares a read-only
assistant but still whitelists the Shell tool ("Shell"), leaving mutating
commands available; remove "Shell" from the Ask-mode tool whitelist (or replace
it with a strictly read-only shell policy) so the mode's behavior matches its
contract, and apply the same change to the other Ask-mode block referenced
(lines 24-30) to ensure both "Ask mode" entries do not permit the Shell tool.

In `@src/pythinker_code/prompts/compact.md`:
- Around line 8-34: The compact.md template has multiple level-2 headings (e.g.,
"## Goal", "## Constraints & Preferences", "## Progress", "## Key Decisions",
"## Next Steps", "## Critical Context", "## Relevant Files") with no blank lines
before/after them causing MD022; fix by inserting a single blank line both above
and below each of these headings (and any nested "###" headings like "### Done",
"### In Progress", "### Blocked") so every heading is separated by blank lines,
ensuring the template conforms to markdownlint's MD022 rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 58108c71-1ae7-488d-983a-ded09466f65c

📥 Commits

Reviewing files that changed from the base of the PR and between e067caf and 6dde750.

📒 Files selected for processing (18)

• CHANGELOG.md
• docs/en/customization/agent-architecture.md
• docs/en/customization/agents.md
• src/pythinker_code/agents/default/agent.yaml
• src/pythinker_code/agents/default/ask.yaml
• src/pythinker_code/agents/default/debug.yaml
• src/pythinker_code/agents/default/scout.yaml
• src/pythinker_code/agents/default/system.md
• src/pythinker_code/agentspec.py
• src/pythinker_code/cli/__init__.py
• src/pythinker_code/prompts/compact.md
• src/pythinker_code/soul/agent.py
• src/pythinker_code/soul/pythinkersoul.py
• src/pythinker_code/soul/toolset.py
• tests/core/test_agent_spec.py
• tests/core/test_default_agent.py
• tests/core/test_load_agent.py
• tests/core/test_permission_profiles.py

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pythinker_code/agentspec.py	83.33%	2 Missing and 2 partials ⚠️
src/pythinker_code/soul/pythinkersoul.py	0.00%	1 Missing and 1 partial ⚠️
src/pythinker_code/soul/toolset.py	93.93%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!