ww-agentic-workflows 1.0.0.dev3__tar.gz → 1.0.0.dev6__tar.gz

ww_agentic_workflows-1.0.0.dev6/.claude/skills/noww/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, `./ww lookup` or `./ww record`, and do not
+start, continue, or complete a ww task. Carry out requests directly, as in a
+project without ww. A ww task already in progress stays as it is; do not reset
+or fail it.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev6}/.claude/skills/ww/SKILL.md

@@ -17,17 +17,29 @@ change, start from step 1 then.
    carry out the request without ww and do not ask.
 2. To continue an existing task, run
    `./ww instruction <task-id> --role manager` instead of starting a new one.
-3. Otherwise choose the workflow that matches the request, keep its default
-   modes unless the user's wording matches another mode, and start the task
-   with the start command `discover` shows. Pass the user's requirements,
-   normalized, as `--requirements`. When the request names an external
-   ticket, such as a Jira key, use that key as the task ID; omit the ID only
-   when there is none or the workflow obtains its own.
-   When no workflow fits and you are about to change files, do not start
-   `catchall` directly: run `./ww lookup [<task>] --agent <agent>` with the
-   task the conversation works on or the request names, as written, and
-   follow its answer, then do the work as you would without ww. Read-only work
-   needs no task.
+3. Otherwise decide how the request is carried out, in this order:
+   a. It names a ticket or clearly matches a configured workflow's
+      description, and is more than a small change: propose that workflow, and
+      offer the alternative in the same choice, "run `<workflow>`" / "just do
+      it, register afterwards". A workflow the user named is started without
+      asking. When one is chosen, keep its default
+      modes unless the user's wording matches another mode, and start the task
+      with the start command `discover` shows. Pass the user's requirements,
+      normalized, as `--requirements`. When the request names an external
+      ticket, such as a Jira key, use that key as the task ID; omit the ID
+      only when there is none or the workflow obtains its own.
+   b. Otherwise it is direct work: do it as you would in a plain conversation,
+      with no question asked, then run
+      `./ww record <task> --summary "..."`. `./ww lookup [<task>] --agent
+      <agent>` names the task and the command; pass the task the conversation
+      works on or the request names, as written. Read-only work needs no task.
+   c. Judge each prompt on its own. A series of small requests stays a series
+      of direct-work entries; never promote them into a workflow because they
+      add up.
+   d. Ask only when it is genuinely ambiguous, and never again on the same
+      task once the operator chose direct work.
+   e. If `record` fails or is forgotten, ww records the commits it had not
+      seen on the next run; say so, and do not retry it endlessly.
    When the first page of `start` says rules have no check
    yet, tell the user once and carry on: it never blocks the task, and the
    `ww-scriptize` skill builds those checks when they want it.

ww_agentic_workflows-1.0.0.dev6/.codex/skills/noww/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, `./ww lookup` or `./ww record`, and do not
+start, continue, or complete a ww task. Carry out requests directly, as in a
+project without ww. A ww task already in progress stays as it is; do not reset
+or fail it.

ww_agentic_workflows-1.0.0.dev6/.codex/skills/ww/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ww
+description: Carry out a development request through ww, this project's workflow tool. Use only when the request changes something (implement, fix, refactor, merge, edit documentation) or the user explicitly asks to work via ww, to start or continue a ww task, or to run a ww workflow; where `./ww discover` says ww is used by default, use it before changing files for any request, since every change then goes through ww. Never use it for reviews, questions, explanations, investigations, status checks or other read-only work, even when they concern ww or a ww task.
+---
+
+# Work through ww
+
+ww is for development: requests that change files. A review, question,
+explanation, investigation, status check or other read-only request never
+goes through ww; answer it directly, without these steps and without a task,
+even where ww is used by default. When a read-only conversation turns into a
+change, start from step 1 then.
+
+1. Run `./ww discover` and read all of it. If it says ww is disabled, stop:
+   do not use ww, and tell the user. If it says ww is used only on request
+   and the user did not explicitly ask for ww (invoking this skill counts),
+   carry out the request without ww and do not ask.
+2. To continue an existing task, run
+   `./ww instruction <task-id> --role manager` instead of starting a new one.
+3. Otherwise decide how the request is carried out, in this order:
+   a. It names a ticket or clearly matches a configured workflow's
+      description, and is more than a small change: propose that workflow, and
+      offer the alternative in the same choice, "run `<workflow>`" / "just do
+      it, register afterwards". A workflow the user named is started without
+      asking. When one is chosen, keep its default
+      modes unless the user's wording matches another mode, and start the task
+      with the start command `discover` shows. Pass the user's requirements,
+      normalized, as `--requirements`. When the request names an external
+      ticket, such as a Jira key, use that key as the task ID; omit the ID
+      only when there is none or the workflow obtains its own.
+   b. Otherwise it is direct work: do it as you would in a plain conversation,
+      with no question asked, then run
+      `./ww record <task> --summary "..."`. `./ww lookup [<task>] --agent
+      <agent>` names the task and the command; pass the task the conversation
+      works on or the request names, as written. Read-only work needs no task.
+   c. Judge each prompt on its own. A series of small requests stays a series
+      of direct-work entries; never promote them into a workflow because they
+      add up.
+   d. Ask only when it is genuinely ambiguous, and never again on the same
+      task once the operator chose direct work.
+   e. If `record` fails or is forgotten, ww records the commits it had not
+      seen on the next run; say so, and do not retry it endlessly.
+   When the first page of `start` says rules have no check
+   yet, tell the user once and carry on: it never blocks the task, and the
+   `ww-scriptize` skill builds those checks when they want it.
+4. Follow every ww response exactly: run each displayed command with all
+   placeholders replaced, and keep going until ww reports that the workflow
+   is complete or reports an error. On `interactive: true` steps, converse
+   naturally until intent to finish is clear, ask if ambiguous, and treat
+   "done for today" as a pause. Record and end the interaction before
+   completing it. Use the host choice tool when available; keep asynchronous
+   choices pending until an answer arrives, and do not treat timeouts or
+   preselection as answers. After completion, relay any optional
+   `ww-deduce-feedback` suggestion; do not insert learning into the plan.
+   Deduction uses ww commands and explicit existing point IDs; rule review
+   and pruning are separate, and rules require operator approval.
+5. Never run a ww-owned handler yourself, edit ww state, or read
+   `ww.yaml` or ww's source to work out what to do next. For a handler repair
+   assignment, fix the cause and complete with an artifact; ww retries the
+   command. In `auto`, the manager dispatches the repair with `next`. When
+   ww reports `awaiting_operator` (a failed handler or work, an interrupted
+   command, a loop at its iteration limit, a changed workflow), stop and report the task, its
+   `operator_reason` and the exact error to the user (unless they gave a
+   standing authorization for routine repairs such as dependency installation,
+   formatting or retries: apply it to a stop of that kind without asking again,
+   and ask only for a material decision or an action outside it); when they
+   decide, run the recovery command ww showed, `./ww next <task-id> --retry` to run the
+   handler again, `--force --reason` to skip it or leave the loop, or
+   `--replan` / `--keep-plan` for a changed workflow. A `pass_incomplete`
+   stop is cleared by recording what it names with `./ww update-item`, then
+   `./ww next <task-id> --retry`; `--force` is refused there.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev6}/CHANGELOG.md

@@ -11,6 +11,65 @@ yet, is in [documentation/limitations.md](documentation/limitations.md).
 
 ## 2026-10-05
 
+- Fixed: in the `auto` runtime, a worker's `loop --continue` below the loop's limit left the task stuck: the
+  continue ended the assignment yet opened the next round's first step for a worker that no longer held a
+  token, so the worker's next command was refused and the manager's `next` reported a step in progress. The
+  continue now ends the assignment with its handoff block, and the manager's `next` dispatches the first step
+  of the next round as a new assignment.
+- Removed: the session-start task list, stop reminders, interruption records and transcript recovery, and the
+  `interrupted` command. Hooks, events and `agent_hooks` keys stay accepted. `5414a34`
+- Added: `add-child` is accepted while a per-child stage of a roadmap-style parent is active, not only while the
+  collecting step is. The new child is appended after the last planned child with its own expanded lifecycle;
+  once the last child's stages have finished the command is refused. `00338d9`
+- Added: `ww handoff <task> [--run ID] [--assignment TOKEN] [--json]` prints the handoff block of an ended assignment
+  again, for a worker whose output was cut short; the completion page and the `auto` runtime instruction name it.
+  The change set is reproduced only while the assignment is the latest one, otherwise the block says so. `aae3ed2`
+- Fixed: when a child task's run has completed, its handoff block names the parent task's `next` command
+  ("Manager: continue with the parent task: ...") instead of a command that fails because the child is completed;
+  a child partway through its run keeps its own. The handoff JSON carries `continuation_task_id`. `6b6669c`
+- Fixed: a child task's `ww/git` worktree is named like its branch, the parent's rendered `worktree_name_format`
+  plus `-<child id>` (`ww-worktrees/TASK-51-A`), so it no longer lands inside the parent's checkout as untracked
+  content; any other rendered name holding a `/` has each one replaced with `-`. Worktrees already created inside
+  a parent's are not migrated. `6b6669c`
+- Fixed: the continuation line of a requested-worker page names the flags (`--selected-agent`, `--model`,
+  `--reasoning`) whose values follow the request. `6b6669c`
+- Changed: ww's own roadmap workflow's `fix` step tells the worker to prefix its commits with the child ID, as the
+  child's own commits are. `6b6669c`
+
+- Added: direct work replaces the `catchall` workflow. A change no workflow fits is made as in a plain
+  conversation and registered afterwards with `record <task> --summary "<text>"`, which appends an entry to
+  the task's `direct-work.json` with the commits ww finds itself (the task's recorded branch since its base,
+  minus the commits ww already knows; without a recorded branch, the current branch's commits that name the task
+  ID). A task needs no run, and `lookup` no longer asks before a task ww has not seen. When the manager asks for
+  a task's page with `instruction --role manager`, ww records any commits it had not seen as a `reconciled` entry
+  and prints one line at the top of the page, so a forgotten or failed `record` is made up for. `status` lists the
+  entries and short SHAs. The agent instructions, the `ww` and `noww` skills and `discover` now say: propose a
+  matching workflow with "just do it, register afterwards" as the alternative, otherwise work directly and ask
+  nothing, judge each prompt on its own, and never ask again on a task once direct work was chosen. Existing
+  projects keep their installed skills; `init --force` or copying the bundled ones picks up the new wording.
+- Removed: the `catchall` workflow, its `discover` section (`catchall` is gone from the JSON, `direct_work`
+  replaces it) and the `lookup` menu. A `catchall` entry under `workflows` in `ww.json` is ignored and `lint`
+  warns about it, instead of failing.
+- The repair page for a failed automatic handler now says what to do when the cause is the environment rather than
+  the work (a sandbox or permission denial, a network or package-install error, a held lock): change no project
+  files, fix the environment or ask the operator, and say in the completion that the cause was environmental.
+- A rule file can narrow a rule to files by content with `contains`, a list of plain, case-sensitive strings (no
+  regular expressions) in its frontmatter: a file must match a `paths` glob, if any, and contain one of the
+  strings. A check whose strings are in no changed file is not applicable, a converted check covering several
+  rules takes the union of their strings, and the step page prints the strings beside the globs. `rules add` and
+  `rules edit` take `--contains <text>...` and report how many project files hold each string. Rules written in a
+  step's own `rules` list still take no `paths` or `contains`.
+- `complete` and `loop` take `--adjustments "<text>"` for the changes the operator asked for during a step. ww
+  stores it on the step record, shows it in `status`, beside the summary on the next step's page and on the
+  verifier's page, and hands it to feedback deduction as a labelled `adjustments` field; a repair completion
+  refuses it. Every worker step page now asks the worker to record such requests in the artifact and in the flag.
+- A workflow can set `manual: true`: `discover` and `lookup` leave it out, `start` still accepts it, and `inherit`
+  does not copy the setting. A workflow named `manual` in the `- name: description` shorthand must now use the
+  `name:` key.
+- A handoff now gives the new run the target workflow's declared `runtime`, and replaces the run-level `model` and
+  `reasoning` with the target's declared values, keeping the source run's values for what the target does not
+  declare.
+- The specification and features now describe how a child gets its external ID.
 - The `ww` skill and agent instructions now say ww is only for development: reviews, questions, investigations,
   status checks and other read-only requests never invoke the skill or start a task. Existing projects keep their
   installed skill; `init --force` or copying the bundled one picks up the new wording.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ww-agentic-workflows
-Version: 1.0.0.dev3
+Version: 1.0.0.dev6
 Summary: A local-first, resumable workflow CLI for people and AI agents.
 Project-URL: Homepage, https://agenticworkflows.dev
 Project-URL: Documentation, https://github.com/from-developers-for-developers/agentic-workflows/tree/main/documentation
@@ -323,14 +323,14 @@ one:
 - `--role manager` is the role driving the task; a worker performing a single
   assignment uses `--role worker`.
 
-A request no workflow fits still goes through ww once it changes files. The
-agent records it with `catchall`, a one-step workflow ww provides to every
-project, and otherwise works exactly as it would without ww. Questions and
-other read-only work never start a task. The agent first runs `./ww lookup`
-with the task you named, however you wrote it (`12345` finds `FOOBAR-12345`),
-and a task ww has never seen is only created after you confirm it in the
-agent's choice menu. Say `/noww` when you want the
-agent to leave ww out.
+A request no workflow fits is direct work: the agent does it exactly as it
+would without ww, then registers it with `./ww record <task> --summary "..."`,
+and ww keeps the summary and the commits it finds for it. Questions and other
+read-only work never start a task. The agent first runs `./ww lookup` with the
+task you named, however you wrote it (`12345` finds `FOOBAR-12345`), and asks
+you nothing unless the request clearly matches a workflow, in which case it
+offers that workflow or "just do it, register afterwards". Say `/noww` when
+you want the agent to leave ww out.
 
 If you would rather open the task yourself — to pin an external ticket key, or
 to hand a prepared task to an agent — the same command works typed in.
@@ -649,7 +649,7 @@ ww-agentic-workflows complete TASK-123 --role worker \
 - [architecture.md](documentation/architecture.md) describes internals, boundaries, state, and
   design decisions.
 - [agent-hooks.md](documentation/agent-hooks.md) covers the agent's own hooks
-  (session-start, stop, interrupt): what they do, per-agent support, and
+  (the session-start line): what it does, per-agent support, and
   install/uninstall/show.
 - [examples.md](documentation/examples.md) is a set of complete, tested
   `ww.yaml` examples, one per control or behaviour.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev6}/README.md

@@ -285,14 +285,14 @@ one:
 - `--role manager` is the role driving the task; a worker performing a single
   assignment uses `--role worker`.
 
-A request no workflow fits still goes through ww once it changes files. The
-agent records it with `catchall`, a one-step workflow ww provides to every
-project, and otherwise works exactly as it would without ww. Questions and
-other read-only work never start a task. The agent first runs `./ww lookup`
-with the task you named, however you wrote it (`12345` finds `FOOBAR-12345`),
-and a task ww has never seen is only created after you confirm it in the
-agent's choice menu. Say `/noww` when you want the
-agent to leave ww out.
+A request no workflow fits is direct work: the agent does it exactly as it
+would without ww, then registers it with `./ww record <task> --summary "..."`,
+and ww keeps the summary and the commits it finds for it. Questions and other
+read-only work never start a task. The agent first runs `./ww lookup` with the
+task you named, however you wrote it (`12345` finds `FOOBAR-12345`), and asks
+you nothing unless the request clearly matches a workflow, in which case it
+offers that workflow or "just do it, register afterwards". Say `/noww` when
+you want the agent to leave ww out.
 
 If you would rather open the task yourself — to pin an external ticket key, or
 to hand a prepared task to an agent — the same command works typed in.
@@ -611,7 +611,7 @@ ww-agentic-workflows complete TASK-123 --role worker \
 - [architecture.md](documentation/architecture.md) describes internals, boundaries, state, and
   design decisions.
 - [agent-hooks.md](documentation/agent-hooks.md) covers the agent's own hooks
-  (session-start, stop, interrupt): what they do, per-agent support, and
+  (the session-start line): what it does, per-agent support, and
   install/uninstall/show.
 - [examples.md](documentation/examples.md) is a set of complete, tested
   `ww.yaml` examples, one per control or behaviour.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev6}/WW_AGENT_INSTRUCTIONS.md

@@ -3,8 +3,7 @@
 ww saves progress, runs handlers, and names the next role; it is only for
 development. Where ww is used by default, every file change goes through ww
 unless the user asks you not to. Reviews, questions, investigations and other
-read-only work never use ww, its skill or a task. When no workflow fits a change, run
-`./ww lookup [<task>] --agent <agent>` and follow it; it never creates a task without operator confirmation.
+read-only work never use ww, its skill or a task.
 
 ## Start here
 
@@ -14,7 +13,7 @@ Before starting new work, run:
 ./ww discover
 ```
 
-It lists the project's workflows, modes, the start command, resume commands, and
+It lists the project's workflows, modes, the start command, and
 whether to use ww unasked. If disabled, stop; if used only on request, use it only when
 the user asks for ww. Choose the matching workflow and keep its default modes
 unless the request matches another mode; ask only when the choice would
@@ -23,6 +22,17 @@ materially change the work.
 When a request names an external ticket, use that as the task ID. Omit the ID
 only when none is named or the workflow obtains it in its first step.
 
+A request that names a ticket or clearly matches a workflow's description, and
+is more than a small change: propose that workflow, and offer the alternative in
+the same choice, "run `<workflow>`" / "just do it, register afterwards". Any
+other request is direct work: do it as in a plain conversation, ask nothing,
+then run `./ww record <task> --summary "..."` (`./ww lookup [<task>] --agent
+<agent>` names the task). Judge each prompt on its own; a series of small
+requests stays direct work, never a workflow. Ask only when genuinely ambiguous,
+and never again on a task once the operator chose direct work. If `record`
+fails or is forgotten, ww records the commits on the next manager
+page (`instruction --role manager`): do not retry.
+
 To continue an existing task, run `./ww instruction <task-id> --role manager`;
 a worker resuming its assignment uses `--role worker`. Check status with
 `./ww status <task-id>`.

ww_agentic_workflows-1.0.0.dev6/documentation/agent-hooks.md

@@ -0,0 +1,135 @@
+# Agent hooks
+
+ww's instructions to agents are static, so a session needs one pointer to
+find ww at all. Agent hooks are the agent's own hooks, installed with `ww hook`
+— not the workflow hooks of `ww.yaml` (see
+[Workflow hooks, variables, and transitions](features.md#workflow-hooks-variables-and-transitions)
+in the feature reference), which run as part of a plan and can run
+handlers, gate completion, or trigger a check. Agent hooks are gentle by
+design: they add one line of context, and nothing they do ever blocks the
+agent.
+
+ww registers one hook, `session-start`, which runs when a session starts,
+resumes, or is compacted. It prints a reminder that ww coordinates work here
+(under `"enabled": "on_request"`: that ww is used only when the user asks for
+it) and how to list its workflows. It lists no task: `discover` lists the
+project's workflows, and the operator names the task to continue.
+
+There is no pre-spawn hook yet: ww does not intercept an agent's own
+subagent calls. `subagents: false` is enforced only through the step's
+page today; see [Agent limitations](limitations.md#agent-limitations).
+
+## What `session-start` prints
+
+What `session-start` prints stays in the agent's context for the whole
+session, so it is one line:
+
+```text
+This project coordinates work through ww: `./ww discover` lists its workflows.
+```
+
+After a compaction it starts with a line before that one: "Context was
+compacted; ww's task state is authoritative." Only the main session gets this
+context: no hook is registered for a subagent's start, since a worker receives
+its bootstrap command from the manager.
+
+## `stop` and `interrupt` are retired
+
+Earlier versions of ww also registered `stop` and `interrupt` hooks, which
+listed unfinished tasks, reminded an agent to close a step, and recorded
+interrupted sessions. They are gone: a reminder written for one session
+confused another, and nothing in them was needed to continue a task.
+
+The events stay accepted so a hooks file written by an older ww keeps
+working. `ww hook stop` and `ww hook interrupt` exit 0 with no output and
+record nothing; the audit log notes the call. The `agent_hooks` keys
+`check_unfinished` and `recent_days` in `ww.json` are still validated and
+still accepted, and have no effect. Running `hook install` again replaces an
+older registration with the one `session-start` entry, and `hook uninstall`
+removes every ww entry, whichever events it registered.
+
+## Agents and their files
+
+| Agent | Project file | Native event | Local file |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `SessionStart` | `.claude/settings.local.json` |
+| Codex | `.codex/hooks.json` | `SessionStart` | none; user file `~/.codex/hooks.json` |
+| Cursor | `.cursor/hooks.json` | `sessionStart` | none; user file `~/.cursor/hooks.json` |
+| Antigravity | `.agents/hooks.json`, group `ww` | `PreInvocation` | none; user file `~/.gemini/config/hooks.json` |
+
+Claude Code's `SessionStart` has no matcher, so it fires for every source,
+compaction included. Antigravity has no session-start event, so ww answers
+only its first pre-invocation of a conversation, as an ephemeral message that
+never accumulates. Codex loads project hooks only once the project's `.codex/`
+layer is trusted: review them with `/hooks` in Codex.
+
+These per-agent gaps (no session-start event, a trust gate) are permanent
+differences between agents, not bugs; see
+[Agent limitations](limitations.md#agent-limitations) for the summary.
+
+## Install, remove, and show
+
+```console
+ww-agentic-workflows hook install --agent claudecode
+ww-agentic-workflows hook uninstall --agent codex
+ww-agentic-workflows hook show --agent cursor
+ww-agentic-workflows hook install --agent claudecode --local
+```
+
+`install` merges ww's entry into whatever the file already holds and leaves
+every other entry alone. ww recognises its own entries by their command, so a
+second `install` changes nothing and `uninstall` removes exactly what ww added,
+including the `stop` and `interrupt` entries an older ww registered. `show`
+prints the file and the exact snippet, that is, what ww registers, for a
+machine or an agent where `install` cannot run. A file that is not valid JSON,
+or cannot be written, makes `install` fail with the path and the full snippet
+to add by hand.
+
+`--local` writes the agent's project file kept out of version control, so the
+hooks stay one person's choice. Only Claude Code has one,
+`.claude/settings.local.json`; for the other agents `--local` fails and names
+their user-level file, which applies to every project on the machine. Without
+`--local` the hooks go into the shared project file, which is usually committed,
+so everyone who clones the project gets them. When ww's hooks sit in both of
+Claude Code's files every hook would run twice, so `install` and `show` print a
+notice with the command that removes one copy.
+
+The registered command calls the project's tracked `./ww` launcher: through
+`"$CLAUDE_PROJECT_DIR"` for Claude Code, from the project root for Cursor, and
+from the repository's top level (`git rev-parse --show-toplevel`) for Codex and
+Antigravity. The launcher resolves the durable root through the shared Git
+directory, so a session in a task worktree reaches the same state; the launcher
+must therefore be tracked for worktree sessions.
+
+The runtime form, `ww hook session-start|stop|interrupt --agent <agent>`, is
+what the agents call; it reads the agent's JSON payload on stdin.
+
+## When a hook fails or runs too often
+
+A hook never breaks the agent. On any error, a bad argument, or outside a ww
+root, it exits 0 with no output: some agents read exit code 2 as "continue", and
+an unexpected message would enter the agent's context. The worst outcome is a
+lost hint. When the command cannot start at all, for example a missing
+launcher or an untrusted Codex hook, the agent shows its own non-blocking hook
+error. A hook that times out is killed by the agent, which carries on.
+
+Running more often than needed is harmless. Antigravity calls its
+pre-invocation hook before every model call; only the first one returns
+context.
+
+Every hook call is written to the audit log, `.ww/executions.jsonl`, with the
+event, the agent, and ww's decision, so a session can be followed there:
+
+```json
+{"command": "hook", "hook_event": "session-start", "hook_agent": "claudecode", "hook_decision": "context", "outcome": "ok"}
+```
+
+A failure is logged with `outcome: error` and the exception type. The agent's
+payload is never logged.
+
+## See also
+
+- [Agent limitations](limitations.md#agent-limitations): per-agent hook
+  gaps, nested subagents, and why a worker cannot talk to the operator.
+- [architecture.md](architecture.md#agent-hooks) for how the hook answers
+  are computed internally.