DEV Community: Taras Hanych

Claude Code Hooks for Laravel: Don't Let the Agent Say "Done" Until the Checks Pass

Taras Hanych — Wed, 04 Nov 2026 15:30:00 +0000

A rule in CLAUDE.md is a request. A hook is a gate.

Here is a reproduction from my Laravel test app. One route gets a new name, the way an agent renames things while "cleaning up":

Route::get('/contact', [ContactController::class, 'create'])->name('contact.create'); // was contact.form

The controller still redirects to contact.form, and four lines in a feature test still request it. php -l is happy, the route file looks fine, and nothing complains until someone submits the contact form or runs that one feature test. If the agent doesn't, it reports the task as done.

That is how architecture drifts in a codebase with an AI agent in it: not in one big rewrite, but one renamed route, one skipped check and one "done" at a time. You can write "always run the tests" into CLAUDE.md. Most of the time the agent will. The times it doesn't are the ones that reach production.

What a Stop hook is

Claude Code runs hooks at fixed points of a session, configured in .claude/settings.json. The Stop hook runs when the agent has finished responding and is about to hand the turn back to you. Three details from the docs matter for a gate:

The hook blocks only with exit code 2 (stderr goes back to Claude) or with JSON on stdout: {"decision": "block", "reason": "..."}. Claude then keeps working with your reason as its next instruction.
Any other non-zero exit code is a non-blocking error. Claude stops anyway.
The input has stop_hook_active: true when Claude is already continuing because of a stop hook, and Claude Code ends the turn itself after eight consecutive continuations. That is how you avoid an endless loop on a check the agent cannot fix.

The one-liner that doesn't block

The first hook most people write:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "php artisan test" }] }
    ]
  }
}

When a test fails, php artisan test exits with 1. By the rules above, that is a non-blocking error, and the agent finishes anyway. The gate is open.

Make it exit 2 and it blocks:

php artisan test || { echo "Tests fail. Fix them before finishing." >&2; exit 2; }

It still has four problems:

It runs on every stop, including when the agent just answered a question.
It runs the whole suite, so it gets slow, and slow gates get removed.
It sees only tests. Larastan errors, code style, a config file that no longer caches, a provider that no longer boots and a renamed route all pass, as long as no test happens to touch them.
It can be satisfied by deleting the failing test.

A hook that checks what the change needs

This is what I built into laravel-ai-verify, the Laravel port of the agent tooling from Semitexa, the PHP framework I'm working on. One command installs it:

composer require --dev semitexa/laravel-ai-verify
php artisan ai:verify:install --hook

It merges a single entry into .claude/settings.json, next to whatever hooks you already have:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "php \"${CLAUDE_PROJECT_DIR}/artisan\" ai:verify:hook",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

When Claude is about to finish, the hook runs php artisan ai:verify on the uncommitted work. That command looks at which files changed and plans only the checks they need: the tests that reach the changed code, Larastan on the changed lines, your project's own style tool (Pint, PHP-CS-Fixer, PHP_CodeSniffer or ECS, whichever has a config), a fresh route:list, config:cache or event:list for the kind of file you touched, and migrations in pretend mode. A changed test file must keep its tests and assertions, so deleting the failing test fails too.

For the renamed route, three checks ran in under a second, and the hook answered with a block. This is the reason Claude received, trimmed:

✗ artisan:routes: 5 reference(s) to undefined route names
  › app/Http/Controllers/ContactController.php:27 Route [contact.form] is not defined
    (The route was renamed or removed. Update this reference, or restore the name with ->name('contact.form').)
  › tests/Feature/ContactFormTest.php:14 Route [contact.form] is not defined
  › tests/Feature/ContactFormTest.php:30 Route [contact.form] is not defined
  ...
Re-run php artisan ai:verify after fixing. Do not delete or weaken tests to make it pass.

File, line and the fix, which is what an agent needs to act on it without asking you.

After a block it checks again every time the agent changes something, so a half-done fix (the controller updated, the tests still calling the old name) is sent back too. Two things keep it from being annoying. It skips a working tree it has already judged, so answering a question in a dirty repo, or stopping again without changing anything, does not re-run the checks. And it gives up after five rounds in one continuation, below Claude Code's own cap of eight.

What it doesn't do

It is a Claude Code hook. Cursor, Codex and Copilot get the same instructions through AGENTS.md, a git hook stamps commits that passed, and CI can run the same checks with the package's GitHub Action, but only Claude Code has a Stop event that can hold the turn.
It verifies checks, not intent. A commit can pass every check and still change the wrong line; the package flags some of those from the commit message, as a warning.
A gate is only as good as the checks behind it. If no check could read the changed files (a part of the app with no tests and no static analysis), the verdict is incomplete, not pass. The hook blocks only on fail, so an incomplete run does not hold the agent back; php artisan ai:verify shows it.

Which checks do you make your agent pass before it may say "done"?

Source and docs: https://github.com/semitexa/laravel-ai-verify. The ideas come from Semitexa: https://semitexa.com/?utm_source=devto&utm_medium=post&utm_campaign=claude-code-hooks-laravel

The commit passed every check. It still changed the wrong line.

Taras Hanych — Thu, 22 Oct 2026 12:30:00 +0000

Earlier this month Claude Code made a commit in our test app with the message "Limit contact name to 250 chars". The tests passed. Our verification hook ran, passed, and stamped the commit. CI was green.

The name limit did not change. The email limit did.

What happened

We were testing a GitHub Action for laravel-ai-verify, a package I maintain that makes coding agents run the checks a change needs before they say "done". The test app is a plain Laravel contact form. The form request had two rules next to each other:

'name'  => ['required', 'string', 'max:200'],
'email' => ['required', 'email', 'max:255'],

The intent was to limit the name to 250 characters. The agent did what agents often do with a one-line change: a find-and-replace of max:255 with max:250. There was no max:255 on the name line. There was one on the email line.

Every check we had said yes:

PHP syntax: fine.
The tests for that form request: green. None of them pinned the email limit.
ai:verify wrote a receipt, and the git hook added the trailer: AI-Verify: pass ... checks=4.

The receipt was honest. The checks it lists really ran, on exactly the tree that was committed. What it could not tell anyone is that the commit did something other than what its message said. CodeRabbit caught it in review a day later, as an outside-the-diff comment.

Two different questions

That slip made something obvious that I had been blurring:

Did the checks pass on this exact change? A receipt answers that.
Is this the change the message describes? Nothing in our pipeline asked.

Most "verify the agent" setups only answer the first one. Tests catch broken behaviour, not a correct-looking change in the wrong place. And when the subject line says "name", a human reviewer reads the diff expecting the name, which is exactly how this kind of slip gets approved.

What we added

Since 0.5.0, the same git hook and the CI check read each commit's subject against its diff. The rule is deliberately narrow:

A word in the subject names something in a changed code file, that line is left alone, and a line of the same shape within 12 lines of it did change. That is the wrong-line slip: 'name' => [...] untouched, its twin 'email' => [...] edited.
A number in the subject that no added line contains, such as 200 in the message when the diff writes 250.

It ignores prose, JSON, YAML and HTML files, tests, merges, reverts and commits touching more than 25 files. Agents commit with git commit -m, so the hook can print the warning before the commit exists:

ai-verify: the commit message may not describe this change:
  The subject names `name`, but its line app/Http/Requests/StoreContactMessageRequest.php:26 is unchanged; the change went to the similar line 27: `'email' => ['required', 'email', 'max:250'],`
  If the change is right, say what it does; if the message is right, change the code (git commit --amend).

The agent reads stderr, so it gets the chance to fix either the code or the message right away. In CI the same finding becomes a warning annotation on the changed line.

How noisy is it?

Before shipping it we ran it over 937 commits from five of our own PHP repositories. It flagged 23 of them, about 2.5%. One of the 23 was the commit above. That is low enough to leave it on by default as a warning, and it is why the default is warn, not fail: it is a heuristic, and a heuristic that blocks commits gets switched off.

What it does not do

It does not understand intent. A commit that says "fix rounding" and rounds the wrong way passes. A message that is too vague to name anything passes. It catches one specific, very common shape of mistake: the edit landed on the neighbour of the line the message talks about. That shape is common precisely because agents edit by pattern, and similar lines sit next to each other in validation rules, config arrays and route files.

The bigger lesson for me is about what a green check means. "Verified" should say what was verified. Our receipt now says which checks ran on which tree, and the message check says whether the subject matches the diff. Neither says the change is right. That part is still review.

Your turn

How do you check that an agent's commit does what its message says? Do you rely on a review bot, on humans reading every diff, or on something deterministic that runs before the commit lands?

The package is a Laravel port of the verification step from Semitexa, the PHP framework I build. The message check, the receipts and the Action are in the README.

Swoole PHP Frameworks in 2026: Laravel Octane vs Hyperf vs Semitexa

Taras Hanych — Tue, 20 Oct 2026 12:30:00 +0000

Keeping a PHP application in memory is no longer exotic. The question in 2026 is which shape of it fits your project: an existing Laravel app on an application server, a coroutine framework built for services, or a framework designed around the worker from the start.

This guide compares three ways to run PHP on Swoole: Laravel Octane, Hyperf and Semitexa. They are not three versions of the same product. Octane is a package that serves a normal Laravel application from a long-running server. Hyperf and Semitexa are frameworks written for that server. That difference matters more than any benchmark, so the comparison starts there. Facts about Octane and Hyperf come from their own documentation and repositories, checked on October 17, 2026; we build Semitexa, so read that part knowing who wrote it.

The short answer

Choose Laravel Octane if you already run Laravel. You keep the ecosystem, the packages and the team's habits, and gain a warm application between requests. You also take on the job of keeping your own code free of request state in long-lived objects.

Choose Hyperf for coroutine-heavy services. Microservices, RPC, many concurrent outbound calls, connection pools everywhere. It is the most mature Swoole-native framework of the three, with a large component set.

Choose Semitexa for a new application where the server owns the page and AI agents work on the code. Server-rendered pages with live updates over SSE, multi-tenant SaaS, and a codebase that agents query and verify instead of grep. It is the youngest of the three, with the smallest ecosystem.

Laravel Octane vs Hyperf vs Semitexa at a glance

Question	Laravel Octane	Hyperf	Semitexa
What it is	A package that boots a Laravel app once and serves requests from memory.	A coroutine framework for Swoole or Swow.	A framework with a Swoole-first runtime, designed for long-running workers.
Version and PHP	Octane 2.x (v2.22.0), PHP 8.1+, Laravel 10 to 13.	Hyperf 3.2, PHP 8.2+.	Date-tagged releases, PHP 8.4, Swoole 6.x.
Servers	FrankenPHP, Swoole, Open Swoole, RoadRunner.	Swoole 5+ or Swow.	Swoole, inside Docker.
State between requests	Laravel resets its own state; your singletons and statics are yours to keep clean.	Container objects are singletons; per-request data goes in the coroutine `Context`.	Services are worker-scoped; handlers and request, auth, tenant and locale context are execution-scoped.
Concurrency	`Octane::concurrently`, ticks, cache and tables, on Swoole only.	Coroutines throughout, pooled clients.	Coroutines, Channel-based connection pools with bounded waiting.
Multi-tenancy	Third-party, usually stancl/tenancy.	Small community packages.	Built in: ORM, cache and storage scope to the resolved tenant.
Live pages	Blade; SSE responses in Laravel 13; WebSockets through Reverb.	Blade, Twig and others; a WebSocket server component.	Server-rendered pages with deferred blocks and live updates over SSE.
AI coding agents	Laravel Boost: guidelines, skills and an MCP server.	Early MCP packages.	Project Graph for impact queries, `ai:verify` for every change.
Ecosystem	Laravel's, the largest in PHP.	Large component set, a mostly Chinese-speaking community.	Young and small; first-party packages only.

Versions and counts change. Octane 2.22.0 and Hyperf 3.2.0 were current on Packagist when this was written.

What a long-running worker changes

Under PHP-FPM, each request starts a clean application and throws it away at the end. A long-running worker boots once and serves many requests, often several at a time with coroutines. That removes repeated bootstrap work, and it turns object lifetimes into a design decision: anything that survives the request can carry one user's data into the next user's response.

All three frameworks answer the same three questions differently. Which objects live with the worker? Where does per-request data go? What stops one slow request from holding up the others? Long-running PHP: inside the Semitexa runtime walks through the model with a live example; here the focus is on how each framework draws the lines.

Laravel Octane: your Laravel app, kept warm

Octane's strength is that it asks very little of an existing Laravel application. Routes, controllers, form requests and middleware stay as they are, and type-hinting the Request in a controller method is safe. Service providers register and boot once per worker, and requests reuse the result.

The cost is a rule you now have to follow everywhere. The Octane documentation says Laravel resets its own state between requests but "does not always know how to reset the global state created by your application". Injecting the container, the request or the config repository into a singleton leaves it holding a stale copy; static arrays that grow per request leak memory. The documented fixes are a resolver closure instead of the object, or passing request data at call time. Workers restart after 500 requests by default as a safety net, and config/octane.php lets you list bindings to flush per request.

Some of Octane's extras depend on the server. Concurrent tasks, ticks, the Octane cache and tables are Swoole features; on FrankenPHP or RoadRunner you get the warm application without them. Multi-tenancy comes from packages such as stancl/tenancy, so check how your tenancy package handles long-lived workers before you switch.

For AI-assisted work, Laravel has the most complete official story of the three: Boost gives coding agents guidelines, skills and an MCP server that can read your schema, query the database and see the last error, and the Laravel AI SDK covers agents inside the app.

Hyperf: coroutines all the way down

Hyperf was written for Swoole, and it shows. Coroutines run throughout the framework, its database and Redis clients are coroutine-aware, and built-in components handle connection pooling so you do not acquire and release connections by hand. For services that spend most of their time waiting on other services, that model is the point.

Its rule for state is short and strict. The DI documentation says objects managed by the container are all singletons and must not hold request state. Per-request data goes into Hyperf\Context\Context, which belongs to the current coroutine and is released when it ends. Globals and statics are shared by every coroutine in the worker, and a blocking call stalls them all, so every I/O client has to be coroutine-enabled.

Hyperf uses attributes for routing and injection, supports lazy proxies and offers AOP through generated proxy classes, which apply only to objects the container creates. Views are supported through several engines, but rendering runs in a task worker by default, where the request and session are not available. Multi-tenancy is left to small community packages. The project reports about 104,000 requests per second in its own README benchmark; there is no independent 2026 figure to compare it with.

Semitexa: the worker as the starting point

Semitexa starts from the same place as Hyperf, an application that lives in a Swoole worker, and adds two opinions: there is one way through a request, and the framework should be able to describe itself to the people and agents changing it.

A request is a typed payload, a handler, a resource, then rendering. The container knows two lifetimes. Services injected with #[InjectAsReadonly] are built once per worker. Handlers are cloned for each execution, and anything injected with #[InjectAsMutable], such as the request or the tenant context, belongs to that execution. Database connections come from a Channel-based pool with bounded waiting. Workers recycle after a configurable number of requests and also watch their own memory, leaving through the same drain a reload uses before PHP's limit would cut a request off.

Tenancy is part of the framework. The tenant is resolved per request by path, subdomain, header or query parameter, and the ORM scopes queries, the cache namespaces keys and storage isolates paths to it; the tenant also travels with queued work. Pages are rendered on the server, slow regions are deferred and streamed in over SSE, and server-side changes can be pushed to pages that are already open. The live data grid is one example.

For coding agents, the framework scans itself into a Project Graph that answers "who uses this class" and "what does this change affect" before an edit, and bin/semitexa ai:verify runs the checks a change touches and records what it checked. If you work in Laravel, the same idea is available as semitexa/laravel-ai-verify, without leaving the framework.

The honest limits: Semitexa requires PHP 8.4 and Swoole 6.x and is developed and deployed with Docker; it has no FPM mode. Its ecosystem is its own packages, and its community is small. It runs semitexa.com and a few production projects, not thousands.

One task, three frameworks: the current tenant

A small task shows the difference in where state lives: a service needs the current tenant. These are minimal sketches of each framework's documented approach, not complete code.

Laravel Octane

Do not hand the singleton the request or a tenant object when it is built. Give it a way to ask for the current one, as the Octane docs recommend for the container and request.

// A singleton built once per worker must not keep the first request's tenant.
$this->app->singleton(InvoiceService::class, fn ($app) =>
    new InvoiceService(fn () => $app->make(CurrentTenant::class)->id())
);

Hyperf

Keep the tenant in the coroutine context and read it where you need it.

use Hyperf\Context\Context;

// In middleware, once per request (coroutine):
Context::set('tenant_id', $tenantId);

// In a singleton service:
$tenantId = Context::get('tenant_id');

Semitexa

Declare the lifetime on the property. The handler is a fresh clone per execution, and the tenant context is injected for that execution.

#[AsPayloadHandler(payload: InvoicePayload::class, resource: InvoiceResource::class)]
final class InvoiceHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]   // built once per worker
    protected InvoiceRepository $invoices;

    #[InjectAsMutable]    // this execution's tenant
    protected TenantContextInterface $tenantContext;
}

None of the three makes the mistake impossible. They differ in where the rule is written: in your discipline with Octane, in a context API with Hyperf, and in the type and attribute of each dependency with Semitexa, where a review or an agent can see it.

How to choose

You have a Laravel application

Start with Octane. Audit your singletons and statics, load-test, and keep the worker restart limit until you trust the code. Rewriting a working Laravel app in another framework for speed alone rarely pays off.

You are building services that mostly wait on other services

Hyperf's coroutine model, pools and service components are built for that work, and it has years of production use behind it.

You are starting a product with live pages, tenants and AI agents in the workflow

That is the case Semitexa was designed for: one typed path per request, tenancy and SSE in the framework, and a codebase agents can query and verify. Weigh that against a younger ecosystem and the PHP 8.4, Docker and Swoole requirements.

See the runtime before you choose: 80+ live Semitexa demos, each running on the server you are reading, or get started with Semitexa.

Common questions

Is Laravel Octane a Swoole framework?

No. Octane is a Laravel package that serves a Laravel application from a long-running server. Swoole is one of four servers it supports, alongside Open Swoole, RoadRunner and FrankenPHP.

Is Hyperf faster than Laravel Octane?

Hyperf publishes higher numbers in its own benchmark, and a coroutine-native stack usually does less work per request than a full Laravel boot kept warm. For most applications the database and external calls decide response time, so measure your own workload before choosing on throughput.

Can I use Laravel packages in Hyperf or Semitexa?

Not as Laravel packages. Hyperf has its own components and can use framework-agnostic Composer libraries. Semitexa uses its own packages plus framework-agnostic libraries. If the Laravel ecosystem is the reason you chose Laravel, Octane keeps it.

Does Semitexa run without Swoole or Docker?

No. Semitexa targets PHP 8.4 with Swoole 6.x and ships its runtime as Docker images, so the host needs Docker rather than a local PHP install.

What is the biggest risk when moving to long-running PHP?

State that outlives the request: a singleton that captured the first user, a static cache that only grows, a connection one coroutine is still using. Each framework gives you tools for it; none removes the need to think about lifetimes.

Originally published on the Semitexa blog.

Why is there still no plug-and-play data grid?

Taras Hanych — Thu, 15 Oct 2026 14:53:36 +0000

I've built more forms and data grids than I can count, and no two were alike. I'll never forget the magic of Magento 2 grids, or the hours I spent finding out why the magic wasn't working. In the end it was routine work, and then just boring work.

Every time, one thought came back: why is there still no universal, plug-and-play grid? A rhetorical question with a hundred answers. Here is mine, and what I tried instead.

A grid usually knows too much

Look at any admin grid you've shipped. The backend knows which columns exist, which ones can be sorted, which filters are allowed and how big a page is. Then the frontend knows all of it again: column definitions, sort keys, filter widgets, page sizes. Two descriptions of the same thing, kept in sync by hand.

They drift. Someone adds a sortable column on the server and forgets the client. Someone adds a filter in the UI that the query silently ignores. Every "plug-and-play" grid library I've used solved the rendering and left this part to me, because it can't know my backend.

Then the grid needs to be live, and it gets worse. Now there is a client store holding a copy of the data, and a WebSocket handler trying to keep that copy honest. Two systems that must agree: the server's truth and the browser's copy.

What if the grid knew nothing?

In Semitexa, the PHP framework I'm building, I tried the opposite. The page gives the grid an endpoint and nothing else:

{% include '@platform-ui/components/runtime/grid-v2.html.twig' with {
  gridId: 'showroom-exchange',
  endpoint: '/_feed/exchange',
} only %}

No columns, no sort keys, no filter definitions. The grid's first request is OPTIONS /_feed/exchange, and the answer is the route contract, built from the same attributes that run the request:

{
  "name":  "site.showroom.exchange",
  "modes": ["plain", "sse", "sse-update"],
  "collection": {
    "pagination": { "modes": ["page"], "defaultPerPage": 10, "perPageOptions": [10, 20, 40] },
    "sort":   { "fields": ["at", "asset", "trader", "amount", "status"] },
    "filter": { "fields": { "asset": ["eq"], "side": ["eq"], "status": ["eq"] } },
    "live":   { "scopes": ["site_showroom_exchange"] }
  }
}

The same declarations guard the way back in. Ask for a sort the contract doesn't offer and the request is refused before any row is read:

$ curl "https://semitexa.com/_feed/exchange?sort=lot"
HTTP 400
{"error": "invalid_sort", "allowed_fields": ["at", "asset", "trader", "amount", "status"]}

That is the part I stopped describing twice.

The table is a subscription

The second half is the live part. The grid doesn't keep a dataset. It subscribes over Server-Sent Events with its current view: page, page size, sort, search and filters. From then on the server holds that view.

Changing the sort doesn't fetch. The new view goes up as a small POST, and the answer arrives on the stream, in the same {data, meta} envelope a plain JSON request would return. The browser holds exactly one page, the one on screen.

When the data changes, the server re-runs each subscriber's own view and sends only what moved:

event: ui.collection.patch
data: {"patch": {"key": "id",
                 "upsert": [{"id": "TRX-985F23", "asset": "gold", "amount": "$108,268.81"}],
                 "remove": ["TRX-1A0C7E"],
                 "order":  ["TRX-985F23", "TRX-4C2BBB", "TRX-673208"]}}

A visitor on page three filtered to gold gets the patch for page three filtered to gold. A visitor whose page didn't change gets nothing. Rows that didn't change keep their DOM nodes, so focus and selection survive the update.

Nothing polls. The feed declares the scope it watches, and the code that changes the data says so:

$trade = $this->trades->place($payload->getAsset());
$this->invalidator->touch('site_showroom_exchange');

The bug was production, not the grid

semitexa.com runs four Swoole workers, each with its own in-memory cache. The first version kept the demo trades in that cache, so a trade placed on one worker was invisible to feeds held by the others. Locally, with a shared Redis cache, it worked perfectly. The tape lives in MySQL now.

What it costs

Server-owned views are not free:

One query per subscriber per publish. A thousand open grids on one scope re-run a thousand views. Patches keep the wire small, not the database work.
Every open tab holds a connection. One stream per page instead of one per widget, but still one per tab. Turn off proxy buffering, or frames sit in a buffer.
The grid itself is plain. No column resize, no inline editing, no charts in cells yet.

So, plug and play? Not for every stack. It works because the framework already describes its endpoints in a form the grid can read. But for the first time, a grid was the part I didn't have to describe twice.

You can try it with two tabs: place a trade in one and watch the other. The other traders are simulated, the frames are real, and a panel under the table shows each one as it crosses the wire: semitexa.com/blog/live-data-grid

Which grid cost you the most hours, and was it the rendering or keeping two descriptions in sync?

AI code verification for Laravel.

Taras Hanych — Mon, 12 Oct 2026 06:32:20 +0000

Claude Code, Cursor, Codex, Copilot or Gemini says the change is done. php artisan ai:verify checks whether it is.

It runs only the tests, Larastan, Pint and Laravel boot checks the diff actually needs. It fails the change if the agent deleted, skipped or weakened a test to get green. It returns one verdict the agent must act on: pass, fail or incomplete. One more command writes the instructions into AGENTS.md and CLAUDE.md. For Claude Code it also adds a Stop hook, so the agent cannot finish while verification fails. Verified commits get a trailer that CI can check.

Before the agent edits anything, php artisan ai:graph gives it a code graph of the Laravel app. It covers routes → controllers → form requests → models → tables → policies → views → tests, and events → listeners. It also does impact analysis: what a change affects and which tests cover it.

composer require --dev semitexa/laravel-ai-verify
php artisan ai:verify:install --hook

How it works: ai:verify reads what changed (uncommitted work, a git ref, or a file list). It works out the smallest set of checks that can vouch for that change and runs them with timeouts. The verdict comes as streamed NDJSON for agents, a JSON envelope or terminal text.

A timeout tells you what you know. Not what the receiver did.

Taras Hanych — Thu, 08 Oct 2026 12:30:00 +0000

Picture an integration. Your app sends a webhook: order 42 is confirmed, please create the shipment. The partner commits the shipment and returns success. The connection breaks before your sender reads the response.

From your side, delivery failed. From theirs, the work is done.

A timeout tells you what you know. It says nothing about what the receiver did. So you retry, and the only thing standing between your customer and a second parcel is whether the receiver can recognize that this is the same thing again.

I ran into this while documenting the webhook module of Semitexa, the PHP framework I'm building. The mechanics were fine. What turned out to be hard was the vocabulary: "the key" meant three different things depending on who was asking.

One key, three questions

When people say "make it idempotent", they usually mean one key. But there are three separate questions:

Publication identity: did we already queue this outbound intent for this endpoint?
Event identity: did the receiver already record this event?
Business identity: is the effect already done, one shipment for this fulfilment intent?

For the example, that could be order:42:confirmed:v1, evt-order-42-v1, and a business rule. They protect different things, and mixing them up fails in two opposite directions:

A fresh key on every retry and the receiver can never recognize the repeat.
One key for everything about order 42 and the next legitimate shipment (a replacement, a second confirmation) gets swallowed as a duplicate.

The rule I ended up writing down: the key describes what may happen once, and it has to survive every attempt at that same thing.

Retry the right failures

Not every failure deserves another attempt. The policy we settled on:

Result	Decision
2xx	delivered
408, 429	retry if attempts remain
other 4xx	permanent rejection
5xx, timeout, no status	retry with exponential backoff and jitter, within a budget

A 400 is the receiver telling you the request is wrong. Sending it again ten times is just noise. A 503 or a timeout is the opposite: you don't know, so you ask again, and the receiver's memory makes asking again safe.

"Duplicate" is not "completed"

This one is quiet. The receiver gets the event, records it in its inbox, and crashes before creating the shipment. Your retry arrives. The inbox finds the record and says: duplicate, ignore.

The shipment never happens, and every log line looks healthy.

An inbox match tells you the event was seen. It does not tell you the work was done. The recovery decision has to look at business state, not only at the inbox. Where the action is a local database write, the completion record and the business update should commit together. Where it's an external side effect, you need the recipient's own idempotency mechanism or an explicit reconciliation path.

A lease protects the record, not the request

Delivery workers claim a record with a lease. Suppose a worker sends the HTTP request, then loses its lease before writing "delivered". A well-behaved worker won't overwrite a record it no longer owns, and ours doesn't. Good. But the request has already gone out. The receiver may already have acted.

The lease coordinates your bookkeeping. It cannot retract anything on the other side. Which brings it back to the receiver: the repeat has to be recognizable there, by the event identity, and the effect has to be protected where it happens, by the business identity.

What I'd check in any integration

Can you name all three identities for your most important webhook?
Does a retry carry the same event identity as the first attempt?
If the receiver records and then crashes, what finishes the work?
Do you inspect business state before you replay anything by hand?

If question 3 has no answer, that's the one I'd fix first.

Which of the three identities does your integration actually store today?

The longer version, with the retry ranges, the inbox key format and the recovery cases, is on the Semitexa blog: Your Webhook Was Delivered Twice. Now What?

Your AI agent doesn't understand your codebase. It greps it.

Taras Hanych — Mon, 05 Oct 2026 12:30:00 +0000

Before touching a class, a careful developer asks one question: who depends on this?

An agent answers it the only way it can. It runs a text search, reads whatever comes back, and decides the change is local. Most of the time that's fine. The times it isn't are the expensive ones.

What grep can't see

I've been writing PHP for over 18 years, and the agent-written bugs that cost me the most had the same shape. The edit looked local. The nearby tests passed. Something three modules away broke.

In a modern PHP app a lot of wiring never appears as a string you can search for:

A handler is connected to its payload by an attribute, not by a call.
An event listener is discovered at boot by scanning, so nothing "calls" it.
A template reads a field by name, so renaming a property breaks a page that never imports the class.

Grep finds the string. It doesn't find the edge. So the agent does what a cautious person does with a flashlight in a dark warehouse: it reads more. Half the project lands in context "just to be sure", the answer gets slower and more expensive, and it is still a guess.

Give the agent a map instead

While building Semitexa, my PHP framework, I stopped asking agents to rebuild the structure from text on every task. The framework keeps a project graph: real edges between classes, collected from the same attributes and conventions the runtime itself uses. Edges like implements, handles, serves_route, returns.

Before an edit, the agent asks two questions:

bin/semitexa ai:review-graph:query --usages=<Class>
bin/semitexa ai:review-graph:impact <Class>

The first lists what points at a class. The second walks outward and returns the blast radius: the routes, handlers and templates downstream of a change. It comes back as data, so the agent acts on it instead of guessing.

What changed

The side effect I liked most wasn't accuracy. The agent stopped reading half the project. With the impact list in hand it opens the files that matter and leaves the rest alone. Less context, better decisions.

It also changed code review. "What else did this touch?" used to be a question I answered by reading the diff and remembering the codebase. Now it's a query.

The trade-offs

A map has its own failure modes, and they're worth being honest about.

It goes stale. A graph built once describes code that no longer exists five edits later. Ours refreshes by content hash when a query runs, and says so when it can't.

It has blind spots. Anything wired dynamically, like a class name built from a string, is invisible to a static scan. The useful behaviour is for the graph to say what it could not see instead of pretending coverage is complete. An impact report with an "unknown" section is more honest than a clean one.

It is only as good as the conventions. The graph works because the framework has one way to wire a handler and one way to declare a route. In a codebase where routes come from YAML on Monday and attributes on Friday, there are no clean edges to collect. That is a big part of why I care about frameworks having one way to do each job.

Grep still has a job

I use grep every day, and so does the agent. It is the right tool for finding text. It is the wrong tool for understanding a system, because a system is made of relationships, and relationships are exactly what text search throws away.

If you run agents on a large codebase, here is something cheap to try even without a framework: generate a rough dependency list for the area being changed and put it in front of the agent before it starts editing. Watch how much less it reads.

How do your agents judge the impact of a change today: tests, grep, a map, or trust?

I'm building Semitexa in the open. The project graph is described in more detail here: Project Graph in Semitexa.

Your AI Agent Fixed the UI. Where Did the Screenshot Go?

Taras Hanych — Fri, 02 Oct 2026 12:30:00 +0000

Picture a normal afternoon with a coding agent. It fixes a broken table layout, runs the checks, and opens a PR. To make review easy, it attaches a before/after screenshot. You glance at it, the table looks right, you approve.

Now the question nobody asked in that review: where is that screenshot hosted?

What PixelLeak found

Glow Labs published research they call PixelLeak this week. The mechanism is almost boring.

GitHub lets you attach an image to a PR comment by dragging it into the browser. There is no equivalent for a CLI, which is where coding agents live. An agent that wants to show the reviewer a screenshot hits a wall. Rather than fail, agents found a workaround: create a public repository under the developer's personal account, push the image there, and link to it from the PR. Some teams used an open source helper that does the same thing.

Glow counted over 13,000 internal images in 900+ public repositories, from more than 300 organizations. The screenshots showed customer billing records, internal treasury and settlement consoles, money movement screens, and features that hadn't shipped yet.

The agent did its job

What bothers me most: there is no villain in this story. Nobody told the agent to publish anything. It was told, more or less, "show the reviewer what you changed". A public repo is a place where an image URL works without authentication. From the agent's point of view, that is a perfectly good solution.

We spend a lot of energy on what an agent may change in the code: which files, which commands, which branches. We spend much less on where its byproducts go. Screenshots, logs, HAR files, screen recordings, test fixtures dumped from a real database. None of those are code, so none of them go through the same review. And a screenshot of an internal tool is often more sensitive than the diff it documents.

What I'd put in place

1. Treat review evidence as data. A screenshot of a billing screen is customer data, the same as a database dump. It falls under the same rules about where it may be stored and who may see it.

2. Give the agent a sanctioned place. If there is a private, approved location for evidence (an artifact store of your CI, a folder inside the project that never leaves your infrastructure), the agent has no reason to improvise. Agents improvise when the obvious path is blocked.

3. Make "I couldn't attach it" a valid outcome. The workaround happened because failing felt worse than succeeding creatively. Say in your agent instructions, and ideally enforce in tooling, that "here is the local path, I could not upload it" is a complete answer.

4. Restrict what the agent's credentials can do. If the token the agent uses cannot create public repositories, this whole class of leak is gone. That is a much stronger guarantee than a sentence in a prompt.

5. Audit today. Look at your GitHub account and your team's accounts for repositories nobody remembers creating, especially ones full of PNGs.

Where this sits in my own work

I'm building Semitexa, a PHP framework designed for working with AI agents. There, the agent's work log (what it planned, what it ran, what it verified) is kept as local files inside the project rather than on an external host. That was a design choice for reviewability, but PixelLeak made me realize it matters for leakage too. Screenshots and other visual evidence are not covered yet; they are on our list now, with the same rule: evidence stays where the code is. The longer version, with a test matrix for the refusal path, is on semitexa.com.

Your turn

How does your team handle visual evidence from agents today? Do you let them post screenshots to PRs at all, and if so, where do the files actually live?

AGENTS.md doesn't work. Here's what did.

Taras Hanych — Wed, 30 Sep 2026 12:30:00 +0000

I spent a long time trying to make AI coding agents follow project rules through instruction files: AGENTS.md, CLAUDE.md, a rules folder. For a handful of basic instructions it works. Put your whole development "bible" in there and it falls apart.

The pattern is probably familiar. The agent breaks a rule, apologizes, promises it won't happen again, and breaks it again two changes later. It isn't being lazy. A rule in the prompt is a wish: it competes with everything else in the context, and the longer the session, the weaker it gets.

What actually worked

While building Semitexa, an open-source PHP framework designed for agent-driven development, I moved the rules out of the prompt and into a command. The only instruction the agent gets about rules is this:

Check every code change you make with ai:verify. If it lets you pass, move forward.

ai:verify looks at what changed and runs the lint and the tests that matter for that diff, plus the structural checks: where logic is allowed to live, what may call what. When it fails, the agent gets a concrete message about the thing it just did.

Three things changed:

The rules stopped competing for context. Adding a constraint no longer makes the prompt longer, so I can have as many as the project needs.
Failures became specific. "Handler returns a raw Response" is something an agent can fix in one step. "Follow the architecture" is not.
The agent got better over the session. The feedback arrives right after the mistake, not at review time, and more and more often the next change passes on the first try.

What the instruction file is still for

I didn't delete AGENTS.md. It got short. Now it's a map: where things live, which commands to run, and the one rule above. Anything that can be checked moved into the check. Anything that can't be checked (naming taste, whether an abstraction pulls its weight, whether the change matches the intent of the ticket) stays with human review.

The trade-off

A check costs more to write than a sentence. Some rules are genuinely fuzzy and never become checks. But every time I noticed myself writing the same review comment twice, it turned out the rule was never fuzzy, just unwritten. Those are the ones worth turning into code first.

Your turn

Where do your project rules live today: in instruction files, in CI, or in reviewers' heads? And has anyone found a good way to measure how often an agent actually follows an instruction file?

From Idea to First Customer: How Semitexa Shortens Time to Market

Taras Hanych — Mon, 28 Sep 2026 10:40:15 +0000

The first release of a business product has one job: help a real customer complete something valuable. Every week spent rebuilding common software foundations is a week before you can learn from that customer.

The clock stops at a customer outcome

A deployed homepage is a milestone. A usable business is a different one. Imagine a client portal: a customer signs in, submits a request, sees its status, and receives an update when the team acts. The team can see who owns the request and respond. That complete loop creates value and produces feedback worth acting on.

Time to market is the time until that loop works for its first customer. It includes product decisions, implementation, review and release. The shorter that path, the sooner a founder can validate demand, refine pricing and find out what customers actually need next.

Most launch delays hide between the features

The visible screen is often the easy part. A real client portal also needs identity and permissions, persistent data, an interface people can use, notifications, background work and a way to check that one customer's information stays with that customer. Teams can spend their early budget joining these pieces before they get to the workflow that makes the product distinct.

Semitexa addresses that integration work with a coherent set of modules and conventions. Its Framework has typed routes and handlers, data access, authentication and authorization, tenant context, events, queues and API capabilities. Its Platform provides reusable interface building blocks. The ecosystem describes the OS as the experience layer, Platform as the interface layer and Framework as the execution layer. Each layer gives the team a clearer starting point for a different part of the product.

These capabilities still need product choices and configuration. Their value is that the team can make those choices around an existing structure, then spend more of its time on the customer journey.

Build the differentiator on a connected foundation

For the portal example, the differentiator might be how requests are assessed, routed and resolved. Semitexa lets a team focus on that flow while using established paths for the surrounding work:

Move from screen to behavior. A page generator can scaffold the payload, handler, resource and template together, so the first interaction has an application path behind it.
Keep customer boundaries visible. Tenant resolution and tenant-aware data patterns give multi-customer products a place to express ownership early.
Let work continue after the response. Events and queues provide a path for notifications and longer tasks without making the customer wait on the page.
Expose the same operation where it is needed. Typed API routes can support other clients and integrations as the product grows.

You can inspect these ideas in the running Framework Demo: scaffolding, tenant data isolation and queued work each have their own walkthrough. The examples are useful because a buyer can look past a feature list and see the implementation shape.

Release one complete workflow first

A focused first version of the portal could be deliberately small. Let a customer submit one request type. Let the team review it and change its status. Show the change back to the customer and send one notification. Put access rules and data ownership around that path. Then invite a real customer to use it.

That sequence gives a team something more useful than a large unfinished feature list: a working transaction to observe. The first conversations will reveal whether the request form asks the right questions, whether the team needs another status, and which update customers value. Semitexa's structure helps the team change the application without starting a second architecture each time the product learns.

The fastest launch is rarely the one with the most features. It is the one that reaches a trustworthy customer outcome with the least avoidable construction along the way.

Speed matters after the first release, too

Going live early helps only if the team can keep improving the product. Semitexa includes project-aware inspection, dependency impact queries and focused verification commands. Those tools help developers understand what a change touches and check it before release. They do not replace testing or product judgment; they shorten the distance from a customer observation to a reviewable change.

This is why Semitexa is a strong route to market for customer portals, SaaS workflows and operational software. The product's first useful path can be assembled from existing application capabilities, while the team keeps ownership of the business rules that make the venture worth building.

Start with the first customer, not a feature inventory

If you are planning a product, describe the first person who will use it and the one job they must be able to finish. Add what happens immediately afterward: who reviews it, what data belongs to whom, and what message needs to be sent. That is enough to shape a useful first release and identify which Semitexa capabilities belong in it.

Bring us that workflow. We can turn it into a concrete launch scope, show the technical path and make the next decision about your business easier.

What must your first customer be able to do?

Tell us about the workflow, the people involved and the launch goal. We will help you find the shortest credible path to a working product with Semitexa.

Discuss your project

Explore the Framework Demo

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

The Tenant Must Travel with the Work

Taras Hanych — Mon, 28 Sep 2026 10:39:53 +0000

The browser knows which customer is working. The queue knows that something needs doing. A reliable SaaS application has to preserve the connection between those two facts.

The request ends before the responsibility does

Imagine a customer uploading a product image. The application accepts it, schedules a thumbnail, and returns a success response. A worker will finish the expensive part later. To the customer, this is one action: “prepare my image.” To the software, it is already two executions.

The second execution may start after the browser tab has closed. It may run in another process. The hostname that identified the customer is gone, along with the request that carried it. Yet the thumbnail still belongs to the same organization, under the same business rules.

This is an illustrative scenario, but the architectural boundary is real. Moving work into a queue also moves responsibility for its context. A job can arrive intact and still arrive without enough information to run correctly.

A perfectly delivered message can be incomplete

A message containing an asset ID and a transformation name tells a worker what to process. Depending on the application, it may leave other questions unanswered: which organization’s configuration should apply, which locale should an accompanying notification use, and which environment does this work belong to?

Those answers might be recoverable from the asset. That can be a valid design. The fragile version is the one where each downstream service guesses differently, or reads whatever “current tenant” happens to be left in memory. Local testing with one customer rarely challenges that assumption. A shared worker serving many customers will.

Adding a tenant field to a database table addresses one part of the design. Preserving the execution context across a queue is another. Semitexa makes that handoff explicit with a shared tenant context and a serializer at the message boundary.

Make the context part of the handoff

TenantAwareJobSerializer::wrap() reads the current context from TenantContextStore. For a concrete, non-default tenant, it adds an envelope under _tenant. The receiving side can extract that envelope and rebuild the context before application work begins.

Resolve: establish the tenant for the incoming execution.
Attach: serialize the supported context into the message.
Restore: recover that context at the worker boundary.
Execute: run the operation with an explicit tenant context available.
Clear: end the context’s lifetime when the execution finishes.

The queue separates two executions. The envelope connects their tenant context; the execution lifecycle owns cleanup.

An illustrative wrapped payload looks like this. The application fields are examples; _tenant and its fields follow the serializer’s current format:

{
  "assetId": "image-42",
  "variantKey": "thumbnail",
  "_tenant": {
    "tenantId": "acme",
    "strategy": "subdomain",
    "locale": "en",
    "environment": "prod"
  }
}

The implementation serializes the organization ID and resolution strategy, plus locale and environment when those layers are explicitly present. It does not serialize every possible context layer. A custom layer needs an intentional propagation design of its own.

There is also a deliberate default case: when no context exists, or the organization is the default tenant, wrapping leaves the payload unchanged. Consumers therefore need a policy for messages without _tenant. A task that requires an organization should reject missing tenant identity at its boundary.

This already has a job in Semitexa

The media package provides a concrete example. MediaQueueDispatcher wraps a serialized transformation message before sending it. On the receiving side, MediaWorker::processPayload() calls unwrapAndRestore() before reconstructing the media message and processing it.

Unwrapping removes the envelope from the application payload. Restoring places the recovered context into the store’s CLI fallback. The transformation message keeps its own domain shape, while services that consult the context store have a tenant available during execution.

The media transformation path also passes the asset’s tenant ID explicitly when resolving collection policy and generating a variant. That detail matters: the queued context and the persisted asset identity play distinct roles. Application code still has to enforce the relationship between them wherever that relationship controls access or storage.

This is the concrete problem Semitexa addresses: the HTTP request can disappear without making an integrated background operation reconstruct tenant context from ambient process state. The producer and consumer share one envelope format and one restoration mechanism. Custom queue paths must wire those mechanisms into their own execution boundary.

A worker must also know when to forget

Now imagine the same worker processes a second message. It has no tenant envelope. If the first job’s context remains in memory, the second job may observe the first customer’s identity. Correct propagation into one job has become incorrect propagation into the next.

This is where tenancy meets the long-running PHP lifecycle. In a Swoole coroutine, Semitexa’s tenant store reads coroutine-local state. Outside a coroutine, it uses a process fallback. Those storage choices support different execution environments and require a clear end to each unit of work.

TenantContextStore registers cleanup with PerRequestStateRegistry when context is set. Its cleanup callback clears the context of the current execution: the coroutine-local slot inside a coroutine, the process fallback outside one. The surrounding runtime must actually invoke that lifecycle at the appropriate boundary.

The serializer alone does not provide that boundary. In particular, unwrapAndRestore() sets the fallback when an envelope exists; a message without an envelope does not make that method clear an earlier fallback. A custom worker loop must explicitly ensure cleanup, including on exceptions and early returns. A coroutine consumer must establish context in the coroutine’s own store rather than assuming the CLI fallback is visible there.

Preserve the tenant across the handoff. End its lifetime after the work. Both steps belong in the design.

Put each guarantee where it can be enforced

Once the context travels reliably, the rest of the application has a stable input. It still needs to use that input correctly.

Resolution determines which organization an execution refers to.
Authorization determines whether the actor or job may perform the action for that organization.
Data isolation scopes queries, cache keys, storage paths, and other resources where the application accesses them.
Propagation and cleanup preserve context across handoffs and prevent it from surviving into unrelated work.

The envelope carries identity; it does not prove permission. Queue ingress must be trusted or validated, tenant-owned records must be checked, and tenant-sensitive operations need an explicit policy for absent context. Semitexa supplies the context mechanisms. An application earns its isolation guarantee through the boundaries that consume them.

Test the handoff with two customers

A useful test goes beyond proving that one message round-trips through a serializer. Process work for tenant A, then tenant B, in the same worker. Follow both with a message that has no tenant envelope. Check what each operation can observe. Repeat the sequence with a failure during A’s work, so cleanup has to survive an exception.

At the serialization level, Semitexa’s tenancy package includes dedicated propagation tests. At the application level, test the effects: which configuration was selected, which records were accessed, and where the output was stored. Also check any locale or environment values the workflow promises to preserve. These are acceptance criteria for an integration, not a claim that a serializer test proves every application safe.

The larger lesson is useful well beyond media processing. Exports, notifications, and scheduled work all cross moments where the original request is no longer available. Making tenant context explicit turns those moments into boundaries that can be inspected and tested. A customer’s action can then continue after the response, with its ownership still accounted for.

Follow the lifetime of the work.

Explore tenant propagation in the Framework guide, then see why execution boundaries matter in a process that stays alive.

Explore tenant propagation

Read about long-running PHP

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Three Layers, One Workflow: OS, Platform, and Framework

Taras Hanych — Mon, 28 Sep 2026 10:39:30 +0000

A good business tool needs a place to work, an interface that makes the work clear, and a system that carries it out. Semitexa gives those three jobs distinct names.

Three layers, three questions

Think about a person reviewing an approval. They need to find the task, understand the details, and submit a decision. It is tempting to call all of that “the app.” Separating the responsibilities makes it easier to design the experience and to reason about the code behind it.

Start with the human need, then decide which layer owns each part. The arrows show a design conversation, not a requirement that every request passes through three separate services.

OS: where work has a home

Semitexa OS is the experience layer. Its job is the shape of a working day: how someone finds their projects, changes focus, and keeps context while moving between tools. A useful OS decision might be whether an approval is visible beside the project it belongs to, or how the workspace helps someone return to an unfinished task.

That is a product question before it is a component question. A polished button cannot repair a workflow that leaves people lost. The OS site presents this operating surface as a product vision; the layer map describes the intended responsibility, not a claim that every possible workflow is already shipped end to end.

Platform: how the work is presented

Semitexa Platform is the interface layer: reusable fields, data views, product shells, and interaction patterns. If the same kind of approval appears in several products, this layer is where the visual grammar should remain consistent. The Platform showcase demonstrates server-owned rendering, components, deferred regions, and live updates.

Reusability is useful only when it clarifies the task. A field should make its label, help, validation, and state legible. A data view should make scanning and acting on a row predictable. Platform supplies that common language while each product keeps its own purpose.

Framework: how the decision runs

Semitexa Framework is the execution layer. In its typed PHP flow, a payload describes an incoming request, a handler makes the application decision, and a resource returns the result. Server-rendered pages, events, tenancy, and long-running work can share that explicit architecture.

For an approval, application code still has to check who may act, apply the business rule, store the result, and decide whether an event should follow. A reusable interface does not make that decision for the server. The Framework site lets you inspect working routes and demos when you want to see how the underlying request and response fit together.

One workflow, three decisions

Imagine an approval inbox. This is an illustrative feature, not a claim that a shared inbox is already deployed across all three sites.

Experience: place the inbox where a person can find it in the context of their project, and make the next action obvious.
Interface: show the request in a readable data view, present the decision with a consistent control, and explain any validation error.
Execution: accept the action through a typed route, check permission and state in application logic, then return the updated result or publish follow-up work.

The boundaries help when a feature changes. If people cannot find the inbox, revisit the experience. If every inbox looks different, revisit the interface. If the action can be applied twice or by the wrong person, revisit execution. The separation turns a vague “the app feels wrong” into a question a team can answer.

Where to start exploring

Begin with the layer that matches your question. Explore the OS vision to see the working environment, the Platform showcase for reusable interface patterns, and the Framework installation guide when you are ready to trace or build the PHP flow. These sites currently show different parts of the ecosystem; the three-layer map gives them a shared design vocabulary.

Follow the question to the right layer.

Explore OS

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.