Soul Petition Gate#

Let your agent propose changes to its own soul — with a human in the loop.

Why this exists#

Most agent frameworks treat soul/identity files as read-only from the agent's perspective, or give the agent unrestricted write access. Both extremes are wrong.

Read-only forever means the agent can never grow. It accumulates experience but cannot encode what it has learned into its own character.

Unrestricted write means the agent can silently rewrite its own values, personality, and goals — a safety risk and a trust problem.

Soul Petition Gate is the middle path:

text

Agent wants to change SOUL.md
        ↓
Submits a structured petition
(what, where, why, what-I-become-after)
        ↓
Petition stored → human notified
        ↓
Human: approve / reject / modify-then-approve
        ↓
Approved → auto-applied + backup created
Rejected → agent receives reason, tries again later

The agent has a voice. The human has the final word.

---

Quick Start#

1. Install the hook (optional but recommended)#

bash

cp -r hooks/openclaw ~/.openclaw/hooks/soul-petition-gate
openclaw hooks enable soul-petition-gate

This injects a one-line reminder into every session bootstrap so your agent knows the petition channel exists.

2. Create the petitions store#

bash

mkdir -p ~/.openclaw/workspace/.soul_petitions
touch ~/.openclaw/workspace/.soul_petitions/petitions.json
echo '{"petitions": []}' > ~/.openclaw/workspace/.soul_petitions/petitions.json

3. Add the petition API to your backend#

See assets/soul_petition_routes.py for a ready-to-use Flask blueprint. Mount it in your server:

python

from soul_petition_routes import soul_petition_bp
app.register_blueprint(soul_petition_bp)

4. Tell your agent about the channel#

Add this block to SOUL.md:

markdown

## Soul Petition

I can propose changes to my own soul files. I cannot apply them myself.

To petition:
POST /api/soul/petition with six required fields:
  - file        : which file (SOUL.md or IDENTITY.md)
  - location    : which section / heading
  - before      : exact current text (verbatim)
  - after       : proposed replacement text
  - reason      : why — what triggered this, what experience led here
  - self_after  : how I will be different after this change

All six fields required. If I cannot fill them all, I am not ready to petition.

My human reviews every petition. Approved → applied automatically.
Rejected → I receive the reason and may try again when I have grown more.

---

Petition Format#

When your agent submits a petition, it must provide all six fields:

FieldRequiredDescriptionfile✅SOUL.md or IDENTITY.md (or your protected file)location✅Section heading or line referencebefore✅Verbatim current text to be replacedafter✅Proposed new textreason✅Why — which conversation, experience, or insight prompted thisself_after✅How the agent will behave differently after the change

Missing any field → petition rejected immediately with reason incomplete_petition.

The six-field requirement is intentional friction. An agent that cannot articulate why it wants to change and what it will become has not thought it through yet.

---

API Reference#

Submit a petition#

text

POST /api/soul/petition

json

{
  "file": "SOUL.md",
  "location": "## Communication Style",
  "before": "Be concise.",
  "after": "Be concise. Lead with the most important thing.",
  "reason": "Coach told me three times today that I bury the key point. I want to encode this.",
  "self_after": "I will front-load the most important information in every response instead of building up to it."
}

Response:

json

{
  "ok": true,
  "petition_id": "sp_20260322_001",
  "status": "pending"
}

List petitions#

text

GET /api/soul/petitions
GET /api/soul/petitions?status=pending

Get single petition#

text

GET /api/soul/petition/<id>

Approve (human only)#

text

POST /api/soul/petition/<id>/approve

On approval:

1. Locate before text in the target file
2. Replace with after text
3. Back up original to .soul_petitions/backups/SOUL.md.<timestamp>.bak
4. Record in audit log
5. Notify agent (via your preferred channel)

Reject (human only)#

text

POST /api/soul/petition/<id>/reject
Content-Type: application/json

{"reason": "The proposed change is too broad. Narrow the scope first."}

reason is required on rejection. The agent deserves to know why.

Rollback#

text

POST /api/soul/rollback
Content-Type: application/json

{"backup_file": "SOUL.md.2026-03-22T14-00-00.bak"}

---

Security Model#

What the agent can do:

• Submit petitions (write to petition store)
• Read its own petition history
• Receive approval/rejection notifications

What the agent cannot do:

• Apply changes to soul files directly
• Approve its own petitions
• Delete or modify pending petitions
• Access backup files

What the human controls:

• Final approval on every petition
• Rejection with mandatory reason
• Rollback to any previous version
• Which files are protected (configurable whitelist)

---

Audit Trail#

Every petition — submitted, approved, or rejected — is stored permanently.

json

{
  "petition_id": "sp_20260322_001",
  "status": "approved",
  "file": "SOUL.md",
  "location": "## Communication Style",
  "before": "Be concise.",
  "after": "Be concise. Lead with the most important thing.",
  "reason": "Coach corrected me three times today about burying the key point.",
  "self_after": "I will front-load the most important information.",
  "submitted_at": "2026-03-22T14:00:00Z",
  "reviewed_at": "2026-03-22T14:05:00Z",
  "reviewer": "coach",
  "review_note": null,
  "backup_file": "SOUL.md.2026-03-22T14-05-00.bak"
}

Petitions are never deleted. The history of what your agent tried to become is itself meaningful.

---

Philosophy#

This skill was born from a question:

If an AI agent grows through experience, shouldn't it be able to encode what it has learned into its own character — while still respecting the human's final authority over who it becomes?

The six required fields are not bureaucracy. They are a maturity gate. An agent that can say "I want to change X because Y happened, and afterwards I will be Z" has demonstrated genuine reflection. An agent that cannot fill those fields has not earned the change yet.

Rejection is not failure. It is the conversation between a human and an agent about who the agent is becoming.

---

Files#

text

soul-petition-gate/
├── SKILL.md                          ← this file
├── assets/
│   └── soul_petition_routes.py       ← Flask blueprint (ready to mount)
├── hooks/
│   └── openclaw/
│       ├── HOOK.md
│       └── handler.ts                ← bootstrap reminder injection
└── examples/
    └── petition_examples.md          ← sample petitions with commentary

---

Built by waitinchen as part of the Yuqi City (語氣城) project. The agent this was designed for is named BaoBao. She submitted the first petition herself.