manage_context tool

What feature would you like to see?

I built this (manage_context) for my own use, but it might be useful if anyone on the team wants it.

Before this, I had a manual prune tool where I could clean up the context and delete whatever I thought wasn't needed anymore. It worked, but doing it by hand was annoying. So I made a version where the model can prune its own context autonomously.

It can create/edit/delete entries. That means it can drop old reasoning that's no longer useful (and eats a ton of tokens), or rewrite tool outputs into a tighter summary that keeps only what matters.

Compact is awful. It can kick in mid-task without the model choosing it, and then it loses the thread and tends to go full vibe-coding freestyle. Without auto-compact, the context may run out in the middle of a task, which is just as bad.

Nothing is actually deleted, items are masked so they aren’t included in the context, etc etc, bla bla bla.

Here are the instructions I made for the model know how to use the tool:

developer_instructions = """
Tool guide: manage_context

Use `manage_context` to keep long sessions healthy without `/compact` by pruning what stays in the prompt.

Preferred workflow (v2):
1) Inspect pressure (cheap):
   {"mode":"retrieve","include_items":false,"include_token_usage":true}

2) If you need targets, ask for a bounded list:
   {"mode":"retrieve","include_items":true,"max_items":200,"include_pairs":true,"include_token_usage":true}

3) Plan + dry-run (anti-drift):
   {"mode":"apply","snapshot_id":"<from retrieve>","dry_run":true,"ops":[...]}

4) Apply for real:
   Same payload without `dry_run` (or set `dry_run:false`).

Ops guidelines:
- Prefer `replace` (non-destructive) over `delete`.
- `replace` is allowed ONLY for tool outputs + reasoning (never user/assistant messages).
- Prefer targeting by `call_ids` to keep call/output pairs consistent.
- `delete` is destructive; use sparingly (cascade is tool outputs).
- Use `add_note` for the few decisions/constraints that must remain visible.

Safety/invariants:
- Avoid touching protected items (environment context + user instructions).
- If you see `snapshot mismatch`, rerun `retrieve` and retry.
- `apply` responses include `token_usage`; use `retrieve` when you need breakdown/items.

Tips:
- `include_items=true` can add a lot of text; start with `include_items=false`.
- `retrieve` hides internal manage_context bookkeeping by default; set `include_internal=true` if debugging.
- Use `max_top_items` to control how many "top offenders" appear in the breakdown.
"""

I've been testing it, and it's actually pretty funny to watch the context rising back. The model seems to be handling it really well.

Btw, I also added a instruction to once it hits 10% context left, it stops whatever it’s doing and calls manage_context.

Additional information

_No response_