Kit

​

For

​

Use when

• The person asks for an agent that works with some of the project’s Shapes.
• You must choose how much that agent may change.
• You need the address to add to an MCP client, or a key for a machine.
• A Brain needs agents of its own (card brain).

​

Not this

• A limit on what an agent or key reads: use a View (card view).
• The agents and access you give one client, in one place: use a Brain (card brain).
• Which credential you hold and what it can do: use card credential.

​

Rules

1. kit.1 A Kit limits actions, not data. Your job: to limit what an agent reads, create its connection with --view <view-id> (card view). Without a View, the agent reads the project as far as its tools and the person who made it allow.
2. kit.2 Describe the agent, and Penumbra chooses its tools. Your job: run penumbra kits draft --name "<name>" --shape <shape> --level <level>. Give 1 to 20 published Shapes. The Kit level is read, propose, confirm or apply. read reads only. propose stages changes that a person submits. confirm changes the project with each change approved first. apply changes it directly, and the project’s approval rules still hold. Enforced: a Kit level that your role cannot give is refused with level_unavailable, and the answer names the highest level you can give.
3. kit.3 Choose the lowest Kit level that does the job. Your job: read the lines under “an agent with it” that the draft prints, and tell the person in those words. The person decides the Kit level, not you.
4. kit.4 Check a draft, and publish what you checked. Your job: run penumbra kits check <kit-id>. It prints the tools and a review digest. Publish with penumbra kits publish <kit-id> --digest <digest>. Enforced: a draft that changed after the check is refused with kit_draft_changed. Without --digest, publish checks the draft itself first.
5. kit.5 A refused draft says what to fix, field by field. Enforced: a draft that is saved but not ready exits with code 3 and kit_not_ready. The output starts with “to fix:” and gives one line for each field. Fix those fields and run penumbra kits draft --kit <kit-id> again with the same flags.
6. kit.6 A published version does not change, and a connection keeps the tools it was made with. Enforced: a newer version of the Kit adds no tool to a connection that exists. Your job: to give an agent the newer version, make a new connection on it.
7. kit.7 An address grants nothing by itself. Enforced: a client that opens it signs in, and the person approves it. Your job: give the address to the person, who adds it to an MCP client such as Claude.
8. kit.8 A machine connection has its own key, and the key is shown once. Your job: run penumbra kits connections create "<name>" --kit <kit-id> and store the key it prints. Enforced: Penumbra cannot show the key again, and it works for 30 days. The key opens the Kit’s address only. The API refuses it. If it is lost, the person rotates or revokes the connection in the App.
9. kit.9 Kits and connections belong to a person. Enforced: a key or a connected agent that runs penumbra kits list, or any other Kit command, is refused with human_session_required and exit code 3. Making a connection needs a project owner or admin. Limiting it to a View also needs someone who manages access.
10. kit.10 A connection for a View or a Brain can only read. Your job: run penumbra kits show <kit-id> and use a version that says “reads only”. Enforced: another version is refused with view_requires_read_only or brain_kit_not_read_only (card rules view.6 and brain.5).
11. kit.11 A new Kit is private to the person who made it. Enforced: a Brain refuses a Kit that is not shared with the project, with brain_kit_unavailable. Your job: the CLI has no command that shares a Kit. Ask a project owner or admin to open Tools, then Kits, and set Who can use this Kit? to Members of this project.
12. kit.12 A Kit cannot lower the project’s approval rules. Enforced: every connection follows the project’s rules for destructive, publication and paid changes (card approval). Kit level confirm also holds every submit for approval. Your job: do not promise the person that an apply agent changes the project without a check. Read the consequence lines that the draft prints.
13. kit.13 Instructions are text sent to the client. Enforced: more than 8192 characters is refused. The CLI refuses it before it sends the draft, with invalid_input and exit code 2. The cell names the same limit instructions_too_long. A Kit counts characters, and a Brain counts bytes (card rule brain.11). Your job: never put a secret in them, because the client can read them. They do not change what the agent may do.
14. kit.14 Publishing and making a connection are keyed. Enforced when you ask: run the same command with the same --request-id, and you get the same version or connection, not a second one. A repeat of a connection does not show the key again. Without the flag, the CLI makes a new key for each run.
15. kit.15 Retiring a Kit ends every connection on it. Your job: tell the person before they retire it. Penumbra revokes the connections and cancels the approvals that wait for them. The CLI has no command for it. The person retires a Kit in the App with Retire Kit.

​

Failure signs

• The agent reads more than the person meant: it has no View (rule kit.1).
• penumbra kits publish is refused with kit_draft_changed: rule kit.4.
• A draft exits with kit_not_ready: rule kit.5.
• penumbra kits list is refused with human_session_required: rule kit.9.
• A Brain refuses the Kit: rules kit.10 and kit.11.
• An agent has a tool that the person did not expect: the Kit version it was made with has it (rule kit.6).
• An agent cannot find something the person sees: problem hidden-reads-as-missing.

​

Doors

​

Keep going