Claude Hooks Sdk Laravel Package

Product Decisions This Supports

Build vs. buy for AI-agent guardrails — and a third option: "just use bash." Claude Code hooks are the enforcement point for what an autonomous coding agent is allowed to do. This SDK turns that enforcement layer into typed, testable, reviewable PHP instead of scattered shell scripts. For a PHP/Laravel shop, it is a build option that costs hours rather than a sprint, is ownable by engineers already on payroll, and adds no new runtime or vendor contract.

Roadmap sequencing for a governed AI rollout. Each hook is an independently shippable, independently measurable guardrail a PM can order and fund:

1. Secret/credential write-blocker — deny writes to .env, CI secret files, infra config.
2. Destructive-command blocker — rm -rf, git push --force, production migrations.
3. Quality gate on edits — auto-format plus PHPStan/Pint after Edit/Write, with failures returned into the agent's context so it self-corrects rather than stalls.
4. Audit trail — every tool invocation, decision, and input hash logged into the Laravel log/metrics pipeline the org already trusts.
5. Context injection — branch, ticket ID, feature flags prepended to prompts.
6. Notifications — Slack/email on Stop or Notification for long-running tasks.

Definition of "done" for agent governance. Hooks convert a policy document ("the agent must not touch production config") into an executable, code-reviewable artifact. That is a product deliverable, not an engineering nicety, and it is the difference between a policy that exists and one that is enforced.

Audit and compliance evidence. Every agent action becomes attributable and reviewable — which directly answers SOC 2 and internal-audit questions like "who let the agent touch production config?" and supports post-incident review of AI-assisted changes. Reconstructing this after the fact is expensive; capturing it inline is nearly free.

Enforcement-layer decision: agent-time vs. CI. Hooks prevent the action; CI catches it afterwards. Hooks are the cheaper feedback loop — no round-trip to a pipeline — while CI remains the backstop. Make this an explicit decision rather than duplicating policy in both places.

Metrics to instrument from day one: hook invocations per repo, blocked-action count and reason, false-positive/override rate, p95 latency added per agent interaction, and percentage of repos with a committed hook config. The last one is the leading indicator that the "AI-assisted development" initiative has crossed from experimentation into governed rollout — often the specific evidence needed to unlock a broader mandate and budget.

Reuse of existing platform investment. Hooks written in PHP call internal services through the HTTP client, config, and logging already in place, and land in the same repo, review flow, and test suite as everything else. No second language for the platform team to support.

Scope boundary. This is developer tooling, not application runtime. Model it in require-dev, deploy it at the repository and workstation level, and never let it appear in a production request path.

When to Consider This Package

Adopt when:

• The org is PHP/Laravel-centric and is expanding Claude Code beyond a handful of engineers.
• Hook logic is more than a two-line shell script — you need typed payload parsing, conditional branching, and unit tests.
• Someone must own the guardrails long term, and that person writes PHP, not bash or Python.
• Hooks need to reach internal APIs, config, or logging without standing up a separate runtime.
• You are prepared to pin an exact version and wrap the SDK behind a thin internal interface, because the hook event schema is owned by Anthropic and will change.

Look elsewhere when:

• Hooks are trivial — one command, no branching. Plain shell in .claude/settings.json is cheaper and carries no dependency risk.
• The team is not PHP-first. Anthropic's docs and community examples skew shell/Python/Node; a mismatch creates a permanent support burden.
• You need vendor SLAs, LTS, or a completed security review. This is a 68-star package with a single July 2025 release from a credible vendor (Beyond Code) — but a side SDK, not a supported product.
• Zero dependents means the API surface is unproven; do not put it on a critical path without a fallback.
• The underlying need is really CI policy, not agent policy — enforce where gates already exist and keep hooks thin.

Risk posture to state up front. MIT-licensed and cheap to trial, but treat it as early-stage. Budget roughly a day to spike against the current hook schema, define one internal interface plus one payload DTO, and design so each hook can fall back to raw shell if the package stalls. Assign a named owner and a quarterly version-tracking review, since the SDK and Claude Code move on independent schedules. Design against three failure modes: silent schema drift after a CLI upgrade, a hanging hook blocking the agent session, and a misconfigured hook that never fires and is never noticed — mitigate with fail-open exit codes, hard timeouts, invocation telemetry, and an upgrade canary. Support is community-only: acceptable for developer tooling, disqualifying for anything gating a production deploy.

How to Pitch It (Stakeholders)

Executives. As we expand AI coding agents, the risk shifts from "can the model write code" to "what is it allowed to touch." This MIT-licensed package lets our existing PHP team put enforceable, auditable guardrails around the agent — blocking destructive commands, protecting secrets, logging every action — in days rather than a quarter, with no new vendor contract and no new language in our stack. It is a small, reversible bet that de-risks a much larger AI-rollout decision and produces compliance evidence we would otherwise have to reconstruct after the fact.

Engineering leadership. It is a Composer dependency (kept in require-dev) that provides typed hook payloads and testable PHP classes, so guardrails live in the same repo, code review, and test suite as everything else. We pin the version, wrap it behind one internal interface with one payload DTO, and keep a shell fallback — total exposure is a one-day spike plus one class to swap. In return we get a single place to evolve our AI-agent policy as the hook schema changes, and telemetry on what the agent actually tried to do. Note the portability prerequisite: Claude Code and a PHP binary must exist on every developer machine and CI runner that triggers a hook.

The engineering team. Install it, write hooks as small classes, test them like anything else, and stop hand-rolling JSON parsing in bash. Verify the plumbing before the logic — ship a hook that dumps the raw payload and always allows, confirm events are actually arriving, then add rules; "the hook doesn't fire" is almost always a matcher/config problem, not an SDK problem. Start with one guardrail — a write-blocker on credentials and infra paths — prove it in a week, then layer on formatting gates and audit logging. Keep hooks fast and bounded by hard timeouts, and make deny messages actionable so the agent self-corrects instead of stalling.