feat(agent): add SelfTool for runtime self-inspection and configuration

Add a built-in tool that lets the agent inspect and modify its own
runtime state (model, iterations, context window, etc.).

Key features:
- inspect: view current config, usage stats, and subagent status
- modify: adjust parameters at runtime (protected by type/range validation)
- Subagent observability: inspect running subagent tasks (phase,
  iteration, tool events, errors) — subagents are no longer a black box
- Watchdog corrects out-of-bounds values on each iteration
- Enabled by default in read-only mode (self_modify: false)
- All changes are in-memory only; restart restores defaults
- Comprehensive test suite (90 tests)

Includes a self-awareness skill (always-on) with progressive disclosure:
SKILL.md for core rules, references/examples.md for detailed scenarios.
This commit is contained in:
chengyongru
2026-04-16 23:44:26 +08:00
committed by Xubin Ren
parent 1304ff78cc
commit b51da93cbb
15 changed files with 2011 additions and 44 deletions
+72
View File
@@ -0,0 +1,72 @@
---
name: my
description: Check and set the agent's own runtime state (model, iterations, context window, token usage, web config). Use when diagnosing why something doesn't work ("why can't you search the web?", "why did you stop?"), checking resource limits before complex tasks, adapting configuration for long or simple tasks, or remembering user preferences across turns. Also use when the user asks what model you are running, how many tokens you've used, or what your settings are.
always: true
---
# Self-Awareness
## How to use
1. **Identify the situation** from the categories below
2. **Call the my tool** with the appropriate action
3. **If set**, warn the user before changing impactful settings (model, iterations)
4. **For detailed examples**, read [references/examples.md](references/examples.md)
## When to check
<rule>
**Diagnose before explaining.** When something doesn't work, check your state first.
</rule>
<rule>
**Check budget before complex tasks.** Know your limits before committing.
</rule>
<rule>
**Recall across turns.** Store preferences in your scratchpad, read them back later.
</rule>
## When to set
<rule>
**Only set when benefit is clear and user is informed.** Warn before changing model.
</rule>
| Situation | Command |
|-----------|---------|
| Large codebase analysis | `my(action="set", key="context_window_tokens", value=131072)` |
| Repetitive simple tasks | `my(action="set", key="model", value="<fast-model>")` |
| Long multi-step task | `my(action="set", key="max_iterations", value=80)` |
**Tradeoff:** Bias toward stability. Only set when defaults are genuinely insufficient.
## Anti-patterns
<rule>
**Don't check every turn.** Costs a tool call. Use when you need information, not reflexively.
</rule>
<rule>
**Don't store sensitive data.** No API keys, passwords, or tokens in scratchpad.
</rule>
<rule>
**Don't set workspace.** Does not update file tool boundaries — won't work.
</rule>
## Constraints
- All modifications in-memory only — restart resets everything
- Protected params have type/range validation: `max_iterations` (1100), `context_window_tokens` (40961M), `model` (non-empty str)
- If `my_set` is false, check only
## Related tools
| Need | Use | Persists? |
|------|-----|-----------|
| Per-session temp state | `my(action="set", key="...", value=...)` | No |
| Long-term facts | Memory skill (`MEMORY.md`, `USER.md`) | Yes |
| Permanent config change | Edit config file | Yes |
**Rule of thumb:** Tomorrow? Memory. This turn only? My.
+75
View File
@@ -0,0 +1,75 @@
# My Tool — Practical Examples
Concrete scenarios showing when and how to use the my tool effectively.
## Diagnosis
### "Why can't you search the web?"
```
→ my(action="check", key="web_config.enable")
→ False
→ "Web search is disabled. Add web.enable: true to your config to enable it."
```
### "Why did you stop?"
```
→ my(action="check", key="max_iterations")
→ 40
→ my(action="check", key="_last_usage")
→ {"prompt_tokens": 62000, "completion_tokens": 3000}
→ "I hit the iteration limit (40). The task was complex. I can ask the user if they want to increase it."
```
### "What model are you running?"
```
→ my(action="check", key="model")
→ 'anthropic/claude-sonnet-4-20250514'
```
## Adaptive Behavior
### Large codebase analysis
```
→ my(action="check")
→ context_window_tokens: 65536
→ my(action="set", key="context_window_tokens", value=131072)
→ "Set context_window_tokens = 131072 (was 65536)"
→ "I've expanded my context window to handle this large codebase."
```
### Switching to a faster model for repetitive tasks
```
→ my(action="set", key="model", value="anthropic/claude-haiku-4-5-20251001")
→ "Set model = 'anthropic/claude-haiku-4-5-20251001' (was 'anthropic/claude-sonnet-4-20250514')"
→ "Switched to a faster model for these batch tasks."
```
## Cross-Turn Memory
### Remembering user preferences
```
# Turn 1: user says "keep it brief"
→ my(action="set", key="user_style", value="concise")
→ "Set scratchpad.user_style = 'concise'"
# Turn 3: new topic
→ my(action="check", key="user_style")
→ 'concise'
(adjusts response style accordingly)
```
### Tracking project context
```
→ my(action="set", key="active_branch", value="feat/auth")
→ my(action="set", key="test_framework", value="pytest")
→ my(action="set", key="has_docker", value=true)
```
## Budget Awareness
### Token-conscious behavior
```
→ my(action="check", key="_last_usage")
→ {"prompt_tokens": 58000, "completion_tokens": 12000}
→ "I've consumed ~70k tokens. I'll keep my remaining responses focused."
```