Kjell Tore Guttormsen 2da95b3cd3 feat(ultraplan-local): v2.2.0 — /ultra-cc-architect-local

New optional command between /ultraresearch-local and /ultraplan-local that
matches brief+research against Claude Code features (hooks, subagents, skills,
output-styles, MCP, plan-mode, worktrees, background-agents) and produces an
architecture note with brief-anchored rationale plus explicit gaps.

Added:
- commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps)
- agents/architect-orchestrator.md (opus) — 6-phase background orchestrator
- agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals
- agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts
- agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER
- skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern)

Changed (non-breaking):
- commands/ultraplan-local.md — auto-discovers architecture/overview.md
- agents/planning-orchestrator.md — cross-references cc_features_proposed
- plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword
- CHANGELOG, README, CLAUDE.md (plugin + marketplace root)

Pipeline becomes brief → research → architect → plan → execute. Architect is
optional; existing project dirs keep working unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-18 12:38:06 +02:00

3.2 KiB

Raw Blame History

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
hooks-reference	CC hooks API — event types, payload shapes, exit codes, and where hooks run.	reference	hooks	https://docs.claude.com/en/docs/claude-code/hooks	hooks-api-surface	2026-04-18	null	approved

Hooks — Reference

Hooks are shell commands or scripts that the Claude Code harness runs in response to events. They give the harness — not Claude — the final say on whether a tool call, prompt, or session action proceeds. Claude cannot bypass a hook by prompting itself; the hook runs outside the model's control loop.

Event types

UserPromptSubmit — fires when the user sends a prompt. Runs before Claude processes it. Common use: inject extra context, reject disallowed prompts.
PreToolUse — fires before a tool call. Can deny the call. Common use: block destructive commands, require confirmation.
PostToolUse — fires after a tool call completes. Sees the result. Common use: log side effects, redact output, trigger follow-up work.
Stop — fires when the agent finishes a turn. Common use: commit reminders, session summaries.
Notification — fires when Claude wants to show the user a notification (e.g., long-running task).
SessionStart — fires when a session begins. Common use: print repo state, inject context.

Payload shape

Hooks receive a JSON payload on stdin. Common fields:

session_id — the current session identifier.
transcript_path — path to the conversation transcript.
cwd — current working directory.
tool_name (PreToolUse, PostToolUse) — which tool is running.
tool_input (PreToolUse) — the arguments to the tool.
tool_response (PostToolUse) — the tool's result.
prompt (UserPromptSubmit) — the submitted text.

Exact field availability depends on event type. Read the payload JSON rather than assuming a schema.

Exit codes and control

Hooks communicate back via exit code and stdout JSON:

Exit 0, no stdout → proceed normally.
Exit 0, stdout JSON with decision field → harness honors the decision (e.g., {"decision": "block", "reason": "..."}).
Exit non-zero → harness treats as a denial or error, depending on event and hook type.

Some hook types support structured output beyond deny/allow (e.g., adding context to the prompt). Details differ per event.

Where hooks live

Project hooks: .claude/settings.json hooks field, paths relative to project.
User hooks: ~/.claude/settings.json (global).
Plugin hooks: packaged with a plugin, activated when the plugin is enabled.

Hooks run in the harness process's shell, not in Claude's tool-use sandbox. They can spawn subprocesses, read environment variables, and touch the filesystem.

Implications for architecture

Hooks are the mechanism for deterministic policy (things that must always or never happen, regardless of what Claude decides).
Hooks are load-bearing for security: prompt-injection-resistant defenses live here, not in prompts.
Hooks add latency to every tool call they gate — keep them fast.
Hook output is part of the context window; verbose hooks burn tokens quickly.

3.2 KiB Raw Blame History