subsession-delete

Delete an OpenClaw child session cleanly by removing its transcript, trajectory files, and sessions.json index entry.

Security Scan

The skill's code, instructions, and requirements align with its stated purpose (deleting a child session from disk and index); it is a local destructive tool with no external network calls or credential requirements.

Purpose & Capability

The name/description match the included script and SKILL.md: the script locates session files under ~/.openclaw/agents/<agent>/sessions, deletes the transcript and trajectory files, and rewrites sessions.json. No unrelated credentials, binaries, or network access are requested.

Instruction Scope

SKILL.md and the script confine actions to local session files and the sessions.json index. This is destructive by design; the skill recommends dry-run by default. Note: there is no automatic backup before overwriting sessions.json and the prune logic removes any JSON entries whose sessionId matches (or keys that equal the sessionKey), so users should confirm the target and consider backing up sessions.json first.

Install Mechanism

Instruction-only skill with a small included Python script; there is no install step, no third-party downloads, and nothing is written to system locations beyond the targeted sessions directory.

Credentials

No environment variables, credentials, or external tokens are requested or used. The script reads/writes only the sessions directory under the current user's home — proportionate to the stated task.

Persistence & Privilege

The skill does not request permanent/always-on inclusion and does not modify other skills or global agent settings. It writes only to the agent's sessions.json and target session files under ~/.openclaw; this is expected for a deletion tool.

Assessment

This tool appears to do exactly what it says: permanently delete session files and clean the session index locally. Before running with --execute: (1) run the default dry-run first to see which files would be removed; (2) backup ~/.openclaw/agents/<agent>/sessions/sessions.json (and any transcripts) so you can restore if needed; (3) confirm you are operating on the correct agent and not a primary/active session; (4) run as the same user who owns the .openclaw files (do not run as root unnecessarily); (5) be aware the prune logic removes JSON nodes whose sessionId matches or whose key equals the sessionKey — if your sessions.json has unexpected structure this could remove more than a single entry. No network traffic or credentials are used by this skill.

Use this skill when you need to remove a spawned child session cleanly so it disappears from both disk and the session index/UI.

Scope

This skill removes a child session by:

• deleting the main transcript .jsonl
• deleting related .trajectory.jsonl and .trajectory-path.json
• removing matching entries from sessions.json
• verifying the session no longer appears in session listings

Safety boundary

• Treat this as destructive local deletion.
• Confirm the exact target session before execution.
• Prefer deleting child/subagent test sessions, not active primary sessions.
• Default to dry-run first unless the user explicitly wants immediate deletion.

Recommended command

python3 skills/subsession-delete/scripts/delete_subsession.py \
  --session-key 'agent:subtest2:subagent:EXAMPLE' \
  --execute

You can also target by session id:

python3 skills/subsession-delete/scripts/delete_subsession.py \
  --session-id '3e16bcb6-998c-45dd-9906-001792b8b706' \
  --agent-id subtest2 \
  --execute

Behavior

1. Resolve the agent/session target from sessionKey or sessionId
2. Load the target agent's sessions.json
3. Identify all matching session files
4. Delete the files that exist
5. Remove matching sessions.json records
6. Verify the session id/key no longer appears in the index

Report back

Return:

• target session key/id
• deleted file paths
• whether sessions.json changed
• verification result

Guardrails

• Do not guess the target session.
• Do not delete unrelated sessions in the same folder.
• If the session is missing on disk but still indexed, clean the index too.
• If the session is active/running, stop and ask before forcing deletion.