Mediabot v3 continues its 3.4 development cycle with a focused extension of the script-event bridge.

This round adds one new observable channel event: kick.

It may sound small, but it closes an important gap for moderation-aware scripts. Joins, parts and topic changes were already scriptable. Kicks now join the same guarded event model.

🧹 Why kick matters

A kick is not just another message. It is a moderation action.

With the new route, a script can observe who performed the kick, who was removed, and why.

The event envelope contains:

nick    = the operator who performed the kick
kicked  = the victim
message = the reason, when one exists

That gives script authors enough context to build lightweight moderation traces, channel notices, audit helpers or custom logging.

In Hogwarts terms: when a prefect throws someone out of the Great Hall, Filch writes it down. 🧹

🗝️ Strictly opt-in

Nothing runs unless the administrator explicitly routes the event.

Example:

EVENTS=kick=examples/kickwatch.pl

There is still no fallback to the default script for events. That is intentional.

Events are noisier and riskier than commands, so the bridge keeps the model strict: no route, no script.

🛡️ Same safety gates as the rest of the event bridge

Kick events inherit the same protection model as join, part and topic:

• per-event and per-channel cooldown;
• channel-scope protection;
• dry-run/apply separation;
• IRC output still gated by ALLOW_IRC;
• scripts cannot silently reply into another channel;
• event observer failures cannot break the normal IRC handler.

Mass-kicks are counted and throttled, not turned into a script storm.

That is the right tradeoff: useful observability without giving automation a license to run wild.

🧍 Bot self-protection

Kick has one extra rule: is_self covers both roles.

The event is suppressed when the bot is the kicker, and also when the bot is the victim.

That avoids silly or unsafe behavior. If the bot just kicked someone, it does not need to comment on itself. If the bot has just been kicked, it cannot safely speak in that channel anyway.

🦉 New reference script: kickwatch.pl

A new example script ships with the bridge:

plugins/scripts/examples/kickwatch.pl

It demonstrates the intended pattern:

• read nick, kicked and message;
• publish a concise moderation trace in the same channel;
• log the event;
• stay silent on IRC if accidentally routed to the wrong event.

It is an example, not a policy engine. That is exactly what a reference script should be.

🚫 Why nick is still excluded

The nick event remains deliberately unsupported.

Unlike join, part, topic and kick, a nickname change does not belong to one clear channel. That makes channel scope ambiguous.

Rather than inventing a dangerous shortcut, Mediabot keeps nick out of the event whitelist for now.

Mrs Norris may roam every corridor at once, but the script bridge does not. 🐈

✅ Validation

This round was validated with:

10470/10470 tests passed

The dedicated kick-event test covers the core event, the plugin route, the reference script, the bot self-suppression rule, and the negative contract that nick stays unsupported.

No database schema change.
No live configuration required unless you choose to enable the new route.

🧙 Summary

This pass extends the event bridge in the safest useful direction:

• kick becomes observable by scripts;
• kickwatch.pl provides a real reference example;
• the event stays opt-in and cooldown-protected;
• bot self-events are suppressed;
• nick remains excluded by design.

A small feature, but a useful one for communities that care about moderation traces without turning their IRC bot into a chaos charm. 🪄